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[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
- 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) 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
- 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[VersionEntry]
A list of versions in the changelog, with the most recent version first
- 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) 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
constructorkwargs – 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') 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 recentnew_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
ifnew_version
is disabled and none are found.
- get_version(name: Optional[str] = None) 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