Data model

class proclamation.project.Project(settings, ref_parser=None, default_base=None)

A project has sections and fragments.

property fragment_filenames

Return filenames for all fragments added in all sections.

populate_sections(ref_parser=None)

Load fragments associated with each section.

sections

List of all sections in this project. Do not modify.

class proclamation.types.Section(name, relative_directory=None, sort_by_prefix=False)

A section is a component/aspect of a project.

Changes for a Section are (potentially) separated out in the news file. For example, sections might include “Drivers”, “UI”, etc.

A section contains Fragment objects. They are typically populated from a directory of files through a call to populate_from_directory(). They are kept sorted.

add_fragment(fragment)

Add a fragment to this section.

This does not call fragment.parse_file(). However, populate_from_directory() is the usual place this gets called from, and it does call parse_file.

property fragment_filenames

Return a generator of filenames for all Fragment objects added.

populate_from_directory(directory, ref_parser)

Iterate through a directory, trying to parse each filename as a reference.

Files that parse properly are assumed to be fragments, and a Fragment object is instantiated for them. Files with multiple bullet points are considered to be multiple fragments.

class proclamation.types.Fragment(filename, reference: Reference | None = None, ref_parser=None, io=None)

A single changelog entry, provided as text to insert into the templates.

A fragment comes from a file or stream.

The fragment filename is parsed to provide one reference. Optionally, an extremely small subset of “YAML front matter” can be used to list additional references in the fragment file contents. Delimit the front matter with — both before and after, and place one reference per line (with or without leading -) between those delimiters.

ARBITRARY_MAX_PREFIX_LEN = 40

If the first colon in a fragment is after this many characters or more, we assume it’s not actually the prefix. It may instead be, for example, a URL included in the fragment text.

add_ref(s)

Parse a string as a reference and add it to this fragment.

parse_file() → List[Fragment]

Open the file and parse content, and front matter if any.

If io was provided at construction time, that is parsed instead.

If the file contains more than one bulleted item, a new fragment for each additional item beyond the first will be created and returned in a list.

property prefix

Get the colon-delimited prefix or first word of the content.

property ref

Get the first reference used for a fragment, which becomes an ID.

refs: List[Reference]

All references added for a fragment, including the first.

Do not modify manually.