diff options
author | Jordan Cook <jordan.cook@pioneer.com> | 2022-04-16 21:54:47 -0500 |
---|---|---|
committer | Jordan Cook <jordan.cook@pioneer.com> | 2022-04-17 13:42:21 -0500 |
commit | 613de4e1bb379d922cb7bd6c703fc81762f5d3bc (patch) | |
tree | b25b7dcc56b80fa6e53a496c2ca1c4a543211629 | |
parent | d6ee9143965d53dae44ca3a98802b2cc7ad6eeb7 (diff) | |
download | requests-cache-613de4e1bb379d922cb7bd6c703fc81762f5d3bc.tar.gz |
Move backend docs to user guide, separate from API reference docs
19 files changed, 214 insertions, 204 deletions
diff --git a/docs/_static/memory_32px.png b/docs/_static/memory_32px.png Binary files differnew file mode 100644 index 0000000..3960ca2 --- /dev/null +++ b/docs/_static/memory_32px.png diff --git a/docs/api/requests_cache.backends.base.md b/docs/api/requests_cache.backends.base.md deleted file mode 100644 index f4601a8..0000000 --- a/docs/api/requests_cache.backends.base.md +++ /dev/null @@ -1,8 +0,0 @@ -# Base -```{eval-rst} -.. automodule:: requests_cache.backends.base - :members: - :undoc-members: - :inherited-members: - :show-inheritance: -```
\ No newline at end of file diff --git a/docs/api/requests_cache.backends.gridfs.md b/docs/api/requests_cache.backends.gridfs.md deleted file mode 100644 index 18a2583..0000000 --- a/docs/api/requests_cache.backends.gridfs.md +++ /dev/null @@ -1,23 +0,0 @@ -# GridFS -```{image} ../_static/mongodb.png -``` - -[GridFS](https://docs.mongodb.com/manual/core/gridfs/) is a specification for storing large files -in MongoDB. - -## Use Cases -Use this backend if you are using MongoDB and expect to store responses **larger than 16MB**. See -{py:mod}`~requests_cache.backends.mongodb` for more general info. - -## API Reference -```{eval-rst} -.. automodsumm:: requests_cache.backends.gridfs - :classes-only: - :nosignatures: - -.. automodule:: requests_cache.backends.gridfs - :members: - :undoc-members: - :inherited-members: - :show-inheritance: -``` diff --git a/docs/conf.py b/docs/conf.py index 03f58f2..17fd900 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,7 +6,7 @@ Notes: * API reference docs are generated based on module docstrings * Google-style docstrings are used throughout the project * apidoc is used to generate source files for the majority of module docs -* The `api/` directory contains manually written docs for some modules +* The `api/` directory contains manually formatted sources for some modules * The `_templates` directory contains some Sphinx templates that modify auto-generated sources """ import os @@ -66,11 +66,10 @@ myst_enable_extensions = [ 'smartquotes', ] -# Ignore auto-generated pages for which manually written docs exist +# Ignore a subset of auto-generated pages exclude_patterns = [ '_build', f'{APIDOC_DIR.stem}/requests_cache.rst', - f'{APIDOC_DIR.stem}/requests_cache.backends.*.rst', f'{EXTRA_APIDOC_DIR.stem}/*', ] @@ -165,5 +164,6 @@ def patch_automodapi(app): def copy_module_docs(app): + """Copy manually written doc sources to apidoc directory""" for doc in EXTRA_APIDOC_DIR.iterdir(): copy(doc, APIDOC_DIR) diff --git a/docs/user_guide/backends.md b/docs/user_guide/backends.md index 2740af1..fa27ae9 100644 --- a/docs/user_guide/backends.md +++ b/docs/user_guide/backends.md @@ -1,41 +1,38 @@ (backends)= # {fa}`database` Backends -![](../_static/sqlite_32px.png) -![](../_static/redis_32px.png) -![](../_static/mongodb_32px.png) -![](../_static/dynamodb_32px.png) -![](../_static/files-json_32px.png) - This page contains general information about the cache backends supported by requests-cache. -See {py:mod}`.requests_cache.backends` for additional details on each individual backend. -The default backend is SQLite, since it's simple to use, requires no extra dependencies or -configuration, and has the best all-around performance for the majority of use cases. +The default backend is SQLite, since it requires no extra dependencies or configuration, and has +great all-around performance for the most common use cases. -```{note} -In environments where SQLite is explicitly disabled, a non-persistent in-memory cache is used by -default. -``` +Here is a full list of backends available, and any extra dependencies required: -## Backend Dependencies -Most of the other backends require some extra dependencies, listed below. +Backend | Class | Alias | Dependencies +------------------------------------------------------|----------------------------|----------------|---------------------------------------------------------- +![](../_static/sqlite_32px.png) {ref}`sqlite` | {py:class}`.SQLiteCache` | `'sqlite'` | +![](../_static/redis_32px.png) {ref}`redis` | {py:class}`.RedisCache` | `'redis'` | [redis-py](https://github.com/andymccurdy/redis-py) +![](../_static/mongodb_32px.png) {ref}`mongodb` | {py:class}`.MongoCache` | `'mongodb'` | [pymongo](https://github.com/mongodb/mongo-python-driver) +![](../_static/mongodb_32px.png) {ref}`gridfs` | {py:class}`.GridFSCache` | `'gridfs'` | [pymongo](https://github.com/mongodb/mongo-python-driver) +![](../_static/dynamodb_32px.png) {ref}`dynamodb` | {py:class}`.DynamoDbCache` | `'dynamodb'` | [boto3](https://github.com/boto/boto3) +![](../_static/files-json_32px.png) {ref}`filesystem` | {py:class}`.FileCache` | `'filesystem'` | +![](../_static/memory_32px.png) Memory | {py:class}`.BaseCache` | `'memory'` | -Backend | Class | Alias | Dependencies --------------------------------------------------------|----------------------------|----------------|------------- -[SQLite](https://www.sqlite.org) | {py:class}`.SQLiteCache` | `'sqlite'` | -[Redis](https://redis.io) | {py:class}`.RedisCache` | `'redis'` | [redis-py](https://github.com/andymccurdy/redis-py) -[MongoDB](https://www.mongodb.com) | {py:class}`.MongoCache` | `'mongodb'` | [pymongo](https://github.com/mongodb/mongo-python-driver) -[GridFS](https://docs.mongodb.com/manual/core/gridfs/) | {py:class}`.GridFSCache` | `'gridfs'` | [pymongo](https://github.com/mongodb/mongo-python-driver) -[DynamoDB](https://aws.amazon.com/dynamodb) | {py:class}`.DynamoDbCache` | `'dynamodb'` | [boto3](https://github.com/boto/boto3) -Filesystem | {py:class}`.FileCache` | `'filesystem'` | -Memory | {py:class}`.BaseCache` | `'memory'` | +<!-- Hidden ToC tree to add pages to sidebar ToC --> +```{toctree} +:hidden: +:glob: true + +backends/* +``` ## Choosing a Backend Here are some general notes on choosing a backend: * All of the backends perform well enough that they usually won't become a bottleneck until you - start hitting around **700-1000 requests per second**. -* It's recommended to start with SQLite until you have a specific reason to switch. -* If/when you outgrow SQLite, the next logical choice would usually be Redis. + start hitting around **700-1000 requests per second** +* It's recommended to start with SQLite until you have a specific reason to switch +* If/when you encounter limitations with SQLite, the next logical choice is usually Redis +* Each backend has some unique features that make them well suited for specific use cases; see + individual backend docs for more details Here are some specific situations where you may want to choose one of the other backends: * Your application is distributed across multiple machines, without access to a common filesystem @@ -46,9 +43,6 @@ Here are some specific situations where you may want to choose one of the other * You want to reuse your cached response data outside of requests-cache * You want to use a specific feature available in one of the other backends -Docs for {py:mod}`backend modules <requests_cache.backends>` contain more details on use cases -for each one. - ## Specifying a Backend You can specify which backend to use with the `backend` parameter for either {py:class}`.CachedSession` or {py:func}`.install_cache`. You can specify one by name, using the aliases listed above: @@ -56,7 +50,7 @@ or {py:func}`.install_cache`. You can specify one by name, using the aliases lis >>> session = CachedSession('my_cache', backend='redis') ``` -Or by instance: +Or by instance, which is preferable if you want to pass additional backend-specific options: ```python >>> backend = RedisCache(host='192.168.1.63', port=6379) >>> session = CachedSession('my_cache', backend=backend) @@ -74,10 +68,7 @@ DynamoDB | Table name Filesystem | Cache directory Each backend class also accepts optional parameters for the underlying connection. For example, -{py:class}`.SQLiteCache` accepts parameters for {py:func}`sqlite3.connect`: -```python ->>> session = CachedSession('my_cache', backend='sqlite', timeout=30) -``` +the {ref}`sqlite` backend accepts parameters for {py:func}`sqlite3.connect`. ## Testing Backends If you just want to quickly try out all of the available backends for comparison, diff --git a/docs/api/requests_cache.backends.dynamodb.md b/docs/user_guide/backends/dynamodb.md index a4fcb23..ebd2e01 100644 --- a/docs/api/requests_cache.backends.dynamodb.md +++ b/docs/user_guide/backends/dynamodb.md @@ -1,21 +1,41 @@ +(dynamodb)= # DynamoDB -```{image} ../_static/dynamodb.png +```{image} ../../_static/dynamodb.png ``` -[DynamoDB](https://aws.amazon.com/dynamodb) highly scalable NoSQL document database hosted on -[Amazon Web Services](https://aws.amazon.com). +[DynamoDB](https://aws.amazon.com/dynamodb) is a fully managed, highly scalable NoSQL document +database hosted on [Amazon Web Services](https://aws.amazon.com). ## Use Cases -In terms of features, DynamoDB is roughly comparable to MongoDB and other NoSQL databases. It is a -fully managed service, making it very convenient to use if you are already on AWS. It is an -especially good fit for serverless applications running on -[AWS Lambda](https://aws.amazon.com/lambda). +In terms of features, DynamoDB is roughly comparable to MongoDB and other NoSQL databases. Since +it's a managed service, no server setup or maintenance is required, and it's very convenient to use +if your application is already on AWS. It is an especially good fit for serverless applications +running on [AWS Lambda](https://aws.amazon.com/lambda). ```{warning} DynamoDB item sizes are limited to 400KB. If you need to cache larger responses, consider using a different backend. ``` +## Usage Example +Initialize with a {py:class}`.DynamoDbCache` instance: +```python +>>> from requests_cache import CachedSession, DynamoDbCache +>>> session = CachedSession(backend=DynamoDbCache()) +``` + +Or by alias: +```python +>>> session = CachedSession(backend='dynamodb') +``` + +## Connection Options +This backend accepts any keyword arguments for {py:meth}`boto3.session.Session.resource`: +```python +>>> backend = DynamoDbCache(region_name='us-west-2') +>>> session = CachedSession(backend=backend) +``` + ## Creating Tables Tables will be automatically created if they don't already exist. This is convienient if you just want to quickly test out DynamoDB as a cache backend, but in a production environment you will @@ -26,24 +46,3 @@ details you'll need: - Partition key (aka namespace): `namespace` - Range key (aka sort key): `key` - Attributes: `namespace` (string) and `key` (string) - -## Connection Options -The DynamoDB backend accepts any keyword arguments for {py:meth}`boto3.session.Session.resource`. -These can be passed via {py:class}`.DynamoDbCache`: -```python ->>> backend = DynamoDbCache(region_name='us-west-2') ->>> session = CachedSession('http_cache', backend=backend) -``` - -## API Reference -```{eval-rst} -.. automodsumm:: requests_cache.backends.dynamodb - :classes-only: - :nosignatures: - -.. automodule:: requests_cache.backends.dynamodb - :members: - :undoc-members: - :inherited-members: - :show-inheritance: -``` diff --git a/docs/api/requests_cache.backends.filesystem.md b/docs/user_guide/backends/filesystem.md index f1137b0..9fdee7c 100644 --- a/docs/api/requests_cache.backends.filesystem.md +++ b/docs/user_guide/backends/filesystem.md @@ -1,5 +1,6 @@ +(filesystem)= # Filesystem -```{image} ../_static/files-generic.png +```{image} ../../_static/files-generic.png ``` This backend stores responses in files on the local filesystem, with one file per response. @@ -12,6 +13,18 @@ for example: - Using cached responses as sample data for automated tests - Reading cached responses directly from another application or library, without depending on requests-cache +## Usage Example +Initialize with a {py:class}`.FileCache` instance: +```python +>>> from requests_cache import CachedSession, FileCache +>>> session = CachedSession(backend=FileCache()) +``` + +Or by alias: +```python +>>> session = CachedSession(backend='filesystem') +``` + ## File Formats By default, responses are saved as pickle files. If you want to save responses in a human-readable format, you can use one of the other available {ref}`serializers`. For example, to save responses as @@ -41,16 +54,3 @@ Or as YAML (requires `pyyaml`): - Write performance will vary based on the serializer used, in the range of roughly 1-3ms per write. - This backend stores response files in a single directory, and does not currently implement fan-out. This means that on most filesystems, storing a very large number of responses will result in reduced performance. - This backend currently uses a simple threading lock rather than a file lock system, so it is not an ideal choice for highly parallel applications. - -## API Reference -```{eval-rst} -.. automodsumm:: requests_cache.backends.filesystem - :classes-only: - :nosignatures: - -.. automodule:: requests_cache.backends.filesystem - :members: - :undoc-members: - :inherited-members: - :show-inheritance: -``` diff --git a/docs/user_guide/backends/gridfs.md b/docs/user_guide/backends/gridfs.md new file mode 100644 index 0000000..568d5b9 --- /dev/null +++ b/docs/user_guide/backends/gridfs.md @@ -0,0 +1,23 @@ +(gridfs)= +# GridFS +```{image} ../../_static/mongodb.png +``` + +[GridFS](https://docs.mongodb.com/manual/core/gridfs/) is a specification for storing large files +in MongoDB. + +## Use Cases +Use this backend if you are using MongoDB and expect to store responses **larger than 16MB**. See +{py:mod}`~requests_cache.backends.mongodb` for more general info. + +## Usage Example +Initialize with a {py:class}`.GridFSCache` instance: +```python +>>> from requests_cache import CachedSession, GridFSCache +>>> session = CachedSession(backend=GridFSCache()) +``` + +Or by alias: +```python +>>> session = CachedSession(backend='gridfs') +``` diff --git a/docs/api/requests_cache.backends.mongodb.md b/docs/user_guide/backends/mongodb.md index 5b643d9..11201b2 100644 --- a/docs/api/requests_cache.backends.mongodb.md +++ b/docs/user_guide/backends/mongodb.md @@ -1,5 +1,6 @@ +(mongodb)= # MongoDB -```{image} ../_static/mongodb.png +```{image} ../../_static/mongodb.png ``` [MongoDB](https://www.mongodb.com) is a NoSQL document database. It stores data in collections @@ -9,8 +10,27 @@ database. ## Use Cases MongoDB scales well and is a good option for larger applications. For raw caching performance, it is not quite as fast as {py:mod}`~requests_cache.backends.redis`, but may be preferable if you already -have an instance running, or if it has a specific feature you want to use. See below for some -relevant examples. +have an instance running, or if it has a specific feature you want to use. See sections below for +some relevant examples. + +## Usage Example +Initialize with a {py:class}`.MongoCache` instance: +```python +>>> from requests_cache import CachedSession, MongoCache +>>> session = CachedSession(backend=MongoCache()) +``` + +Or by alias: +```python +>>> session = CachedSession(backend='mongodb') +``` + +## Connection Options +This backend accepts any keyword arguments for {py:class}`pymongo.mongo_client.MongoClient`: +```python +>>> backend = MongoCache(host='192.168.1.63', port=27017) +>>> session = CachedSession('http_cache', backend=backend) +``` ## Viewing Responses Unlike most of the other backends, response data can be easily viewed via the @@ -26,7 +46,7 @@ Here is an example response viewed in :::{admonition} Screenshot :class: toggle -```{image} ../_static/mongodb_vscode.png +```{image} ../../_static/mongodb_vscode.png ``` ::: @@ -82,24 +102,3 @@ requests for some period of time: >>> backend.set_ttl(timedelta(days=7)) >>> session = CachedSession(backend=backend, expire_after=timedelta(days=1)) ``` - -## Connection Options -The MongoDB backend accepts any keyword arguments for {py:class}`pymongo.mongo_client.MongoClient`. -These can be passed via {py:class}`.MongoCache`: -```python ->>> backend = MongoCache(host='192.168.1.63', port=27017) ->>> session = CachedSession('http_cache', backend=backend) -``` - -## API Reference -```{eval-rst} -.. automodsumm:: requests_cache.backends.mongodb - :classes-only: - :nosignatures: - -.. automodule:: requests_cache.backends.mongodb - :members: - :undoc-members: - :inherited-members: - :show-inheritance: -``` diff --git a/docs/api/requests_cache.backends.redis.md b/docs/user_guide/backends/redis.md index 7e6f8a7..cfe1898 100644 --- a/docs/api/requests_cache.backends.redis.md +++ b/docs/user_guide/backends/redis.md @@ -1,5 +1,6 @@ +(redis)= # Redis -```{image} ../_static/redis.png +```{image} ../../_static/redis.png ``` [Redis](https://redis.io) is an in-memory data store with on-disk persistence. @@ -8,25 +9,20 @@ Redis offers a high-performace cache that scales exceptionally well, making it an ideal choice for larger applications, especially those that make a large volume of concurrent requests. -## Persistence -Redis operates on data in memory, and by default also persists data to snapshots on disk. This is -optimized for performance, with a minor risk of data loss, and is usually the best configuration -for a cache. If you need different behavior, the frequency and type of persistence can be customized -or disabled entirely. See [Redis Persistence](https://redis.io/topics/persistence) for details. - -## Expiration -Redis natively supports TTL on a per-key basis, and can automatically remove expired responses from -the cache. This will be set by by default, according to normal {ref}`expiration settings <expiration>`. +## Usage Example +Initialize your session with a {py:class}`.RedisCache` instance: +```python +>>> from requests_cache import CachedSession, RedisCache +>>> session = CachedSession(backend=RedisCache()) +``` -If you intend to reuse expired responses, e.g. with {ref}`conditional-requests` or `stale_if_error`, -you can disable this behavior with the `ttl` argument: +Or by alias: ```python ->>> backend = RedisCache(ttl=False) +>>> session = CachedSession(backend='redis') ``` ## Connection Options -The Redis backend accepts any keyword arguments for {py:class}`redis.client.Redis`. These can be -passed via {py:class}`.RedisCache`: +This backend accepts any keyword arguments for {py:class}`redis.client.Redis`: ```python >>> backend = RedisCache(host='192.168.1.63', port=6379) >>> session = CachedSession('http_cache', backend=backend) @@ -35,11 +31,28 @@ passed via {py:class}`.RedisCache`: Or you can pass an existing `Redis` object: ```python >>> from redis import Redis + >>> connection = Redis(host='192.168.1.63', port=6379) >>> backend = RedisCache(connection=connection)) >>> session = CachedSession('http_cache', backend=backend) ``` +## Persistence +Redis operates on data in memory, and by default also persists data to snapshots on disk. This is +optimized for performance, with a minor risk of data loss, and is usually the best configuration +for a cache. If you need different behavior, the frequency and type of persistence can be customized +or disabled entirely. See [Redis Persistence](https://redis.io/topics/persistence) for details. + +## Expiration +Redis natively supports TTL on a per-key basis, and can automatically remove expired responses from +the cache. This will be set by by default, according to normal {ref}`expiration settings <expiration>`. + +If you intend to reuse expired responses, e.g. with {ref}`conditional-requests` or `stale_if_error`, +you can disable this behavior with the `ttl` argument: +```python +>>> backend = RedisCache(ttl=False) +``` + ## Redislite If you can't easily set up your own Redis server, another option is [redislite](https://github.com/yahoo/redislite). It contains its own lightweight, embedded Redis @@ -51,16 +64,3 @@ database, and can be used as a drop-in replacement for redis-py. Usage example: >>> backend = RedisCache(connection=Redis()) >>> session = CachedSession(backend=backend) ``` - -## API Reference -```{eval-rst} -.. automodsumm:: requests_cache.backends.redis - :classes-only: - :nosignatures: - -.. automodule:: requests_cache.backends.redis - :members: - :undoc-members: - :inherited-members: - :show-inheritance: -``` diff --git a/docs/api/requests_cache.backends.sqlite.md b/docs/user_guide/backends/sqlite.md index eea2407..c4e0744 100644 --- a/docs/api/requests_cache.backends.sqlite.md +++ b/docs/user_guide/backends/sqlite.md @@ -1,15 +1,35 @@ +(sqlite)= # SQLite -```{image} ../_static/sqlite.png +```{image} ../../_static/sqlite.png ``` - [SQLite](https://www.sqlite.org/) is a fast and lightweight SQL database engine that stores data either in memory or in a single file on disk. ## Use Cases Despite its simplicity, SQLite is a powerful tool. For example, it's the primary storage system for -a number of common applications including Dropbox, Firefox, and Chrome. It's well suited for -caching, and requires no extra configuration or dependencies, which is why it's the default backend -for requests-cache. +a number of common applications including Firefox, Chrome, and many components of both Android and +iOS. It's well suited for caching, and requires no extra configuration or dependencies, which is why +it's 'used as the default backend for requests-cache. + +## Usage Example +SQLite is the default backend, but if you want to pass extra connection options or just want to be +explicit, initialize your session with a {py:class}`.SQLiteCache` instance: +```python +>>> from requests_cache import CachedSession, SQLiteCache +>>> session = CachedSession(backend=SQLiteCache()) +``` + +Or by alias: +```python +>>> session = CachedSession(backend='sqlite') +``` + +## Connection Options +This backend accepts any keyword arguments for {py:func}`sqlite3.connect`: +```python +>>> backend = SQLiteCache('http_cache', timeout=30) +>>> session = CachedSession(backend=backend) +``` ## Cache Files - See {ref}`files` for general info on specifying cache paths @@ -62,29 +82,3 @@ available: and some other AWS services use ephemeral storage that only persists for the lifetime of the instance. This is fine for short-term caching. For longer-term persistance, you can use an [attached EBS volume](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-attaching-volume.html). - -## Connection Options -The SQLite backend accepts any keyword arguments for {py:func}`sqlite3.connect`. These can be passed -via {py:class}`.CachedSession`: -```python ->>> session = CachedSession('http_cache', timeout=30) -``` - -Or via {py:class}`.SQLiteCache`: -```python ->>> backend = SQLiteCache('http_cache', timeout=30) ->>> session = CachedSession(backend=backend) -``` - -## API Reference -```{eval-rst} -.. automodsumm:: requests_cache.backends.sqlite - :classes-only: - :nosignatures: - -.. automodule:: requests_cache.backends.sqlite - :members: - :undoc-members: - :inherited-members: - :show-inheritance: -``` diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation.md index 174baf3..a5d4176 100644 --- a/docs/user_guide/installation.md +++ b/docs/user_guide/installation.md @@ -39,4 +39,4 @@ of python, here are the latest compatible versions and their documentation pages * **python 2.7:** [requests-cache 0.5.2](https://requests-cache.readthedocs.io/en/v0.5.0) * **python 3.4:** [requests-cache 0.5.2](https://requests-cache.readthedocs.io/en/v0.5.0) * **python 3.5:** [requests-cache 0.5.2](https://requests-cache.readthedocs.io/en/v0.5.0) -* **python 3.6:** [requests-cache 0.7.4](https://requests-cache.readthedocs.io/en/v0.7.4) +* **python 3.6:** [requests-cache 0.7.5](https://requests-cache.readthedocs.io/en/v0.7.5) diff --git a/requests_cache/backends/__init__.py b/requests_cache/backends/__init__.py index 4051d14..250be7e 100644 --- a/requests_cache/backends/__init__.py +++ b/requests_cache/backends/__init__.py @@ -73,6 +73,8 @@ def init_backend(cache_name: str, backend: BackendSpecifier = None, **kwargs) -> backend.cache_name = cache_name return backend # If no backend is specified, use SQLite as default, unless the environment doesn't support it + # TODO: Deprecate fallback to memory? + # Unsupported SQLite is a rare case, and should probably be handled by the user instead. elif not backend: sqlite_supported = issubclass(BACKEND_CLASSES['sqlite'], BaseCache) backend = 'sqlite' if sqlite_supported else 'memory' diff --git a/requests_cache/backends/dynamodb.py b/requests_cache/backends/dynamodb.py index 260a078..5f03523 100644 --- a/requests_cache/backends/dynamodb.py +++ b/requests_cache/backends/dynamodb.py @@ -1,3 +1,9 @@ +"""DynamoDB cache backend. For usage details, see :ref:`Backends: DynamoDB <dynamodb>`. + +.. automodsumm:: requests_cache.backends.dynamodb + :classes-only: + :nosignatures: +""" from typing import Dict, Iterable import boto3 @@ -10,7 +16,7 @@ from . import BaseCache, BaseStorage class DynamoDbCache(BaseCache): - """DynamoDB cache backend + """DynamoDB cache backend. Args: table_name: DynamoDB table name @@ -59,6 +65,7 @@ class DynamoDbDict(BaseStorage): self.connection = connection or boto3.resource('dynamodb', **connection_kwargs) self.namespace = namespace + # TODO: Create default table as on-demand instead of provisioned? try: self.connection.create_table( AttributeDefinitions=[ diff --git a/requests_cache/backends/filesystem.py b/requests_cache/backends/filesystem.py index 021204b..f633a22 100644 --- a/requests_cache/backends/filesystem.py +++ b/requests_cache/backends/filesystem.py @@ -1,3 +1,9 @@ +"""Filesystem cache backend. For usage details, see :ref:`Backends: Filesystem <filesystem>`. + +.. automodsumm:: requests_cache.backends.filesystem + :classes-only: + :nosignatures: +""" from contextlib import contextmanager from os import makedirs from pathlib import Path @@ -12,7 +18,7 @@ from .sqlite import AnyPath, SQLiteDict, get_cache_path class FileCache(BaseCache): - """Filesystem backend. + """Filesystem cache backend. Args: cache_name: Base directory for cache files diff --git a/requests_cache/backends/gridfs.py b/requests_cache/backends/gridfs.py index 0e0e5ee..20c2b06 100644 --- a/requests_cache/backends/gridfs.py +++ b/requests_cache/backends/gridfs.py @@ -1,3 +1,9 @@ +"""GridFS cache backend. For usage details, see :ref:`Backends: GridFS <gridfs>` and :ref:`Backends: MongoDB <mongodb>`. + +.. automodsumm:: requests_cache.backends.gridfs + :classes-only: + :nosignatures: +""" from logging import getLogger from threading import RLock @@ -15,10 +21,6 @@ logger = getLogger(__name__) class GridFSCache(BaseCache): """GridFS cache backend. - Example: - - >>> session = CachedSession('http_cache', backend='gridfs') - Args: db_name: Database name connection: :py:class:`pymongo.MongoClient` object to reuse instead of creating a new one diff --git a/requests_cache/backends/mongodb.py b/requests_cache/backends/mongodb.py index 2e3b116..9605988 100644 --- a/requests_cache/backends/mongodb.py +++ b/requests_cache/backends/mongodb.py @@ -1,3 +1,9 @@ +"""MongoDB cache backend. For usage details, see :ref:`Backends: MongoDB <mongodb>`. + +.. automodsumm:: requests_cache.backends.mongodb + :classes-only: + :nosignatures: +""" from datetime import timedelta from logging import getLogger from typing import Iterable, Mapping, Optional, Union @@ -14,7 +20,7 @@ logger = getLogger(__name__) class MongoCache(BaseCache): - """MongoDB cache backend + """MongoDB cache backend. Args: db_name: Database name diff --git a/requests_cache/backends/redis.py b/requests_cache/backends/redis.py index a5c0675..d79af35 100644 --- a/requests_cache/backends/redis.py +++ b/requests_cache/backends/redis.py @@ -1,3 +1,9 @@ +"""Redis cache backend. For usage details, see :ref:`Backends: Redis <redis>`. + +.. automodsumm:: requests_cache.backends.redis + :classes-only: + :nosignatures: +""" from logging import getLogger from typing import Iterable @@ -13,7 +19,7 @@ logger = getLogger(__name__) # TODO: TTL tests # TODO: Option to set a different (typically longer) TTL than expire_after, like MongoCache class RedisCache(BaseCache): - """Redis cache backend + """Redis cache backend. Args: namespace: Redis namespace diff --git a/requests_cache/backends/sqlite.py b/requests_cache/backends/sqlite.py index baff2f8..fa75848 100644 --- a/requests_cache/backends/sqlite.py +++ b/requests_cache/backends/sqlite.py @@ -1,3 +1,9 @@ +"""SQLite cache backend. For usage details, see :ref:`Backends: SQLite <sqlite>`. + +.. automodsumm:: requests_cache.backends.sqlite + :classes-only: + :nosignatures: +""" import sqlite3 import threading from contextlib import contextmanager |