protokolo.config module

The global configuration of Protokolo.

protokolo.config.parse_toml(toml: str | IO[bytes], section: Sequence[str] | None = None) → dict[str, Any]

Parse a string representing a TOML file, and return a dictionary representing the defined section.

Parameters:

• toml – A TOML string or binary file object.

• sections – A list of nested sections, for example ["protokolo", "section"] to return the values of [protokolo.section]

Raises:

• TypeError – toml is not a valid type.

• tomllib.TOMLDecodeError – not valid TOML.

class protokolo.config.TOMLConfig(values: dict[str, str | int | float | bool | datetime | date | None | Mapping[str, TOMLValue] | list[TOMLType]] = NOTHING, source=None)

Bases: object

A utility class to hold data parsed from a TOML file.

Immediately after object instantiation, validate() is called.

source: str | None

classmethod from_dict(values: dict[str, Any], source: str | PathLike | None = None) → Self

Generate TOMLConfig from a dictionary containing the keys and values. This is useless for the TOMLConfig base class, but potentially useful for subclasses that change the __init__ signature.

Raises:

• DictTypeError – value isn’t an expected/supported type.

• DictTypeListError – if a list contains elements other than a dict.

as_dict() → dict[str, str | int | float | bool | datetime | date | None | Mapping[str, TOMLValue] | list[TOMLType]]

Return a mapping of the TOMLConfig.

validate() → None

Verify that all keys contain valid TOML types. This is automatically run on object instantiation.

Raises:

• DictTypeError – value isn’t an expected/supported type.

• DictTypeListError – if a list contains elements that aren’t supported.

class protokolo.config.SectionAttributes(values: dict[str, str | int | float | bool | datetime | date | None | Mapping[str, TOMLValue] | list[TOMLType]] = NOTHING, source=None, title: str = 'TODO: No section title defined', level: int = 1, order: int | None = None)

Bases: TOMLConfig

A data container to hold some metadata for a compile.Section object.

classmethod from_dict(values: dict[str, Any], source: str | PathLike | None = None) → Self

Generate SectionAttributes from a dictionary containing the keys and values.

Raises:

• AttributeNotPositiveError – one of the values should have been positive.

• DictTypeError – value isn’t an expected/supported type.

• DictTypeListError – if a list contains elements other than a dict.

validate() → None

Raises:

• AttributeNotPositiveError – one of the values should have been positive.

• DictTypeError – value isn’t an expected/supported type.

• DictTypeListError – if a list contains elements other than a dict.

property title: str

The title of a section. If no value is provided, it defaults to ‘TODO: No section title defined’.

property level: int

The level of the section heading, which must not be zero or lower.

property order: int | None

The order of the section in relation to others. It must not be zero or lower, and may be None, in which case it is alphabetically sorted after all sections that do have an order.

class protokolo.config.GlobalConfig(values: dict[str, str | int | float | bool | datetime | date | None | Mapping[str, TOMLValue] | list[TOMLType]] = NOTHING, source=None, changelog: str | None = None, markup: str | None = None, directory: str | None = None)

Bases: TOMLConfig

A container object for config values of the global .protokolo.toml file.

classmethod from_file(path: str | PathLike) → Self

Factory method to create a GlobalConfig from a path. The exact table that is loaded from the file depends on the file name. In pyproject.toml, the table [tool.protokolo] is loaded, whereas [protokolo] is loaded everywhere else.

Raises:

• OSError – if the file could not be opened.

• tomllib.TOMLDecodeError – if the file could not be decoded.

• DictTypeError – value isn’t an expected/supported type.

• DictTypeListError – if a list contains elements other than a dict.

classmethod find_config(directory: str | PathLike) → Path | None

In directory, find the config file.

The order of precedence (highest to lowest) is:

• .protokolo.toml

• pyproject.toml

property changelog: str | None

The path to the change log file.

property markup: str | None

The markup language used by the project.

property directory: str | None

The directory where the change log fragments are stored.