Skip to content
Back to top
View this page

# 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.