# Taurus 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

If one wants to permanently modify options for all applications, the recommended way is to do it by declaring 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 we follow the xdg standard: /etc/xdg/taurus/taurus.ini for system and ~/.config/taurus/taurus.ini for user.

- on windows machines we use %PROGRAMDATA%taurustaurus.ini for system and %APPDATA%taurustaurus.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.

One can also programmatically call the tauruscustomsettings.load_configs() function at any point to load other configuration files

In both cases, the values of existing variables in tauruscustomsettings are overwritten in case of 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 key-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

This module exposes global configuration options. It declares the default values of some of these options, but they may be modified when loading custom settings configuration files (e.g., at import time).

DEFAULT_QT_API = ''

  Set preferred API (if one is not already loaded). Accepted values are “pyqt5”, “pyqt”, “pyside2”, “pyside”. Set to an empty string to let taurus choose the first that works from the accepted values.

DEFAULT_SCHEME = 'tango'

  Default scheme (if not defined, “tango” is assumed)

EXTRA_SCHEME_MODULES = []

  Extra Taurus schemes. You can add a list of modules to be loaded for providing support to new schemes (e.g. `EXTRA_SCHEME_MODULES = ['myownschememodule']`

FILTER_OLD_TANGO_EVENTS = True

  Filter old tango events: Sometimes `TangoAttribute` can receive an event with an older timestamp than its current one. See https://gitlab.com/taurus-org/taurus/-/issues/216

  - `True` discards (Tango) events whose timestamp is older than the cached one.

  - `False` (or commented out) for backwards (pre 4.1) compatibility

IMAGE_ALT = '.*'

  Widget alternatives. See `PLOT_ALT` for a full description.

IMPLICIT_OPTPARSE = False

  Implicit optparse legacy support: In taurus < 4.6.5 if `TaurusApplication` did not receive an explicit `cmd_line_parser` keyword argument, it implicitly used a `optparse.OptionParser` instance. This was inconvenient because it forced the user to explicitly pass `cmd_line_parser=None` when using other mechanisms such as `click` or `argparse` to parse CLI options. In taurus >=4.6.5 this is no longer the case by default, but the old behaviour can be restored by setting `IMPLICIT_OPTPARSE = True`

LIGHTWEIGHT_IMPORTS = False

  Lightweight imports:

  - `True` enables delayed imports (may break older code).

  - `False` (or commented out) for backwards compatibility

ORGANIZATION_LOGO = 'logos:taurus.png'

  Custom organization logo. Set the absolute path to an image file to be used as your organization logo. Qt registered paths can also be used. If not set, it defaults to “logos:taurus.png” (note that “logos:” is a Qt registered path for “<taurus>/qt/qtgui/icon/logos/”)

PLOT_ALT = '.*'

  Widget alternatives. Some widgets may have alternative implementations. The different implementations are registered in entry point groups (`taurus.plot.alt`, `taurus.trend.alt`, …) and they are tried in alphabetical order of their registered entry point names (the first one that works is used). You can restrict the set of available implementation alternatives to be tried (or even just select a given alternative) by setting the corresponding `*_ALT` variable with a name regexp pattern that must be matched by the entry point name in order to be tried. For example, to force the `taurus_pyqtgraph` implementation for the plots, set `PLOT_ALT = "tpg"`.

  The following variables control the alternatives:

  - `PLOT_ALT`

  - `TREND_ALT`

  - `TREND2D_ALT`

  - `IMAGE_ALT`

  Leaving the variable undefined is equivalent to setting it to “.*”

PLY_OPTIMIZE = 1

  PLY (lex/yacc) optimization: 1=Active (default) , 0=disabled. Set `PLY_OPTIMIZE = 0` if you are getting yacc exceptions while loading synoptics

QT_AUTO_INIT_LOG = True

  Auto initialize Qt logging to python logging

QT_AUTO_REMOVE_INPUTHOOK = True

  Remove input hook (only valid for `PyQt`)

QT_AVOID_ABORT_ON_EXCEPTION = True

  Avoid application abort on unhandled python exceptions (which happens since PyQt 5.5). http://pyqt.sf.net/Docs/PyQt5/incompatibilities.html#unhandled-python-exceptions # noqa If `True` (or commented out) an except hook is added to force the old behaviour (exception is just printed) on `pyqt5`

QT_DESIGNER_PATH = None

  Full Qt designer path (including filename. Default is None, meaning to look for the system designer following `Qt.QLibraryInfo.BinariesPath` If this fails, taurus tries to locate binary manually

QT_THEME_DIR = ''

  Select the theme to be used. The path can be absolute or relative to the dir of `taurus.qt.qtgui.icon`. If not set, the dir of `taurus.qt.qtgui.icon` will be used.

QT_THEME_FORCE_ON_LINUX = False

  In Linux the `QT_THEME_NAME` is not applied (to respect the system theme) setting `QT_THEME_FORCE_ON_LINUX = True` overrides this.

QT_THEME_NAME = 'Tango'

  The name of the icon theme (e.g. ‘Tango’, ‘Oxygen’, etc). Default=’Tango’

SAVE_SETTINGS_ON_CLOSE = None

  Default behaviour for `TaurusMainWindow`. On close, `TaurusMainWindow` will ask the user if he wants to save. Set to `True` if you want to save automatically without being warned. Set to `False` in case you do notwant to be asked and do not want to Save current window.

STRICT_MODEL_NAMES = False

  Strict RFC3986 URI names in models.

  - `True` makes Taurus only use the strict URI names

  - `False` False enables a backwards-compatibility mode for pre-sep3 model names

SYSTEM_CFG_FILE = '/etc/xdg/taurus/taurus.ini'

  Path to the system-wide config file

TANGO_AUTOSUBSCRIBE_CONF = True

  Whether `TangoAttribute` is subscribed to configuration events by default.

  - Setting to `True` (or not setting it) makes the `TangoAttribute` auto-subscribe

  - Setting to `False` avoids this subscription, which prevents issues such as https://gitlab.com/taurus-org/taurus/-/issues/1118 but it also prevents clients to be notified when configurations (e.g., units, format) change.

TANGO_EVENTS_TO_SUBSCRIBE = ['CHANGE_EVENT']

  An array with all the tango event types to subscribe when using setModel(). The posible options are all the existent tango event types except “ATTR_CONF_EVENT” as it has its own taurus custom setting. Leaving an empty array will won’t subscribe to any event and will enable the taurus polling. Note: this setting currently only supports [“CHANGE_EVENT”] and [], but it was created for future compatibility when supporting all event types

TANGO_FORCE_READ_IF_SUBSCRIPTION_FAILS = 'ONLY_CORE'

  Select when taurus will perform a tango read when the subscription to change events fails (the attribute doesn’t send events). Possible values are the options in `FORCE_READ_OPTIONS` fake enum:

  - `"NEVER"`: never read when subscription fails.

  - `"ONLY_CORE"`: (default) force read when using taurus core but avoid the read when running applications (TaurusApplication).

  - `"ALWAYS"`: always read when subscription fails.

TANGO_SERIALIZATION_MODE = 'TangoSerial'

  Default serialization mode for the tango scheme. Possible values are: ‘Serial’, ‘Concurrent’, or ‘TangoSerial’ (default)

TREND2D_ALT = '.*'

  Widget alternatives. See `PLOT_ALT` for a full description.

TREND_ALT = '.*'

  Widget alternatives. See `PLOT_ALT` for a full description.

T_FORM_COMPACT = False

  Compact mode for widgets True sets the preferred mode of TaurusForms to use “compact” widgets

T_FORM_CUSTOM_WIDGET_MAP = {}

  DEPRECATED. Use `taurus.form.item_factories` plugin group instead A map for using custom widgets for certain devices in TaurusForms. It is a dictionary with the following structure: device_class_name:(classname_with_full_module_path, args, kwargs) where the args and kwargs will be passed to the constructor of the class

T_FORM_ITEM_FACTORIES = {'exclude': (), 'include': ('.*',)}

  Default include and exclude patterns for `TaurusForm` item factories See `TaurusForm.setItemFactories` docs. By default, all available factories are enabled (and tried alphabetically)

USER_CFG_FILE = '/sbuild-nonexistent/.config/taurus/taurus.ini'

  Path to the user-specific config file