`breadcord.config`¶

`Setting`¶

Bases: SettingsNode, Generic[_T]

A single setting key-value pair, plus metadata such as the setting description.

A :class:Setting instance is equivalent to a leaf node in a tree structure, or a file in a filesystem.

The data type of the setting is inferred from the initial value's data type, and it is enforced in subsequent writes to the value of this setting.

Parameters:

Name	Type	Description	Default
`key`	`str`	The identifier used for this node by the parent node in the settings tree.	required
`value`	`_T`	The value for the setting to hold.	required
`description`	`str`	A description of the setting, usually specified in the settings schema using TOML comments.	`''`
`parent`	`SettingsGroup \| None`	The parent node, or `None` if it is a root node.	`None`
`in_schema`	`bool`	Whether the setting is present in the settings schema.	`False`

Attributes:

Name	Type	Description
`type`	`type`	The data type held by the setting.

`valuepropertywritable`¶

The value held by the setting.

`observe(observer=None, *, always_trigger=False)`¶

Register an observer function which is called whenever the setting value is updated.

This method can be used as a decorator, with optional parentheses for arguments.

Parameters:

Name	Type	Description	Default
`observer`	`Callable[[Any, Any], Any] \| None`	The callback function. Takes two parameters `old` and `new`, which correspond to the value of the setting before and after it is updated respectively.	`None`
`always_trigger`	`bool`	If the observer should be called even if the updated value is equal to the previous value.	`False`

`SettingsGroup`¶

Bases: SettingsNode

A collection of :class:Setting and child :class:SettingsGroup instances.

A :class:SettingsGroup instance is equivalent to a parent node in a tree structure, or a directory in a filesystem.

Parameters:

Name	Type	Description	Default
`key`	`str`	The identifier used for this node by the parent node in the settings tree.	required
`settings`	`list[Setting] \| None`	A list of settings to add to this settings group.	`None`
`children`	`list[SettingsGroup] \| None`	A list of :class:`SettingsGroup` nodes to attach to this node as children.	`None`
`parent`	`SettingsGroup \| None`	The parent node, or `None` if it is a root node.	`None`
`in_schema`	`bool`	Whether the setting is present in the settings schema.	`False`
`schema_path`	`str \| PathLike[str] \| None`	The path to a settings schema to apply to this settings group.	`None`
`observers`	`dict[str, list[Callable[[Any, Any], None]]] \| None`	The :class:`dict` of observers to assign the node. Should only be specified for root nodes.	`None`

`add_child(child)`¶

Set a child :class:SettingsGroup object as a child node to the current node.

Parameters:

Name	Type	Description	Default
`child`	`SettingsGroup`	The settings group to attach as a child node.	required

`as_toml(*, table=False, warn_schema=True)`¶

as_toml(*, table: Literal[False], warn_schema: bool = True) -> TOMLDocument

as_toml(*, table: Literal[True], warn_schema: bool = True) -> Table

Export the descendent settings as a :class:TOMLDocument or :class:Table instance.

This method works recursively on any settings which have a value of a :class:SettingsGroup instance, adding them to the TOML document as tables.

Parameters:

Name	Type	Description	Default
`table`	`bool`	Whether a table should be generated instead of a document.	`False`
`warn_schema`	`bool`	Whether settings not declared in the schema should warn the user.	`True`

`get(key, default=None)`¶

Get a :class:Setting object by its key.

:class:SettingsGroup implements __getattr__, so a setting can be accessed by attribute as a shortcut. For example, settings.debug can be used instead of settings.get('debug').

Parameters:

Name	Type	Description	Default
`key`	`str`	The key for the setting (the identifier before the equals sign in a TOML document).	required
`default`	`_T`	The value to return if the key doesn't exist, by default `None`.	`None`

Returns:

Type	Description
`Setting \| _T`	The setting object if it exists, otherwise the default value.

`get_child(key, allow_new=False)`¶

Get a child :class:SettingsGroup object by its key.

:class:SettingsGroup implements __getattr__, so a child node can be accessed by attribute as a shortcut. For example, settings.ExampleModule can be used instead of settings.get_child('ExampleModule').

Parameters:

Name	Type	Description	Default
`key`	`str`	The key for the child group.	required
`allow_new`	`bool`	Whether a new :class:`SettingsGroup` instance should be created if it doesn't exist.	`False`

`load_schema(*, file_path=None, body=None)`¶

load_schema(*, file_path: str | PathLike[str] | None = None, body: None = None) -> None

load_schema(*, file_path: None = None, body: list[tuple[Key | None, Item]]) -> None

Load and deserialise a settings schema, for the settings to follow.

Parameters:

Name	Type	Description	Default
`file_path`	`str \| PathLike[str] \| None`	Path to the schema file.	`None`
`body`	`list[tuple[Key \| None, Item]] \| None`	The parsed TOML body data to interpret as. Overrides loading from `file_path` when present.	`None`

`set(key, value, *, strict=True)`¶

Set the value for a setting by its key, creating new settings as necessary if not using strict mode.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key for the setting (the identifier before the equals sign in a TOML document).	required
`value`	`Any`	The new value to set for the setting.	required
`strict`	`bool`	Whether :class:`KeyError` should be thrown when the key doesn't exist in the schema.	`True`

`update_from_dict(data, *, strict=True)`¶

Recursively sets settings from a provided :class:dict object.

Note that new :class:SettingsGroup instances will be created as necessary to match the structure of the :class:dict, regardless of the value of strict.

Parameters:

Name	Type	Description	Default
`data`	`dict`	A dict containing key-value pairs.	required
`strict`	`bool`	Whether :class:`KeyError` should be thrown when a key doesn't exist, instead of creating a new setting.	`True`

`walk(*, skip_groups=False, skip_settings=False)`¶

Recursively traverses all child nodes and returns them as a flat list.

Parameters:

Name	Type	Description	Default
`skip_groups`	`bool`	Whether :cls:`SettingsGroup` objects should be skipped	`False`
`skip_settings`	`bool`	Whether :cls:`Setting` objects should be skipped	`False`

`SettingsNode`¶

An abstract base class representing a node in a settings tree structure.

This class is subclassed by :class:Setting and :class:SettingsGroup.

Parameters:

Name	Type	Description	Default
`key`	`str`	The identifier used for this node by the parent node in the settings tree.	required
`parent`	`SettingsGroup \| None`	The parent node, or `None` if it is a root node.	`None`
`in_schema`	`bool`	Whether the node is present in the settings schema.	`False`

Attributes:

Name	Type	Description
`description`		A description of the node, usually specified in the settings schema using TOML comments.
`parent`		The parent node, or `None` if it is a root node.
`in_schema`		Whether the node is present in the settings schema.

`keyproperty`¶

The identifier used for this node by the parent node in the settings tree.

`path()`¶

Return a series of node references representing the path to this node from the root node.

`path_id()`¶

Return a string identifier representing the path to this node from the root node.

`root()`¶

Return the root node of the settings tree this node belongs to.

This method is equivalent to calling node.path()[0].

`load_toml(file_path)`¶

Load and deserialise a TOML file into a :class:TOMLDocument instance.

Parameters:

Name	Type	Description	Default
`file_path`	`str \| PathLike[str]`	Path to the TOML file.	required

Returns:

Type	Description
`dict[str, Any]`	A dict structure representing the hierarchy of the TOML document.

`parse_schema_chunk(chunk)`¶

Convert a TOMLDocument.body chunk representing a single schema setting into a :class:Setting instance.

Any comments located before the key-value pair will be used for the setting's description.

Parameters:

Name	Type	Description	Default
`chunk`	`list[tuple[Key \| None, Item]]`	A sub-list of TOMLDocument.body. Must contain one key-value pair.	required

breadcord.config¶

Setting¶

valuepropertywritable¶

observe(observer=None, *, always_trigger=False)¶

SettingsGroup¶

add_child(child)¶

as_toml(*, table=False, warn_schema=True)¶

get(key, default=None)¶

get_child(key, allow_new=False)¶

load_schema(*, file_path=None, body=None)¶

set(key, value, *, strict=True)¶

update_from_dict(data, *, strict=True)¶

walk(*, skip_groups=False, skip_settings=False)¶

SettingsNode¶

keyproperty¶

path()¶

path_id()¶

root()¶

load_toml(file_path)¶

parse_schema_chunk(chunk)¶

`breadcord.config`¶

`Setting`¶

`valuepropertywritable`¶

`observe(observer=None, *, always_trigger=False)`¶

`SettingsGroup`¶

`add_child(child)`¶

`as_toml(*, table=False, warn_schema=True)`¶

`get(key, default=None)`¶

`get_child(key, allow_new=False)`¶

`load_schema(*, file_path=None, body=None)`¶

`set(key, value, *, strict=True)`¶

`update_from_dict(data, *, strict=True)`¶

`walk(*, skip_groups=False, skip_settings=False)`¶

`SettingsNode`¶

`keyproperty`¶

`path()`¶

`path_id()`¶

`root()`¶

`load_toml(file_path)`¶

`parse_schema_chunk(chunk)`¶