API Reference

SFS Settings: Simple, Flexible, and Secure Settings Management

This module provides a flexible, secure way to manage application settings from environment variables and secret stores. It offers three distinct patterns:

  1. Setting variables directly in the sfs_settings module

  2. Setting variables in the calling module namespace

  3. Returning values for manual assignment

Key Features:

  • Environment variable integration with .env file support

  • Secure secret storage via the keyring library

  • Type conversion and validation

  • Lazy evaluation with reobtain_each_usage option

  • Stack inspection to modify the correct module namespace

Basic Examples:

Set and get in sfs-settings itself:

import sfs_settings as sfs
sfs.track_env_var("DATABASE_URL")
print(sfs.DATABASE_URL)  # Uses the value from DATABASE_URL environment variable

Set and get in the calling module:

from sfs_settings import set_env_var_locally
set_env_var_locally("DATABASE_URL")
print(DATABASE_URL)  # Variable is now available in the local namespace

Use values directly:

from sfs_settings import return_env_var
db_url = return_env_var("DATABASE_URL")
print(db_url)
exception SettingsNotFoundError[source]

Bases: ValueError

Raised when a required setting is not found.

exception SettingsValidationError[source]

Bases: ValueError

Raised when a setting fails validation.

return_env_var(env_var_name, default=None, validator_function=<function <lambda>>, reobtain_each_usage=False, conversion_function=<class 'str'>)[source]

Get a value from an environment variable.

Parameters:

  • env_var_name (str) – The name of the environment variable to get.

  • default (str or None, Optional) – The default value to use if the environment variable is not set.

  • validator_function (Callable[[Any], bool], Optional) – An auxiliary function that validates the value according to user specified criteria.

  • reobtain_each_usage (bool, Optional) – If True, the value will be reobtained each time it is used. If False, the value will be obtained once and then reused. Set to True if the value changes during runtime and the program needs the updated value in order to operate correctly.

  • conversion_function (Callable[[str], Any] or type, Optional) – An auxiliary function that converts the value from a string to the desired type. Use this for complex or nested types.

Returns:

The value of the environment variable.

Return type:

Any

return_secret_var(store_name, name_in_store, default=None, validator_function=<function <lambda>>, reobtain_each_usage=True, conversion_function=<class 'str'>)[source]

Get a secret from a secret store (and help set if missing and no default is provided).

To understand better, here’s an example from the CLI:
Set:

python -m keyring -b keyring.backends.SecretService.Keyring set Passwords pythonkeyringcli -> asks for password

Get:

python -m keyring -b keyring.backends.SecretService.Keyring get Passwords pythonkeyringcli -> prints password

And in your passwords manager, in my case Wallet Manager, this appears under the tree as: “Secret Service” -> “Passwords” -> “Password for ‘pythonkeyringcli’ on ‘Passwords’”

But you’ll notice that you can’t retrieve all your other passwords. This is a security feature. Only passwords a program has set can be retrieved by that program. However, this can become finicky. This is a trade-off.

Warning

You may have to use sey_keyring() if the correct backend is not automatically set. Please refer to https://pypi.org/project/keyring/ for more information.

Parameters:

  • store_name (str) – The name of the secret store to get the secret from.

  • name_in_store (str) – The name of the secret in the secret store.

  • default (str or None, Optional) – The default value to use if the secret is not set.

  • validator_function (Callable[[Any], bool], Optional) – An auxiliary function that validates the value according to user specified criteria.

  • reobtain_each_usage (bool, Optional) – If True, the value will be reobtained each time it is used. If False, the value will be obtained once and then reused. Set to True if the value changes during runtime and the program needs the updated value in order to operate correctly. For security reasons, it is recommended to set this to True.

  • conversion_function (Callable[[str], Any] or type, Optional) – An auxiliary function that converts the value from a string to the desired type. Use this for complex or nested types.

Returns:

The retrieved secret value after any conversion has been applied.

Return type:

Any

set_env_var_locally(name, default=None, validator_function=<function <lambda>>, reobtain_each_usage=False, conversion_function=<class 'str'>)[source]

Set a variable in the calling module with the same name as the environment variable given as name.

Parameters:

  • name (str) – The name of the environment variable to get and set.

  • default (str or None, Optional) – The default value to use if the environment variable is not set.

  • validator_function (Callable[[Any], bool], Optional) – An auxiliary function that validates the value according to user specified criteria.

  • reobtain_each_usage (bool, Optional) – If True, the value will be reobtained each time it is used. If False, the value will be obtained once and then reused. Set to True if the value changes during runtime and the program needs the updated value in order to operate correctly. For security reasons, it is recommended to set this to True.

  • conversion_function (Callable[[str], Any] or type, Optional) – An auxiliary function that converts the value from a string to the desired type. Use this for complex or nested types.

Returns:

This function does not return anything. It sets a variable in the calling module as a side effect.

Return type:

None

set_secret_var_locally(var_name, store_name, name_in_store, default=None, validator_function=<function <lambda>>, reobtain_each_usage=True, conversion_function=<class 'str'>)[source]

Get a secret from a secret store (and help set if missing and no default is provided).

To understand better, here’s an example from the CLI:
Set:

python -m keyring -b keyring.backends.SecretService.Keyring set Passwords pythonkeyringcli -> asks for password

Get:

python -m keyring -b keyring.backends.SecretService.Keyring get Passwords pythonkeyringcli -> prints password

And in your passwords manager, in my case Wallet Manager, this appears under the tree as: “Secret Service” -> “Passwords” -> “Password for ‘pythonkeyringcli’ on ‘Passwords’”

But you’ll notice that you can’t retrieve all your other passwords. This is a security feature. Only passwords a program has set can be retrieved by that program. However, this can become finicky. This is a trade-off.

Warning

You may have to use sey_keyring() if the correct backend is not automatically set. Please refer to https://pypi.org/project/keyring/ for more information.

Parameters:

  • var_name (str) – The name of the variable to get and set in the calling module.

  • store_name (str) – The name of the secret store to get the secret from.

  • name_in_store (str) – The name of the secret in the secret store.

  • default (str or None, Optional) – The default value to use if the secret is not set.

  • validator_function (Callable[[Any], bool], Optional) – An auxiliary function that validates the value according to user specified criteria.

  • reobtain_each_usage (bool, Optional) – If True, the value will be reobtained each time it is used. If False, the value will be obtained once and then reused. Set to True if the value changes during runtime and the program needs the updated value in order to operate correctly. For security reasons, it is recommended to set this to True.

  • conversion_function (Callable[[str], Any] or type, Optional) – An auxiliary function that converts the value from a string to the desired type. Use this for complex or nested types.

Returns:

This function does not return anything. It sets a variable in the calling module as a side effect.

Return type:

None

track_env_var(env_var_name, default=None, validator_function=<function <lambda>>, reobtain_each_usage=False, conversion_function=<class 'str'>)[source]

Set a variable in the calling module with the same name as the environment variable given as name.

Parameters:

  • env_var_name (str) – Name of an environmental variable to obtain the value of.

  • default (str or None, Optional) – If not None, a default value to use if the environmental value specified by env_var_name is not set.

  • validator_function (Callable[[Any], bool], Optional) – An additional validation function to accept or reject the obtained value.

  • reobtain_each_usage (bool, Optional) – If true, on each access reobtain the value. If not, it is only obtained once when this function is called.

  • conversion_function (Callable[[str], Any] or type, Optional) – A function or type that converts the obtained value to the desired type.

Returns:

This function does not return anything. It sets a variable in the calling module as a side effect.

Return type:

None

track_secret_var(var_name, store_name, name_in_store, default=None, validator_function=<function <lambda>>, reobtain_each_usage=True, conversion_function=<class 'str'>)[source]

Get a secret from a secret store (and help set if missing and no default is provided).

To understand better, here’s an example from the CLI:
Set:

python -m keyring -b keyring.backends.SecretService.Keyring set Passwords pythonkeyringcli -> asks for password

Get:

python -m keyring -b keyring.backends.SecretService.Keyring get Passwords pythonkeyringcli -> prints password

And in your passwords manager, in my case Wallet Manager, this appears under the tree as: “Secret Service” -> “Passwords” -> “Password for ‘pythonkeyringcli’ on ‘Passwords’”

But you’ll notice that you can’t retrieve all your other passwords. This is a security feature. Only passwords a program has set can be retrieved by that program. However, this can become finicky. This is a trade-off.

Warning

You may have to use sey_keyring() if the correct backend is not automatically set. Please refer to https://pypi.org/project/keyring/ for more information.

Parameters:

  • var_name (str) – The name of the variable to get and set.

  • store_name (str) – The name of the secret store to get the secret from.

  • name_in_store (str) – The name of the secret in the secret store.

  • default (str or None, Optional) – The default value to use if the secret is not set.

  • validator_function (Callable[[Any], bool], Optional) – An auxiliary function that validates the value according to user specified criteria.

  • reobtain_each_usage (bool, Optional) – If True, the value will be reobtained each time it is used. If False, the value will be obtained once and then reused. Set to True if the value changes during runtime and the program needs the updated value in order to operate correctly. For security reasons, it is recommended to set this to True.

  • conversion_function (Callable[[str], Any] or type, Optional) – An auxiliary function that converts the value from a string to the desired type. Use this for complex or nested types.

Returns:

This function does not return anything. It sets a variable in the calling module as a side effect.

Return type:

None