The settings module

Settings for PyExpLabSys component are handled via the Settings class in the settings module.

Getting started

To use the settings module instantiate a Settings object and access the settings as attributes:

>>> from PyExpLabSys.settings import Settings
>>> settings = Settings()
>>> settings.util_log_max_emails_per_period
5

User settings can be modified at run time simply by assigning a new value to the attributes:

>>> settings.util_log_max_emails_per_period = 7
>>> settings.util_log_max_emails_per_period
7

Details

The settings are handled in two layers; defaults and user settings.

The defaults are stored in the PyExpLabSys/defaults.yaml file.

Note

It is not possible to write to a setting that does not have a default

Note

In the defaults, a value of null is used to indicate a settings that must be overwritten by a user setting before any modules tries to use it.

The user settings are stored in a user editable file. The path used is stored in the settings.USERSETTINGS_PATH variable. On Linux system the user settings path is ~/.config.PyExpLabSys.user_settings.yaml.

Note

If the value is None, it means that your operating system is not yet supported by the settings module. This should be reported as an issue on Github.

All Settings objects share the same settings, so changes made via one object will be used everywhere, in fact that is what makes it possible to modify settings at runtime (as shown above). Do however note, that different modules reads the settings at different points in time. Some will read them when an object from that module is instantiated and others will read them at module import time. That means, that for some modules it will be necessary to modify the settings before the rest of the PyExpLabSys modules is imported, in order to be able to modify them at runtime. At which point in time the settings are read should be stated in the module documentation.

Auto-generated module documentation

This module contains the modules used for settings for PyExpLabSys

To use the settings module instantiate a Settings object and access the settings as attributes:

>>> from PyExpLabSys.settings import Settings
>>> settings = Settings()
>>> settings.util_log_max_emails_per_period
5

The settings in the Settings are formed by 2 layers. The bottom layer are the defaults, that are stored in the PyExpLabSys/defaults.yaml file. On top of those are placed the user settings, that originate from the file whose path is in the settings.USERSETTINGS_PATH variable. The user settings can me modified at run time as opposed to having to write them to the user settings file before running. This is done simply by writing to the properties on the settings object:

>>> settings.util_log_max_emails_per_period = 7
>>> settings.util_log_max_emails_per_period
7

All Settings objects share the same settings, so these changes will be used when using other parts of PyExpLabSys that makes use of one of the settings. Do however note, that different parts of PyExpLabSys use the settings at different times (instantiate, call etc.) so check with the documentation for each component when the settings needs to be modified to take effect.

PyExpLabSys.settings.value_str(obj)

Return a object and type str or NOT_SET if obj is None

class PyExpLabSys.settings.Settings

Bases: object

The PyExpLabSys settings object

The settings are available to get and setable on this object as attributes i.e:

>>> from PyExpLabSys.settings import Settings
>>> settings = Settings()
>>> settings.util_log_max_emails_per_period
5

The settings are stored as a ChainMap of the defaults and the user settings and this ChainMap object containing the current state of the settings is shared between all Settings objects.

To get a list of all available settings see the Settings.settings_names attribute. To get a pretty print of all settings names, types, default values, user setting values (if any) use the Settings.print_settings() method.

settings = ChainMap({'util_log_warning_email': 'fake@non.com', 'util_log_error_email': 'fake@non.com', 'util_log_mail_host': 'none'}, {'sql_server_host': None, 'sql_database': None, 'common_sql_reader_user': None, 'common_sql_reader_password': None, 'common_liveserver_host': None, 'common_liveserver_port': None, 'util_log_warning_email': None, 'util_log_error_email': None, 'util_log_mail_host': None, 'util_log_max_emails_per_period': 5, 'util_log_email_throttle_time': 86400, 'util_log_backlog_limit': 250})

The settings ChainMap

settings_names = ['sql_server_host', 'sql_database', 'common_sql_reader_user', 'common_sql_reader_password', 'common_liveserver_host', 'common_liveserver_port', 'util_log_warning_email', 'util_log_error_email', 'util_log_mail_host', 'util_log_max_emails_per_period', 'util_log_email_throttle_time', 'util_log_backlog_limit']

The available setting names

__init__()

Initialize self. See help(type(self)) for accurate signature.

print_settings()

Pretty print of all default and user settings

PyExpLabSys.settings.main()

Main function used to simple testing