Skip to content
Back to top
View this page

# VersionScanner

class chango.abc.VersionScanner

  Bases: `Collection`[`Version`]

  Abstract base class for a version scanner that can list available versions.

  Hint

  Objects of this class can be used as `Collection` of versions as returned by the `get_available_versions()` method.

  abstractmethod get_available_versions(start_from=None, end_at=None)

    Get the available versions.

    Important

    Unreleased changes must not be included in the returned version identifiers.

    Parameters:

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

      - end_at (`Version` | `str`, optional) – The version identifier to end at. If `None`, end at the latest available version, excluding unreleased changes.

    Returns:

      The available versions.

    Return type:

      Tuple[`Version`]

  abstractmethod get_changes(uid)

    Get the changes either for a given version identifier or all available.

    Hint

    To easily extract the UIDs from the change files, `chango.helpers.change_uid_from_file()` can be used.

    Important

    The returned UIDs must be in the order in which the changes were made.

    Parameters:

      uid (`Version` | `str` | `None`) – The version identifier to get the change files for. If `None`, get the change files for unreleased changes must be returned.

    Returns:

      UIDs of the changes corresponding to the version identifier.

    Return type:

      Tuple[`str`]

    Raises:

      ChanGoError – If the version with the given identifier is not available.

  abstractmethod get_latest_version()

    Get the latest version

    Returns:

      The latest version

    Return type:

      `Version`

    Raises:

      ChanGoError – If no versions are available.

  get_version(uid)

    Get the version with the given identifier.

    Hint

    The default implementation calls `get_available_versions()`. Implementations may override this method to provide a more efficient way to get the version.

    Parameters:

      uid (`str`) – The version identifier to get the version for.

    Returns:

      The version.

    Return type:

      `Version`

    Raises:

      ChanGoError – If the version with the given identifier is not available.

  abstractmethod has_unreleased_changes()

    Check if there are changes in the repository that are not yet released in a version.

    Returns:

      `True` if there are unreleased changes, `False` otherwise.

    Return type:

      `bool`

  invalidate_caches()

    Invalidate any internal caches that may be used by the implementation.

    Important

    - This method is not required to do anything if the implementation does not use any caches. By default, it does nothing.

    - This method is called by `chango.abc.ChanGo.release()` and `chango.abc.ChanGo.write_change_note()` after the respective operation has been completed. This gives the implementation the opportunity to clear any caches that may have been affected by the operation.

  abstractmethod is_available(uid)

    Check if the version with the given identifier is available.

    Tip

    `None` may be passed for convenience, but it’s recommended that an implementation calls `has_unreleased_changes()` internally.

    Parameters:

      uid (`Version` | `str` | `None`) – The version identifier to check.

  abstractmethod lookup_change_note(uid)

    Lookup a change note with the given identifier.

    Parameters:

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

    Returns:

      The metadata about the change note specifying the file

        path and version it belongs to.

    Return type:

      `chango.ChangeNoteInfo`

    Raises:

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