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.