Contributing

Thank you for considering contributing! Here is how to get set up and what we expect.

How to setup

  • Install uv (the project uses uv for dependency management and command execution).

  • Clone the repo:

    git clone https://github.com/darkstussy/aioscraper.git
cd aioscraper

  • Install Python interpreters used by the test matrix (uv will fetch them if missing):

    uv python install 3.11 3.12 3.13 3.14

  • Sync the environment with all extras and dev dependencies:

    uv sync --extra aiohttp-speedups --extra httpx --extra uvloop

  • Enable git hooks (we recommend prek, a Rust alternative to pre-commit; using pre-commit is fine if you prefer):

    uv tool install prek
prek install

Running tests

  • Unit/integration tests:

    uv run pytest

  • Some HTTP integration tests spin up local aiohttp/httpx clients and may require network/socket permissions in your environment.

Style, linting, typing

  • Formatting and linting use Ruff (configured in .ruff.toml).

  • Type checking uses BasedPyright (configured in pyrightconfig.json).

  • Please format code and add tests for new behavior.

  • Keep documentation in sync with code changes.

Note

Install IDE extensions for better development experience:

Build documentation

The project documentation is built with Sphinx. You may need make available on your system. Build the docs with:

uv run --with-requirements docs/requirements.txt sphinx-build -M html docs docs/build -W

After a successful build, view the generated documentation by opening docs/build/html/index.html in your browser.

Submitting changes

  • Open an issue first if you’re proposing a larger change.

  • Keep commits focused and include a brief description of motivation and behavior.