wr-profiles 4.2.1

配置文件

配置文件 表示由环境变量支持的单一服务的可配置 属性 集合。

在您的应用程序中，可以存在多个无关的配置文件，每个配置文件都提供了访问不同服务属性的接口。

与同一服务关联的配置文件实例共享相同的基类，并由在该基类中指定的 profile_root 来识别。这是所有相关环境变量名称形成的根。

不同服务的配置文件不共享任何信息。在下文讨论中，不同的配置文件实例或种类都与同一服务相关，例如，相同的 profile_root。

from wr_profiles import envvar_profile_cls

@envvar_profile_cls
class WarehouseProfile:
    host: str = "localhost"
    username: str
    password: str

warehouse_profile = WarehouseProfile()

配置文件名称

配置文件的个别实例通过其名称（profile_name 属性）来识别。

活动配置文件

活动配置文件 是根据环境变量应使用的服务的配置文件。

默认情况下，可以通过设置特殊环境变量 <PROFILE_ROOT>_PROFILE 来切换活动配置文件。对于 WarehouseProfile，这将是 WAREHOUSE_PROFILE。

可以通过设置您类的 profile_activating_envvar 来自定义此变量的名称。

如果没有设置此变量，活动配置文件将是一个 空字符串，并且查询的环境变量形式为

<PROFILE_ROOT>_<PROPERTY_NAME>

例如，WAREHOUSE_HOST。

如果设置了 <PROFILE_ROOT>_PROFILE，则活动配置文件将查询环境变量形式

<PROFILE_ROOT>_<PROFILE_NAME>_<PROPERTY_NAME>

例如，如果 WAREHOUSE_PROFILE 设置为 staging，则将在 WAREHOUSE_STAGING_HOST 下查找 host 属性。

父配置文件

可以通过设置以下内容来指示任何特定配置文件（例如，WarehouseProfile 的 staging 配置文件）从 父配置文件 继承属性值：

<PROFILE_ROOT>_<PROFILE_NAME>_PARENT_PROFILE

例如，WAREHOUSE_STAGING_PARENT_PROFILE，如果设置为 production，则意味着如果未设置环境变量 WAREHOUSE_STAGING_HOST，则属性值加载器将咨询 WAREHOUSE_PRODUCTION_HOST。只有在那个变量不存在的情况下，才使用属性的默认值。

限制：默认配置文件（profile_name=""）不能用作父配置文件。如果您将空字符串指定为 <PROFILE_ROOT>_<PROFILE_NAME>_PARENT_PROFILE，则此配置文件将没有父配置文件。这与未设置任何值相同。

实时配置文件与冻结配置文件

实时配置文件始终查询环境变量（os.environ），而冻结配置文件仅在实例化和使用 load() 方法显式加载时这样做。

获取当前活动配置文件

当前活动配置文件始终可以通过无参数实例化的您的配置文件类的实例来获取

warehouse_profile = WarehouseProfile()

通常您只需要一个指向活动配置文件的单例配置文件类。

获取具体配置文件

要处理可能尚未激活的混凝土配置文件，请使用 load 工厂方法。

staging = WarehouseProfile.load("staging")

默认情况下，此配置文件将被冻结，这意味着在实例化过程中它只加载一次。如果您想让它始终咨询环境变量，请传递 profile_is_live=True

staging = WarehouseProfile.load("staging", profile_is_live=True)

自定义配置文件激活环境变量

假设您有 WarehouseProfile 并想在测试中使用它。在测试中，它应该有不同的默认值。

@envvar_profile_cls
class WarehouseTestProfile(WarehouseProfile):

    # If you don't set this, it would be "WAREHOUSE_PROFILE" which would conflict
    # with your non-test profile.
    profile_activating_envvar = "WAREHOUSE_TEST_PROFILE"

    host: str = "test-host"
    username: str = "test-user"

在您的应用程序中，您将有两个实例

profile = WarehouseProfile()
test_profile = WarehouseTestProfile()

现在，当有需要时，您可以在测试中重用非测试配置文件。例如，如果您已设置了形式为 WAREHOUSE_SANDBOX_* 的环境变量，则可以通过将 WAREHOUSE_TEST_PROFILE 设置为 sandbox 来在测试中使用此“沙盒”配置文件。

注意，这两个配置文件的 profile_root 是相同的。

激活配置文件

要激活配置文件，请在不带任何参数的情况下在冻结的配置文件实例上调用 activate 方法，或者，在实时当前配置文件实例上调用 activate(profile_name)

staging.activate()
# or:
warehouse_profile.activate("staging")

获取所有值

warehouse_profile.to_dict()

设置环境变量

请注意，您设置的环境变量通常仅适用于当前进程及其子进程，因此这用途有限 - 它只在使用子进程或在代码的早期某处设置环境变量之前（在其他部分的代码加载环境变量之前）才有意义。

os.environ.update(warehouse_profile.to_envvars())

检查属性是否具有非默认值

warehouse_profile.has_prop_value("username")
# or
warehouse_profile.has_prop_value(WarehouseProfile.username)

检查属性

from wr_profiles import EnvvarProfileProperty

assert isinstance(WarehouseProfile.username, EnvvarProfileProperty)
assert WarehouseProfile.username.name == "username"
assert WarehouseProfile.username.default == "default-username"

环境对象

从版本 4.1 开始，您可以创建一个 Environment 实例，然后将其应用于 os.environ 或 pytest 的 monkeypatch 修复程序。 Environment 是需要设置或取消设置以应用指定环境的环境变量的字典。值在环境创建时确定。

test_env = warehouse_profile.create_env(username='test', password=None)
with test_env.applied():
    assert warehouse_profile.username == 'test'
    assert os.environ['WAREHOUSE_USERNAME'] == 'test'

    assert warehouse_profile.password is None
    assert 'WAREHOUSE_PASSWORD' not in os.environ

将配置委托到配置文件的配置对象

环境变量不一定仅是配置的来源。在非平凡的应用程序中，您可能不会直接从应用程序代码咨询配置文件对象。相反，您将有一个配置对象，它将咨询包括环境变量配置文件在内的不同来源。您的配置类中定义的属性很可能只是配置对象公开的属性的一个子集。如果您不想重复，您可以让您的配置类扩展配置文件类，并让配置类将所有属性委托给配置文件类，除非这些属性是在配置类中实现的。

profile = WarehouseProfile()

class WarehouseConfig(WarehouseProfile):
    @property
    def profile_delegate(self):
        return profile

    @property
    def username(self):
        return profile.username or "anonymous"