niquests-cache 0.0.3

Filesystem-cached niquests sessions.

niquests-cache

Filesystem-cached niquests sessions.

Installation

pip install niquests-cache

Example usage

The cached_session() helper returns a CachedSession or CachedAsyncSession whose cache root is platformdirs.user_cache_path(app_name, appauthor=False) / 'http'. If you omit app_name, niquests-cache is used. Only successful GET and HEAD responses are written to disk; the default time-to-live is 10 minutes (expire_after= on the helper, or per-request—see below).

Sync helper (default app name and TTL):

from niquests_cache import cached_session

session = cached_session()
response = session.get('https://httpbin.org/get')
response.raise_for_status()

Custom application name for user_cache_path (same http subdirectory):

from niquests_cache import cached_session

session = cached_session(app_name='my-application')
response = session.get('https://httpbin.org/get')
response.raise_for_status()

Plain niquests session with no filesystem cache:

from niquests_cache import cached_session

session = cached_session(no_cache=True)

Construct CachedSession when you need an explicit directory or TTL:

from datetime import timedelta
from pathlib import Path

from niquests_cache import CachedSession

cache = Path('.cache') / 'http'
with CachedSession(cache_dir=cache, expire_after=timedelta(hours=1)) as session:
    response = session.get('https://httpbin.org/get')
    response.raise_for_status()

Async helper (use an async context manager):

import asyncio
from datetime import timedelta

from niquests_cache import cached_session

async def main() -> None:
    session = cached_session(aio=True, expire_after=timedelta(minutes=30))
    async with session:
        response = await session.get('https://httpbin.org/get')
        response.raise_for_status()

asyncio.run(main())

Or construct CachedAsyncSession directly:

import asyncio
from datetime import timedelta
from pathlib import Path

from niquests_cache import CachedAsyncSession

async def main() -> None:
    cache = Path('.cache') / 'http'
    async with CachedAsyncSession(cache_dir=cache, expire_after=timedelta(hours=1)) as session:
        response = await session.get('https://httpbin.org/get')
        response.raise_for_status()

asyncio.run(main())

To bypass the cache for a single request, pass expire_after=0 to request (that GET or HEAD is not served from or written to the cache).