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)

Bases: HvcsBase

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_DOMAIN = 'api.bitbucket.org'

DEFAULT_API_PATH_CLOUD = '/2.0'

DEFAULT_API_PATH_ONPREM = '/rest/api/1.0'

DEFAULT_API_SUBDOMAIN_PREFIX = 'api'

DEFAULT_DOMAIN = 'bitbucket.org'

DEFAULT_ENV_TOKEN_NAME = 'BITBUCKET_TOKEN'

commit_hash_url(commit_hash: str) → str

Given a commit hash, return a web URL which links to this commit in the remote VCS.

compare_url(from_rev: str, to_rev: str) → str

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_api_url(endpoint: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) → str

create_server_url(path: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) → str

pull_request_url(pr_number: str | int) → str

Given a number for a PR/Merge request/equivalent, return a web URL that links to that PR in the remote VCS.

remote_url(use_token: bool = True) → str

Get the remote url including the token for authentication if requested

class semantic_release.hvcs.Gitea(remote_url: str, *, hvcs_domain: str | None = None, token: str | None = None, allow_insecure: bool = False, **kwargs: Any)

Bases: HvcsBase

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

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

commit_hash_url(commit_hash: str) → str

Given a commit hash, return a web URL which links to this commit in the remote VCS.

create_api_url(endpoint: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) → str

create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) → int

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) → int

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

create_server_url(path: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) → str

edit_release_notes(release_id: int, release_notes: str) → int

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_release_id_by_tag(tag: str) → int | None

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

pull_request_url(pr_number: str | int) → str

Given a number for a PR/Merge request/equivalent, return a web URL that links to that PR in the remote VCS.

remote_url(use_token: bool = True) → str

Get the remote url including the token for authentication if requested

upload_asset(release_id: int, file: str, label: str | None = None) → bool

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

upload_dists(tag: str, dist_glob: str) → int

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

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)

Bases: HvcsBase

GitHub HVCS interface for interacting with GitHub repositories

This class supports the following products:

• GitHub Free, Pro, & Team

• GitHub Enterprise Cloud

This class does not support the following products:

• GitHub Enterprise Server (on-premises installations)

DEFAULT_API_DOMAIN = 'api.github.com'

DEFAULT_API_SUBDOMAIN_PREFIX = 'api'

DEFAULT_DOMAIN = 'github.com'

DEFAULT_ENV_TOKEN_NAME = 'GH_TOKEN'

asset_upload_url(release_id: str) → str | None

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

commit_hash_url(commit_hash: str) → str

Given a commit hash, return a web URL which links to this commit in the remote VCS.

compare_url(from_rev: str, to_rev: str) → str

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_api_url(endpoint: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) → str

create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) → int

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) → int

Create a new release https://docs.github.com/rest/reference/repos#create-a-release :param tag: Tag to create release for :param release_notes: The release notes for this version :param prerelease: Whether or not this release should be created as a prerelease :return: the ID of the release

create_server_url(path: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) → str

edit_release_notes(release_id: int, release_notes: str) → int

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_release_id_by_tag(tag: str) → int | None

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

pull_request_url(pr_number: str | int) → str

Given a number for a PR/Merge request/equivalent, return a web URL that links to that PR in the remote VCS.

remote_url(use_token: bool = True) → str

Get the remote url including the token for authentication if requested

upload_asset(release_id: int, file: str, label: str | None = None) → bool

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

upload_dists(tag: str, dist_glob: str) → int

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

class semantic_release.hvcs.Gitlab(remote_url: str, *, hvcs_domain: str | None = None, token: str | None = None, allow_insecure: bool = False, **kwargs: Any)

Bases: HvcsBase

Gitlab helper class Note Gitlab doesn’t really have the concept of a separate API domain

DEFAULT_DOMAIN = 'gitlab.com'

DEFAULT_ENV_TOKEN_NAME = 'GITLAB_TOKEN'

commit_hash_url(commit_hash: str) → str

Given a commit hash, return a web URL which links to this commit in the remote VCS.

compare_url(from_rev: str, to_rev: str) → str

Get the comparison link between two version tags.

Parameters:

from_rev – The older version to compare. Can be a commit sha, tag or

branch name.

Parameters:

to_rev – The newer version to compare. Can be a commit sha, tag or

branch name.

Returns:

Link to view a comparison between the two versions.

create_api_url(endpoint: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) → str

create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) → str

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) → str

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

create_server_url(path: str, auth: str | None = None, query: str | None = None, fragment: str | None = None) → str

edit_release_notes(release_id: str, release_notes: str) → str

Edit the changelog associated with a release, if supported

issue_url(issue_number: str | int) → str

merge_request_url(mr_number: str | int) → str

pull_request_url(pr_number: str | int) → str

Given a number for a PR/Merge request/equivalent, return a web URL that links to that PR in the remote VCS.

remote_url(use_token: bool = True) → str

Get the remote url including the token for authentication if requested

class semantic_release.hvcs.HvcsBase(remote_url: str, *args: Any, **kwargs: Any)

Bases: object

Interface for subclasses interacting with a remote VCS

Methods which have a base implementation are implemented here

Methods which aren’t mandatory but should indicate a lack of support gracefully (i.e. without raising an exception) return _not_supported, and can be overridden to provide an implementation in subclasses. This is more straightforward than checking for NotImplemented around every method call.

DEFAULT_ENV_TOKEN_NAME = 'HVCS_TOKEN'

asset_upload_url(release_id: str) → str | None

Return the URL to use to upload an asset to the given release id, if releases are supported by the remote VCS

commit_hash_url(commit_hash: str) → str

Given a commit hash, return a web URL which links to this commit in the remote VCS.

compare_url(from_rev: str, to_rev: str) → str

Get the comparison link between two version tags.

Parameters:

from_rev – The older version to compare. Can be a commit sha, tag or

branch name.

Parameters:

to_rev – The newer version to compare. Can be a commit sha, tag or

branch name.

Returns:

Link to view a comparison between the two versions.

create_or_update_release(tag: str, release_notes: str, prerelease: bool = False) → int | str

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) → int | str

Create a release in a remote VCS, if supported

edit_release_notes(release_id: int, release_notes: str) → int

Edit the changelog associated with a release, if supported

get_release_id_by_tag(tag: str) → int | None

Given a Git tag, return the ID (as the remote VCS defines it) of a corresponding release in the remote VCS, if supported

property owner: str

pull_request_url(pr_number: str) → str

Given a number for a PR/Merge request/equivalent, return a web URL that links to that PR in the remote VCS.

remote_url(use_token: bool) → str

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

upload_asset(release_id: int | str, file: str, label: str | None = None) → bool

Upload an asset (file) to a release with the given release_id, if releases are supported by the remote VCS. Add a custom label if one is given in the “label” parameter and labels are supported by the remote VCS

upload_dists(tag: str, dist_glob: str) → int

Upload built distributions to a release on a remote VCS that supports such uploads

class semantic_release.hvcs.TokenAuth(token: str)

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_DOMAIN
    • Bitbucket.DEFAULT_API_PATH_CLOUD
    • Bitbucket.DEFAULT_API_PATH_ONPREM
    • Bitbucket.DEFAULT_API_SUBDOMAIN_PREFIX
    • Bitbucket.DEFAULT_DOMAIN
    • Bitbucket.DEFAULT_ENV_TOKEN_NAME
    • Bitbucket.commit_hash_url()
    • Bitbucket.compare_url()
    • Bitbucket.create_api_url()
    • Bitbucket.create_server_url()
    • Bitbucket.pull_request_url()
    • Bitbucket.remote_url()
• 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_api_url()
    • Gitea.create_or_update_release()
    • Gitea.create_release()
    • Gitea.create_server_url()
    • Gitea.edit_release_notes()
    • Gitea.get_release_id_by_tag()
    • Gitea.pull_request_url()
    • Gitea.remote_url()
    • Gitea.upload_asset()
    • Gitea.upload_dists()
• semantic_release.hvcs.github module
  • Github
    • Github.DEFAULT_API_DOMAIN
    • Github.DEFAULT_API_SUBDOMAIN_PREFIX
    • Github.DEFAULT_DOMAIN
    • Github.DEFAULT_ENV_TOKEN_NAME
    • Github.asset_upload_url()
    • Github.commit_hash_url()
    • Github.compare_url()
    • Github.create_api_url()
    • Github.create_or_update_release()
    • Github.create_release()
    • Github.create_server_url()
    • Github.edit_release_notes()
    • Github.get_release_id_by_tag()
    • Github.pull_request_url()
    • Github.remote_url()
    • Github.upload_asset()
    • Github.upload_dists()
• semantic_release.hvcs.gitlab module
  • Gitlab
    • Gitlab.DEFAULT_DOMAIN
    • Gitlab.DEFAULT_ENV_TOKEN_NAME
    • Gitlab.commit_hash_url()
    • Gitlab.compare_url()
    • Gitlab.create_api_url()
    • Gitlab.create_or_update_release()
    • Gitlab.create_release()
    • Gitlab.create_server_url()
    • Gitlab.edit_release_notes()
    • Gitlab.issue_url()
    • Gitlab.merge_request_url()
    • Gitlab.pull_request_url()
    • Gitlab.remote_url()
• semantic_release.hvcs.token_auth module
  • TokenAuth
• semantic_release.hvcs.util module
  • build_requests_session()
  • suppress_http_error_for_codes()
  • suppress_not_found()