protokolo.compile module

Code to combine the files in changelog.d/ into a single text block.

class protokolo.compile.Fragment(text: str, source=None)

Bases: object

A fragment, analogous to a file.

text: str

source: PurePath | None

compile() → str

Compile the fragment. For the time being, this just means adding a newline at the end if one does not exist.

class protokolo.compile.Section(attrs: SectionAttributes = NOTHING, markup: Literal['markdown', 'restructuredtext'] = 'markdown', source=None)

Bases: object

A section, analogous to a directory.

attrs: SectionAttributes

markup: Literal['markdown', 'restructuredtext']

source: PurePath | None

fragments: set[Fragment]

subsections: set[Self]

classmethod from_directory(directory: str | PathLike, level: int = 1, markup: Literal['markdown', 'restructuredtext'] = 'markdown', section_format_pairs: dict[str, str] | None = None) → Self

Factory method to recursively create a Section from a directory.

Parameters:

• directory – The changelog.d directory.

• level – The level of the root Section. This is overridden by the level value in .protokolo.toml, if any.

• markup – The markup language.

• section_format_pairs – Additional key-value pairs used to format the section headings, applied recursively to all subsections.

Raises:

• OSError – input/output error.

• ProtokoloTOMLNotFoundError – .protokolo.toml doesn’t exist.

• ProtokoloTOMLIsADirectoryError – .protokolo.toml is not a file.

• tomllib.TOMLDecodeError – .protokolo.toml couldn’t be parsed.

• DictTypeError – .protokolo.toml fields have the wrong type.

• AttributeNotPositiveError – value in .protokolo.toml should be a positive integer.

compile() → str

Compile the entire section recursively, first printing the fragments in order, then the subsections.

Empty sections are not compiled.

Raises:

HeadingFormatError – could not format heading of section.

write_to_buffer(buffer: StringIO | None = None) → StringIO

Like compile, but writing to a StringIO buffer.

Raises:

HeadingFormatError – could not format heading of section.

is_empty() → bool

A Section is empty if it contains neither fragments nor subsections. If it contains no fragments, and its subsections are empty, then it is also considered empty.

sorted_fragments() → Iterator[Fragment]

Yield the fragments, ordered by their source. Fragments that do not have a source are sorted afterwards by their text.

sorted_subsections() → Iterator[Self]

Yield the subsections, first ordered by their order value, then the remainder sorted alphabetically.