IOTX509RefreshableSessionRefreshableSession

class boto3_refresh_session.methods.iot.x509.IOTX509RefreshableSession

A boto3.session.Session object that automatically refreshes temporary credentials returned by the IoT Core credential provider.

Important

As of v7.2.0, boto3-refresh-session requires explicitly installing “iot” as an extra dependency in order to use IoT features, i.e. pip install boto3-refresh-session[iot].

Parameters:

endpointstr

The endpoint URL for the IoT Core credential provider. Must contain ‘.credentials.iot.’.

role_aliasstr

The IAM role alias to use when requesting temporary credentials.

certificatestr | bytes

The X.509 certificate to use when requesting temporary credentials. str represents the file path to the certificate, while bytes represents the actual certificate data.

thing_namestr, optional

The name of the IoT thing to use when requesting temporary credentials. Default is None.

private_keystr | bytes | None, optional

The private key to use when requesting temporary credentials. str represents the file path to the private key, while bytes represents the actual private key data. Optional only if pkcs11 is provided. Default is None.

pkcs11PKCS11 | Dict[str, Any], optional

The PKCS#11 library to use when requesting temporary credentials. If provided, private_key must be None.

castr | bytes | None, optional

The CA certificate to use when verifying the IoT Core endpoint. str represents the file path to the CA certificate, while bytes represents the actual CA certificate data. Default is None.

verify_peerbool = True, optional

Whether to verify the CA certificate when establishing the TLS connection. Default is True.

timeoutfloat | int | None = 10.0, optional

The timeout for the TLS connection in seconds. Default is 10.0.

duration_secondsint | None, optional

The duration for which the temporary credentials are valid, in seconds. Cannot exceed the value declared in the IAM policy. Default is None.

awscrt_log_levelawscrt.LogLevel | None, optional

The logging level for the AWS CRT library, e.g. awscrt.LogLevel.INFO. Default is None.

defer_refreshbool = True, optional

If True then temporary credentials are not automatically refreshed until they are explicitly needed. If False then temporary credentials refresh immediately upon expiration. It is highly recommended that you use True. Default is True.

advisory_timeoutint = 900, optional

USE THIS ARGUMENT WITH CAUTION!!!

Botocore will attempt to refresh credentials early according to this value (in seconds), but will continue using the existing credentials if refresh fails. Default is 15 minutes (900 seconds).

mandatory_timeoutint = 600, optional

USE THIS ARGUMENT WITH CAUTION!!!

Botocore requires a successful refresh before continuing. If refresh fails in this window (in seconds), API calls may fail. Default is 10 minutes (600 seconds).

Attributes

credentials

The current temporary AWS security credentials.

cache

(SessionCache) The client and resource cache used to store and retrieve cached clients.

Methods

client(*args, eviction_policy: EvictionPolicy, max_size: int, **kwargs) -> BaseClient	Creates a low-level service client by name.
get_identity() -> Identity	Returns metadata about the current caller identity.
mqtt(…) -> awscrt.mqtt.Connection	Establishes an MQTT connection using the specified parameters.
refreshable_credentials() -> TemporaryCredentials	Returns the current temporary AWS security credentials.
resource(*args, eviction_policy: EvictionPolicy, max_size: int, **kwargs) -> ServiceResource	Creates a low-level service resource by name.
whoami() -> Identity	Alias for get_identity.

Other Parameters:

**kwargsAny, optional

Optional keyword arguments for the boto3.session.Session object.

Notes

Gavin Adams at AWS was a major influence on this implementation. Thank you, Gavin!

get_identity() → Identity

Returns metadata about the current caller identity.

Returns:

Identity

Dict containing information about the current calleridentity.

mqtt(*, endpoint: str, client_id: str, transport: Literal['x509', 'ws'] = 'x509', certificate: str | bytes | None = None, private_key: str | bytes | None = None, ca: str | bytes | None = None, pkcs11: PKCS11 | Dict[str, Any] | None = None, region: str | None = None, keep_alive_secs: int = 60, clean_start: bool = True, port: int | None = None, use_alpn: bool = False) → Connection

Establishes an MQTT connection using the specified parameters.

Added in version 5.1.0.

Parameters:

endpoint: str

The MQTT endpoint to connect to.

client_id: str

The client ID to use for the MQTT connection.

transport: Transport

The transport protocol to use (e.g., “x509” or “ws”).

certificate: str | bytes | None, optional

The client certificate to use for the connection. Defaults to the session certificate.

private_key: str | bytes | None, optional

The private key to use for the connection. Defaults to the session private key.

ca: str | bytes | None, optional

The CA certificate to use for the connection. Defaults to the session CA certificate.

pkcs11: PKCS11 | Dict[str, Any] | None, optional

PKCS#11 configuration for hardware-backed keys. Defaults to the session PKCS#11 configuration.

region: str | None, optional

The AWS region to use for the connection. Defaults to the session region.

keep_alive_secs: int = 60, optional

The keep-alive interval for the MQTT connection. Default is 60 seconds.

clean_start: bool = True, optional

Whether to start a clean session. Default is True.

port: int | None, optional

The port to use for the MQTT connection. Default is 8883 if not using ALPN, otherwise 443.

use_alpn: bool = False, optional

Whether to use ALPN for the connection. Default is False.

Returns:

awscrt.mqtt.Connection

The established MQTT connection.

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

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 credentials: TemporaryCredentials

The current temporary AWS security credentials.

Alias for refreshable_credentials.

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.

refreshable_credentials() → TemporaryCredentials

Returns the current temporary AWS security credentials.

Returns:

TemporaryCredentials

Temporary AWS security credentials containing:

access_keystr

AWS access key identifier.

secret_keystr

AWS secret access key.

tokenstr

AWS session token.

expiry_timestr

Expiration timestamp in ISO 8601 format.

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

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

whoami() → Identity

Returns metadata about the current caller identity.

Added in version 7.2.15.

Note

This method is an alternative to get_identity().

Returns:

Identity

Dict containing current caller identity metadata.