Metadata-Version: 2.1
Name: azure-appconfiguration
Version: 1.3.0
Summary: Microsoft App Configuration Data Library for Python
Home-page: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/appconfiguration/azure-appconfiguration
Author: Microsoft Corporation
Author-email: azpysdkhelp@microsoft.com
License: MIT License
Description: # Azure App Configuration client library for Python
        
        Azure App Configuration is a managed service that helps developers centralize their application configurations simply and securely.
        
        Modern programs, especially programs running in a cloud, generally have many components that are distributed in nature. Spreading configuration settings across these components can lead to hard-to-troubleshoot errors during an application deployment. Use App Configuration to securely store all the settings for your application in one place.
        
        Use the client library for App Configuration to create and manage application configuration settings.
        
        [Source code](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration) | [Package (Pypi)][package] | [API reference documentation](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration) | [Product documentation][appconfig_docs]
        
        ## Getting started
        
        ### Install the package
        
        Install the Azure App Configuration client library for Python with pip:
        
        ```commandline
        pip install azure-appconfiguration
        ```
        
        ### Prerequisites
        
        * Python 2.7, or 3.5 or later is required to use this package.
        * You need an [Azure subscription][azure_sub], and a [Configuration Store][configuration_store] to use this package.
        
        To create a Configuration Store, you can use the Azure Portal or [Azure CLI][azure_cli].
        
        After that, create the Configuration Store:
        
        ```Powershell
        az appconfig create --name <config-store-name> --resource-group <resource-group-name> --location eastus
        ```
        
        ### Authenticate the client
        
        In order to interact with the App Configuration service, you'll need to create an instance of the
        [AzureAppConfigurationClient][configuration_client_class] class. To make this possible,
        you can either use the connection string of the Configuration Store or use an AAD token.
        
        #### Use connection string
        
        ##### Get credentials
        
        Use the [Azure CLI][azure_cli] snippet below to get the connection string from the Configuration Store.
        
        ```Powershell
        az appconfig credential list --name <config-store-name>
        ```
        
        Alternatively, get the connection string from the Azure Portal.
        
        ##### Create client
        
        Once you have the value of the connection string, you can create the AzureAppConfigurationClient:
        
        ```python
        from azure.appconfiguration import AzureAppConfigurationClient
        
        connection_str = "<connection_string>"
        client = AzureAppConfigurationClient.from_connection_string(connection_str)
        ```
        
        #### Use AAD token
        
        Here we demonstrate using [DefaultAzureCredential][default_cred_ref]
        to authenticate as a service principal. However, [AzureAppConfigurationClient][configuration_client_class]
        accepts any [azure-identity][azure_identity] credential. See the
        [azure-identity][azure_identity] documentation for more information about other
        credentials.
        
        ##### Create a service principal (optional)
        This [Azure CLI][azure_cli] snippet shows how to create a
        new service principal. Before using it, replace "your-application-name" with
        the appropriate name for your service principal.
        
        Create a service principal:
        ```Bash
        az ad sp create-for-rbac --name http://my-application --skip-assignment
        ```
        
        > Output:
        > ```json
        > {
        >     "appId": "generated app id",
        >     "displayName": "my-application",
        >     "name": "http://my-application",
        >     "password": "random password",
        >     "tenant": "tenant id"
        > }
        > ```
        
        Use the output to set **AZURE_CLIENT_ID** ("appId" above), **AZURE_CLIENT_SECRET**
        ("password" above) and **AZURE_TENANT_ID** ("tenant" above) environment variables.
        The following example shows a way to do this in Bash:
        ```Bash
        export AZURE_CLIENT_ID="generated app id"
        export AZURE_CLIENT_SECRET="random password"
        export AZURE_TENANT_ID="tenant id"
        ```
        
        Assign one of the applicable [App Configuration roles](https://docs.microsoft.com/azure/azure-app-configuration/rest-api-authorization-azure-ad) to the service principal.
        
        ##### Create a client
        Once the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and
        **AZURE_TENANT_ID** environment variables are set,
        [DefaultAzureCredential][default_cred_ref] will be able to authenticate the
        [AzureAppConfigurationClient][configuration_client_class].
        
        Constructing the client also requires your configuration store's URL, which you can
        get from the Azure CLI or the Azure Portal. In the Azure Portal, the URL can be found listed as the service "Endpoint"
        
        ```python
        from azure.identity import DefaultAzureCredential
        from azure.appconfiguration import AzureAppConfigurationClient
        
        credential = DefaultAzureCredential()
        
        client = AzureAppConfigurationClient(base_url="your_endpoint_url", credential=credential)
        ```
        
        ## Key concepts
        
        ### Configuration Setting
        
        A Configuration Setting is the fundamental resource within a Configuration Store. In its simplest form it is a key and a value. However, there are additional properties such as the modifiable content type and tags fields that allow the value to be interpreted or associated in different ways.
        
        The Label property of a Configuration Setting provides a way to separate Configuration Settings into different dimensions. These dimensions are user defined and can take any form. Some common examples of dimensions to use for a label include regions, semantic versions, or environments. Many applications have a required set of configuration keys that have varying values as the application exists across different dimensions.
        For example, MaxRequests may be 100 in "NorthAmerica", and 200 in "WestEurope". By creating a Configuration Setting named MaxRequests with a label of "NorthAmerica" and another, only with a different value, in the "WestEurope" label, an application can seamlessly retrieve Configuration Settings as it runs in these two dimensions.
        
        Properties of a Configuration Setting:
        
        ```python
        key : str
        label : str
        content_type : str
        value : str
        last_modified : str
        read_only : bool
        tags : dict
        etag : str
        ```
        
        ## Examples
        
        The following sections provide several code snippets covering some of the most common Configuration Service tasks, including:
        
        * [Create a Configuration Setting](#create-a-configuration-setting)
        * [Get a Configuration Setting](#get-a-configuration-setting)
        * [Delete a Configuration Setting](#delete-a-configuration-setting)
        * [List Configuration Settings](#list-configuration-settings)
        * [Async APIs](#async-apis)
        
        ### Create a Configuration Setting
        
        Create a Configuration Setting to be stored in the Configuration Store.
        There are two ways to store a Configuration Setting:
        
        - add_configuration_setting creates a setting only if the setting does not already exist in the store.
        
        ```python
        config_setting = ConfigurationSetting(
            key="MyKey",
            label="MyLabel",
            value="my value",
            content_type="my content type",
            tags={"my tag": "my tag value"}
        )
        added_config_setting = client.add_configuration_setting(config_setting)
        ```
        
        - set_configuration_setting creates a setting if it doesn't exist or overrides an existing setting.
        
        ```python
        config_setting = ConfigurationSetting(
            key="MyKey",
            label="MyLabel",
            value="my set value",
            content_type="my set content type",
            tags={"my set tag": "my set tag value"}
        )
        returned_config_setting = client.set_configuration_setting(config_setting)
        ```
        
        ### Get a Configuration Setting
        
        Get a previously stored Configuration Setting.
        
        ```python
        fetched_config_setting = client.get_configuration_setting(
            key="MyKey", label="MyLabel"
        )
        ```
        
        ### Delete a Configuration Setting
        
        Delete an existing Configuration Setting.
        
        ```python
        deleted_config_setting = client.delete_configuration_setting(
            key="MyKey", label="MyLabel"
        )
        ```
        
        ### List Configuration Settings
        
        List all configuration settings filtered with label_filter and/or key_filter.
        
        ```python
        
        filtered_listed = client.list_configuration_settings(
            label_filter="My*", key_filter="My*"
        )
        for item in filtered_listed:
            pass  # do something
        
        ```
        
        ### Async APIs
        
        Async client is supported for python 3.5+.
        To use the async client library, import the AzureAppConfigurationClient from package azure.appconfiguration.aio instead of azure.appconfiguration
        
        ```python
        from azure.appconfiguration.aio import AzureAppConfigurationClient
        
        connection_str = "<connection_string>"
        async_client = AzureAppConfigurationClient.from_connection_string(connection_str)
        ```
        
        This async AzureAppConfigurationClient has the same method signatures as the sync ones except that they're async.
        For instance, to retrieve a Configuration Setting asynchronously, async_client can be used:
        
        ```python
        fetched_config_setting = await async_client.get_configuration_setting(
            key="MyKey", label="MyLabel"
        )
        ```
        
        To use list_configuration_settings, call it synchronously and iterate over the returned async iterator asynchronously
        
        ```python
        
        filtered_listed = async_client.list_configuration_settings(
            label_filter="My*", key_filter="My*"
        )
        async for item in filtered_listed:
            pass  # do something
        
        ```
        
        ## Troubleshooting
        
        ### Logging
        
        This SDK uses Python standard logging library.
        You can configure logging print out debugging information to the stdout or anywhere you want.
        
        ```python
        import logging
        
        logging.basicConfig(level=logging.DEBUG)
        ````
        
        Http request and response details are printed to stdout with this logging config.
        
        ## Next steps
        
        ### More sample code
        
        Several App Configuration client library samples are available to you in this GitHub repository.  These include:
        - [Hello world](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/samples/hello_world_sample.py) / [Async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/samples/hello_world_sample_async.py)
        - [Hello world with labels](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/samples/hello_world_advanced_sample.py) / [Async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/samples/hello_world_advanced_sample_async.py)
        - [Make a configuration setting readonly](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/samples/read_only_sample.py) / [Async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/samples/hello_world_sample_async.py)
        - [Read revision history](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/samples/list_revision_sample.py) / [Async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/samples/list_revision_sample_async.py)
        - [Get a setting if changed](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/samples/conditional_operation_sample.py) / [Async version](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/samples/conditional_operation_sample_async.py)
        
         For more details see the [samples README](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/samples/README.md).
        
        ## Contributing
        
        This project welcomes contributions and suggestions. Most contributions require
        you to agree to a Contributor License Agreement (CLA) declaring that you have
        the right to, and actually do, grant us the rights to use your contribution.
        For details, visit https://cla.microsoft.com.
        
        When you submit a pull request, a CLA-bot will automatically determine whether
        you need to provide a CLA and decorate the PR appropriately (e.g., label,
        comment). Simply follow the instructions provided by the bot. You will only
        need to do this once across all repos using our CLA.
        
        This project has adopted the
        [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information,
        see the Code of Conduct FAQ or contact opencode@microsoft.com with any
        additional questions or comments.
        
        <!-- LINKS -->
        [appconfig_docs]: https://docs.microsoft.com/azure/azure-app-configuration/
        [appconfig_rest]: https://github.com/Azure/AppConfiguration#rest-api-reference
        [azure_cli]: https://docs.microsoft.com/cli/azure
        [azure_sub]: https://azure.microsoft.com/free/
        [configuration_client_class]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appconfiguration/azure-appconfiguration/azure/appconfiguration/_azure_appconfiguration_client.py
        [package]: https://pypi.org/project/azure-appconfiguration/
        [configuration_store]: https://azure.microsoft.com/services/app-configuration/
        [default_cred_ref]: https://aka.ms/azsdk-python-identity-default-cred-ref
        [azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity
        [cla]: https://cla.microsoft.com
        [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
        [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
        [coc_contact]: mailto:opencode@microsoft.com
        
        
        # Release History
        
        ## 1.3.0 (2021-11-10)
        
        ### Bugs Fixed
        - Fix the issue that data was persisted according to an incorrect schema/in an incorrect format ([#20518](https://github.com/Azure/azure-sdk-for-python/issues/20518))
        
          `SecretReferenceConfigurationSetting` in 1.2.0 used "secret_uri" rather than "uri" as the schema keywords which 
          broken inter-operation of `SecretReferenceConfigurationSetting` between SDK and the portal. 
          
          Please:
          - Use 1.3.0+ for any `SecretReferenceConfigurationSetting` uses.
          - Call a get method for existing `SecretReferenceConfigurationSetting`s and set them back to correct the format.
        
        ## 1.2.0 (2021-07-06)
        ### Features Added
        * Adds `FeatureFlagConfigurationSetting` and `SecretReferenceConfigurationSetting` models
        * `AzureAppConfigurationClient` can now be used as a context manager.
        * Adds `update_sync_token` to update sync tokens from Event Grid notifications.
        
        ## 1.2.0b2 (2021-06-08)
        
        ### Features
        - Adds context manager functionality to the sync and async `AzureAppConfigurationClient`s.
        
        ### Fixes
        - Fixes a deserialization bug for `FeatureFlagConfigurationSetting` and `SecretReferenceConfigurationSetting`.
        
        ## 1.2.0b1 (2021-04-06)
        
        ### Features
        
        - Adds method `update_sync_token` to include sync tokens from EventGrid notifications.
        - Added `SecretReferenceConfigurationSetting` type to represent a configuration setting that references a KeyVault Secret.
        Added `FeatureFlagConfigurationSetting` type to represent a configuration setting that controls a feature flag.
        
        ## 1.1.1 (2020-10-05)
        
        ### Features
        
        - Improve error message if Connection string secret has incorrect padding    #14140
        
        ## 1.1.0 (2020-09-08)
        
        ### Features
        
        - Added match condition support for `set_read_only` method    #13276
        
        ## 1.0.1 (2020-08-10)
        
        ### Fixes
        
        - Doc & Sample fixes
        
        ## 1.0.0 (2020-01-06)
        
        ### Features
        
        - Add AAD auth support    #8924
        
        ### Breaking changes
        
        - List_configuration_settings & list_revisions now take string key/label filter instead of keys/labels list   #9066
        
        ## 1.0.0b6 (2019-12-03)
        
        ### Features
        
        - Add sync-token support    #8418
        
        ### Breaking changes
        
        - Combine set_read_only & clear_read_only to be set_read_only(True/False)   #8453
        
        ## 1.0.0b5 (2019-10-30)
        
        ### Breaking changes
        
        - etag and match_condition of delete_configuration_setting are now keyword argument only #8161
        
        ## 1.0.0b4 (2019-10-07)
        
        - Add conditional operation support
        - Add set_read_only and clear_read_only methods
        
        ## 1.0.0b3 (2019-09-09)
        
        - New azure app configuration
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: License :: OSI Approved :: MIT License
Description-Content-Type: text/markdown
Provides-Extra: async
