Contributing Guide

Development Status

While the original author no longer has time to work on requests-cache (see note here), one or more maintainers are available via Code Shelter to help keep this project going.

If there is a new feature you would like to see, the best way to make that happen is to submit a PR for it!

Bug Reports & Feedback

If you discover a bug, want to propose a new feature, or have other feedback about requests-cache, please create an issue!

Project Discussion

If you want to discuss ideas about the project in general, or if you have an issue or PR that hasn’t received a response in a timely manner, please reach out on the Code Shelter chat server, under projects/requests-cache.

Pre-release Installation

If you want to test out the latest in-development changes, you can install pre-release versions:

pip install --pre requests-cache

Pre-release documentation can be found here:

Dev Installation

To set up for local development (requires poetry):

$ git clone
$ cd requests-cache
$ poetry install -v -E all

Pre-commit Hooks

Pre-commit config is included 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

To uninstall:

$ pre-commit uninstall


Test Layout

  • 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).

  • See for pytest fixtures that apply the most common mocking steps and other test setup.

Running Tests

  • Run pytest to run all tests

  • Run pytest tests/unit to run only unit tests

  • Run pytest tests/integration to run only integration tests

  • Run ./ to run all tests with some useful options for test coverage reports, multiprocessing, and debugging.

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.

Then, run:

$ docker-compose up -d
pytest tests/integration

Integration Test Alternatives

If you can’t easily run Docker containers in your environment but still want to run some of the integration tests, you can use pytest-httpbin instead of the httpbin container. This just requires installing an extra package and setting an environment variable:

pip install pytest-httpbin
pytest tests/integration/

For backend databases, you can install and run them on the host instead of in a container, as long as they are running on the default port.


Sphinx is used to generate documentation.

To build the docs locally:

$ make -C docs all

To preview:

# MacOS:
$ open docs/_build/index.html
# Linux:
$ xdg-open docs/_build/index.html


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 docs/docker-compose.yml to simplify this.

Run with:

# Optionally add --build to rebuild with updated dependencies
docker-compose -f docs/docker-compose.yml up -d
docker exec readthedocs make all

Pull Requests

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 master branch.


Notes for maintainers:

  • Releases are built and published to pypi based on git tags.

  • Milestones will be used to track progress on major and minor releases.

  • GitHub Actions will build and deploy packages to PyPi on tagged commits on the master branch.

Release steps:

  • Update the version in requests_cache/

  • Update the release notes in

  • Merge changes into the master branch

  • Push a new tag, e.g.: git tag v0.1 && git push origin --tags

  • This will trigger a deployment. Verify that this completes successfully and that the new version can be installed from pypi with pip install


Pre-release builds are convenient for letting testers try out in-development changes. Versions with the suffix .dev (among others) can be deployed to PyPI and installed by users with pip install --pre, and are otherwise ignored by pip install:

# Install latest pre-release build:
pip install -U --pre requests-cache

# Install latest stable build
pip install -U requests-cache


  • See python packaging docs on pre-release versioning for more info on how this works. for more details.

  • Any collaborator can trigger a pre-release build for requests-cache by going to Actions > Deploy > Run workflow.

  • A complete list of builds can by found on PyPI under ‘Release History’.