Contributing

How to Contribute

Requests-cache is in a relatively mature state, but is still under active maintenance. Contributions are welcome, and will be attributed on the Contributors page.

Bug Reports, Feedback, and Discussion

If you discover a bug or want to request a new feature, please create an issue.

If you want to discuss ideas about the project in general, or have a more open-ended question or feedback, please use Discussions.

How to Help

If you are interested in helping out, here are a few ways to get started:

  • Give feedback on open issues

  • See the help-wanted issue label

  • If you find an issue you want to work on, please comment on it so others know it’s in progress

AI Policy

AI-assisted contributions may be accepted if:

  • Contents are fully reviewed, tested, and understood by a human

  • Any user-facing documentation is human-written (excluding minor edits/docstring boilerplate)

  • You comment in a new or existing issue to discuss before submitting a PR

The general principle is that low-effort, fully automated contributions add a maintenance burden for us as maintainers (limited and squishy mortal beings) that is out of proportion with the utility these PRs provide, especially if they are submitted solely for contribution stats.

Pull Requests

Here are some general guidelines for submitting a pull request:

  • Use the PR template

  • In most cases, please submit an issue (or comment on an existing issue) describing the proposed change prior to submitting a PR.

  • Or, if the changes are trivial (minor bugfixes, etc.), just briefly explain the changes in the PR description

  • Add unit test coverage for your changes

  • If your changes add or modify user-facing behavior, add documentation describing those changes

Development Setup

Prerequisites

To setup requests-cache for development, first install these tools:

Next, clone the repository and install dependencies:

git clone https://github.com/requests-cache/requests-cache.git
cd requests-cache
uv sync --frozen --all-extras --all-groups
uv tool install prek

uv will automatically install python and create a new virtual environment if needed.

Linting & Formatting

Code linting and formatting tools used include:

All of these will be run by GitHub Actions on pull requests. You can also run them locally with prek (or pre-commit, if you prefer):

prek run -a

Pre-Commit Hooks

Optionally, you can use prek to automatically

prek install

To disable hooks:

prek uninstall

This can save you some time in that it will show you errors immediately rather than waiting for CI jobs to complete, or if you forget to manually run the checks before committing.

Testing

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

Have a look at conftest.py for pytest fixtures that apply the most common mocking steps and other test setup.

Overview:

  • Run uv run pytest to run all tests

  • Run uv run pytest tests/unit to run only unit tests

  • Run uv run pytest tests/integration to run only integration tests

Running Unit Tests

Unit tests can be run without running any additional services:

uv run pytest tests/unit

Integration Tests with Docker

A live web server and backend databases are required to run integration tests, and a docker-compose config is included to make this easier. First, install docker and docker compose.

Start the docker containers:

docker compose up -d

After this, you can run all the tests:

uv run pytest

or just the integration tests:

uv run pytest tests/integration

After, you are done testing, shutdown the docker containers:

docker compose down

Integration Tests without Docker

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:

export USE_PYTEST_HTTPBIN=true
uv pip install pytest-httpbin
uv run pytest tests/integration/test_sqlite.py

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.

Documentation

Sphinx is used to generate documentation.

To build the docs locally:

uv run sphinx-build docs docs/_build/html

To preview:

open docs/_build/html/index.html

Alternatively, you also use sphinx-autobuild to rebuild the docs and live reload in the browser whenever doc contents change:

uv run sphinx-autobuild --open-browser docs docs/_build/html

Readthedocs

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

Notes for Maintainers

Releases

  • 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 main branch.

Release steps:

  • Update the version in pyproject.toml

  • Update the release notes in HISTORY.md

  • Generate a sample cache for the new version (used by unit tests) with python tests/generate_test_db.py

  • Merge changes into the main 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

  • A readthedocs build will be triggered by the new tag. Verify that this completes successfully.

Downstream builds:

  • We also maintain a Conda package, which is automatically built and published by conda-forge whenever a new release is published to PyPI. The feedstock repo only needs to be updated manually if there are changes to dependencies.

  • For reference: repology lists additional downstream packages maintained by other developers.

Pre-Releases

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

Notes: