AppConfig

AWS App Config configuration retrieval and caching utility

CLASS	DESCRIPTION
`AppConfigProvider`	AWS App Config Provider

FUNCTION	DESCRIPTION
`get_app_config`	Retrieve a configuration value from AWS App Config.

AppConfigProvider ¶

AppConfigProvider(environment: str, application: str | None = None, config: Config | None = None, boto_config: Config | None = None, boto3_session: Session | None = None, boto3_client: AppConfigDataClient | None = None)

Bases: BaseProvider

AWS App Config Provider

An expired or corrupted poll token starts a new configuration session and retries retrieval once. If the replacement token is expired or corrupted, retrieval raises GetParameterError and the next call can start a fresh session. Other service errors, including polling too early, retain the token and do not trigger session recovery. If reading the response body fails, retrieval raises GetParameterError and discards that configuration's token so the next retrieval can recover. Caching and transforms still apply, and recovery does not reset other configuration profiles.

PARAMETER DESCRIPTION

environment

Environment of the configuration to pass during client initialization

TYPE: str

application

Application of the configuration to pass during client initialization

TYPE: str | None DEFAULT: None

config

Botocore configuration to pass during client initialization

TYPE: Config | None DEFAULT: None

boto3_session

1	`Boto3 session to create a boto3_client from`

TYPE: Session DEFAULT: None

boto3_client

Boto3 AppConfigData Client to use, boto3_session will be ignored if both are provided

TYPE: AppConfigDataClient | None DEFAULT: None

Example

Retrieves the latest configuration value from App Config

>>> from aws_lambda_powertools.utilities import parameters
>>>
>>> appconf_provider = parameters.AppConfigProvider(environment="my_env", application="my_app")
>>>
>>> value : bytes = appconf_provider.get("my_conf")
>>>
>>> print(value)
My configuration value

Retrieves a configuration value from App Config in another AWS region

>>> from botocore.config import Config
>>> from aws_lambda_powertools.utilities import parameters
>>>
>>> config = Config(region_name="us-west-1")
>>> appconf_provider = parameters.AppConfigProvider(environment="my_env", application="my_app", config=config)
>>>
>>> value : bytes = appconf_provider.get("my_conf")
>>>
>>> print(value)
My configuration value

Source code in aws_lambda_powertools/utilities/parameters/appconfig.py

def __init__(
    self,
    environment: str,
    application: str | None = None,
    config: Config | None = None,
    boto_config: Config | None = None,
    boto3_session: boto3.session.Session | None = None,
    boto3_client: AppConfigDataClient | None = None,
):
    """
    Initialize the App Config client
    """

    super().__init__()

    if config:
        warnings.warn(
            message="The 'config' parameter is deprecated in V3 and will be removed in V4. "
            "Please use 'boto_config' instead.",
            category=PowertoolsDeprecationWarning,
            stacklevel=2,
        )

    if boto3_client is None:
        boto3_session = boto3_session or boto3.session.Session()
        boto3_client = boto3_session.client("appconfigdata", config=boto_config or config)

    self.client = boto3_client

    self.application = resolve_env_var_choice(
        choice=application,
        env=os.getenv(constants.SERVICE_NAME_ENV, "service_undefined"),
    )
    self.environment = environment
    self.current_version = ""

    self._next_token: dict[str, str] = {}  # nosec - token for get_latest_configuration executions
    # Dict to store the recently retrieved value for a specific configuration.
    self.last_returned_value: dict[str, bytes] = {}

    super().__init__(client=self.client)

get_app_config ¶

get_app_config(name: str, environment: str, application: str | None = None, transform: TransformOptions = None, force_fetch: bool = False, max_age: int | None = None, **sdk_options) -> str | bytes | list | dict | None

Retrieve a configuration value from AWS App Config.

PARAMETER	DESCRIPTION
`name`	Name of the configuration TYPE: `str`
`environment`	Environment of the configuration TYPE: `str`
`application`	Application of the configuration TYPE: `str \| None` DEFAULT: `None`
`transform`	Transforms the content from a JSON object ('json') or base64 binary string ('binary') TYPE: `TransformOptions` DEFAULT: `None`
`force_fetch`	Force update even before a cached item has expired, defaults to False TYPE: `bool` DEFAULT: `False`
`max_age`	Maximum age of the cached value TYPE: `int \| None` DEFAULT: `None`
`sdk_options`	SDK options to propagate to `start_configuration_session` API call DEFAULT: `{}`

RAISES	DESCRIPTION
`GetParameterError`	When the parameter provider fails to retrieve a parameter value for a given name.
`TransformParameterError`	When the parameter provider fails to transform a parameter value.

Example

Retrieves the latest version of configuration value from App Config

>>> from aws_lambda_powertools.utilities.parameters import get_app_config
>>>
>>> value = get_app_config("my_config", environment="my_env", application="my_env")
>>>
>>> print(value)
My configuration value

Retrieves a configuration value and decodes it using a JSON decoder

>>> from aws_lambda_powertools.utilities.parameters import get_app_config
>>>
>>> value = get_app_config("my_config", environment="my_env", application="my_env", transform='json')
>>>
>>> print(value)
My configuration's JSON value

Source code in aws_lambda_powertools/utilities/parameters/appconfig.py

def get_app_config(
    name: str,
    environment: str,
    application: str | None = None,
    transform: TransformOptions = None,
    force_fetch: bool = False,
    max_age: int | None = None,
    **sdk_options,
) -> str | bytes | list | dict | None:
    """
    Retrieve a configuration value from AWS App Config.

    Parameters
    ----------
    name: str
        Name of the configuration
    environment: str
        Environment of the configuration
    application: str
        Application of the configuration
    transform: str, optional
        Transforms the content from a JSON object ('json') or base64 binary string ('binary')
    force_fetch: bool, optional
        Force update even before a cached item has expired, defaults to False
    max_age: int, optional
        Maximum age of the cached value
    sdk_options: dict, optional
        SDK options to propagate to `start_configuration_session` API call

    Raises
    ------
    GetParameterError
        When the parameter provider fails to retrieve a parameter value for
        a given name.
    TransformParameterError
        When the parameter provider fails to transform a parameter value.

    Example
    -------
    **Retrieves the latest version of configuration value from App Config**

        >>> from aws_lambda_powertools.utilities.parameters import get_app_config
        >>>
        >>> value = get_app_config("my_config", environment="my_env", application="my_env")
        >>>
        >>> print(value)
        My configuration value

    **Retrieves a configuration value and decodes it using a JSON decoder**

        >>> from aws_lambda_powertools.utilities.parameters import get_app_config
        >>>
        >>> value = get_app_config("my_config", environment="my_env", application="my_env", transform='json')
        >>>
        >>> print(value)
        My configuration's JSON value
    """
    # If max_age is not set, resolve it from the environment variable, defaulting to DEFAULT_MAX_AGE_SECS
    max_age = resolve_max_age(env=os.getenv(constants.PARAMETERS_MAX_AGE_ENV, DEFAULT_MAX_AGE_SECS), choice=max_age)

    # One provider per environment/application pair, created on first use
    provider_key = f"appconfig:{environment}:{application}"
    if provider_key not in DEFAULT_PROVIDERS:
        DEFAULT_PROVIDERS[provider_key] = AppConfigProvider(environment=environment, application=application)

    return DEFAULT_PROVIDERS[provider_key].get(
        name,
        max_age=max_age,
        transform=transform,
        force_fetch=force_fetch,
        **sdk_options,
    )