repo

class pygithub_mate.repo.IsTagLatestOnDefaultBranchResult(is_latest: bool, latest_commit_sha: str, tag_and_ref: TagAndRef)

A container for the result of checking if a tag is the latest on the main branch.

Parameters:

• is_latest – True if the tag points to the latest commit on the default branch

• latest_commit_sha – SHA of the latest commit on the default branch

• tag_and_ref – The Git tag and reference objects for the tag

class pygithub_mate.repo.BaseGitHubRepo(verbose: bool = True, printer: ~typing.Callable[[str], None] = <built-in function print>, github_kwargs: dict[str, ~typing.Any] = REQ, data: dict[str, ~typing.Any] = <factory>, owner_name: str = REQ, repo_name: str = REQ)

GitHub repository operations.

Provides comprehensive repository management functionality including tag creation, deletion, branch operations, and commit tracking. Follows the command pattern with repository details stored as attributes and dynamic operations as method parameters.

Parameters:

• owner_name – GitHub repository owner/organization name

• repo_name – Repository name

property repo_full_name: str

Full name of the repository in the format “owner/repo”.

property repo: Repository

GitHub repository object.

property repo_default_branch_name: str

Default branch name of the repository.

get_latest_commit_sha_on_branch(branch_name: str) → str

Get the SHA of the latest commit on a specific branch.

Parameters:

branch_name – Name of the branch to query

Returns:

SHA hash of the latest commit on the branch

get_latest_commit_sha_on_default_branch() → str

Get the SHA of the latest commit on the repository’s default branch.

Returns:

SHA hash of the latest commit on the default branch

property latest_commit_sha_on_default_branch: str

SHA of the latest commit on the repository’s default branch.

get_git_tag_and_ref(tag_name: str) → TagAndRef

Retrieve the Git tag and reference objects for the specified tag.

Attempts to fetch both the Git tag object and the Git reference for the specified tag name. Handles cases where the tag or reference doesn’t exist.

Parameters:

tag_name – Name of the tag to retrieve

Returns:

TagAndRef object containing: - tag=None, ref=None if the tag reference doesn’t exist - tag=None, ref=GitRef if the reference exists but the tag object doesn’t - tag=GitTag, ref=GitRef if both exist

Raises:

GithubException – For API errors other than 404 (not found)

is_tag_latest_on_default_branch(tag_name: str) → IsTagLatestOnDefaultBranchResult

Check if the specified tag points to the latest commit on the default branch.

Compares the commit SHA that the tag points to with the SHA of the latest commit on the default branch to determine if the tag is up-to-date.

Parameters:

tag_name – Name of the tag to check

Returns:

IsTagLatestOnDefaultBranchResult object containing: - is_latest: True if tag is latest, False otherwise (or if tag doesn’t exist) - latest_commit_sha: SHA of the latest commit on the default branch - tag_and_ref: TagAndRef object containing the Git tag and reference

Note:

If the tag doesn’t exist, is_latest will be False.

delete_tag(tag_name: str) → bool

Delete the existing Git tag reference if it exists.

Attempts to find and delete the Git tag reference for the specified tag name. This removes the tag from the repository, making it available for recreation.

Parameters:

tag_name – Name of the tag to delete

Returns:

True if a tag was found and deleted, False if no tag existed

Raises:

GithubException – If the deletion fails due to API errors other than 404

create_tag_on_commit(commit_sha: str, tag_name: str, tag_message: str | None = None, create_git_tag_kwargs: dict[str, Any] | None = None) → TagAndRef

Create a new Git tag and reference pointing to a specific commit.

Creates both a Git tag object and a Git reference for the specified tag name.

Parameters:

• commit_sha – SHA of the commit to tag

• tag_name – Name for the new Git tag

• tag_message – Optional message for the tag (defaults to “Tag {tag_name}”)

• create_git_tag_kwargs – Additional keyword arguments for tag creation

Returns:

TagAndRef object containing the created Git tag and reference

create_tag_on_latest_commit_on_default_branch(tag_name: str, tag_message: str | None = None, create_git_tag_kwargs: dict[str, Any] | None = None) → TagAndRef

Create a new Git tag and reference pointing to the latest commit on default branch.

Creates both a Git tag object and a Git reference for the specified tag name. Always uses the latest commit from the default branch.

Parameters:

• tag_name – Name for the new Git tag

• tag_message – Optional message for the tag (defaults to “Tag {tag_name}”)

• create_git_tag_kwargs – Additional keyword arguments for tag creation

Returns:

TagAndRef object containing the created Git tag and reference

Raises:

GithubException – If tag creation fails (e.g., tag already exists)

get_git_release(release_name: str) → GitRelease | None

Retrieve the GitHub release object for the specified release.

Attempts to fetch the GitHub release associated with the release name. Returns None if the release doesn’t exist.

Parameters:

release_name – Name/tag of the release to retrieve

Returns:

The GitHub release object if it exists, None otherwise

Raises:

• GithubException – For API errors other than 404 (not found)

• Exception – For other unexpected errors

put_tag_on_commit(commit_sha: str, tag_name: str, tag_message: str | None = None, create_git_tag_kwargs: dict[str, Any] | None = None) → TagAndRef

Ensure a Git tag points to a specific commit, updating or recreating the tag as needed.

If the tag exists and already points to the desired commit, no action is taken. If the tag exists but points to a different commit, it is deleted and recreated. If the tag does not exist, it is created.

Parameters:

• commit_sha – SHA of the commit to tag

• tag_name – Name for the new Git tag

• tag_message – Optional message for the tag (defaults to “Tag {tag_name}”)

• create_git_tag_kwargs – Additional keyword arguments for tag creation

Returns:

TagAndRef object containing the Git tag and reference

put_tag_on_latest_commit_on_branch(branch_name: str, tag_name: str, tag_message: str | None = None, create_git_tag_kwargs: dict[str, Any] | None = None) → TagAndRef

Ensure a Git tag points to the latest commit on the specified branch.

Parameters:

• branch_name – Name of the branch to get the latest commit from

• tag_name – Name for the Git tag

• tag_message – Optional message for the tag (defaults to “Tag {tag_name}”)

• create_git_tag_kwargs – Additional keyword arguments for tag creation

Returns:

TagAndRef object containing the Git tag and reference

put_tag_on_latest_commit_on_default_branch(tag_name: str, tag_message: str | None = None, create_git_tag_kwargs: dict[str, Any] | None = None) → TagAndRef

Ensure a Git tag points to the latest commit on the default branch.

Parameters:

• tag_name – Name for the Git tag

• tag_message – Optional message for the tag (defaults to “Tag {tag_name}”)

• create_git_tag_kwargs – Additional keyword arguments for tag creation

Returns:

TagAndRef object containing the Git tag and reference

delete_release(release_name: str) → bool

Delete the existing GitHub release if it exists.

Attempts to find and delete the GitHub release associated with the specified release name. This is typically called before creating a new release to ensure clean state.

Parameters:

release_name – Name/tag of the release to delete

Returns:

True if a release was found and deleted, False if no release existed

Raises:

GithubException – If the deletion fails due to API errors

create_release(tag_name: str, release_name: str, release_message: str | None = None, create_git_release_kwargs: dict[str, Any] | None = None) → GitRelease

Create a new GitHub release for the specified tag and name.

Creates a GitHub release associated with the specified tag. The release will use the provided tag name, release name, and release message (with a default if not provided).

Parameters:

• tag_name – Name of the Git tag to associate with the release

• release_name – Name for the GitHub release

• release_message – Optional message for the release (defaults to “Release {release_name}”)

• create_git_release_kwargs – Additional keyword arguments for release creation

Returns:

The created GitHub release object

Raises:

GithubException – If release creation fails (e.g., release already exists)

Note

The associated tag must exist before creating a release.

put_release(commit_sha: str, tag_name: str, release_name: str, tag_message: str | None = None, release_message: str | None = None, create_git_tag_kwargs: dict[str, Any] | None = None, create_git_release_kwargs: dict[str, Any] | None = None)

Ensure a GitHub release and its associated tag point to a specific commit.

This method performs comprehensive release management by coordinating both tag and release operations. It validates consistency between existing releases and tags, and recreates them as needed to ensure they point to the desired commit.

The workflow handles multiple scenarios: - If no release exists: Creates tag and release - If release exists with matching tag: Validates tag points to desired commit - If release exists with different tag: Raises error to prevent conflicts - If tag exists but points elsewhere: Deletes both release and tag, then recreates

Parameters:

• commit_sha – SHA of the commit to associate with the release

• tag_name – Name of the Git tag to create or update

• release_name – Name of the GitHub release to create or update

• tag_message – Optional message for the tag (defaults to “Tag {tag_name}”)

• release_message – Optional message for the release (defaults to “Release {release_name}”)

• create_git_tag_kwargs – Additional keyword arguments for tag creation

• create_git_release_kwargs – Additional keyword arguments for release creation

Returns:

ReleaseAndTagAndRef object containing the release and tag objects

Raises:

• ValueError – If existing release has a different tag name than expected

• GithubException – If any GitHub API operation fails

• NotImplementedError – If release exists but its associated tag doesn’t exist (unexpected state)

put_release_on_latest_commit_on_branch(branch_name: str, tag_name: str, release_name: str, tag_message: str | None = None, release_message: str | None = None, create_git_tag_kwargs: dict[str, Any] | None = None, create_git_release_kwargs: dict[str, Any] | None = None) → ReleaseAndTagAndRef

Ensure a GitHub release and its associated tag point to the latest commit on the specified branch.

Parameters:

• tag_name – Name of the Git tag to create or update

• release_name – Name of the GitHub release to create or update

• branch_name – Name of the branch to get the latest commit from

• tag_message – Optional message for the tag (defaults to “Tag {tag_name}”)

• release_message – Optional message for the release (defaults to “Release {release_name}”)

• create_git_tag_kwargs – Additional keyword arguments for tag creation

• create_git_release_kwargs – Additional keyword arguments for release creation

Returns:

ReleaseAndTagAndRef object containing the release and tag objects

put_release_on_latest_commit_on_default_branch(tag_name: str, release_name: str, tag_message: str | None = None, release_message: str | None = None, create_git_tag_kwargs: dict[str, Any] | None = None, create_git_release_kwargs: dict[str, Any] | None = None) → ReleaseAndTagAndRef

Ensure a GitHub release and its associated tag point to the latest commit on the default branch.

Parameters:

• tag_name – Name of the Git tag to create or update

• release_name – Name of the GitHub release to create or update

• tag_message – Optional message for the tag (defaults to “Tag {tag_name}”)

• release_message – Optional message for the release (defaults to “Release {release_name}”)

• create_git_tag_kwargs – Additional keyword arguments for tag creation

• create_git_release_kwargs – Additional keyword arguments for release creation

Returns:

ReleaseAndTagAndRef object containing the release and tag objects

put_assets_to_release(release: GitRelease, path_to_name_mapping: dict[os.PathLike, str])

Upload assets to a release, replacing any existing assets with the same names only if their SHA-256 digest differs.

For each asset name, if an asset already exists in the release:

• The existing asset is deleted and replaced only if the SHA-256 digest of the new file is different.

• If the digest matches, the asset is not re-uploaded.

If the asset does not exist, it is uploaded.

Parameters:

• release – The GitHub release object to upload assets to

• path_to_name_mapping – A mapping of file paths to asset names for upload