Development#

This page describes how to setup development environment. You don’t need to follow the instructions if you just use starknet.py as a package.

Development dependencies#

  • poetry - dependency manager.

  • pyenv - recommended for installing and switching python versions locally.

  • cairo-lang - required to compile contracts (poe compile_contracts)

Setup#

In order to run tests on devnet, you need to install starknet-devnet-rs. The correct version of devnet to use corresponds to the Starknet and RPC specification that are currently supported by Starknet.py. Information about the supported version for the latest release can be found in the migration guide.

To avoid version discrepancies or other related issues, we recommend installing this dependency using the cargo install command, and specifying a certain commit along with the correct Starknet and RPC versions.

Below is the command you can use to do this, designed for compatibility with the current version of Starknet.py:

cargo install \
--locked \
--git https://github.com/0xSpaceShard/starknet-devnet-rs.git \
--rev c6ffb99

If you choose to install starknet-devnet-rs using a different method, please make sure to add the executable starknet-devnet to your PATH environment variable.

In order to be able to run tests on testnet and integration networks (starknet_py/tests/e2e/tests_on_networks/), you must set some environmental variables:

  • GOERLI_INTEGRATION_RPC_URL

  • GOERLI_TESTNET_RPC_URL

  • SEPOLIA_INTEGRATION_RPC_URL

  • SEPOLIA_TESTNET_RPC_URL

  • GOERLI_INTEGRATION_ACCOUNT_PRIVATE_KEY

  • GOERLI_INTEGRATION_ACCOUNT_ADDRESS

  • GOERLI_TESTNET_ACCOUNT_PRIVATE_KEY

  • GOERLI_TESTNET_ACCOUNT_ADDRESS

The existing tests don’t execute any invoke transactions on the Sepolia networks. If you plan to incorporate such tests, please also set the following environment variables:

  • SEPOLIA_INTEGRATION_ACCOUNT_PRIVATE_KEY

  • SEPOLIA_INTEGRATION_ACCOUNT_ADDRESS

  • SEPOLIA_TESTNET_ACCOUNT_PRIVATE_KEY

  • SEPOLIA_TESTNET_ACCOUNT_ADDRESS

The best way to set environment variables is to create test-variables.env file in starknet_py/tests/e2e/ directory, so they can be loaded by the python-dotenv library. You can find an example file test-variables.env.template in the same directory with the format of how it should look like.

# Install dependencies
poetry install

# Compile contracts
poe compile_contracts

# Make sure everything was installed properly
poe test

Git hooks#

Run this snippet to enable lint checks and automatic formatting before commit/push.

cp pre-push ./.git/hooks/
cp pre-commit ./.git/hooks/
chmod +x ./.git/hooks/pre-commit
chmod +x ./.git/hooks/pre-push

Documentation#

Sphinx is used for generating documentation.

# Install additional dependencies for docs
poetry install -E docs

# Generate HTML documentation
poe docs_create

# Open generated HTML documentation
poe docs_open

Tests#

# Run whole suite
poe test

# Generate test report in terminal
poe test_report

# Generate HTML report and open it in the browser
poe test_html

# Run only unit tests
poe test_unit

# Run only e2e tests
poe test_e2e

Running e2e tests in PyCharm#

  1. Run starkware-devnet script before running e2e tests in PyCharm.

  2. Use E2E tests configuration to run or debug.

⚠️ Warning: Make sure to fill your interpreter in the configuration, to match your project’s poetry venv.

Code style guide#

Rules to follow when writing a code:

  1. Check the code with pylint

poe lint

  1. Format the code with black

poe format

  1. Run a typechecker (pyright)

poe typecheck

  1. Add constant values to the constants.py file.

  2. Prefer keyword-only arguments where appropriate.

  3. All public classes providing async api should be marked with the @add_sync_methods decorator.

  4. Error messages should start with a capital letter.

  5. Use Argument x is… instead of X is… when error message starts with argument (property) name.

  6. All sentences (in docstrings/errors) should be ended with a period.

  7. When adding a TODO comment, it must have a corresponding issue to it. The format for the comment is: # TODO (#issue no.): ....

Release checklist#

Perform these actions before releasing a new starknet.py version

  1. Bump package version in pyproject.toml

  2. Re-lock using poetry lock --no-update

  3. Make a PR to development with name of format vMAJOR.MINOR.PATCHES-alpha and merge it making sure that the merge commit message is the same as PR name

  4. Merge development into master without squashing

git checkout master
git merge development

  1. Make a new release on GitHub

  2. Run release action from master branch