semantic_release.hvcs package¶
- class semantic_release.hvcs.Bitbucket(remote_url: str, *, hvcs_domain: str | None = None, hvcs_api_domain: str | None = None, token: str | None = None, allow_insecure: bool = False, **kwargs: Any)[source]¶
Bases:
RemoteHvcsBase
Bitbucket HVCS interface for interacting with BitBucket repositories
This class supports the following products:
BitBucket Cloud
BitBucket Data Center Server (on-premises installations)
This interface does its best to detect which product is configured based on the provided domain. If it is the official bitbucket.org, the default domain, then it is considered as BitBucket Cloud which uses the subdomain api.bitbucket.org/2.0 for api communication.
If the provided domain is anything else, than it is assumed to be communicating with an on-premise or 3rd-party maintained BitBucket instance which matches with the BitBucket Data Center Server product. The on-prem server product uses a path prefix for handling api requests which is configured to be server.domain/rest/api/1.0 based on the documentation in April 2024.
- DEFAULT_API_PATH_CLOUD = '/2.0'¶
- DEFAULT_API_PATH_ONPREM = '/rest/api/1.0'¶
- DEFAULT_API_SUBDOMAIN_PREFIX = 'api'¶
- DEFAULT_API_URL_CLOUD = 'https://api.bitbucket.org/2.0'¶
- DEFAULT_DOMAIN = 'bitbucket.org'¶
- DEFAULT_ENV_TOKEN_NAME = 'BITBUCKET_TOKEN'¶
- compare_url(from_rev: str, to_rev: str) str [source]¶
Get the Bitbucket comparison link between two version tags. :param from_rev: The older version to compare. :param to_rev: The newer version to compare. :return: Link to view a comparison between the two versions.
- create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) int | str [source]¶
Create or update a release for the given tag in a remote VCS, attaching the given changelog, if supported
- create_release(tag: str, release_notes: str, prerelease: bool = False, assets: list[str] | None = None) int | str [source]¶
Create a release in a remote VCS, if supported
Which includes uploading any assets as part of the release
- get_changelog_context_filters() tuple[Callable[..., Any], ...] [source]¶
Return a list of functions that can be used as filters in a Jinja2 template
ex. filters to convert text to URLs for issues and commits
- class semantic_release.hvcs.Gitea(remote_url: str, *, hvcs_domain: str | None = None, token: str | None = None, allow_insecure: bool = False, **kwargs: Any)[source]¶
Bases:
RemoteHvcsBase
Gitea helper class
- DEFAULT_API_PATH = '/api/v1'¶
- DEFAULT_DOMAIN = 'gitea.com'¶
- DEFAULT_ENV_TOKEN_NAME = 'GITEA_TOKEN'¶
- asset_upload_url(release_id: str) str [source]¶
Get the correct upload url for a release https://gitea.com/api/swagger#/repository/repoCreateReleaseAttachment :param release_id: ID of the release to upload to
- create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) int [source]¶
Post release changelog :param version: The version number :param changelog: The release notes for this version :return: The status of the request
- create_release(tag: str, release_notes: str, prerelease: bool = False, assets: list[str] | None = None) int [source]¶
Create a new release
Ref: https://gitea.com/api/swagger#/repository/repoCreateRelease
- Parameters:
tag – Tag to create release for
release_notes – The release notes for this version
prerelease – Whether or not this release should be specified as a
prerelease
- Returns:
Whether the request succeeded
- edit_release_notes(release_id: int, release_notes: str) int [source]¶
Edit a release with updated change notes https://gitea.com/api/swagger#/repository/repoEditRelease :param id: ID of release to update :param release_notes: The release notes for this version :return: The ID of the release that was edited
- get_changelog_context_filters() tuple[Callable[..., Any], ...] [source]¶
Return a list of functions that can be used as filters in a Jinja2 template
ex. filters to convert text to URLs for issues and commits
- get_release_id_by_tag(tag: str) int | None [source]¶
Get a release by its tag name https://gitea.com/api/swagger#/repository/repoGetReleaseByTag :param tag: Tag to get release for :return: ID of found release
- remote_url(use_token: bool = True) str [source]¶
Get the remote url including the token for authentication if requested
- upload_dists(tag: str, dist_glob: str) int [source]¶
Upload distributions to a release :param tag: Tag to upload for :param path: Path to the dist directory :return: The number of distributions successfully uploaded
- upload_release_asset(release_id: int, file: str, label: str | None = None) bool [source]¶
Upload an asset to an existing release https://gitea.com/api/swagger#/repository/repoCreateReleaseAttachment :param release_id: ID of the release to upload to :param file: Path of the file to upload :param label: this parameter has no effect :return: The status of the request
- class semantic_release.hvcs.Github(remote_url: str, *, hvcs_domain: str | None = None, hvcs_api_domain: str | None = None, token: str | None = None, allow_insecure: bool = False, **kwargs: Any)[source]¶
Bases:
RemoteHvcsBase
GitHub HVCS interface for interacting with GitHub repositories
This class supports the following products:
GitHub Free, Pro, & Team
GitHub Enterprise Cloud
GitHub Enterprise Server (on-premises installations)
This interface does its best to detect which product is configured based on the provided domain. If it is the official github.com, the default domain, then it is considered as GitHub Enterprise Cloud which uses the subdomain api.github.com for api communication.
If the provided domain is anything else, than it is assumed to be communicating with an on-premise or 3rd-party maintained GitHub instance which matches with the GitHub Enterprise Server product. The on-prem server product uses a path prefix for handling api requests which is configured to be server.domain/api/v3 based on the documentation in April 2024.
- DEFAULT_API_DOMAIN = 'api.github.com'¶
- DEFAULT_API_PATH_CLOUD = '/'¶
- DEFAULT_API_PATH_ONPREM = '/api/v3'¶
- DEFAULT_API_SUBDOMAIN_PREFIX = 'api'¶
- DEFAULT_API_URL_CLOUD = 'https://api.github.com'¶
- DEFAULT_DOMAIN = 'github.com'¶
- DEFAULT_ENV_TOKEN_NAME = 'GH_TOKEN'¶
- asset_upload_url(release_id: str) str | None [source]¶
Get the correct upload url for a release https://docs.github.com/en/enterprise-server@3.5/rest/releases/releases#get-a-release :param release_id: ID of the release to upload to :return: URL to upload for a release if found, else None
- compare_url(from_rev: str, to_rev: str) str [source]¶
Get the GitHub comparison link between two version tags. :param from_rev: The older version to compare. :param to_rev: The newer version to compare. :return: Link to view a comparison between the two versions.
- create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) int [source]¶
Post release changelog :param version: The version number :param release_notes: The release notes for this version :return: The status of the request
- create_release(tag: str, release_notes: str, prerelease: bool = False, assets: list[str] | None = None) int [source]¶
Create a new release
REF: https://docs.github.com/rest/reference/repos#create-a-release
- Parameters:
tag – Tag to create release for
release_notes – The release notes for this version
prerelease – Whether or not this release should be created as a prerelease
assets – a list of artifacts to upload to the release
- Returns:
the ID of the release
- edit_release_notes(release_id: int, release_notes: str) int [source]¶
Edit a release with updated change notes https://docs.github.com/rest/reference/repos#update-a-release :param id: ID of release to update :param release_notes: The release notes for this version :return: The ID of the release that was edited
- get_changelog_context_filters() tuple[Callable[..., Any], ...] [source]¶
Return a list of functions that can be used as filters in a Jinja2 template
ex. filters to convert text to URLs for issues and commits
- get_release_id_by_tag(tag: str) int | None [source]¶
Get a release by its tag name https://docs.github.com/rest/reference/repos#get-a-release-by-tag-name :param tag: Tag to get release for :return: ID of release, if found, else None
- remote_url(use_token: bool = True) str [source]¶
Get the remote url including the token for authentication if requested
- upload_dists(tag: str, dist_glob: str) int [source]¶
Upload distributions to a release :param version: Version to upload for :param path: Path to the dist directory :return: The number of distributions successfully uploaded
- upload_release_asset(release_id: int, file: str, label: str | None = None) bool [source]¶
Upload an asset to an existing release https://docs.github.com/rest/reference/repos#upload-a-release-asset :param release_id: ID of the release to upload to :param file: Path of the file to upload :param label: Optional custom label for this file :return: The status of the request
- class semantic_release.hvcs.Gitlab(remote_url: str, *, hvcs_domain: str | None = None, token: str | None = None, allow_insecure: bool = False, **kwargs: Any)[source]¶
Bases:
RemoteHvcsBase
Gitlab HVCS interface for interacting with Gitlab repositories
- DEFAULT_DOMAIN = 'gitlab.com'¶
- DEFAULT_ENV_TOKEN_NAME = 'GITLAB_TOKEN'¶
- create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) str [source]¶
Create or update a release for the given tag in a remote VCS, attaching the given changelog, if supported
- create_release(tag: str, release_notes: str, prerelease: bool = False, assets: list[str] | None = None) str [source]¶
Post release changelog :param tag: Tag to create release for :param release_notes: The release notes for this version :param prerelease: This parameter has no effect :return: The tag of the release
- get_changelog_context_filters() tuple[Callable[..., Any], ...] [source]¶
Return a list of functions that can be used as filters in a Jinja2 template
ex. filters to convert text to URLs for issues and commits
- class semantic_release.hvcs.HvcsBase(remote_url: str, *args: Any, **kwargs: Any)[source]¶
Bases:
object
Interface for subclasses interacting with a remote vcs environment
Methods generally have a base implementation are implemented here but likely just provide a not-supported message but return gracefully
This class cannot be instantated directly but must be inherited from and implement the designated abstract methods.
- abstract get_changelog_context_filters() tuple[Callable[..., Any], ...] [source]¶
Return a list of functions that can be used as filters in a Jinja2 template
ex. filters to convert text to URLs for issues and commits
- property owner: str¶
- abstract remote_url(use_token: bool) str [source]¶
Return the remote URL for the repository, including the token for authentication if requested by setting the use_token parameter to True,
- property repo_name: str¶
- class semantic_release.hvcs.RemoteHvcsBase(remote_url: str, *args: Any, **kwargs: Any)[source]¶
Bases:
HvcsBase
Interface for subclasses interacting with a remote VCS
This abstract class is defined to provide common helper functions and a set of basic methods that all remote VCS environments usually support.
If the remote vcs implementation (via subclass) does not support a functionality then it can just call super()’s method which defaults as a non-supported log message and empty results. This is more straightforward than checking for NotImplemented around every function call in the core library code.
- DEFAULT_ENV_TOKEN_NAME = 'HVCS_TOKEN'¶
- property api_url: Url¶
- create_api_url(endpoint: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) str [source]¶
- abstract create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) int | str [source]¶
Create or update a release for the given tag in a remote VCS, attaching the given changelog, if supported
- abstract create_release(tag: str, release_notes: str, prerelease: bool = False, assets: list[str] | None = None) int | str [source]¶
Create a release in a remote VCS, if supported
Which includes uploading any assets as part of the release
- create_repo_url(repo_path: str, query: str | None = None, fragment: str | None = None) str [source]¶
- create_server_url(path: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) str [source]¶
- property hvcs_domain: Url¶
- class semantic_release.hvcs.TokenAuth(token: str)[source]¶
Bases:
AuthBase
requests Authentication for token based authorization. This allows us to attach the Authorization header with a token to a session.
Submodules¶
- semantic_release.hvcs.bitbucket module
Bitbucket
Bitbucket.DEFAULT_API_PATH_CLOUD
Bitbucket.DEFAULT_API_PATH_ONPREM
Bitbucket.DEFAULT_API_SUBDOMAIN_PREFIX
Bitbucket.DEFAULT_API_URL_CLOUD
Bitbucket.DEFAULT_DOMAIN
Bitbucket.DEFAULT_ENV_TOKEN_NAME
Bitbucket.commit_hash_url()
Bitbucket.compare_url()
Bitbucket.create_or_update_release()
Bitbucket.create_release()
Bitbucket.get_changelog_context_filters()
Bitbucket.pull_request_url()
Bitbucket.remote_url()
Bitbucket.upload_dists()
- semantic_release.hvcs.gitea module
Gitea
Gitea.DEFAULT_API_PATH
Gitea.DEFAULT_DOMAIN
Gitea.DEFAULT_ENV_TOKEN_NAME
Gitea.asset_upload_url()
Gitea.commit_hash_url()
Gitea.create_or_update_release()
Gitea.create_release()
Gitea.edit_release_notes()
Gitea.get_changelog_context_filters()
Gitea.get_release_id_by_tag()
Gitea.issue_url()
Gitea.pull_request_url()
Gitea.remote_url()
Gitea.upload_dists()
Gitea.upload_release_asset()
- semantic_release.hvcs.github module
Github
Github.DEFAULT_API_DOMAIN
Github.DEFAULT_API_PATH_CLOUD
Github.DEFAULT_API_PATH_ONPREM
Github.DEFAULT_API_SUBDOMAIN_PREFIX
Github.DEFAULT_API_URL_CLOUD
Github.DEFAULT_DOMAIN
Github.DEFAULT_ENV_TOKEN_NAME
Github.asset_upload_url()
Github.commit_hash_url()
Github.compare_url()
Github.create_or_update_release()
Github.create_release()
Github.edit_release_notes()
Github.get_changelog_context_filters()
Github.get_release_id_by_tag()
Github.issue_url()
Github.pull_request_url()
Github.remote_url()
Github.upload_dists()
Github.upload_release_asset()
- semantic_release.hvcs.gitlab module
Gitlab
Gitlab.DEFAULT_DOMAIN
Gitlab.DEFAULT_ENV_TOKEN_NAME
Gitlab.commit_hash_url()
Gitlab.compare_url()
Gitlab.create_or_update_release()
Gitlab.create_release()
Gitlab.edit_release_notes()
Gitlab.get_changelog_context_filters()
Gitlab.issue_url()
Gitlab.merge_request_url()
Gitlab.pull_request_url()
Gitlab.remote_url()
Gitlab.upload_dists()
- semantic_release.hvcs.remote_hvcs_base module
- semantic_release.hvcs.token_auth module
- semantic_release.hvcs.util module