slm.settings¶

These settings utilities help us compose settings across multiple files.

Warning

These functions only work when called from a settings file because they operate on the calling scope. Do not call these functions from any other location.

slm.settings.split_email_str(email)[source]¶

Split an email string into display name and email address.

If there is no display name it will be the empty string.

Parameters:: email (str) – An email string. E.g.: * name@example.com * Last, First <name@example.com> * "First Last" <name@example.com>
Returns:: A 2-tuple of (display name, email address)
Return type:: Tuple[str, str]

slm.settings.env(**kwargs)[source]¶

Fetch the environ.Env object that should be used to configure settings. If an environment file exists it will be read in. The environment file precendence is:

The path in the environment variable SLM_ENV

BASE_DIR / .env

Returns:: The FileAwareEnv object configured to read our environment variables and files.
Return type:: FileAwareEnv

slm.settings.base_dir(scope=None)[source]¶

Fetch the BASE_DIR, this will raise an ImproperlyConfigured exception if it does not exist yet.

Parameters:: scope – The settings scope (do not pass if calling from a settings file)
Returns:: The BASE_DIR as a pathlib.Path object.
Raises:: ImproperlyConfigured if BASE_DIR is not defined.
Return type:: Path

slm.settings.set_default(var_name, default, set_if_none=True)[source]¶

Set the value of the given variable in the calling scope to a default value if it has been not been previously defined.

Parameters:

var_name (str) – The name of the variable to set in the calling scope.
default (Any) – The value to set the variable to if its undefined
set_if_none (bool) – Treat the variable as undefined if it is None, default: True

Returns:

the variable that was set

Return type:

Any

slm.settings.is_defined(var_name)[source]¶

Returns true if the given variable has been defined in the calling scope.

Parameters:: var_name (str) – The name of the variable to check for
Returns:: True if the variable is defined, false otherwise
Return type:: bool

slm.settings.get_setting(var_name, default=<class 'slm.settings._NotGiven'>)[source]¶

Returns the value of the setting if it exists, if it does not exist the value given to default is returned. If no default value is given and the setting does not exist a NameError is raised

Parameters:

var_name (str) – The name of the variable to check for
default (Any) – The default value to return if the variable does not exist

Raises:

NameError – if the name is undefined and no default is given.

Return type:

Any

slm.settings.slm_path(value, must_exist=False, mk_dirs=False)[source]¶

Resolve a configuration path. If the path is relative it will be resolved under BASE_DIR. If the value is falsey it will be returned as-is even if must_exist is set.

Parameters:

value (str) – The path as a string
must_exist (bool) – If True, raise an ImproperlyConfigured if the path does not exist.
mk_dirs (bool) – If True and the path is relative to BASE_DIR create the path as a directory if it does not already exist.

Raises:

ImproperlyConfigured if BASE_DIR is needed but not defined, or does not exist or if must_exist is True but the path does not exist.

Return type:

str | None

slm.settings.slm_path_must_exist(value, *, must_exist=True, mk_dirs=False)¶

A shortcut for slm_path() with must_exist=True.

Parameters:

value (str)
must_exist (bool)
mk_dirs (bool)

Return type:

str | None

slm.settings.slm_path_mk_dirs_must_exist(value, *, must_exist=True, mk_dirs=True)¶

A shortcut for slm_path() with must_exist=True and mk_dirs=True.

Parameters:

value (str)
must_exist (bool)
mk_dirs (bool)

Return type:

str | None

slm.settings.unset(var_name)[source]¶

Unset the value of the given variable in the calling scope.

Parameters:: var_name (str) – The name of the variable to unset in the calling scope.

slm.settings.resource(package, file)[source]¶

Use a packaged resource file as a settings file include. If you are including a settings file from another package you should pass this to split_settings.tools.include:

include(resource("slm.settings", "root.py"))

Parameters:

package (str) – The string import path of the package containing the module
file (PathLike) – The name of the python settings module

Returns:

The full string path to the resource.