`changelog` Module¶

Contains the Changelog class that represents a parsed changelog file that can be read from and written to disk as markdown, as well as the VersionEntry class that represents a single version within that changelog.

class VersionEntry(name: str = 'Unreleased', date: Optional[datetime.date] = None, tags: Optional[List[str]] = None, link: Optional[str] = None, link_id: Optional[str] = None, line_no: Optional[int] = None)¶

A serialized representation of a single version entry in a Changelog, containing the changes made since the previous version

Parameters

name (str) – The version’s name
date (Optional[datetime.date]) – When the version was released
tags – The version’s tags
link – The version’s URL
link_id – The version’s link ID
line_no – What line in the original file the version starts on

name: str¶: The version’s name

date: Optional[datetime.date]¶: When the version was released

tags: List[str]¶: The version’s tags

link: Optional[str]¶: The version’s URL

link_id: Optional[str]¶: The version’s link ID, uses the version name by default when writing

line_no: Optional[int]¶: What line the version occurs at in the file, or None if the version was not read from a file. This is not guaranteed to be correct after the changelog has been modified, and it has no effect on the written file

sections: Dict[str, List[str]]¶: The dictionary of change entries in the version, organized by section. Uncategorized changes have a section of an empty string.

classmethod from_header(header: str, line_no: Optional[int] = None) → yaclog.changelog.VersionEntry ¶

Create a new version entry from a markdown header

Parameters

header – A markdown header to parse
line_no – Line number the header is on

Returns

a new VersionEntry with the header’s information

add_entry(contents: str, section: str = '') → None ¶

Add a new entry to the version

Parameters

contents – The contents string to add
section – Which section to add to.

body(md: bool = True, color: bool = False) → str ¶

Get the version’s body as a string

Parameters

md – Format headings as markdown
color – Add color codes to the string for display in a terminal

Returns

The formatted version body, without the version header

header(md: bool = True, color: bool = False) → str ¶

Get the version’s header as a string

Parameters

md – Format headings as markdown
color – Add color codes to the string for display in a terminal

Returns

The formatted version header

text(md: bool = True, color: bool = False) → str ¶

Get the version’s contents as a string

Parameters

md – Format headings as markdown
color – Add color codes to the string for display in a terminal

Returns

The formatted version header and body

property released¶: Returns true if a PEP440 version number is present in the version name, and has no prerelease segments

property version¶: Returns the PEP440 version number from the version name, or None if none is found

class Changelog(path=None, preamble: str = '# Changelog\n\nAll notable changes to this project will be documented in this file')¶

A serialized representation of a Markdown changelog made up of a preamble, multiple versions, and a link table.

Contents will be automatically read from disk if the file exists

Parameters

path – The changelog’s path on disk.
preamble (str) – The changelog preamble to use if the file does not exist.

path¶: The path of the changelog’s file on disk

preamble: str¶: Any text at the top of the changelog before any version information, including the title. It can contain the title, an explanation of the file’s purpose, as well as any general machine-readable information for use with other tools.

versions: List[yaclog.changelog.VersionEntry]¶: A list of versions in the changelog, with the most recent version first

links: Dict[str, str]¶: Link definitions at the end of the changelog, as a dictionary of {id: url}

read(path=None) → None ¶

Read a markdown changelog file from disk. The object’s contents will be overwritten by the file contents if reading is successful.

Parameters: path – The changelog’s path on disk. By default, path is used

write(path=None) → None ¶

Write a changelog to a Markdown file.

Parameters: path – The changelog’s path on disk. By default, path is used.

add_version(index: int = 0, *args, **kwargs) → yaclog.changelog.VersionEntry ¶

Add a new version to the changelog

Parameters

index – Where to add the new version in the log. Defaults to the top
args – args to forward to the VersionEntry constructor
kwargs – kwargs to forward to the VersionEntry constructor

Returns

The created entry

current_version(released: Optional[bool] = None, new_version: bool = False, new_version_name: str = 'Unreleased') → yaclog.changelog.VersionEntry ¶

Get the current version from the changelog

Parameters

released – if the returned version should be a released version, an unreleased version, or None to return the most recent
new_version – if a new version should be created if none exist.
new_version_name – The name of the version to create if there are no matches and new_version is True.

Returns

The current version matching the criteria, or None if new_version is disabled and none are found.

get_version(name: Optional[str] = None) → yaclog.changelog.VersionEntry ¶

Get a version from the changelog by name.

Parameters: name – The name of the version to get, or None to return the most recent. The first version with this value in its name is returned.
Returns: The first version with the selected name

changelog Module¶

`changelog` Module¶