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:
The user settings file, a YAML mapping of setting names to values, at
SMARTER_USER_SETTINGS_FILE(defaultDEFAULT_USER_SETTINGS_FILE). Locally it isuser-settings/settings.yamlin the repository’s root, which Docker Compose mounts. The Helm chart writes it fromdjangoSettingsin its values. Nested settings, such asLOGGINGorCACHES, are written as YAML.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:
smarter.settings.base_aws, in the AWS environmentsthe environment’s module, e.g.
smarter.settings.prodthe user settings file
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_FILEis 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:
ExceptionThe 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’, insettings.Each environment’s settings module calls it with
globals(), after its last assignment of a setting and beforesmarter.settings.base.log_settings_diagnostics().- Parameters:
- Return type:
- 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:
- Return type:
- 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.
- 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:
- 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.
- smarter.settings.user.literal_value(text)[source]
Return the value that an environment variable’s text writes.
- 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.
- smarter.settings.user.settings_from_environment(environ, current_settings)[source]
Return the settings that
DJANGO_*environment variables set.- Parameters:
- Return type:
- 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:
- 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_filereads the same variable.- Parameters:
- Return type:
- Returns:
SMARTER_USER_SETTINGS_FILEorUSER_SETTINGS_FILE, elseDEFAULT_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:
- Return type:
- Returns:
For a bool, True for
1,true,yesoron, 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.