To set up for local development (requires poetry):
$ git clone https://github.com/requests-cache/aiohttp-client-cache $ cd aiohttp-client-cache $ poetry install -E backends -E docs
CI jobs will run code style checks, type checks, linting, etc. If you would like to run these same checks locally, you can use pre-commit. This is optional but recommended.
To install pre-commit hooks:
To manually run checks on all files:
pre-commit run --all-files # Alternative alias with nox: nox -e lint
To disable pre-commit hooks:
Tests are divided into unit and integration tests:
Unit tests can be run without any additional setup, and don’t depend on any external services
Integration tests depend on additional services, which are easiest to run using Docker (see Integration Tests section below)
pytestto run all tests
pytest test/unitto run only unit tests
pytest test/integrationto run only integration tests
For CI jobs (including PRs), these tests will be run for each supported python version. You can use nox to do this locally, if needed:
nox -e test
Or to run tests for a specific python version:
nox -e test-3.10
To generate a coverage report:
nox -e cov
nox --list for a ful list of available commands.
Integration Test Containers#
A live web server and backend databases are required to run integration tests, and docker-compose config is included to make this easier. First, install docker and install docker-compose.
docker-compose up -d pytest test/integration
Sphinx is used to generate documentation.
To build the docs locally:
$ nox -e docs
# MacOS: $ open docs/_build/index.html # Linux: $ xdg-open docs/_build/index.html
Documentation is automatically built and published by Readthedocs whenever code is merged into the
Sometimes, there are differences in the Readthedocs build environment that can cause builds to
succeed locally but fail remotely. To help debug this, you can use the
readthedocs/build container to build
the docs. A configured build container is included in
docker-compose.yml to simplify this.
docker-compose up -d --build docker exec readthedocs make all
Here are some general guidelines for submitting a pull request:
If the changes are trivial, just briefly explain the changes in the PR description.
Otherwise, please submit an issue describing the proposed change prior to submitting a PR.
Add unit test coverage for your changes
If your changes add or modify user-facing behavior, add documentation describing those changes
Submit the PR to be merged into the
Releases are built and published to pypi based on git tags. Milestones will be used to track progress on major and minor releases.
Here is a brief overview of the main classes and modules. See API Reference for more complete documentation.
session.CachedSession: A mixin and wrapper class, respectively, for
aiohttp.ClientSession. There is little logic here except wrapping
ClientSession._request()with caching behavior.
response.CachedResponse: A wrapper class built from an
aiohttp.ClientResponse, with additional cache-related info. This is what is serialized and persisted to the cache.
backends.base.CacheBackend: Most of the caching logic lives here, including saving and retrieving responses. It contains two
BaseCacheobjects for storing responses and redirects, respectively.
backends.base.BaseCache: Base class for lower-level storage operations, overridden by individual backends.
Other modules under
backends.*: Backend implementations that subclass
cache_control: Utilities for determining cache expiration and other cache actions
cache_keys: Utilities for creating cache keys