AnchorPy

The AnchorPy CLI provides utilities to streamline working with Anchor programs in Python. You can use it to initialize test files or launch an interactive IPython shell with a pre-configured workspace.

To see all available commands and options, run:

anchorpy --help

$ anchorpy --help
Usage: anchorpy [OPTIONS] COMMAND [ARGS]...

  AnchorPy CLI.

Options:
  --install-completion [bash|zsh|fish|powershell|pwsh]
                                  Install completion for the specified shell.
  --show-completion [bash|zsh|fish|powershell|pwsh]
                                  Show completion for the specified shell, to
                                  copy it or customize the installation.
  --help                          Show this message and exit.

Commands:
  init   Create a basic Python test file for an Anchor program.
  shell  Start IPython shell with AnchorPy workspace object initialized.

AnchorPy supports workspaces to easily access deployed programs. Unlike JavaScript/TypeScript where workspaces are often globally available, in AnchorPy you must explicitly create and close them.

Key differences:

• Use create_workspace() to instantiate a workspace.
• Access programs using snake_case (e.g., workspace["basic_0"]), matching the naming convention used in Rust/lib.rs.
• Use await close_workspace(workspace) to close all HTTP clients within the workspace and prevent warnings.
• For testing, workspace_fixture is available as a factory.

import asyncio
from anchorpy import create_workspace, close_workspace

async def main():
    # Read the deployed program from the workspace.
    workspace = create_workspace()
    program = workspace["basic_0"]
    
    # Execute the RPC.
    await program.rpc["initialize"]()
    
    # Close all HTTP clients in the workspace.
    await close_workspace(workspace)

asyncio.run(main())

To interact with a smart contract, you can generate a Program client by providing its Interface Definition Language (IDL) and its deployed program ID.

It is recommended to use a generated client (which provides proper type hints) instead of the dynamic client where possible. When using the dynamic client, you must ensure the underlying HTTP client is closed to avoid warnings. This can be done using an async with context manager or by explicitly calling await program.close().

from pathlib import Path
import asyncio
from solders.pubkey import Pubkey
from anchorpy import Idl, Program

async def main():
    # Read the generated IDL.
    with Path("target/idl/basic_0.json").open() as f:
        raw_idl = f.read()
    idl = Idl.from_json(raw_idl)
    
    # Address of the deployed program.
    program_id = Pubkey.from_string("<YOUR-PROGRAM-ID>")
    
    # Generate the program client from IDL using a context manager.
    async with Program(idl, program_id) as program:
        # Execute the RPC using bracket notation for the method name.
        await program.rpc["initialize"]()

asyncio.run(main())

When calling an RPC function that requires specific accounts or signers, AnchorPy uses an explicit Context object. This is a departure from the TypeScript/JavaScript implementation where accounts are passed in a plain options object.

To call a function with arguments and context:

1. Define an accounts dictionary containing the required public keys.
2. Wrap the accounts and signers list in a Context object.
3. Pass the arguments followed by the ctx keyword argument to the RPC method.

import asyncio
from solders.keypair import Keypair
from solders.system_program import ID as SYS_PROGRAM_ID
from anchorpy import create_workspace, close_workspace, Context

async def main():
    workspace = create_workspace()
    program = workspace["basic_1"]
    my_account = Keypair()
    
    # Define the accounts required by the instruction
    accounts = {
        "my_account": my_account.pubkey(),
        "user": program.provider.wallet.public_key,
        "system_program": SYS_PROGRAM_ID
    }
    
    # Execute the RPC with arguments and an explicit Context object
    await program.rpc["initialize"](
        1234, 
        ctx=Context(accounts=accounts, signers=[my_account])
    )
    
    await close_workspace(workspace)

asyncio.run(main())