boto3_client_cache.session

High-level API which provides a subclass of boto3.session.Session that implements automatic caching for clients and resources. It also provides functions to set up the default session with caching capabilities.

Examples

Probably the easiest way to use this library is by using client:

>>> from boto3_client_cache import client
>>> s3_client = client("s3")
>>> s3_client_again = client("s3")
>>> assert s3_client is s3_client_again  # True, since the client is cached

You can create a session by instantiating the Session class:

>>> from boto3_client_cache import Session
>>> session = Session(region_name="us-east-1")
>>> s3_client = session.client("s3")
>>> s3_client_again = session.client("s3")
>>> assert s3_client is s3_client_again  # True, since the client is cached

You can also set a default session:

>>> from boto3_client_cache import client, setup_default_session
>>> setup_default_session(region_name="us-east-1")
>>> s3_client = client("s3")
>>> s3_client_again = client("s3")
>>> assert s3_client is s3_client_again  # True, since the client is cached

Functions

client(*args[, eviction_policy, max_size])	Returns a cached client from the default session if it exists, otherwise creates a new client and caches it.
resource(*args[, eviction_policy, max_size])	Returns a cached resource from the default session if it exists, otherwise creates a new resource and caches it.
setup_default_session(**kwargs)	Sets up the default session with caching capabilities.

Classes

Session	A subclass of boto3.session.Session which implements automatic caching for clients and resources.
SessionCache	Class representing the cache for a session, which contains separate client and resource caches for different eviction policies.
SessionClientCache	Class representing the client cache for a session, which contains separate caches for different eviction policies (LRU and LFU).
SessionResourceCache	Class representing the resource cache for a session, which contains separate caches for different eviction policies (LRU and LFU).

class boto3_client_cache.session.Session

A subclass of boto3.session.Session which implements automatic caching for clients and resources.

Added in version 2.1.0.

Parameters:

*args

Positional arguments to be passed to the parent class. Refer to the boto3.session.Session documentation for more details on accepted arguments.

**kwargs

Keyword arguments to be passed to the parent class. Refer to the boto3.session.Session documentation for more details on accepted arguments.

Attributes

cache

(CacheTypedDict) A dictionary containing the client and resource caches for different eviction policies.

Methods

client(*args, eviction_policy: EvictionPolicy, max_size: int, **kwargs) -> BaseClient	Returns a cached client if it exists, otherwise creates a new client and caches it.
resource(*args, eviction_policy: EvictionPolicy, max_size: int, **kwargs) -> ServiceResource	Returns a cached resource if it exists, otherwise creates a new resource and caches it.

Notes

Important

The cache is not globally shared across all sessions. Each session maintains its own cache, so modifications to the cache in one session will not affect other sessions. To manage a cache across multiple sessions, use the low-level API instead (i.e. boto3_client_cache.cache.ResourceCache and boto3_client_cache.cache.ClientCache) in tandem with boto3.

Important

Calls to Session.client and Session.resource on the same session instance are serialized by a lock to ensure thread safety when accessing the cache. If you need higher concurrency, use multiple session instances or use the low-level API instead (i.e. boto3_client_cache.cache.ResourceCache and boto3_client_cache.cache.ClientCache) in tandem with boto3.

Examples

Initialize a session and initialize a client, which will be added to the LRU cache, and ensure duplicate clients are not created.

>>> from boto3_client_cache import Session
>>> session = Session(region_name="us-east-1")
>>> s3_client = session.client("s3")
>>> s3_client_again = session.client("s3")
>>> s3_client is s3_client_again
True

Initialize a session and initialize a resource, which will be added to the LFU cache with a max size of 20, and ensure duplicate resources are not created.

>>> from boto3_client_cache import Session
>>> session = Session(region_name="us-east-1")
>>> s3_resource = session.resource("s3", eviction_policy="LFU", max_size=20)
>>> s3_resource_again = session.resource("s3", eviction_policy="LFU", max_size=20)
>>> s3_resource is s3_resource_again
True

Inspect the LRU cache directly.

>>> from boto3_client_cache import Session
>>> session = Session(region_name="us-east-1")
>>> session.client("s3")
>>> print(session.cache["client"]["LRU"])
ClientCache:
- Session.client('s3')

property available_profiles

The profiles available to the session credentials

client(*args, eviction_policy: Literal['LRU', 'LFU'] | None = None, max_size: int | None = None, **kwargs) → BaseClient

Returns a cached client from the default session if it exists, otherwise creates a new client and caches it.

Added in version 2.1.0.

Parameters:

eviction_policyEvictionPolicy, optional

The type of cache to create. Case sensitive. Options are “LRU” and “LFU”. Defaults to “LRU”.

max_sizeint | None, optional

The maximum size of the client cache. If None, the cache size is left unchanged. New caches default to a max size of 10. Beware that modifying this value after the cache has already been initialized may evict existing clients. Default is None.

*args

Positional arguments to be passed to the default session’s client method. Check boto3.session.Session.client() for more details on accepted arguments.

**kwargs

Keyword arguments to be passed to the default session’s client method. Check boto3.session.Session.client() for more details on accepted arguments.

Returns:

BaseClient

A cached client if it exists, otherwise a new client that has been cached.

Raises:

ClientCacheError

Raised when an error occurs related to cache operations, such as using an invalid key, eviction policy, or value type.

ClientCacheExistsError

Raised when attempting to add a client which already exists in the cache.

ClientCacheNotFoundError

Raised when attempting to retrieve or delete a client which does not exist in the cache.

Notes

Important

Calls to this method are serialized by a lock to ensure thread safety when accessing the cache. If you need higher concurrency, use multiple session instances or use the low-level API instead (i.e. boto3_client_cache.cache.ResourceCache and boto3_client_cache.cache.ClientCache) in tandem with boto3.

Examples

>>> from boto3_client_cache import client
>>> s3_client = client("s3", region_name="us-east-1")
>>> s3_client_again = client("s3", region_name="us-east-1")
>>> s3_client is s3_client_again
True

property events

The event emitter for a session

get_available_partitions()

Lists the available partitions

Return type:

list

Returns:

Returns a list of partition names (e.g., [“aws”, “aws-cn”])

get_available_regions(service_name, partition_name='aws', allow_non_regional=False)

Lists the region and endpoint names of a particular partition.

The list of regions returned by this method are regions that are explicitly known by the client to exist and is not comprehensive. A region not returned in this list may still be available for the provided service.

Parameters:

• service_name (string) – Name of a service to list endpoint for (e.g., s3).

• partition_name (string) – Name of the partition to limit endpoints to. (e.g., aws for the public AWS endpoints, aws-cn for AWS China endpoints, aws-us-gov for AWS GovCloud (US) Endpoints, etc.)

• allow_non_regional (bool) – Set to True to include endpoints that are not regional endpoints (e.g., s3-external-1, fips-us-gov-west-1, etc).

Returns:

Returns a list of endpoint names (e.g., [“us-east-1”]).

get_available_resources()

Get a list of available services that can be loaded as resource clients via Session.resource().

Return type:

list

Returns:

List of service names

get_available_services()

Get a list of available services that can be loaded as low-level clients via Session.client().

Return type:

list

Returns:

List of service names

get_credentials()

Return the botocore.credentials.Credentials object associated with this session. If the credentials have not yet been loaded, this will attempt to load them. If they have already been loaded, this will return the cached credentials.

get_partition_for_region(region_name)

Lists the partition name of a particular region.

Parameters:

region_name (string) – Name of the region to list partition for (e.g., us-east-1).

Return type:

string

Returns:

Returns the respective partition name (e.g., aws).

property profile_name

The read-only profile name.

property region_name

The read-only region name.

resource(*args, eviction_policy: Literal['LRU', 'LFU'] | None = None, max_size: int | None = None, **kwargs) → ServiceResource

Returns a cached resource from the default session if it exists, otherwise creates a new resource and caches it.

Added in version 2.1.0.

Parameters:

eviction_policyEvictionPolicy, optional

The type of cache to create. Case sensitive. Options are “LRU” and “LFU”. Defaults to “LRU”.

max_sizeint | None, optional

The maximum size of the resource cache. If None, the cache size is left unchanged. New caches default to a max size of 10. Beware that modifying this value after the cache has already been initialized may evict existing resources. Default is None.

*args

Positional arguments to be passed to the default session’s resource method. Check boto3.session.Session.resource() for more details on accepted arguments.

**kwargs

Keyword arguments to be passed to the default session’s resource method. Check boto3.session.Session.resource() for more details on accepted arguments.

Returns:

ServiceResource

A cached resource if it exists, otherwise a new resource that has been cached.

Raises:

ResourceCacheError

Raised when an error occurs related to cache operations, such as using an invalid key, eviction policy, or value type.

ResourceCacheExistsError

Raised when attempting to add a resource which already exists in the cache.

ResourceCacheNotFoundError

Raised when attempting to retrieve or delete a resource which does not exist in the cache.

Notes

Tip

For correct typing, you may want to import mypy-boto3-* and use the generated type annotations for casting clients, which will be compatible with this method.

Important

Calls to this method are serialized by a lock to ensure thread safety when accessing the cache. If you need higher concurrency, use multiple session instances or use the low-level API instead (i.e. boto3_client_cache.cache.ResourceCache and boto3_client_cache.cache.ClientCache) in tandem with boto3.

Examples

>>> from boto3_client_cache import resource
>>> s3_resource = resource("s3", region_name="us-east-1")
>>> s3_resource_again = resource("s3", region_name="us-east-1")
>>> s3_resource is s3_resource_again
True

class boto3_client_cache.session.SessionCache

Class representing the cache for a session, which contains separate client and resource caches for different eviction policies.

Added in version 2.1.0.

class boto3_client_cache.session.SessionClientCache

Class representing the client cache for a session, which contains separate caches for different eviction policies (LRU and LFU).

Added in version 2.1.0.

class boto3_client_cache.session.SessionResourceCache

Class representing the resource cache for a session, which contains separate caches for different eviction policies (LRU and LFU).

Added in version 2.1.0.

boto3_client_cache.session.client(*args, eviction_policy: Literal['LRU', 'LFU'] | None = None, max_size: int | None = None, **kwargs) → BaseClient

Returns a cached client from the default session if it exists, otherwise creates a new client and caches it.

Added in version 2.1.0.

Parameters:

eviction_policyEvictionPolicy, optional

The type of cache to create. Case sensitive. Options are “LRU” and “LFU”. Defaults to “LRU”.

max_sizeint | None, optional

The maximum size of the client cache. If None, the cache size is left unchanged. New caches default to a max size of 10. Beware that modifying this value after the cache has already been initialized may evict existing clients. Default is None.

*args

Positional arguments to be passed to the default session’s client method. Check boto3.session.Session.client() for more details on accepted arguments.

**kwargs

Keyword arguments to be passed to the default session’s client method. Check boto3.session.Session.client() for more details on accepted arguments.

Returns:

BaseClient

A cached client if it exists, otherwise a new client that has been cached.

Raises:

ClientCacheError

Raised when an error occurs related to cache operations, such as using an invalid key, eviction policy, or value type.

ClientCacheExistsError

Raised when attempting to add a client which already exists in the cache.

ClientCacheNotFoundError

Raised when attempting to retrieve or delete a client which does not exist in the cache.

Notes

Important

Calls to this method are serialized by a lock to ensure thread safety when accessing the cache. If you need higher concurrency, use multiple session instances or use the low-level API instead (i.e. boto3_client_cache.cache.ResourceCache and boto3_client_cache.cache.ClientCache) in tandem with boto3.

Examples

>>> from boto3_client_cache import client
>>> s3_client = client("s3", region_name="us-east-1")
>>> s3_client_again = client("s3", region_name="us-east-1")
>>> s3_client is s3_client_again
True

boto3_client_cache.session.resource(*args, eviction_policy: Literal['LRU', 'LFU'] | None = None, max_size: int | None = None, **kwargs) → ServiceResource

Returns a cached resource from the default session if it exists, otherwise creates a new resource and caches it.

Added in version 2.1.0.

Parameters:

eviction_policyEvictionPolicy, optional

The type of cache to create. Case sensitive. Options are “LRU” and “LFU”. Defaults to “LRU”.

max_sizeint | None, optional

The maximum size of the resource cache. If None, the cache size is left unchanged. New caches default to a max size of 10. Beware that modifying this value after the cache has already been initialized may evict existing resources. Default is None.

*args

Positional arguments to be passed to the default session’s resource method. Check boto3.session.Session.resource() for more details on accepted arguments.

**kwargs

Keyword arguments to be passed to the default session’s resource method. Check boto3.session.Session.resource() for more details on accepted arguments.

Returns:

ServiceResource

A cached resource if it exists, otherwise a new resource that has been cached.

Raises:

ResourceCacheError

Raised when an error occurs related to cache operations, such as using an invalid key, eviction policy, or value type.

ResourceCacheExistsError

Raised when attempting to add a resource which already exists in the cache.

ResourceCacheNotFoundError

Raised when attempting to retrieve or delete a resource which does not exist in the cache.

Notes

Tip

For correct typing, you may want to import mypy-boto3-* and use the generated type annotations for casting clients, which will be compatible with this method.

Important

Calls to this method are serialized by a lock to ensure thread safety when accessing the cache. If you need higher concurrency, use multiple session instances or use the low-level API instead (i.e. boto3_client_cache.cache.ResourceCache and boto3_client_cache.cache.ClientCache) in tandem with boto3.

Examples

>>> from boto3_client_cache import resource
>>> s3_resource = resource("s3", region_name="us-east-1")
>>> s3_resource_again = resource("s3", region_name="us-east-1")
>>> s3_resource is s3_resource_again
True

boto3_client_cache.session.setup_default_session(**kwargs) → Session

Sets up the default session with caching capabilities.

Added in version 2.1.0.

Parameters:

**kwargs

Keyword arguments to be passed to the default session.

Returns:

Session

The default session with caching capabilities.