%global _empty_manifest_terminate_build 0 Name: python-coveo-settings Version: 2.1.1 Release: 1 Summary: Settings driven by environment variables. License: Apache-2.0 URL: https://github.com/coveooss/coveo-python-oss/tree/main/coveo-settings Source0: https://mirrors.nju.edu.cn/pypi/web/packages/3c/3f/8b484f15584ca17e9453dddb6eafacb7e084ac2b564f392197e870f2a67f/coveo_settings-2.1.1.tar.gz BuildArch: noarch %description # coveo-settings Whenever you want the user to be able to configure something through an environment variable, this module has your back: ```python from coveo_settings import StringSetting, BoolSetting DATABASE_URL = StringSetting('project.database.url') DATABASE_USE_SSL = BoolSetting('project.database.ssl') ``` The user can then configure the environment variables `project.database.url` and `project.database.ssl` to configure the application. When accessed, the values are automatically converted to the desired type: - `StringSetting` will always be a string - `BoolSetting` is either True or False, but accepts "yes|no|true|false|1|0" as input (case-insensitive, of course) - `IntSetting` and `FloatSetting` are self-explanatory - `DictSetting` allows you to use JSON maps - `PathSetting` gives a Path instance, and also implements PathLike and the `/` operator If the input cannot be converted to the value type, an `TypeConversionConfigurationError` exception is raised. A default (fallback) value may be specified. The fallback may be a `callable`. A validation callback may be specified for custom logic and error messages. Not limited to environment variables; supports redirection to custom implementations. **A setting can be set as sensitive for logging purposes. When logging, use repr(setting) to get the correct representation.** ## Accessing the value There are various ways to obtain the value: ```python from coveo_settings import BoolSetting DATABASE_USE_SSL = BoolSetting('project.database.ssl') # this method will raise an exception if the setting has no value and no fallback use_ssl = bool(DATABASE_USE_SSL) use_ssl = DATABASE_USE_SSL.get_or_raise() assert use_ssl in [True, False] # this method will not raise an exception use_ssl = DATABASE_USE_SSL.value assert use_ssl in [True, False, None] # use "is_set" to check if there is a value set for this setting; skips validation check if DATABASE_USE_SSL.is_set: use_ssl = bool(DATABASE_USE_SSL) # use "is_valid" to verify if the value passes the validation callback. implies is_set. if not DATABASE_USE_SSL.is_valid: ... ``` ## Loose environment key matching Matching the key of the environment variable `project.database.ssl` is done very loosely: - case-insensitive - dots and underscores are ignored completely (`foo_bar` and `f__ooba.r` are equal) - useful for some runners that don't support dots in environment variable keys ## Use ready validation You can quickly validate that a string is in a specific list like this: ```python from coveo_settings.settings import StringSetting from coveo_settings.validation import InSequence ENV = StringSetting("environment", fallback="dev", validation=InSequence("prod", "staging", "dev")) ``` ## Redirection You can register custom redirection schemes in order to support any data source. Much like `https://` is a clear scheme, you may register callback functions to trigger when the value of a setting starts with the scheme(s) you define. For instance, let's support a custom API and a file storage: ```python from coveo_settings import settings_adapter, StringSetting, ConfigValue @settings_adapter("internal-api::") def internal_api_adapter(key: str) -> ConfigValue: # the scheme was automatically removed for convenience; only the resource remains assert "internal-api::" not in key return "internal api" # implement logic to obtain value from internal api @settings_adapter("file::", strip_scheme=False) def file_adapter(key: str) -> ConfigValue: # you can keep the scheme by specifying `strip_scheme=False` assert key.startswith("file::") return "file adapter" # implement logic to parse the key and retrieve the setting value assert StringSetting('...', fallback="internal-api::settings/user-name").value == "internal api" assert StringSetting('...', fallback="file::settings.yaml/user-name").value == "file adapter" # even though we used `fallback` above, the redirection is driven by the user: import os REDIRECT_ME = StringSetting('test') os.environ['test'] = "file::user.json::name" assert REDIRECT_ME.value == "file adapter" os.environ['test'] = "internal-api::url" assert REDIRECT_ME.value == "internal api" ``` Keep in mind that there's no restriction on the prefix scheme; it's your responsibility to pick something unique that can be set as the value of an environment variable. ### Redirection is recursive The value of a redirection may be another redirection and may juggle between adapters. A limit of 50 redirections is supported: ```python import os from coveo_settings import StringSetting os.environ["expected"] = "final value" os.environ["redirected"] = "env->expected" os.environ["my-setting"] = "env->redirected" assert StringSetting("my-setting").value == "final value" ``` ### Builtin environment redirection The builtin redirection scheme `env->` can be used to redirect to a different environment variable. The example below demonstrates the deprecation/migration of `my-setting` into `new-setting`: ```python import os from coveo_settings import StringSetting os.environ["new-setting"] = "correct-value" os.environ["my-setting"] = "env->new-setting" assert StringSetting("my-setting").value == "correct-value" ``` ## Cached You can set a setting to cache the first valid value with `cached=True`. This is particularly useful in redirection scenarios to avoid repeating requests too often. ## Setting the value You can override the value using `setting.value = "some value"` and clear the override with `setting.value = None`. Clearing the override resumes the normal behavior of the environment variables and the fallback value, if set. This is typically used as a way to propagate CLI switches globally. For mocking scenarios, refer to the `Mocking` section below. ## Mocking When you need a setting value for a test, use the `mock_config_value` context manager: ```python from coveo_settings import StringSetting from coveo_settings.mock import mock_config_value SETTING = StringSetting(...) assert not SETTING.is_set with mock_config_value(SETTING, 'new-value'): assert SETTING.is_set ``` You can also clear the value: ```python from coveo_settings import StringSetting from coveo_settings.mock import mock_config_value SETTING = StringSetting(..., fallback='test') assert SETTING.is_set with mock_config_value(SETTING, None): assert not SETTING.is_set ``` %package -n python3-coveo-settings Summary: Settings driven by environment variables. Provides: python-coveo-settings BuildRequires: python3-devel BuildRequires: python3-setuptools BuildRequires: python3-pip %description -n python3-coveo-settings # coveo-settings Whenever you want the user to be able to configure something through an environment variable, this module has your back: ```python from coveo_settings import StringSetting, BoolSetting DATABASE_URL = StringSetting('project.database.url') DATABASE_USE_SSL = BoolSetting('project.database.ssl') ``` The user can then configure the environment variables `project.database.url` and `project.database.ssl` to configure the application. When accessed, the values are automatically converted to the desired type: - `StringSetting` will always be a string - `BoolSetting` is either True or False, but accepts "yes|no|true|false|1|0" as input (case-insensitive, of course) - `IntSetting` and `FloatSetting` are self-explanatory - `DictSetting` allows you to use JSON maps - `PathSetting` gives a Path instance, and also implements PathLike and the `/` operator If the input cannot be converted to the value type, an `TypeConversionConfigurationError` exception is raised. A default (fallback) value may be specified. The fallback may be a `callable`. A validation callback may be specified for custom logic and error messages. Not limited to environment variables; supports redirection to custom implementations. **A setting can be set as sensitive for logging purposes. When logging, use repr(setting) to get the correct representation.** ## Accessing the value There are various ways to obtain the value: ```python from coveo_settings import BoolSetting DATABASE_USE_SSL = BoolSetting('project.database.ssl') # this method will raise an exception if the setting has no value and no fallback use_ssl = bool(DATABASE_USE_SSL) use_ssl = DATABASE_USE_SSL.get_or_raise() assert use_ssl in [True, False] # this method will not raise an exception use_ssl = DATABASE_USE_SSL.value assert use_ssl in [True, False, None] # use "is_set" to check if there is a value set for this setting; skips validation check if DATABASE_USE_SSL.is_set: use_ssl = bool(DATABASE_USE_SSL) # use "is_valid" to verify if the value passes the validation callback. implies is_set. if not DATABASE_USE_SSL.is_valid: ... ``` ## Loose environment key matching Matching the key of the environment variable `project.database.ssl` is done very loosely: - case-insensitive - dots and underscores are ignored completely (`foo_bar` and `f__ooba.r` are equal) - useful for some runners that don't support dots in environment variable keys ## Use ready validation You can quickly validate that a string is in a specific list like this: ```python from coveo_settings.settings import StringSetting from coveo_settings.validation import InSequence ENV = StringSetting("environment", fallback="dev", validation=InSequence("prod", "staging", "dev")) ``` ## Redirection You can register custom redirection schemes in order to support any data source. Much like `https://` is a clear scheme, you may register callback functions to trigger when the value of a setting starts with the scheme(s) you define. For instance, let's support a custom API and a file storage: ```python from coveo_settings import settings_adapter, StringSetting, ConfigValue @settings_adapter("internal-api::") def internal_api_adapter(key: str) -> ConfigValue: # the scheme was automatically removed for convenience; only the resource remains assert "internal-api::" not in key return "internal api" # implement logic to obtain value from internal api @settings_adapter("file::", strip_scheme=False) def file_adapter(key: str) -> ConfigValue: # you can keep the scheme by specifying `strip_scheme=False` assert key.startswith("file::") return "file adapter" # implement logic to parse the key and retrieve the setting value assert StringSetting('...', fallback="internal-api::settings/user-name").value == "internal api" assert StringSetting('...', fallback="file::settings.yaml/user-name").value == "file adapter" # even though we used `fallback` above, the redirection is driven by the user: import os REDIRECT_ME = StringSetting('test') os.environ['test'] = "file::user.json::name" assert REDIRECT_ME.value == "file adapter" os.environ['test'] = "internal-api::url" assert REDIRECT_ME.value == "internal api" ``` Keep in mind that there's no restriction on the prefix scheme; it's your responsibility to pick something unique that can be set as the value of an environment variable. ### Redirection is recursive The value of a redirection may be another redirection and may juggle between adapters. A limit of 50 redirections is supported: ```python import os from coveo_settings import StringSetting os.environ["expected"] = "final value" os.environ["redirected"] = "env->expected" os.environ["my-setting"] = "env->redirected" assert StringSetting("my-setting").value == "final value" ``` ### Builtin environment redirection The builtin redirection scheme `env->` can be used to redirect to a different environment variable. The example below demonstrates the deprecation/migration of `my-setting` into `new-setting`: ```python import os from coveo_settings import StringSetting os.environ["new-setting"] = "correct-value" os.environ["my-setting"] = "env->new-setting" assert StringSetting("my-setting").value == "correct-value" ``` ## Cached You can set a setting to cache the first valid value with `cached=True`. This is particularly useful in redirection scenarios to avoid repeating requests too often. ## Setting the value You can override the value using `setting.value = "some value"` and clear the override with `setting.value = None`. Clearing the override resumes the normal behavior of the environment variables and the fallback value, if set. This is typically used as a way to propagate CLI switches globally. For mocking scenarios, refer to the `Mocking` section below. ## Mocking When you need a setting value for a test, use the `mock_config_value` context manager: ```python from coveo_settings import StringSetting from coveo_settings.mock import mock_config_value SETTING = StringSetting(...) assert not SETTING.is_set with mock_config_value(SETTING, 'new-value'): assert SETTING.is_set ``` You can also clear the value: ```python from coveo_settings import StringSetting from coveo_settings.mock import mock_config_value SETTING = StringSetting(..., fallback='test') assert SETTING.is_set with mock_config_value(SETTING, None): assert not SETTING.is_set ``` %package help Summary: Development documents and examples for coveo-settings Provides: python3-coveo-settings-doc %description help # coveo-settings Whenever you want the user to be able to configure something through an environment variable, this module has your back: ```python from coveo_settings import StringSetting, BoolSetting DATABASE_URL = StringSetting('project.database.url') DATABASE_USE_SSL = BoolSetting('project.database.ssl') ``` The user can then configure the environment variables `project.database.url` and `project.database.ssl` to configure the application. When accessed, the values are automatically converted to the desired type: - `StringSetting` will always be a string - `BoolSetting` is either True or False, but accepts "yes|no|true|false|1|0" as input (case-insensitive, of course) - `IntSetting` and `FloatSetting` are self-explanatory - `DictSetting` allows you to use JSON maps - `PathSetting` gives a Path instance, and also implements PathLike and the `/` operator If the input cannot be converted to the value type, an `TypeConversionConfigurationError` exception is raised. A default (fallback) value may be specified. The fallback may be a `callable`. A validation callback may be specified for custom logic and error messages. Not limited to environment variables; supports redirection to custom implementations. **A setting can be set as sensitive for logging purposes. When logging, use repr(setting) to get the correct representation.** ## Accessing the value There are various ways to obtain the value: ```python from coveo_settings import BoolSetting DATABASE_USE_SSL = BoolSetting('project.database.ssl') # this method will raise an exception if the setting has no value and no fallback use_ssl = bool(DATABASE_USE_SSL) use_ssl = DATABASE_USE_SSL.get_or_raise() assert use_ssl in [True, False] # this method will not raise an exception use_ssl = DATABASE_USE_SSL.value assert use_ssl in [True, False, None] # use "is_set" to check if there is a value set for this setting; skips validation check if DATABASE_USE_SSL.is_set: use_ssl = bool(DATABASE_USE_SSL) # use "is_valid" to verify if the value passes the validation callback. implies is_set. if not DATABASE_USE_SSL.is_valid: ... ``` ## Loose environment key matching Matching the key of the environment variable `project.database.ssl` is done very loosely: - case-insensitive - dots and underscores are ignored completely (`foo_bar` and `f__ooba.r` are equal) - useful for some runners that don't support dots in environment variable keys ## Use ready validation You can quickly validate that a string is in a specific list like this: ```python from coveo_settings.settings import StringSetting from coveo_settings.validation import InSequence ENV = StringSetting("environment", fallback="dev", validation=InSequence("prod", "staging", "dev")) ``` ## Redirection You can register custom redirection schemes in order to support any data source. Much like `https://` is a clear scheme, you may register callback functions to trigger when the value of a setting starts with the scheme(s) you define. For instance, let's support a custom API and a file storage: ```python from coveo_settings import settings_adapter, StringSetting, ConfigValue @settings_adapter("internal-api::") def internal_api_adapter(key: str) -> ConfigValue: # the scheme was automatically removed for convenience; only the resource remains assert "internal-api::" not in key return "internal api" # implement logic to obtain value from internal api @settings_adapter("file::", strip_scheme=False) def file_adapter(key: str) -> ConfigValue: # you can keep the scheme by specifying `strip_scheme=False` assert key.startswith("file::") return "file adapter" # implement logic to parse the key and retrieve the setting value assert StringSetting('...', fallback="internal-api::settings/user-name").value == "internal api" assert StringSetting('...', fallback="file::settings.yaml/user-name").value == "file adapter" # even though we used `fallback` above, the redirection is driven by the user: import os REDIRECT_ME = StringSetting('test') os.environ['test'] = "file::user.json::name" assert REDIRECT_ME.value == "file adapter" os.environ['test'] = "internal-api::url" assert REDIRECT_ME.value == "internal api" ``` Keep in mind that there's no restriction on the prefix scheme; it's your responsibility to pick something unique that can be set as the value of an environment variable. ### Redirection is recursive The value of a redirection may be another redirection and may juggle between adapters. A limit of 50 redirections is supported: ```python import os from coveo_settings import StringSetting os.environ["expected"] = "final value" os.environ["redirected"] = "env->expected" os.environ["my-setting"] = "env->redirected" assert StringSetting("my-setting").value == "final value" ``` ### Builtin environment redirection The builtin redirection scheme `env->` can be used to redirect to a different environment variable. The example below demonstrates the deprecation/migration of `my-setting` into `new-setting`: ```python import os from coveo_settings import StringSetting os.environ["new-setting"] = "correct-value" os.environ["my-setting"] = "env->new-setting" assert StringSetting("my-setting").value == "correct-value" ``` ## Cached You can set a setting to cache the first valid value with `cached=True`. This is particularly useful in redirection scenarios to avoid repeating requests too often. ## Setting the value You can override the value using `setting.value = "some value"` and clear the override with `setting.value = None`. Clearing the override resumes the normal behavior of the environment variables and the fallback value, if set. This is typically used as a way to propagate CLI switches globally. For mocking scenarios, refer to the `Mocking` section below. ## Mocking When you need a setting value for a test, use the `mock_config_value` context manager: ```python from coveo_settings import StringSetting from coveo_settings.mock import mock_config_value SETTING = StringSetting(...) assert not SETTING.is_set with mock_config_value(SETTING, 'new-value'): assert SETTING.is_set ``` You can also clear the value: ```python from coveo_settings import StringSetting from coveo_settings.mock import mock_config_value SETTING = StringSetting(..., fallback='test') assert SETTING.is_set with mock_config_value(SETTING, None): assert not SETTING.is_set ``` %prep %autosetup -n coveo-settings-2.1.1 %build %py3_build %install %py3_install install -d -m755 %{buildroot}/%{_pkgdocdir} if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi pushd %{buildroot} if [ -d usr/lib ]; then find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/lib64 ]; then find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/bin ]; then find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/sbin ]; then find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst fi touch doclist.lst if [ -d usr/share/man ]; then find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst fi popd mv %{buildroot}/filelist.lst . mv %{buildroot}/doclist.lst . %files -n python3-coveo-settings -f filelist.lst %dir %{python3_sitelib}/* %files help -f doclist.lst %{_docdir}/* %changelog * Fri May 05 2023 Python_Bot - 2.1.1-1 - Package Spec generated