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: boto3.session.Session | None = None,
    boto3_client: AppConfigDataClient | None = None,
)

Bases: BaseProvider

AWS App Config Provider

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

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:
    """
    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)

    # Only create the provider if this function is called at least once
    if "appconfig" not in DEFAULT_PROVIDERS:
        DEFAULT_PROVIDERS["appconfig"] = AppConfigProvider(environment=environment, application=application)

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