Developer Guide

This page is for people who want to contribute to Astra itself.

Setting up a development environment

git clone https://github.com/paman7647/Astra.git
cd Astra
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python -m playwright install chromium

Project structure

astra/
├── __init__.py   # Public exports
├── constants.py   # Global config values
├── client/    # Client class and lifecycle
│ ├── client.py  # Main Client
│ ├── authenticator.py # QR / pairing auth
│ ├── sync_engine.py # Background sync and health
│ └── methods/   # Chat, Group, Account mixins
├── protocol/   # Bridge to WhatsApp Web JS
│ ├── gateway.py  # ProtocolBridge.call()
│ └── js_engine.py  # Injected JS
├── core/bridge/   # Domain-specific JS bridges
├── errors/    # Typed exceptions and error codes
├── events/    # Event dispatcher, filters
├── models/    # Data classes (Message, Chat, User)
├── connection/   # Browser manager, reconnection
└── utils/    # Helpers (health, media, retry)

Code style

  • Formatting: ruff (configured in pyproject.toml).

  • Type hints: Use them on all public methods.

  • Docstrings: Google style (Napoleon parses them for Sphinx).

  • Logging: Use logging.getLogger(__name__). No emojis in log messages.

  • Errors: Raise typed AstraError subclasses, never bare Exception.

# Check formatting
ruff check astra/

# Type check
mypy astra/

Adding a new error code

  1. Add the code to astra/errors/codes.py:

NEW_ERROR = _CodeDef("E3099", "Messaging", "Something failed.", "Try again.", True)

  1. Add the exception class to astra/errors/exceptions.py:

class NewError(AstraError):
 def __init__(self, message=None, **kwargs):
  super().__init__(**_from_code(ErrorCode.NEW_ERROR, message, **kwargs))

  1. Export it from astra/errors/__init__.py.

  2. Add a row to ERROR_CODES.md.

Adding a new bridge method

  1. Add the JavaScript function in astra/protocol/js_engine.py.

  2. Create or extend the domain bridge in astra/core/bridge/.

  3. Add the Python method to the appropriate mixin in astra/client/methods/.

  4. Wrap the call in a try/except with a typed error.

Building docs

The documentation is built with Sphinx. The [dev] extras you installed above include Sphinx itself, but you will also need a theme such as sphinx_rtd_theme which is used by the default configuration. There are two common user errors when running the build:

  • running the command from the wrong directory (you must be inside the docs folder)

  • forgetting to install the theme, which leads to a ThemeError

Sphinx’s default error message is a bit opaque; if you see “no theme named ‘sphinx_rtd_theme’”, simply install it with:

pip install sphinx_rtd_theme

and rerun the build from the documentation root:

cd docs              # change into the docs directory first
python3 -m sphinx -b html source _build/html
open _build/html/index.html

If the build succeeds, the generated HTML will appear under docs/_build/html. The open command works on macOS; use your preferred method on other platforms.