Configurator

class Configurator(local=True, user=True, default=True, **kwargs)[source]

Bases: MutableMapping, dict

A dictionary-like class for managing matplotlib settings stored in rc_matplotlib and ultraplot settings stored in rc_ultraplot. This class is instantiated as the rc object on import. See the user guide for details.

Parameters:

local (bool, default: True) – Whether to load settings from the local_files file.
user (bool, default: True) – Whether to load settings from the user_file file.
default (bool, default: True) – Whether to reload built-in default ultraplot settings.

Attributes Summary

changed

A dictionary of settings that have changed from the ultraplot defaults.

Methods Summary

`category`(cat, *[, trimcat, context])	Return a dictionary of settings beginning with the substring `cat + '.'`.
`context`(*args[, mode, file])	Temporarily modify the rc settings in a "with as" block.
`fill`(props, *[, context])	Return a dictionary filled with settings whose names match the string values in the input dictionary.
`find`(key, *[, context])	Return a single setting.
`load`(path)	Load settings from the specified file.
`load_file`(*[, new_obj, message])
`local_files`()	Return locations of files named `ultraplotrc` in this directory and in parent directories.
`local_folders`([subfolder])	Return locations of folders named `ultraplot_cmaps`, `ultraplot_cycles`, `ultraplot_colors`, and `ultraplot_fonts` in this directory and in parent directories.
`register_handler`(name, func)	Register a callback function to be executed when a setting is modified.
`reset`([local, user, default])	Reset the configurator to its initial state.
`save`([path, user, comment, backup, description])	Save the current settings to a `ultraplotrc` file.
`update`(args, *kwargs)	Update several settings at once.
`user_file`()	Return location of the default ultraplotrc file.
`user_folder`([subfolder])	Return location of the default ultraplot folder.

Attributes Documentation

changed: A dictionary of settings that have changed from the ultraplot defaults.

See also

Configurator.save

Methods Documentation

category(cat, *, trimcat=True, context=False)[source]

Return a dictionary of settings beginning with the substring cat + '.'. Optionally limit the search to the context level.

Parameters:

cat (str, optional) – The rc setting category.
trimcat (bool, default: True) – Whether to trim cat from the key names in the output dictionary.
context (bool, default: False) – If True, then settings not found in the context dictionaries are omitted from the output dictionary. See context.

context(*args, mode=0, file=None, **kwargs)[source]

Temporarily modify the rc settings in a “with as” block.

Parameters:

*args – Dictionaries of rc keys and values.
file (path-like, optional) – Filename from which settings should be loaded.
**kwargs – rc names and values passed as keyword arguments. If the name has dots, simply omit them.

Other Parameters:

mode ({0, 1, 2}, optional) – The context mode. Dictates the behavior of find, fill, and category within a “with as” block when called with context=True.

The options are as follows:

mode=0: Matplotlib’s rc_matplotlib settings and ultraplot’s rc_ultraplot settings are all returned, whether or not they are local to the “with as” block.
mode=1: Matplotlib’s rc_matplotlib settings are only returned if they are local to the “with as” block. For example, if rc['axes.titlesize'] was passed to context, then uplt.rc.find('axes.titlesize', context=True) will return this value, but uplt.rc.find('axes.titleweight', context=True) will return None. This is used internally when instantiating axes.
mode=2: Matplotlib’s rc_matplotlib settings and ultraplot’s rc_ultraplot settings are only returned if they are local to the “with as” block. This is used internally when formatting axes.

Note

Context “modes” are primarily used internally but may also be useful for power users. Mode 1 is used when format is called during axes instantiation, and mode 2 is used when format is manually called by users. The latter prevents successive calls to format from constantly looking up and re-applying unchanged settings and significantly increasing the runtime.

Example

The below applies settings to axes in a specific figure using context.

>>> import ultraplot as uplt
>>> with uplt.rc.context(ticklen=5, metalinewidth=2):
>>>     fig, ax = uplt.subplots()
>>>     ax.plot(data)

The below applies settings to a specific axes using format, which uses context internally.

>>> import ultraplot as uplt
>>> fig, ax = uplt.subplots()
>>> ax.format(ticklen=5, metalinewidth=2)

fill(props, *, context=False)[source]

Return a dictionary filled with settings whose names match the string values in the input dictionary. Optionally limit the search to the context level.

Parameters:

props (dict-like) – Dictionary whose values are setting names – for example rc.fill({'edgecolor': 'axes.edgecolor', 'facecolor': 'axes.facecolor'}).
context (bool, default: False) – If True, then settings not found in the context dictionaries are omitted from the output dictionary. See context.

find(key, *, context=False)[source]

Return a single setting. Optionally limit the search to the context level.

Parameters:

key (str) – The single setting name.
context (bool, default: False) – If True, then None is returned if the setting is not found in the context dictionaries. See context.

load(path)[source]

Load settings from the specified file.

Parameters:: path (path-like) – The file path.

See also

Configurator.save

load_file(*, new_obj=<function Configurator.load>, message="'load_file' was deprecated in version 0.8.0 and may be removed in the next major release (version 2.0.0). Please use 'load' instead.", **kwargs)

static local_files()[source]: Return locations of files named ultraplotrc in this directory and in parent directories. “Hidden” files with a leading dot are also recognized. These are automatically loaded when ultraplot is imported.

See also

Configurator.user_file, Configurator.local_folders

static local_folders(subfolder=None)[source]: Return locations of folders named ultraplot_cmaps, ultraplot_cycles, ultraplot_colors, and ultraplot_fonts in this directory and in parent directories. “Hidden” folders with a leading dot are also recognized. Files in these directories are automatically loaded when ultraplot is imported.

See also

Configurator.user_folder, Configurator.local_files

register_handler(name: str, func: Callable[[Any], Dict[str, Any]]) → None[source]

Register a callback function to be executed when a setting is modified.

This is an extension point for “special” settings that require complex logic or have side-effects, such as updating other matplotlib settings. It is used internally to decouple the configuration system from other subsystems and avoid circular imports.

namestr
The name of the setting (e.g., 'cycle').

funccallable
The handler function to be executed. The function must accept a single positional argument, which is the new value of the setting, and must return a dictionary. The keys of the dictionary should be valid matplotlib rc setting names, and the values will be applied to the rc_matplotlib object.
>>> def _cycle_handler(value):
...     # ... logic to create a cycler object from the value ...
...     return {'axes.prop_cycle': new_cycler}
>>> rc.register_handler('cycle', _cycle_handler)

reset(local=True, user=True, default=True, **kwargs)[source]

Reset the configurator to its initial state.

Parameters:

local (bool, default: True) – Whether to load settings from the local_files file.
user (bool, default: True) – Whether to load settings from the user_file file.
default (bool, default: True) – Whether to reload built-in default ultraplot settings.

save(path=None, user=True, comment=None, backup=True, description=False)[source]

Save the current settings to a ultraplotrc file. This writes the default values commented out plus the values that differ from the defaults at the top of the file.

Parameters:

path (path-like, default: 'ultraplotrc') – The file name and/or directory. The default file name is ultraplotrc and the default directory is the current directory.
user (bool, default: True) – If True then settings that have been changed from the ultraplot defaults are shown uncommented at the top of the file.
backup (bool, default: True) – Whether to “backup” an existing file by renaming with the suffix .bak or overwrite an existing file.
comment (bool, optional) – Whether to comment out the default settings. If not passed this takes the same value as user.
description (bool, default: False) – Whether to include descriptions of each setting (as seen in the user guide table) as comments.

update(*args, **kwargs)[source]

Update several settings at once.

Parameters:

*args (str or dict-like, optional) – A dictionary containing rc keys and values. You can also pass a “category” name as the first argument, in which case all settings are prepended with 'category.'. For example, rc.update('axes', labelsize=20, titlesize=20) changes the rc['axes.labelsize'] and rc['axes.titlesize'] settings.
**kwargs – rc keys and values passed as keyword arguments. If the name has dots, simply omit them.

static user_file()[source]: Return location of the default ultraplotrc file. On Linux, this is either $XDG_CONFIG_HOME/ultraplot/ultraplotrc or ~/.config/ultraplot/ultraplotrc if the XDG directory is unset. On other operating systems, this is ~/.ultraplot/ultraplotrc. The location ~/.ultraplotrc or ~/.ultraplot/ultraplotrc is always returned if the file exists, regardless of the operating system. If multiple valid locations are found, a warning is raised.

See also

Configurator.user_folder, Configurator.local_files

static user_folder(subfolder=None)[source]: Return location of the default ultraplot folder. On Linux, this is either $XDG_CONFIG_HOME/ultraplot or ~/.config/ultraplot if the XDG directory is unset. On other operating systems, this is ~/.ultraplot. The location ~/.ultraplot is always returned if the folder exists, regardless of the operating system. If multiple valid locations are found, a warning is raised.

See also

Configurator.user_file, Configurator.local_folders