Skip to content

AppConfig

Advanced feature flags utility

Usage Documentation

Feature Flags

CLASS DESCRIPTION
AppConfigExtensionStore

Feature flags store that reads from the AWS AppConfig Agent Lambda extension.

AppConfigStore

AppConfigExtensionStore

AppConfigExtensionStore(environment: str, application: str, name: str, max_age: int = 5, envelope: str | None = '', jmespath_options: dict | None = None, logger: Logger | Logger | None = None)

Bases: AppConfigStore

Feature flags store that reads from the AWS AppConfig Agent Lambda extension.

Same behaviour as AppConfigStore(use_extension=True): configuration is read from the extension's local HTTP endpoint instead of calling AppConfig with boto3, so there are no boto3 options to configure. Requires the AWS-AppConfig-Extension layer.

PARAMETER DESCRIPTION
environment

AppConfig environment, e.g. 'dev'

TYPE: str

application

AppConfig application name, e.g. 'powertools'

TYPE: str

name

AppConfig configuration name, e.g. 'features'

TYPE: str

max_age

Seconds to keep the configuration in Powertools' cache before reading the extension again. The extension keeps its own cache and refreshes it in the background; use 0 to read it on every call.

TYPE: int DEFAULT: 5

envelope

JMESPath expression to pluck feature flags data from the configuration

TYPE: str | None DEFAULT: ''

jmespath_options

Alternative JMESPath options to be included when filtering expr

TYPE: dict | None DEFAULT: None

logger

Used to log messages. If None is supplied, one will be created.

TYPE: Logger | Logger | None DEFAULT: None

Example

from aws_lambda_powertools.utilities.feature_flags import AppConfigExtensionStore, FeatureFlags

store = AppConfigExtensionStore(environment="dev", application="product-catalogue", name="features") feature_flags = FeatureFlags(store=store)

Source code in aws_lambda_powertools/utilities/feature_flags/appconfig.py
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
def __init__(
    self,
    environment: str,
    application: str,
    name: str,
    max_age: int = 5,
    envelope: str | None = "",
    jmespath_options: dict | None = None,
    logger: logging.Logger | Logger | None = None,
):
    super().__init__(
        environment=environment,
        application=application,
        name=name,
        max_age=max_age,
        envelope=envelope,
        jmespath_options=jmespath_options,
        logger=logger,
        use_extension=True,
    )

AppConfigStore

AppConfigStore(environment: str, application: str, name: str, max_age: int = 5, sdk_config: Config | None = None, envelope: str | None = '', jmespath_options: dict | None = None, logger: Logger | Logger | None = None, boto_config: Config | None = None, boto3_session: Session | None = None, boto3_client: AppConfigDataClient | None = None, use_extension: bool = False)

Bases: StoreProvider

PARAMETER DESCRIPTION
environment

Appconfig environment, e.g. 'dev/test' etc.

TYPE: str

application

AppConfig application name, e.g. 'powertools'

TYPE: str

name

AppConfig configuration name e.g. my_conf

TYPE: str

max_age

cache expiration time in seconds, or how often to call AppConfig to fetch latest configuration

TYPE: int DEFAULT: 5

sdk_config

Botocore Config object to pass during client initialization

TYPE: Config | None DEFAULT: None

envelope

JMESPath expression to pluck feature flags data from config

TYPE: str | None DEFAULT: ''

jmespath_options

Alternative JMESPath options to be included when filtering expr

TYPE: dict | None DEFAULT: None

logger

Used to log messages. If None is supplied, one will be created.

TYPE: Logger | Logger | None DEFAULT: None

boto_config

Botocore configuration to pass during client initialization

TYPE: Config | None DEFAULT: None

boto3_session

Boto3 session to use for AWS API communication

TYPE: Session DEFAULT: None

boto3_client

Boto3 AppConfigDataClient Client to use, boto3_session and boto_config will be ignored if both are provided

TYPE: AppConfigDataClient DEFAULT: None

use_extension

Fetch the configuration from the AWS AppConfig Agent Lambda extension on localhost instead of calling AppConfig with boto3. Requires the AWS-AppConfig-Extension layer. boto3 options are ignored.

TYPE: bool DEFAULT: False

METHOD DESCRIPTION
get_configuration

Fetch feature schema configuration from AWS AppConfig

ATTRIBUTE DESCRIPTION
get_raw_configuration

Fetch feature schema configuration from AWS AppConfig

TYPE: dict[str, Any]

Source code in aws_lambda_powertools/utilities/feature_flags/appconfig.py
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def __init__(
    self,
    environment: str,
    application: str,
    name: str,
    max_age: int = 5,
    sdk_config: Config | None = None,
    envelope: str | None = "",
    jmespath_options: dict | None = None,
    logger: logging.Logger | Logger | None = None,
    boto_config: Config | None = None,
    boto3_session: boto3.session.Session | None = None,
    boto3_client: AppConfigDataClient | None = None,
    use_extension: bool = False,
):
    """This class fetches JSON schemas from AWS AppConfig

    Parameters
    ----------
    environment: str
        Appconfig environment, e.g. 'dev/test' etc.
    application: str
        AppConfig application name, e.g. 'powertools'
    name: str
        AppConfig configuration name e.g. `my_conf`
    max_age: int
        cache expiration time in seconds, or how often to call AppConfig to fetch latest configuration
    sdk_config: Config | None
        Botocore Config object to pass during client initialization
    envelope : str | None
        JMESPath expression to pluck feature flags data from config
    jmespath_options : dict | None
        Alternative JMESPath options to be included when filtering expr
    logger: A logging object
        Used to log messages. If None is supplied, one will be created.
    boto_config: botocore.config.Config, optional
        Botocore configuration to pass during client initialization
    boto3_session : boto3.Session, optional
        Boto3 session to use for AWS API communication
    boto3_client : AppConfigDataClient, optional
        Boto3 AppConfigDataClient Client to use, boto3_session and boto_config will be ignored if both are provided
    use_extension : bool
        Fetch the configuration from the AWS AppConfig Agent Lambda extension on localhost instead of
        calling AppConfig with boto3. Requires the AWS-AppConfig-Extension layer. boto3 options are ignored.
    """
    super().__init__()
    self.logger = logger or logging.getLogger(__name__)
    self.environment = environment
    self.application = application
    self.name = name
    self.cache_seconds = max_age
    self.config = sdk_config or boto_config
    self.envelope = envelope
    self.jmespath_options = jmespath_options
    self._conf_store: BaseProvider
    if use_extension:
        self._conf_store = AppConfigExtensionProvider(environment=environment, application=application)
    else:
        self._conf_store = AppConfigProvider(
            environment=environment,
            application=application,
            config=sdk_config or boto_config,
            boto3_client=boto3_client,
            boto3_session=boto3_session,
        )
    # Memoised envelope extraction: (raw document, extracted config). The Parameters cache hands back the
    # same raw dict until expiry, so we can reuse the extracted result rather than re-running the JMESPath
    # query and producing a new object on every call.
    self._last_extracted: tuple[dict[str, Any], dict[str, Any]] | None = None

    # Override the user agent to use "feature_flags" instead of "parameters"
    self._register_feature_flags_user_agent()

get_raw_configuration property

get_raw_configuration: dict[str, Any]

Fetch feature schema configuration from AWS AppConfig

get_configuration

get_configuration() -> dict[str, Any]

Fetch feature schema configuration from AWS AppConfig

If envelope is set, it'll extract and return feature flags from configuration, otherwise it'll return the entire configuration fetched from AWS AppConfig.

RAISES DESCRIPTION
ConfigurationStoreError

Any validation error or AppConfig error that can occur

RETURNS DESCRIPTION
dict[str, Any]

parsed JSON dictionary

Source code in aws_lambda_powertools/utilities/feature_flags/appconfig.py
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def get_configuration(self) -> dict[str, Any]:
    """Fetch feature schema configuration from AWS AppConfig

    If envelope is set, it'll extract and return feature flags from configuration,
    otherwise it'll return the entire configuration fetched from AWS AppConfig.

    Raises
    ------
    ConfigurationStoreError
        Any validation error or AppConfig error that can occur

    Returns
    -------
    dict[str, Any]
        parsed JSON dictionary
    """
    config = self.get_raw_configuration

    if self.envelope:
        if self._last_extracted is not None and self._last_extracted[0] is config:
            self.logger.debug("Envelope enabled; reusing previously extracted config for cached document")
            return self._last_extracted[1]

        self.logger.debug("Envelope enabled; extracting data from config", extra={"envelope": self.envelope})
        extracted = jmespath_utils.query(
            data=config,
            envelope=self.envelope,
            jmespath_options=self.jmespath_options,
        )
        self._last_extracted = (config, extracted)
        return extracted

    return config