.. _tauruscustomsettings:

===============
Custom settings
===============

Taurus provides a module located at its root directory called
`tauruscustomsettings` which exposes global configuration options.

It can be accessed programmatically at run time for setting options
for the current execution.

System and user settings files
------------------------------

To permanently modify options for all applications, declare them in the
system-wide or user-specific configuration files (which are loaded automatically when
importing `tauruscustomsettings`).

The default location of the system-wide and user-specific configuration
files is set in `tauruscustomsettings.SYSTEM_CFG_FILE` and
`tauruscustomsettings.USER_CFG_FILE`, respectively. The values are
platform-dependent:

- on POSIX systems Taurus follows the XDG standard: `/etc/xdg/taurus/taurus.ini`
  for system and `~/.config/taurus/taurus.ini` for user.
- on Windows Taurus uses `%PROGRAMDATA%\taurus\taurus.ini` for system
  and `%APPDATA%\taurus\taurus.ini` for user

In case of conflict, the user settings take precedence over the system
settings.

Custom setting file locations
-----------------------------

Apart from the default setting file locations, one can use the `--settings`
option when invoking the taurus CLI command to pass additional settings
file locations.

Applications can also call `tauruscustomsettings.load_configs()` programmatically
to load additional configuration files.

In both cases, newly loaded values overwrite existing variables in
`tauruscustomsettings` when there is a conflict.

Format of the settings files
----------------------------

The settings files are plain-text ``.ini`` files of the form::

    [taurus]
    FOO = "bar"
    BAR = [1, 2, 3]
    baz = False

The keys, which are **case-sensitive**, are exposed as `tauruscustomsettings`
variables and their **values are parsed as Python literals** (e.g., in the above example,
`tauruscustomsettings.FOO` would be the `bar` string,
`tauruscustomsettings.BAR` would be a list and `tauruscustomsettings.baz`
would be a boolean).

Note that all key-values must be declared within a `[taurus]` section.


Default members of tauruscustomsettings
---------------------------------------

.. automodule:: taurus.tauruscustomsettings
    :members:
    :noindex:
    :undoc-members:
    :exclude-members: FORCE_READ_OPTIONS, load_configs