Change Log

Helper utilities for manipulating a Zoo package changelog build for RST/Sphinx.

Zoo ChangeLog has a certain syntax which we’ll outline here.

A changelog is made up of 4 primary sections.

Type	Token	Description
Header	====	Token Surrounds the header label, defaults to “Changelog”.
Version	—-	Underlined with “—-” And Version is in the format of “{version} (year-month-day)”.
Category	~~~~	underlined with “~~~~” either “Added”, “Changes”, “Bug, “Removed”
ChangeMessage	- (messageTopicOrLabel) message body	The formatted message which occurred.

Example Changelog Output:

=========
ChangeLog
=========

1.2.13 (2022-01-2022)
---------------------

Added
~~~~~

Added - (docs) Pycharm setup documentation for zoo tools.
Added - (docs) sphinxcontrib.youtube thirdparty dependency when build docs to support youtube and vimeo links.

Bug Fixes
~~~~~~~~~
BugFix - (MayaPlugin) Fix FileNotFoundError being raised due to incorrect zoo initialization order.

class Changelog(label)

Bases: object

Interface to manage changelog versions and output rst lines via asRstLines.

Parameters:: label (str) – The changelog header label ie. ChangeLog.

children()

Returns the child versions in the order they were added.

Return type:: iterable[ChangelogVersion]

sortedVersions()

Returns a sorted tuple by the version. version sorting using stdlib LooseVersion instances.

Return type:: tuple[str, ChangelogVersion]

printTree(): Simply does a formatted print statement for visual debugging of the changelog hierarchy.

asRstLines()

Returns a formatted flatten list of rst lines which can be written directly into a file.

This doesn’t include newlines. This loops through all current versions, categories and changes and flattens everything.

Return type:: list[str]

class ChangelogVersion(version, date, changelog)

Bases: object

A Single Version in the changelog which manages and sorts categories.

Parameters:

version (str) – The version str ie. 1.0.0. casts to version.LooseVersion.
date (str) – The date that the version was created.
changelog (ChangeLog) – The current changelog instance this version is linked too.

classmethod parseString(st, changelog)

property label

Returns a formatted label ie. 1.0.0 (2022-01-18)

Return type:: str

children()

Returns all child categories in the same order they were added.

Return type:: list[ChangelogCategory]

asRstLines()

Does the same as Changelog.asRstLines but just for the version.

Return type:: list[str]

class ChangelogCategory(changelogVersion, label)

Bases: object

Wraps a Category which contains a list of messages/changes.

Parameters:

changelogVersion (ChangelogVersion) – The version instance which the category is linked too.
label (str)

children()

Returns a list of messages in the order they were added.

Return type:: list[ChangeMessage]

sortMessages()

Sorts and returns current change messages for the category.

Return type:: list[ChangeMessage]

asRstLines()

Does the same as Changelog.asRstLines but just for the category.

Return type:: list[str]

class ChangeMessage(label, subject, body)

Bases: object

Single line message which includes a subject and body.

The output of rst is the below.:

- (subject) body

Parameters:

label (str) – The original string which includes the subject and body of the message.
subject (str) – The subject of the message when converted to rst this will be surround with ().
body (str) – The message body.

classmethod parseString(st)

asRst()

Returns a formatted rst line in the form:

- (label) body

Return type:: str

parseChangelog(changelog)

Providing a changelog as a raw string this function will return a changelog instance.

Parameters:: changelog (str) – The raw string for a RST changelog
Return type:: Changelog

parseChangeLogFile(f)

Providing a changelog File object will generate a Changelog instance.

Parameters:: f (file) – The file instance
Return type:: Changelog

createRstTitle(beforeToken, title, afterToken)

Generates Rst title based on the before and after title

# creates the below ignoring "#"
# -------
# myTitle
# -------
createRstTitle("-", "myTitle", "-")

# creates the below ignoring "#"

# myTitle
# -------
createRstTitle(None, "myTitle", "-")

Parameters:

beforeToken (str) – The token to use for the previous line before the title.
title (str) – The title to use can be any string.
afterToken (str) – The token to use for the next line after the title.

Returns:

MultiLine string.

Return type:

str

parseCategory(cat)

Converts a category label ie. bug to a standardized name for the rst changelog.

Parameters:: cat (str) – category label
Return type:: str

iterChangelog(node)

Generator function which iterators the change log starting from node

Parameters:: node (Changelog or ChangelogVersion or ChangelogCategory or ChangelogMessage)
Returns:
Return type:: list[Changelog or ChangelogVersion or ChangelogCategory or ChangelogMessage]