To set up for local development:
$ git clone https://github.com/JWCook/aiohttp-client-cache $ cd aiohttp-client-cache $ pip install -Ue ".[dev]"
Pre-commit config is uncluded to run the same checks locally that are run in CI jobs by GitHub Actions. This is optional but recommended.
$ pre-commit install --config .github/pre-commit.yml
$ pre-commit uninstall
$ docker-compose up -d pytest test/integration
Sphinx is used to generate documentation.
To build the docs locally:
$ make -C docs html
# 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.
Please add unit test coverage and updated docs (if applicable) for your 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:
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 retriving responses. It contains two
BaseCacheobjects for storing responses and redirects, respectively.
expiration: Utilities for creating cache keys and cache expiration, respectively
backends.base.BaseCache: Base class for lower-level storage operations, overridden by individual backends.
Other backend implementations in
backends.*: A backend implementation subclasses
CacheBackend(for higher-level operations), as well as
BaseCache(for lower-level operations).