aiohttp-client-cache

Warnings

• breaking Upgrading to v0.12.0 or later may invalidate previously cached data due to internal changes. Users should clear their cache or be prepared for a temporary loss of cached responses.
  Fix: Clear existing cache files or databases after updating, or simply allow the cache to repopulate.
• breaking Minimum Python version required is 3.9+ since v0.13.0. Earlier Python versions are no longer supported.
  Fix: Upgrade your Python environment to 3.9 or higher.
• gotcha Caching behavior is determined by a precedence order: Cache-Control request headers > Cache-Control response headers > per-request expiration > per-URL expiration > per-session expiration. This can lead to unexpected caching if not understood.
  Fix: Refer to the documentation on 'Cache Expiration' and 'Cache-Control' to understand how different expiration settings interact and ensure desired caching behavior.
• gotcha By default, `CachedSession` without a specified `cache` backend will use a non-persistent, in-memory cache. Data will be lost when the session or application closes.
  Fix: Always explicitly configure a persistent backend (e.g., `SQLiteBackend`, `RedisBackend`) when you need data to persist across application runs. Example: `CachedSession(cache=SQLiteBackend('my_cache.sqlite'))`.
• gotcha By default, only `GET` and `HEAD` HTTP methods and `200` status codes are cached. Requests using other methods (like `POST`) or responses with other status codes will not be cached unless explicitly configured.
  Fix: Use `allowed_methods` and `allowed_codes` parameters in your backend configuration to cache additional methods or status codes. Example: `SQLiteBackend(allowed_methods=('GET', 'POST'), allowed_codes=(200, 404))`.
• gotcha The library is an 'early work in progress' and breaking changes should be expected until a 1.0 release.
  Fix: Pin your dependency to a specific minor version and thoroughly test when upgrading to newer minor or patch versions.

Install

• pip install aiohttp-client-cache Base installation
• pip install aiohttp-client-cache[all] With all backend dependencies

Imports

• CachedSession

  from aiohttp_client_cache import CachedSession

• SQLiteBackend

  from aiohttp_client_cache import SQLiteBackend

• ClientSession (when caching is desired)

  from aiohttp_client_cache import CachedSession

  Use CachedSession for caching behavior; ClientSession is the uncached aiohttp client.
• aiohttp-cache (for client-side caching)

  from aiohttp_client_cache import CachedSession

  aiohttp-cache is for aiohttp web server caching, not client requests. Use aiohttp-client-cache for client-side caching.

Quickstart

This example demonstrates basic usage of CachedSession with a SQLite backend. The first request to 'httpbin.org/delay/1' will fetch the data and store it in 'demo_cache.sqlite'. Subsequent requests to the same URL will retrieve the response instantly from the cache. The `response.from_cache` attribute indicates if the response was served from the cache.

import asyncio
from aiohttp_client_cache import CachedSession, SQLiteBackend

async def main():
    # Initialize CachedSession with a SQLite backend
    # 'demo_cache' will be the filename for the SQLite database
    async with CachedSession(cache=SQLiteBackend('demo_cache')) as session:
        print("First request (will be slow...")
        response = await session.get('http://httpbin.org/delay/1')
        print(f"Response from cache: {response.from_cache}, Status: {response.status}")

        print("Second request (should be fast...")
        response = await session.get('http://httpbin.org/delay/1')
        print(f"Response from cache: {response.from_cache}, Status: {response.status}")

if __name__ == '__main__':
    asyncio.run(main())