User Settings

The user’s own Django settings, which supersede Smarter’s in every environment. How to write them, and where they go (user-settings/ locally, the Helm chart’s djangoSettings on Kubernetes), is in User-Defined Django Settings.

User-defined Django settings, which supersede every value in smarter.settings.

An operator who runs Smarter sets Django settings of their own in two places, without changing Smarter’s code:

  1. The user settings file, a YAML mapping of setting names to values, at SMARTER_USER_SETTINGS_FILE (default DEFAULT_USER_SETTINGS_FILE). Locally it is user-settings/settings.yaml in the repository’s root, which Docker Compose mounts. The Helm chart writes it from djangoSettings in its values. Nested settings, such as LOGGING or CACHES, are written as YAML.

  2. Environment variables named DJANGO_<SETTING>, e.g. DJANGO_SESSION_COOKIE_AGE=3600.

Every environment’s settings module (local, alpha, beta, next, prod) calls apply_user_settings() after its last assignment of a setting, so nothing in Smarter’s settings can set a value after it, and before it logs its settings, so that the log shows the values that Django runs with. The order, from lowest to highest priority:

  1. smarter.settings.base

  2. smarter.settings.base_aws, in the AWS environments

  3. the environment’s module, e.g. smarter.settings.prod

  4. the user settings file

  5. DJANGO_* environment variables

A user setting replaces the whole setting of that name: a dictionary is not merged with Smarter’s. Settings that Smarter computes from other settings were computed before this runs, so they keep the values they were computed from.

The log names each setting that is set here, and never its value, which may be a password.

smarter.settings.user.ASCII_CONTROL_CHARACTERS = re.compile('[\\x00-\\x1F\\x7F]')

Characters that a copy and paste can leave in an environment variable’s value.

smarter.settings.user.DEFAULT_USER_SETTINGS_FILE = '/home/smarter_user/user-settings/settings.yaml'

in the containers’ home.

Type:

Where the user settings file is when SMARTER_USER_SETTINGS_FILE is unset

smarter.settings.user.ENVIRONMENT_PREFIX = 'DJANGO_'

The prefix of an environment variable that sets the Django setting named by the rest of its name.

smarter.settings.user.IGNORED_ENVIRONMENT_VARIABLES = ('DJANGO_SETTINGS_MODULE',)

DJANGO_* variables that are Django’s own, not settings.

('DJANGO_SETTINGS_MODULE', )
smarter.settings.user.SETTING_NAME = re.compile('^[A-Z][A-Z0-9_]*$')

upper case letters, digits and underscores, starting with a letter.

Type:

A Django setting’s name

exception smarter.settings.user.SmarterUserSettingsError[source]

Bases: Exception

The user settings file, or a DJANGO_* environment variable, can’t be applied.

smarter.settings.user.TRUE_STRINGS = ('1', 'true', 'yes', 'on')

The values of an environment variable that mean True, for a setting whose value is a bool.

('1', 'true', 'yes', 'on')
smarter.settings.user.USER_SETTINGS_FILE_VARIABLE = 'SMARTER_USER_SETTINGS_FILE'

The environment variable that names the user settings file.

smarter.settings.user.apply_user_settings(settings, environ=None)[source]

Set the user settings file’s settings, then the DJANGO_* environment variables’, in settings.

Each environment’s settings module calls it with globals(), after its last assignment of a setting and before smarter.settings.base.log_settings_diagnostics().

Parameters:
Return type:

list[str]

Returns:

The names of the settings set, sorted.

Raises:

SmarterUserSettingsError – If the file or a variable can’t be applied. Django doesn’t start.

smarter.settings.user.check_setting_name(name, source)[source]

Return a setting’s name, if it is one.

Parameters:
  • name (object) – The name, a key of the file’s mapping, or what follows DJANGO_.

  • source (str) – Where the name comes from, for the error.

Return type:

str

Returns:

The name.

Raises:

SmarterUserSettingsError – If it isn’t an upper case setting name.

smarter.settings.user.current_value(name, current_settings)[source]

Return a setting’s value before an environment variable sets it, which gives the variable its type.

Parameters:
  • name (str) – The setting’s name.

  • current_settings (Mapping[str, object]) – The settings module’s namespace.

Return type:

object

Returns:

Smarter’s value, else Django’s default, e.g. [] for SILENCED_SYSTEM_CHECKS, else None.

smarter.settings.user.dict_value(text)[source]

Return an environment variable’s value, for a setting whose value is a dictionary.

Parameters:

text (str) – The variable’s text.

Return type:

dict

Returns:

The JSON object, or the Python dict, that it writes.

Raises:

SmarterUserSettingsError – If it writes neither.

smarter.settings.user.is_known_setting(name, settings)[source]

Return whether a setting exists before the user’s settings: Django’s, a package’s, or Smarter’s.

Parameters:
  • name (str) – The setting’s name.

  • settings (Mapping[str, object]) – The settings module’s namespace.

Return type:

bool

Returns:

True if Smarter’s settings or Django’s defaults define it.

smarter.settings.user.literal_value(text)[source]

Return the value that an environment variable’s text writes.

Parameters:

text (str) – The text.

Return type:

object

Returns:

The JSON value it is (true, 5, ["a"], {"a": 1}), else the Python literal it is (True, ("a", "b")), else the text itself, as a string.

smarter.settings.user.sequence_value(text, sequence_type)[source]

Return an environment variable’s value, for a setting whose value is a list or a tuple.

Parameters:
  • text (str) – The variable’s text.

  • sequence_type (type) – list or tuple, the type of the setting’s value.

Return type:

object

Returns:

A JSON or Python list or tuple, else the comma-separated items, as sequence_type.

smarter.settings.user.settings_from_environment(environ, current_settings)[source]

Return the settings that DJANGO_* environment variables set.

Parameters:
Return type:

dict[str, object]

Returns:

The settings by name.

Raises:

SmarterUserSettingsError – If a variable’s name or value can’t be a setting.

smarter.settings.user.settings_from_file(path)[source]

Return the settings in the user settings file.

Parameters:

path (Path) – The file’s path.

Return type:

dict[str, object]

Returns:

The settings by name, or an empty dict when there is no file, or it is empty.

Raises:

SmarterUserSettingsError – If the file isn’t YAML, isn’t a mapping, or has a key that isn’t a setting name.

smarter.settings.user.user_settings_file_path(environ)[source]

Return the path of the user settings file.

It is read from the environment, not from smarter_settings, so that it is known before any setting is: smarter_settings.user_settings_file reads the same variable.

Parameters:

environ (Mapping[str, str]) – The process’s environment.

Return type:

Path

Returns:

SMARTER_USER_SETTINGS_FILE or USER_SETTINGS_FILE, else DEFAULT_USER_SETTINGS_FILE.

smarter.settings.user.value_like(text, current)[source]

Return an environment variable’s value, of the type of the setting’s current value.

Parameters:
  • text (str) – The variable’s text.

  • current (object) – The setting’s value before this variable.

Return type:

object

Returns:

For a bool, True for 1, true, yes or on, else False. For an int or float, the number. For a list or tuple, a JSON or Python list, else the comma-separated items. For a dict, a JSON object or Python dict. For a string, the text. For anything else, or no current value, literal_value().

Raises:

SmarterUserSettingsError – If the text isn’t a value of the setting’s type.