Configurator

class Configurator(local=True, user=True, default=True, **kwargs)

Bases: collections.abc.MutableMapping, dict

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

Parameters

• local (bool, optional) – Whether to load settings from the local_files file. Default is True.

• user (bool, optional) – Whether to load settings from the user_file file. Default is True.

• default (bool, optional) – Whether to reload built-in default ProPlot settings. Default is True.

Attributes Summary

changed

A dictionary of settings that have been changed from the ProPlot 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 local proplotrc files in this directory and in parent directories.
reset([local, user, default])	Reset the configurator to its initial state.
save([path, user, comment, backup, description])	Save the current settings to a proplotrc file.
update(*args, **kwargs)	Update several settings at once.
user_file()	Return location of the default proplotrc file.
user_folder([subfolder])	Return location of the default proplot folder.

Attributes Documentation

changed

A dictionary of settings that have been changed from the ProPlot defaults.

Methods Documentation

category(cat, *, trimcat=True, context=False)

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, optional) – Whether to trim cat from the key names in the output dictionary. Default is True.

• context (bool, optional) – If True, then each category setting that is not found in the context mode dictionaries is omitted from the output dictionary. See context.

See also

Configurator.find, Configurator.fill

context(*args, mode=0, file=None, **kwargs)

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

Parameters

• *args – Dictionaries of rc names 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:

0. Matplotlib’s rc_matplotlib settings and ProPlots rc_proplot settings are all returned, whether or not context has changed them.

1. Unchanged rc_matplotlib settings return None but rc_proplot settings are returned whether or not context has changed them. This is used in the __init__ call to format. When a lookup returns None, format does not apply it.

2. All unchanged settings return None. This is used during user calls to format.

Note

This is used by ProPlot internally but may also be useful for power users. It was invented to prevent successive calls to format from constantly looking up and re-applying unchanged settings. These gratuitous lookups increased runtime significantly, and resulted in successive calls to format overwriting the previous calls.

Example

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

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

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

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

fill(props, *, context=False)

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.

• context (bool, optional) – If True, then settings not found in the context mode dictionaries are excluded from the output dictionary. See context.

See also

Configurator.category, Configurator.find

find(key, *, context=False)

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

Parameters

• key (str) – The single setting name.

• context (bool, optional) – If True, then None is returned if the setting is not found in the context mode dictionaries. See context.

See also

Configurator.category, Configurator.fill

load(path)

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 and will be removed in a future release. Please use 'load' instead.", **kwargs)

static local_files()

Return locations of local proplotrc files in this directory and in parent directories.

reset(local=True, user=True, default=True, **kwargs)

Reset the configurator to its initial state.

Parameters

• local (bool, optional) – Whether to load settings from the local_files file. Default is True.

• user (bool, optional) – Whether to load settings from the user_file file. Default is True.

• default (bool, optional) – Whether to reload built-in default ProPlot settings. Default is True.

save(path=None, user=True, comment=None, backup=True, description=False)

Save the current settings to a proplotrc 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, optional) – The path. The default file name is proplotrc and the default directory is the current directory.

• user (bool, optional) – If True (the default), the settings you changed since importing proplot are shown uncommented at the very top of the file.

• backup (bool, optional) – If the file already exists and this is set to True, it is moved to a backup file with the suffix .bak.

• comment (bool, optional) – Whether to comment out the default settings. Default is the value of user.

• description (bool, optional) – Whether to include descriptions of each setting as comments. Default is False.

See also

Configurator.load

update(*args, **kwargs)

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, optional – rc keys and values passed as keyword arguments. If the name has dots, simply omit them.

See also

Configurator.category, Configurator.fill

static user_file()

Return location of the default proplotrc file. On Linux, this is either $XDG_CONFIG_HOME/proplot/proplotrc or ~/.config/proplot/proplotrc if the XDG directory is unset. On other operating systems, this is ~/.proplot/proplotrc. The location ~/.proplotrc or ~/.proplot/proplotrc is always returned if the file exists, regardless of the operating system. If multiple valid locations are found, a warning is raised.

static user_folder(subfolder=None)

Return location of the default proplot folder. On Linux, this is either $XDG_CONFIG_HOME/proplot or ~/.config/proplot if the XDG directory is unset. On other operating systems, this is ~/.proplot. The location ~/.proplot is always returned if the folder exists, regardless of the operating system. If multiple valid locations are found, a warning is raised.