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]