ChangeNote

class chango.abc.ChangeNote(slug, uid=None)

Bases: ABC

Abstract base class for a change note describing a single change in a software project.

Parameters:

• slug (str) – A short, human-readable identifier for the change note.

• uid (str) – A unique identifier for the change note. If not provided, a random identifier will be generated. Should be 8 characters long and consist of lowercase letters and digits.

classmethod build_from_github_event(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.

Return type:

CNT

Raises:

NotImplementedError – If the method is not implemented.

abstractmethod classmethod build_template(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) – The unique identifier for the change note or None to generate a random one.

Returns:

The ChangeNote object.

abstract property file_extension

The file extension to use when writing the change note to a file. The extension must not include the leading dot.

Type:

str

property file_name

The file name to use when writing the change note to a file.

classmethod from_bytes(slug, uid, data, encoding='utf-8')

Read a change note from the specified byte data. The data will be the raw binary content of a change note file.

Tip

This convenience method calls from_string() internally.

Parameters:

• slug (str) – The slug of the change note.

• uid (str) – The UID of the change note.

• data (bytes) – The bytes to read from.

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

Returns:

The ChangeNote object.

Return type:

ChangeNote

Raises:

chango.error.ValidationError – If the data is not a valid change note file.

classmethod from_file(file_path, encoding='utf-8')

Read a change note from the specified file.

Tip

This convenience method calls from_bytes() internally.

Parameters:

• file_path (pathlib.Path | str) – The path to the file to read from.

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

Returns:

The ChangeNote object.

Return type:

ChangeNote

Raises:

chango.error.ValidationError – If the data is not a valid change note file.

abstractmethod classmethod from_string(slug, uid, string)

Read a change note from the specified string data. The implementation must be able to handle the case where the string is not a valid change note and raise an ValidationError in that case.

Parameters:

• slug (str) – The slug of the change note.

• uid (str) – The UID of the change note.

• string (str) – The string to read from.

Returns:

The ChangeNote object.

Return type:

ChangeNote

Raises:

chango.error.ValidationError – If the string is not a valid change note.

property slug

The short, human-readable identifier for the change note.

Type:

str

to_bytes(encoding='utf-8')

Write the change note to bytes. This binary data should be suitable for writing to a file and reading back in with from_bytes().

Tip

This convenience method calls to_string() internally.

Parameters:

encoding (str) – The encoding to use.

Returns:

The bytes data.

Return type:

bytes

to_file(directory=None, encoding='utf-8')

Write the change note to the directory.

Hint

The file name will always be the file_name.

Parameters:

• directory – Optional. The directory to write the file to. If not provided, the file will be written to the current working directory.

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

Returns:

The path to the file that was written.

Return type:

pathlib.Path

abstractmethod to_string(encoding='utf-8')

Write the change note to a string. This string should be suitable for writing to a file and reading back in with from_string().

Parameters:

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

Returns:

The string data.

Return type:

str

property uid

The unique identifier for the change note.

Type:

str

update_uid(uid)

Update the UID of the change note. Use with caution.

Parameters:

uid (str) – The new UID to use.