Skip to content

Development Guide

Welcome! Thank you for wanting to make the project better. This section provides an overview on how repository structure and how to work with the code base.

Before you dive into this, it is best to read:

Local Environment

Use a virtual environment and install the project from pyproject.toml with test extras:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[test]"
pre-commit install

If you use uv, keep the same pyproject.toml source of truth:

uv venv
source .venv/bin/activate
uv pip install -e ".[test]"
pre-commit install

Debugging

Python's built-in pdb debugger is enough for most local debugging. You can create a breakpoint anywhere in the code:

def my_function():
    breakpoint()
    ...

When the code reaches the breakpoint, it will drop into an interactive debugger.

See the documentation on pdb for more information.

Testing

You'll be unable to merge code unless linting and tests pass. The main local checks are:

pytest -sv tests/regression
ruff check .
ruff format --check .
bandit -c pyproject.toml -r aiograpi
pip-audit --strict .
mkdocs build --strict

To apply automatic lint and formatting fixes locally:

ruff check . --fix
ruff format .

Generally we should endeavor to write tests for every feature. Every new feature branch should increase the test coverage rather than decreasing it.

We use pytest as our testing framework.

Stages

To customize / override a specific testing stage, please read the documentation specific to that tool:

  1. PyTest
  2. Ruff
  3. Bandit

pyproject.toml

Setuptools is used to package the library through pyproject.toml.

pyproject.toml is the source of truth for package metadata, runtime dependencies, and test/development extras.

Requirements

  • [project].dependencies lists runtime dependencies imported by the library.
  • [project.optional-dependencies].test lists tools needed for tests, linting, docs, and local development.

Publishing is handled by the tag-based publish.yml workflow. Pushes and pull requests run the package workflow first; maintainers cut a version tag only after the checks are green.

Continuous Integration Pipeline

The Package workflow runs pip-audit, Bandit, Ruff, the mypy regression gate, network-free regression tests, and docs builds. On canonical repository pushes it also runs tests/live/smoke.py against the pooled live-account endpoint configured in TEST_ACCOUNTS_URL.

The Publish to PyPI workflow runs only for version tags such as 0.9.0. It verifies the tag matches pyproject.toml, builds the wheel and sdist, publishes through PyPI trusted publishing, creates the GitHub release, and publishes versioned docs with mike.

The Upstream Sync Tracker workflow can be triggered manually or by repository dispatch when instagrapi publishes a new release. It creates a tracking issue with the current async-port baseline and the target upstream tag.