versions
versions
Get information from git tags, commit hashes, and GitHub releases.
Functions
| Name | Description |
|---|---|
| check_version_increments_by_one | Checks if the next version increments by exactly 1 digit from the current version. |
| get_current_hash | Get the current commit hash. |
| get_latest_release_hash | Get the commit hash of the latest release. |
| get_latest_release_tag | Get the tag name of the latest release. |
| get_major_minor_version | Extract the major and minor version from a semantic versioning string. |
| get_releases | Get a list of releases from GitHub. |
| get_tag_hash | Retrieve the commit hash associated with a specific tag in a GitHub repository. |
| is_ancestor | Check if one commit is an ancestor of another. |
| match_semver | Match a version string against the semantic versioning pattern. |
check_version_increments_by_one
versions.check_version_increments_by_one(
current_version,
next_version,
with_leading_v=False,
error_on_false=True,
debug=False,
)Checks if the next version increments by exactly 1 digit from the current version.
Ensures that the next version follows semantic versioning guidelines and increments only one of the major, minor, or patch numbers by 1.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| current_version | str | The current version string. | required |
| next_version | str | The proposed next version string. | required |
| with_leading_v | bool | If True, expects the version strings to start with ‘v’. Defaults to False. | False |
| error_on_false | bool | If True, raises a ValueError when the check fails. Defaults to True. | True |
| debug | bool | If True, prints debug information. Defaults to False. | False |
Returns
| Name | Type | Description |
|---|---|---|
| bool | True if the next version increments by exactly one, False otherwise. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If the next version does not match semantic versioning guidelines or does not increment by exactly one. |
Examples
>>> check_version_increments_by_one("1.0.0", "1.0.1")
True
>>> check_version_increments_by_one("1.0.0", "1.1.0")
True
>>> check_version_increments_by_one("1.0.0", "2.0.0")
True
>>> check_version_increments_by_one("1.0.0", "1.0.2")
False
>>> check_version_increments_by_one("1.0.0", "1.2.0")
False
>>> check_version_increments_by_one("1.0.0", "3.0.0")
Falseget_current_hash
versions.get_current_hash()Get the current commit hash.
Uses git rev-parse HEAD to get the current commit hash.
Returns
| Name | Type | Description |
|---|---|---|
| str | The current commit hash. |
See Also
get_latest_release_hash : Get the commit hash of the latest release.
Examples
>>> get_current_hash()
'abc123def4567890abcdef1234567890abcdef12'get_latest_release_hash
versions.get_latest_release_hash(repo='CCBR/Tools')Get the commit hash of the latest release.
Uses git rev-list to get the commit hash of the latest release tag.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| repo | str | The GitHub repository in the format ‘owner/repo’. Default: ‘CCBR/Tools’ | 'CCBR/Tools' |
Returns
| Name | Type | Description |
|---|---|---|
| str | The commit hash of the latest release. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If the tag is not found in the repository commit history. |
See Also
get_latest_release_tag: Get the tag name of the latest release.
Examples
>>> get_latest_release_hash()
'abc123def4567890abcdef1234567890abcdef12'get_latest_release_tag
versions.get_latest_release_tag(repo='CCBR/Tools')Get the tag name of the latest release.
Uses the GitHub CLI to retrieve the latest release tag from a repository.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| args | str | Additional arguments to pass to the GitHub CLI command (default is ““). | required |
Returns
| Name | Type | Description |
|---|---|---|
| str or None: The tag name of the latest release, or None if no latest release is found. |
See Also
get_releases: Get a list of releases from GitHub.
Examples
>>> get_latest_release_tag()
'v1.0.0'get_major_minor_version
versions.get_major_minor_version(
version_str,
with_leading_v=False,
strict_semver=True,
)Extract the major and minor version from a semantic versioning string.
See the semantic versioning guidelines: https://semver.org/
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| version_str | str | The version string to extract from. | required |
| with_leading_v | bool | Whether to include a leading ‘v’ in the output. | False |
| strict_semver | bool | If True, the version string must match the full semantic versioning pattern. Otherwise, a relaxed format with only the major and minor components is allowed. | True |
Returns
| Name | Type | Description |
|---|---|---|
| str or None: The major and minor version in the format ‘major.minor’, or None if the version string is invalid. |
See Also
match_semver: Match a version string against the semantic versioning pattern.
Examples
>>> get_major_minor_version("1.0.0")
'1.0'
>>> get_major_minor_version("2.1.3-alpha")
'2.1'
>>> get_major_minor_version("invalid_version")
None
>>> get_major_minor_version('3.1', strict_semver=False)get_releases
versions.get_releases(
limit=1,
args='',
json_fields='name,tagName,isLatest,publishedAt',
)Get a list of releases from GitHub.
Uses the GitHub CLI to retrieve a list of releases from a repository. You will need to install it before you can use this function.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| limit | int | The maximum number of releases to retrieve (default is 1). | 1 |
| args | str | Additional arguments to pass to the GitHub CLI command (default is ““). | '' |
| json_fields | str | The JSON fields to include in the output (default is “name,tagName,isLatest,publishedAt”). | 'name,tagName,isLatest,publishedAt' |
Returns
| Name | Type | Description |
|---|---|---|
| list | A list of dictionaries containing release information. |
See Also
get_latest_release_tag : Get the tag name of the latest release. get_latest_release_hash : Get the commit hash of the latest release.
Notes
gh cli docs: https://cli.github.com/manual/gh_release_list
Examples
>>> get_releases(limit=2)
[{'name': 'v1.0.0', 'tagName': 'v1.0.0', 'isLatest': True, 'publishedAt': '2021-01-01T00:00:00Z'},
{'name': 'v0.9.0', 'tagName': 'v0.9.0', 'isLatest': False, 'publishedAt': '2020-12-01T00:00:00Z'}]
>>> get_releases(limit=2, args="--repo CCBR/RENEE")
[{'isLatest': True, 'name': 'RENEE 2.5.12', 'publishedAt': '2024-04-12T14:49:11Z', 'tagName': 'v2.5.12'},
{'isLatest': False, 'name': 'RENEE 2.5.11', 'publishedAt': '2024-01-22T21:02:30Z', 'tagName': 'v2.5.11'}]get_tag_hash
versions.get_tag_hash(tag_name, args='', repo='CCBR/Tools')Retrieve the commit hash associated with a specific tag in a GitHub repository. Args: tag_name (str): The name of the tag for which the commit hash is to be retrieved. repo (str, optional): The GitHub repository in the format ‘owner/repo’. Defaults to ‘CCBR/Tools’. Returns: str: The commit hash (SHA) associated with the specified tag. Raises: requests.exceptions.RequestException: If there is an issue with the HTTP request. KeyError: If the expected data is not found in the API response.
is_ancestor
versions.is_ancestor(ancestor, descendant)Check if one commit is an ancestor of another.
Uses git merge-base –is-ancestor to determine if the ancestor is an ancestor of the descendant.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| ancestor | str | The commit hash of the potential ancestor. | required |
| descendant | str | The commit hash of the potential descendant. | required |
Returns
| Name | Type | Description |
|---|---|---|
| bool | True if the ancestor is an ancestor of the descendant, otherwise False. |
See Also
get_latest_release_hash : Get the commit hash of the latest release. get_current_hash : Get the commit hash of the current.
Examples
>>> is_ancestor("abc123", "def456")
True
>>> is_ancestor("abc123", "ghi789")
Falsematch_semver
versions.match_semver(
version_str,
with_leading_v=False,
strict_semver=True,
pattern=None,
)Match a version string against the semantic versioning pattern.
See the semantic versioning guidelines: https://semver.org/
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| version_str | str | The version string to match against the semantic versioning pattern. | required |
| with_leading_v | bool | If True, the version string is expected to start with a leading ‘v’. | False |
| strict_semver | bool | If True, the version string must match the full semantic versioning pattern. Otherwise, a relaxed format with only the major and minor components is allowed. | True |
| pattern | str | A custom regex pattern to match against the version string. If None, the default semantic versioning pattern is used. | None |
Returns: re.Match or None The match object if the version string matches the semantic versioning pattern, otherwise None.
See Also
get_major_minor_version : Extract the major and minor version from a semantic versioning string.
Examples
>>> match_semver("1.0.0")
<re.Match object; span=(0, 5), match='1.0.0'>
>>> match_semver("1.0.0-alpha+001")
<re.Match object; span=(0, 13), match='1.0.0-alpha+001'>
>>> match_semver("invalid_version")
None