Skip to content
Back to top
View this page

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