ChanGo

class chango.abc.ChanGo

Bases: ABC, Generic

Abstract base class for loading ChangeNote, VersionNote and VersionHistory objects as well as writing ChangeNote objects. This class holds the main interface for interacting with the version history and change notes.

build_github_event_change_note(event, data=None)

Build a change note from a GitHub event.

Important

This is an optional method and by default raises a NotImplementedError. Implement this method if you want to automatically create change notes based on GitHub events.

Tip

This method is useful for automatically creating change note drafts in GitHub actions to ensure that each pull request has documented changes.

See also

GitHub Actions

Parameters:

• event (Dict[str, Any]) – The GitHub event data. This should be one of the events that trigger workflows. The event is represented as a JSON dictionary.

• data (Dict[str, Any] | chango.action.ChanGoActionData, optional) – Additional data that may be required to build the change note.

Returns:

The change note or None if no

change note should be created (e.g., if a change note is already available) for the change.

Return type:

CNT | None

Raises:

NotImplementedError – If the method is not implemented.

abstractmethod build_template_change_note(slug, uid=None)

Build a template change note for the concrete change note type.

Tip

This will be used to create a new change note in the CLI.

Parameters:

• slug (str) – The slug to use for the change note.

• uid (str, optional) – The unique identifier for the change note or None to generate a random one.

Returns:

The ChangeNote object.

Return type:

CNT

abstractmethod build_version_history()

VHT: Build a new empty version history.

abstractmethod build_version_note(version)

Build a new empty version note.

Parameters:

version (Version | None) – The version of the software project this note is for. May be None if the version is not yet released.

Returns:

The VersionNote object.

Return type:

VNT

abstractmethod get_write_directory(change_note, version)

Determine the directory to write a change note to.

Important

• It should be ensured that the directory exists.

• The version does not need to be already available. In that case, it’s expected that version is of type Version.

Parameters:

• change_note (CNT | str) – The change note to write or its UID.

• version (Version | str | None) – The version the change note belongs to. Maybe be None if the change note is not yet released.

Returns:

The directory to write the change note to.

Return type:

pathlib.Path

Raises:

ChanGoError – If the version is a str but not yet available.

abstractmethod load_change_note(uid)

Load a change note with the given identifier.

Parameters:

uid (str) – The unique identifier or file name of the change note to load.

Returns:

The ChangeNote object.

Return type:

CNT

Raises:

ChanGoError – If the change note with the given identifier is not available.

load_version_history(start_from=None, end_at=None)

Load the version history.

Important

By default, unreleased changes are included in the returned version history, if available.

Parameters:

• start_from (Version | str, optional) – The version to start from. If None, start from the earliest available version.

• end_at (Version | str, optional) – The version to end at. If None, end at the latest available version, including unreleased changes.

Returns:

The loaded version VersionHistory.

Return type:

VHT

load_version_note(version)

Load a version note.

Parameters:

version (Version | str | None) – The version of the version note to load or the corresponding uid. May be None if the version is not yet released.

Returns:

The loaded VersionNote.

Return type:

VNT

Raises:

ChanGoError – If the version is not available.

release(version)

Release a version. This calls get_write_directory() for all unreleased change notes and moves the file if necessary.

Tip

This method calls chango.abc.VersionScanner.invalidate_caches() after releasing the version.

Parameters:

version (Version) – The version to release.

Returns:

Whether a release was performed. If no unreleased changes are available, this method returns False.

Return type:

bool

abstract property scanner

The VersionScanner used by this instance.

Type:

VST

write_change_note(change_note, version, encoding='utf-8')

Write a change note to disk.

Important

The version does not need to be already available. In that case, it’s expected that version is of type Version.

Tip

This method calls chango.abc.VersionScanner.invalidate_caches() after writing the change note to disk.

Parameters:

• change_note (CNT | str) – The change note to write.

• version (Version | str | None) – The version the change note belongs to. Maybe be None if the change note is not yet released.

• encoding (str) – The encoding to use for writing.

Returns:

The file path the change note was written to.

Return type:

pathlib.Path

Raises:

ChanGoError – If the version is a str but not yet available.