Algorand Python Language Server

The Algorand Python language extension brings language server-powered capabilities to your smart contract authoring experience in Visual Studio Code. It extends the results from your installed Python language server to provide Algorand Python-specific diagnostics and code actions.

This tutorial demonstrates how to set up and use the Algorand Python extension to identify and resolve common issues early in your development workflow. We’ll walk through identifying and fixing bugs in an Algorand Python smart contract using the extension’s diagnostic features.

Prerequisites

• Visual Studio Code 1.80.0 or higher
• Python extension for Visual Studio Code
• Python 3.12 or higher
• PuyaPy 5.3.0 or higher
• Basic understanding of Algorand smart contracts using Python

Caution

The Algorand Python extension is currently in beta. It works alongside your existing Python language server (recommended with Pylance) to provide additional Algorand-specific diagnostics and code actions for smart contract development. There is currently some latency between making code changes and seeing updated diagnostics, which will be addressed in a future update.

Step 1: Install the Extension

Install the Algorand Python language extension from the VSCode Marketplace:

1. Open the Extensions view in VSCode (Ctrl+Shift+X or Cmd+Shift+X)
2. Search for Algorand Python
3. Click Install on the extension published by the Algorand Foundation

Alternatively, install directly from the marketplace.

Step 2: Set Up Your Project

Initialize an AlgoKit Project

If you’re starting a new project, use AlgoKit to generate a Python smart contract project:

algokit init

Select options for a Python smart contract project from the interactive prompts.

If you haven’t installed algokit, follow these steps.

Create Algokit project Create your first Algokit project

Install PuyaPy

The extension requires PuyaPy version 5.3.0 or higher. Install it as a dev dependency in your project’s virtual environment:

# Activate your virtual environment first
pip install puyapy

We recommend installing PuyaPy in your project’s virtual environment to ensure the extension can automatically discover it. To check the version use:

puyapy --version

It should display 5.3.0 or higher.

Step 3: Enable the Language Server

For new AlgoKit projects, the language server is enabled by default. For existing projects, you need to enable it manually:

1. Open your workspace settings (File > Preferences > Settings or Cmd+,)
2. Search for algorandPython.languageServer.enable
3. Check the box to enable the language server

Alternatively, add this to your .vscode/settings.json:

{
  "algorandPython.languageServer.enable": true
}

To see detailed information about what the language server is doing:

1. Open the Output panel (View > Output or Ctrl+Shift+U)
2. Select Algorand Python Language Server from the dropdown
3. Review logs for diagnostics and extension activity

Step 4: Create an Example Smart Contract

Let’s create a simple contract with a deliberate bug to demonstrate the extension’s capabilities. Replace the Hello World contract with the below contract:

Python

from algopy import ARC4Contract, arc4, Txn, BoxMap
from algopy.arc4 import abimethod

class UserVotes(ARC4Contract):
    def __init__(self) -> None:
        # Each user can vote for multiple proposals
        self.votes = BoxMap(arc4.Address, arc4.DynamicArray[arc4.UInt64])

    @abimethod()
    def cast_vote(self, proposal_id: arc4.UInt64) -> arc4.DynamicArray[arc4.UInt64]:
        voter = arc4.Address(Txn.sender)

        if voter in self.votes:
            current_votes = self.votes[voter].copy()
            current_votes.append(proposal_id)

            # Bug in next line: mutable reference to ARC-4-encoded value must be copied using .copy() when being assigned
            self.votes[voter] = current_votes
        else:
            self.votes[voter] = arc4.DynamicArray[arc4.UInt64](proposal_id)

        return self.votes[voter]

This contract contains an intentional bug when updating the votes BoxMap in the cast_vote function.

Step 5: Observe Real-Time Diagnostics

Once you save the file, the Algorand Python extension will analyze your code. You should see a red squiggly line under current_votes in the if condition.

The extension will display the error mutable reference to ARC-4-encoded value must be copied using .copy() when being assigned to another variable in the contract when you hover over the red line.

Step 6: Apply Quick Fixes

The extension also provides quick fixes for the issue. Look for the lightbulb icon (💡) that appears. It suggests the fix 💡 Add .copy(). Click on the suggestion to add the fix.

Step 7: Fixed Smart Contract

Based on the extension’s diagnostics, your contract should now be updated as follows to address the identified issue:

Python

from algopy import ARC4Contract, arc4, Txn, BoxMap
from algopy.arc4 import abimethod

class UserVotes(ARC4Contract):
    def __init__(self) -> None:
        # Each user can vote for multiple proposals
        self.votes = BoxMap(arc4.Address, arc4.DynamicArray[arc4.UInt64])

    @abimethod()
    def cast_vote(self, proposal_id: arc4.UInt64) -> arc4.DynamicArray[arc4.UInt64]:
        voter = arc4.Address(Txn.sender)

        if voter in self.votes:
            current_votes = self.votes[voter].copy()
            current_votes.append(proposal_id)

            # Bug Fixed in next line: Added mutable reference to ARC-4-encoded value must be copied using .copy() when being assigned
            self.votes[voter] = current_votes.copy()
        else:
            self.votes[voter] = arc4.DynamicArray[arc4.UInt64](proposal_id)

        return self.votes[voter]

Step 8: Verify the Fixes

After applying the fixes, verify that warnings and errors have cleared in the Problems Panel. The extension will continue to provide real-time feedback as you progress in your development.

Configuration Options

The extension provides additional configuration options for customizing your experience:

Enable/Disable Language Server

{
  "algorandPython.languageServer.enable": true
}

Log Level

Adjust the verbosity of messages in the Output panel:

{
  "algorandPython.languageServer.logLevel": "info"
}

Available levels: error, warning, info, debug

Debounce Interval

Configure the delay between code changes and diagnostic updates:

{
  "algorandPython.languageServer.debounceInterval": 500
}

Value in milliseconds. Lower values provide faster feedback but may impact performance.

Troubleshooting

If the extension isn’t working as expected:

Extension Not Providing Diagnostics

1. Verify the extension is installed and enabled:

   • Check Extensions view for Algorand Python
   • Ensure it shows as Enabled

2. Confirm both extensions are installed:

   • Python extension for Visual Studio Code
   • Algorand Python extension

3. Verify the language server is enabled:

   • Check workspace settings for algorandPython.languageServer.enable
   • Should be set to true

4. Verify PuyaPy installation:

   pip show puyapy

   • Ensure version 5.3.0 or higher is installed
   • Confirm it’s in the same virtual environment VS Code is using

Check Python Interpreter

Make sure VS Code is using the correct Python interpreter:

1. Click on the Python version in the status bar (bottom right)
2. Select the interpreter from your project’s virtual environment
3. The interpreter should have PuyaPy installed

File Not Recognized

The extension activates for .py files in Algorand Python projects. Ensure:

• Your file is a Python file with .py extension
• The file contains Algorand Python imports (e.g., from algopy import ...)

Check Language Server Logs

1. Open Output panel (View > Output)
2. Select Algorand Python Language Server from the dropdown
3. Look for error messages or warnings
4. Set log level to debug for more detailed information

Summary

In this tutorial, we covered:

• Installing and configuring the Algorand Python language extension
• Setting up a project
• Using real-time diagnostics to identify issues
• Applying quick fixes to resolve common problems
• Troubleshooting common extension issues

The Algorand Python extension provides valuable assistance throughout your development process, helping you write more correct and robust smart contracts by catching issues early and suggesting improvements as you code.

Next Steps

Learn Algorand Python concepts, write and test smart contracts, debug with AVM Debugger, and follow best practices.

Algorand Python Concepts Explore Algorand Python concepts

Unit Tests Learn about unit testing Python contracts

AVM Debugger Try the AVM Debugger