pontos.github.api package

pontos.github.api.update_from_applied_settings(branch_protection, required_status_checks=None, require_branches_to_be_up_to_date=None, enforce_admins=None, dismissal_restrictions_users=None, dismissal_restrictions_teams=None, dismissal_restrictions_apps=None, dismiss_stale_reviews=None, require_code_owner_reviews=None, required_approving_review_count=None, require_last_push_approval=None, bypass_pull_request_allowances_users=None, bypass_pull_request_allowances_teams=None, bypass_pull_request_allowances_apps=None, restrictions_users=None, restrictions_teams=None, restrictions_apps=None, required_linear_history=None, allow_force_pushes=None, allow_deletions=None, block_creations=None, required_conversation_resolution=None, lock_branch=None, allow_fork_syncing=None, required_signatures=None)

Update branch protection rules from applied settings.

Return keyword arguments for update_protection_rules by merging existing settings with desired updated values.

Return type:

Dict[str, Any]

exception pontos.github.api.GitHubApiError

Error while using the GitHub API

class pontos.github.api.GitHubAsyncRESTApi(token=None, url='https://api.github.com', *, timeout=Timeout(timeout=180.0))

A asynchronous GitHub REST API.

Should be used as an async context manager.

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    repositories = await api.organizations.get_repositories("foo")

Parameters:

• token (str | None) – GitHub API token

• url (str | None) – GitHub URL

• timeout (Timeout | None) – Timeout settings to use

property organizations: GitHubAsyncRESTOrganizations

Organizations related API

property artifacts: GitHubAsyncRESTArtifacts

Artifacts related API

property billing: GitHubAsyncRESTBilling

Billing related API

property branches: GitHubAsyncRESTBranches

Branches related API

property code_scanning: GitHubAsyncRESTCodeScanning

Code scanning related API

property contents: GitHubAsyncRESTContent

Contents related API

property dependabot: GitHubAsyncRESTDependabot

Dependabot related API

property labels: GitHubAsyncRESTLabels

Labels related API

property pulls: GitHubAsyncRESTPullRequests

Pull Requests related API

Deprecated since version 23.3.4: Use pull_requests instead.

property pull_requests: GitHubAsyncRESTPullRequests

Pull Requests related API

property releases: GitHubAsyncRESTReleases

Releases related API

property workflows: GitHubAsyncRESTWorkflows

Workflows related API

property repositories: GitHubAsyncRESTRepositories

Repositories related API

property secret_scanning: GitHubAsyncRESTSecretScanning

Secret scanning related API

property search: GitHubAsyncRESTSearch

Search related API

property teams: GitHubAsyncRESTTeams

Teams related API

property tags: GitHubAsyncRESTTags

Tags related API

property users: GitHubAsyncRESTUsers

Users related API

class pontos.github.api.GitHubAsyncRESTArtifacts(client)

get_all(repo)

List all artifacts of a repository

https://docs.github.com/en/rest/actions/artifacts#list-artifacts-for-a-repository

Parameters:

repo (str) – GitHub repository (owner/name) to use

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

An async iterator for the received artifacts

Return type:

AsyncIterator[Artifact]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for artifact in api.artifacts.get_all("foo/bar"):
        print(artifact)

async get(repo, artifact)

Get a single artifact of a repository

https://docs.github.com/en/rest/actions/artifacts#get-an-artifact

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• artifact (str | int) – ID of the artifact

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

Information about the artifact

Return type:

Artifact

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    artifact = await api.artifacts.get("foo/bar", 123)
    print(artifact)

get_workflow_run_artifacts(repo, run)

List all artifacts for a workflow run

https://docs.github.com/en/rest/actions/artifacts#list-workflow-run-artifacts

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• run (str | int) – The unique identifier of the workflow run

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

An async iterator for the received artifacts

Return type:

AsyncIterator[Artifact]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for artifact in api.artifacts.get_workflow_run_artifacts("foo/bar", 234):
        print(artifact)

async delete(repo, artifact)

Delete an artifact of a repository

https://docs.github.com/en/rest/actions/artifacts#delete-an-artifact

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• artifact (str | int) – ID of the artifact

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.artifacts.delete("foo/bar", 123):

download(repo, artifact)

Download a repository artifact zip file

https://docs.github.com/en/rest/actions/artifacts#download-an-artifact

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• artifact (str | int) – ID of the artifact

Raises:

HTTPStatusError – If the request was invalid

Return type:

AsyncContextManager[AsyncDownloadProgressIterable[bytes]]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(”…”) as api:

print(“Downloading”, end=””)

with Path(“foo.baz”).open(“wb”) as f:

async with api.artifacts.download(

“org/repo”, “123”

) as download:

async for content, progress in download:

f.write(content) print(“.”, end=””)

class pontos.github.api.GitHubAsyncRESTBranches(client)

async exists(repo, branch)

Check if a single branch in a repository exists

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• branch (str) – Branch name to check

Returns:

True if the branch exists

Return type:

bool

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    exists = await api.branches.exists("foo/bar", "baz")

async delete(repo, branch)

Delete a branch on GitHub

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• branch (str) – Branch to be deleted

Raises:

HTTPStatusError – If the request was invalid

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.branches.delete("foo/bar", "baz")

async protection_rules(repo, branch)

Get branch protection rules for a specific repository branch

https://docs.github.com/en/rest/branches/branch-protection#get-branch-protection

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• branch (str) – Get protection rules for this branch

Raises:

HTTPStatusError – If the request was invalid

Returns:

The currently applied branch protection rules

Return type:

BranchProtection

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    rules = await api.branches.protection_rules(
        "foo/bar", "baz"
    )

async update_protection_rules(repo, branch, *, required_status_checks=None, require_branches_to_be_up_to_date=None, enforce_admins=None, dismissal_restrictions_users=None, dismissal_restrictions_teams=None, dismissal_restrictions_apps=None, dismiss_stale_reviews=None, require_code_owner_reviews=None, required_approving_review_count=None, require_last_push_approval=None, bypass_pull_request_allowances_users=None, bypass_pull_request_allowances_teams=None, bypass_pull_request_allowances_apps=None, restrictions_users=None, restrictions_teams=None, restrictions_apps=None, required_linear_history=None, allow_force_pushes=None, allow_deletions=None, block_creations=None, required_conversation_resolution=None, lock_branch=None, allow_fork_syncing=None, required_signatures=None)

Update or create branch protection rules for a specific repository branch.

https://docs.github.com/en/rest/branches/branch-protection#update-branch-protection

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• branch (str) – Get protection rules for this branch

• required_status_checks (Iterable[Tuple[str, str]] | None) – An iterable of status checks to require in order to merge into this branch. Contains tuples of the name of the required check and the ID of the GitHub App that must provide this check. Set this App ID to None to automatically select the GitHub App that has recently provided this check

• require_branches_to_be_up_to_date (bool | None) – Require branches to be up to date before merging.

• enforce_admins (bool | None) – Enforce all configured restrictions for administrators.

• dismissal_restrictions_users (Iterable[str] | None) – Specify which users can dismiss pull request reviews.

• dismissal_restrictions_teams (Iterable[str] | None) – Specify which teams can dismiss pull request reviews

• dismissal_restrictions_apps (Iterable[str] | None) – Specify which apps can dismiss pull request reviews

• dismiss_stale_reviews (bool | None) – Set to True if you want to automatically dismiss approving reviews when someone pushes a new commit.

• require_code_owner_reviews (bool | None) – Blocks merging pull requests until code owners review them.

• required_approving_review_count (int | None) – Specify the number of reviewers required to approve pull requests. Use a number between 1 and 6 or 0 to not require reviewers.

• require_last_push_approval (bool | None) – Whether someone other than the person who last pushed to the branch must approve this pull request.

• bypass_pull_request_allowances_users (Iterable[str] | None) – The list of user logins allowed to bypass pull request requirements.

• bypass_pull_request_allowances_teams (Iterable[str] | None) – The list of team slugs allowed to bypass pull request requirements.

• bypass_pull_request_allowances_apps (Iterable[str] | None) – The list of app slugs allowed to bypass pull request requirements.

• restrictions_users (Iterable[str] | None) – Restrict users who can push to the protected branch.

• restrictions_teams (Iterable[str] | None) – Restrict teams which can push to the protected branch.

• restrictions_apps (Iterable[str] | None) – Restrict apps which can push to the protected branch.

• required_linear_history (bool | None) – Enforce a linear commit Git history.

• allow_force_pushes (bool | None) – Permit force pushes to the protected branch by anyone with write access to the repository

• allow_deletions (bool | None) – Allow deletion of the protected branch by anyone with write access to the repository.

• block_creations (bool | None) – If set to True, the restrictions branch protection settings which limits who can push will also block pushes which create new branches, unless the push is initiated by a user, team, or app which has the ability to push.

• required_conversation_resolution (bool | None) – Require all conversations on code to be resolved before a pull request can be merged into a branch that matches this rule.

• lock_branch (bool | None) – Whether to set the branch as read-only. If this is True, users will not be able to push to the branch.

• allow_fork_syncing (bool | None) – Whether users can pull changes from upstream when the branch is locked. Set to True to allow fork syncing. Set to False to prevent fork syncing.

• required_signature – True to require signed commits on a branch.

Raises:

HTTPStatusError – If the request was invalid

Returns:

The new branch protection rules

Return type:

BranchProtection

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    rules = await api.branches.update_protection_rules(
        "foo/bar",
        "baz",
        enforce_admins=True,
    )

async delete_protection_rules(repo, branch)

Delete branch protection rules for a specific repository branch

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• branch (str) – Delete protection rules for this branch

Raises:

HTTPStatusError – If the request was invalid

async set_enforce_admins(repo, branch, *, enforce_admins)

Enable/disable enforce admin branch protection rule for a specific repository branch.

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• branch (str) – Delete protection rules for this branch

• enforce_admins (bool) – True to enable. False do disable.

Raises:

HTTPStatusError – If the request was invalid

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.branches.set_enforce_admins(
        "foo/bar", "baz", enforce_admins=True,
    )

async set_required_signatures(repo, branch, *, required_signatures)

Enable/disable required signed commits for a repository branch.

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• branch (str) – Delete protection rules for this branch

• required_signature – True to enable. False do disable.

Raises:

HTTPStatusError – If the request was invalid

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.branches.set_required_signatures(
        "foo/bar", "baz", required_signatures=True,
    )

async update_required_status_checks(repo, branch, *, required_status_checks=None, require_branches_to_be_up_to_date=None)

Update required status check branch protection rules of a repository branch.

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• branch (str) – Delete protection rules for this branch

• required_status_checks (Iterable[Tuple[str, str]] | None) – An iterable of status checks to require in order to merge into this branch. Contains tuples of the name of the required check and the ID of the GitHub App that must provide this check. Set this App ID to None to automatically select the GitHub App that has recently provided this check

• require_branches_to_be_up_to_date (bool | None) – Require branches to be up to date before merging.

Raises:

HTTPStatusError – If the request was invalid

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.branches.update_required_status_checks(
        "foo/bar",
        "baz",
        required_status_checks=[
            ("Unittest", None),
            ("Linting", None),
        ],
        require_branches_to_be_up_to_date=True,
    )

async remove_required_status_checks(repo, branch)

Remove required status check branch protection rules of a repository branch.

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• branch (str) – Delete protection rules for this branch

Raises:

HTTPStatusError – If the request was invalid

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.branches.remove_required_status_checks(
        "foo/bar", "baz"
    )

class pontos.github.api.GitHubAsyncRESTContent(client)

async path_exists(repo, path, *, branch=None)

Check if a path (file or directory) exists in a branch of a repository

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• path (str) – to the file/directory in question

• branch (str | None) – Branch to check, defaults to default branch (:

Returns:

True if existing, False else

Return type:

bool

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    exists = await api.contents.path_exists(
        "foo/bar", "src/utils.py"
    )

class pontos.github.api.GitHubAsyncRESTDependabot(client)

async enterprise_alerts(enterprise, *, state=None, severity=None, ecosystem=None, packages=None, scope=None, sort=AlertSort.CREATED, direction=SortOrder.DESC)

Get the list of dependabot alerts for all repositories of a GitHub enterprise

https://docs.github.com/en/rest/dependabot/alerts#list-dependabot-alerts-for-an-enterprise

Parameters:

• enterprise (str) – Name of the enterprise

• state (AlertState | str | None) – Filter alerts by state

• severity (Severity | str | None) – Filter alerts by severity

• ecosystem (str | None) – Filter alerts by package ecosystem

• package – Return alerts only for the provided packages

• scope (DependencyScope | str | None) – Filter alerts by scope of the vulnerable dependency

• sort (AlertSort | str) – The property by which to sort the results. Default is to sort alerts by creation date.

• direction (str | SortOrder) – The direction to sort the results by. Default is desc.

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

An async iterator yielding the dependabot alerts

Return type:

AsyncIterator[DependabotAlert]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for alert in api.dependabot.enterprise_alerts(
        "my-enterprise"
    ):
        print(alert)

async organization_alerts(organization, *, state=None, severity=None, ecosystem=None, packages=None, scope=None, sort=AlertSort.CREATED, direction=SortOrder.DESC)

Get the list of dependabot alerts for all repositories of a GitHub organization

https://docs.github.com/en/rest/dependabot/alerts#list-dependabot-alerts-for-an-organization

Parameters:

• organization (str) – Name of the organization

• state (AlertState | str | None) – Filter alerts by state

• severity (Severity | str | None) – Filter alerts by severity

• ecosystem (str | None) – Filter alerts by package ecosystem

• package – Return alerts only for the provided packages

• scope (DependencyScope | str | None) – Filter alerts by scope of the vulnerable dependency

• sort (AlertSort | str) – The property by which to sort the results. Default is to sort alerts by creation date.

• direction (str | SortOrder) – The direction to sort the results by. Default is desc.

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

An async iterator yielding the dependabot alerts

Return type:

AsyncIterator[DependabotAlert]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for alert in api.dependabot.organization_alerts(
        "my-enterprise"
    ):
        print(alert)

async alerts(repo, *, state=None, severity=None, ecosystem=None, packages=None, scope=None, sort=AlertSort.CREATED, direction=SortOrder.DESC)

Get the list of dependabot alerts for a repository

https://docs.github.com/en/rest/dependabot/alerts#list-dependabot-alerts-for-a-repository

Parameters:

• repo (str) – GitHub repository (owner/name)

• state (AlertState | str | None) – Filter alerts by state

• severity (Severity | str | None) – Filter alerts by severity

• ecosystem (str | None) – Filter alerts by package ecosystem

• package – Return alerts only for the provided packages

• scope (DependencyScope | str | None) – Filter alerts by scope of the vulnerable dependency

• sort (AlertSort | str) – The property by which to sort the results. Default is to sort alerts by creation date.

• direction (str | SortOrder) – The direction to sort the results by. Default is desc.

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

An async iterator yielding the dependabot alerts

Return type:

AsyncIterator[DependabotAlert]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for alert in api.dependabot.alerts(
        "my-enterprise"
    ):
        print(alert)

async alert(repo, alert_number)

Get a single dependabot alert

https://docs.github.com/en/rest/dependabot/alerts#get-a-dependabot-alert

Parameters:

• repo (str) – GitHub repository (owner/name)

• alert_number (str | int) – The number that identifies a Dependabot alert in its repository

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

Dependabot alert information

Return type:

DependabotAlert

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    alert = await api.dependabot.alert("foo/bar", 123)

async update_alert(repo, alert_number, state, *, dismissed_reason=None, dismissed_comment)

Update a single dependabot alert

https://docs.github.com/en/rest/dependabot/alerts#update-a-dependabot-alert

Parameters:

• repo (str) – GitHub repository (owner/name)

• alert_number (str | int) – The number that identifies a Dependabot alert in its repository

• state (AlertState | str) – The state of the Dependabot alert

• dismissed_reason (DismissedReason | str | None) – Required when state is dismissed. A reason for dismissing the alert.

• dismissed_comment (str) – An optional comment associated with dismissing the alert

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

Dependabot alert information

Return type:

DependabotAlert

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    alert = await api.dependabot.update(
        "foo/bar",
        123,
        AlertState.FIXED,
    )

class pontos.github.api.GitHubAsyncRESTLabels(client)

async get_all(repo, issue)

Get all labels that are set in the issue/pr

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• issue (int | str) – Issue/Pull request number

Returns:

An async iterator yielding the labels

Return type:

AsyncIterator[str]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for label in api.labels.get_all("foo/bar", 123):
        print(label)

async delete_all(repo, issue)

Deletes all labels in the issue/pr.

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• issue (int | str) – Issue/Pull request number

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.labels.delete_all("foo/bar", 123)

async set_all(repo, issue, labels)

Set labels in the issue/pr.

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• issue (int | str) – Issue/Pull request number

• labels (Iterable[str]) – Iterable of labels, that should be set. Existing labels will be overwritten.

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.labels.set_all("foo/bar", 123, ["bug", "doc"])

class pontos.github.api.GitHubAsyncRESTOrganizations(client)

async exists(organization)

Check if an organization exists

Parameters:

repo – GitHub repository (owner/name) to use

Returns:

True if the organization exists

Return type:

bool

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    exists = api.organizations.exists("foo")

async get_repositories(organization, *, repository_type=RepositoryType.ALL)

Get information about organization repositories

https://docs.github.com/en/rest/repos/repos#list-organization-repositories

Parameters:

• organization (str) – GitHub organization to use

• repository_type (RepositoryType | str) – Only list repositories of this type.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Returns:

An async iterator yielding the repositories

Return type:

AsyncIterator[Repository]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for repo in api.organizations.get_repositories(
        "foo"
    ):
        print(repo)

async members(organization, *, member_filter=MemberFilter.ALL, role=MemberRole.ALL)

Get information about organization members

https://docs.github.com/en/rest/orgs/members#list-organization-members

Parameters:

• organization (str) – GitHub organization to use

• member_filter (MemberFilter | str) – Include only members of this kind.

• role (MemberRole | str) – Filter members by their role.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Returns:

An async iterator yielding users

Return type:

AsyncIterator[User]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for user in api.organizations.members(
        "foo"
    ):
        print(user)

async invite(organization, *, email=None, invitee_id=None, role=InvitationRole.DIRECT_MEMBER, team_ids=None)

Invite a user to a GitHub Organization

https://docs.github.com/en/rest/orgs/members#create-an-organization-invitation

Parameters:

• organization (str) – GitHub organization to use

• email (str | None) – Email address of the person you are inviting, which can be an existing GitHub user. Either an email or an invitee_id must be given.

• invitee_id (str | int | None) – GitHub user ID for the person you are inviting. Either an email or an invitee_id must be given.

• role (InvitationRole | str) – The role for the new member. admin - Organization owners with full administrative rights to the organization and complete access to all repositories and teams. direct_member - Non-owner organization members with ability to see other members and join teams by invitation. billing_manager - Non-owner organization members with ability to manage the billing settings of your organization.

• team_ids (Iterable[str | int] | None) – Specify IDs for the teams you want to invite new members to.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.organizations.invite("foo", email="john@doe.com")

async remove_member(organization, username)

Remove a member from a GitHub Organization

https://docs.github.com/en/rest/orgs/members#remove-organization-membership-for-a-user

Parameters:

• organization (str) – GitHub organization to use

• username (str) – The handle for the GitHub user account to remove from the organization.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.organizations.remove_member("foo", "a_user")

async outside_collaborators(organization, *, member_filter=MemberFilter.ALL)

Get information about outside collaborators of an organization

https://docs.github.com/en/rest/orgs/outside-collaborators#list-outside-collaborators-for-an-organization

Parameters:

• organization (str) – GitHub organization to use

• member_filter (MemberFilter | str) – Filter the list of outside collaborators.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Returns:

An async iterator yielding users

Return type:

AsyncIterator[User]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for user in api.organizations.outside_collaborators(
        "foo"
    ):
        print(user)

async remove_outside_collaborator(organization, username)

Remove an outside collaborator from a GitHub Organization

https://docs.github.com/en/rest/orgs/outside-collaborators#remove-outside-collaborator-from-an-organization

Parameters:

• organization (str) – GitHub organization to use

• username (str) – The handle for the GitHub user account to remove from the organization.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.organizations.remove_outside_collaborator(
        "foo", "a_user"
    )

class pontos.github.api.GitHubAsyncRESTPullRequests(client)

async exists(repo, pull_request)

Check if a single branch in a repository exists

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• pull_request (int | str) – Pull request number to check

Returns:

True if the pull requests exists

Return type:

bool

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    exists = await api.pull_request.exists("foo/bar", 123)

async get(repo, pull_request)

Get information about a pull request

https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• pull_request (int | str) – Pull request number

Returns:

Information about the pull request

Raises:

httpx.HTTPStatusError – If the request was invalid

Return type:

PullRequest

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    pr = await api.pull_requests.get("foo/bar", 123)
    print(pr)

async commits(repo, pull_request)

Get all commit information of a pull request

https://docs.github.com/en/rest/pulls/pulls#list-commits-on-a-pull-request

Hint: At maximum GitHub allows to receive 250 commits of a pull request.

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• pull_request (int | str) – Pull request number

Returns:

An async iterator yielding pull request commits

Return type:

AsyncIterator[PullRequestCommit]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for commit in api.pull_requests.commits(
        "foo/bar", 123
    ):
        print(commit)

async create(repo, *, head_branch, base_branch, title, body)

Create a new Pull Request on GitHub

https://docs.github.com/en/rest/pulls/pulls#create-a-pull-request

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• head_branch (str) – Branch to create a pull request from

• base_branch (str) – Branch as target for the pull request

• title (str) – Title for the pull request

• body (str) – Description for the pull request. Can be formatted in Markdown

Raises:

httpx.HTTPStatusError if the request was invalid –

Returns:

A new pull request

Return type:

PullRequest

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    pr = await api.pull_requests.create(
        "foo/bar",
        head_branch="a-new-feature",
        base_branch="main",
        title="A new Feature is ready",
        body="Created a new feature",
    )

async update(repo, pull_request, *, base_branch=None, title=None, body=None)

Update a Pull Request on GitHub

https://docs.github.com/en/rest/pulls/pulls#update-a-pull-request

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• pull_request (int | str) – Pull request number

• base_branch (str | None) – Branch as target for the pull request. Leave empty for keeping the current one.

• title (str | None) – Title for the pull request. Leave empty for keeping the current one.

• body (str | None) – Description for the pull request. Can be formatted in Markdown. Leave empty for keeping the current one.

Raises:

httpx.HTTPStatusError if the request was invalid –

Returns:

Updated pull request

Return type:

PullRequest

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    pr = await api.pull_requests.update(
        "foo/bar",
        123,
        title="Another new Feature",
    )

async add_comment(repo, pull_request, comment)

Add a comment to a pull request on GitHub

https://docs.github.com/en/rest/issues/comments#create-an-issue-comment

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• pull_request (int | str) – Pull request number where to add a comment

• comment (str) – The actual comment message. Can be formatted in Markdown.

Raises:

httpx.HTTPStatusError if the request was invalid –

Return type:

Comment

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.pull_requests.add_comment(
        "foo/bar",
        123,
        "A new comment for the pull request",
    )

async update_comment(repo, comment_id, comment)

Update a comment to a pull request on GitHub

https://docs.github.com/en/rest/issues/comments#update-an-issue-comment

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• comment_id (str | int) – The unique identifier of the comment

• comment (str) – The actual comment message. Can be formatted in Markdown.

Raises:

httpx.HTTPStatusError if the request was invalid –

Return type:

Comment

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.pull_requests.update_comment(
        "foo/bar",
        123,
        "A new comment for the pull request",
    )

async comments(repo, pull_request)

Get all comments of a pull request on GitHub

https://docs.github.com/en/rest/issues/comments#list-issue-comments

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• pull_request (int | str) – Pull request number where to add a comment

Raises:

httpx.HTTPStatusError if the request was invalid –

Return type:

AsyncIterator[Comment]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for comment in api.pull_requests.comments(
        "foo/bar",
        123,
    ):
        print(comment)

async files(repo, pull_request, *, status_list=None)

Get files of a pull request

https://docs.github.com/en/rest/pulls/pulls#list-pull-requests-files

Hint: At maximum GitHub allows to receive 3000 files of a commit.

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• pull_request (int | str) – Pull request number

• status_list (Iterable[FileStatus] | None) – Optional iterable of status change types that should be included in the response

Returns:

Information about the files in the pull request as a dict

Return type:

Dict[FileStatus, Iterable[Path]]

Example

from pontos.github.api import GitHubAsyncRESTApi
from pontos.github.models import FileStatus

async with GitHubAsyncRESTApi(token) as api:
    status = await api.pull_requests.files("foo/bar", 123)
    # list changed files
    print(status[FileStatus.MODIFIED])

class pontos.github.api.GitHubAsyncRESTReleases(client)

async create(repo, tag, *, body=None, name=None, target_commitish=None, draft=False, prerelease=False)

Create a new GitHub release

https://docs.github.com/en/rest/releases/releases#create-a-release

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• tag (str) – The git tag for the release

• body (str | None) – Content of the changelog for the release

• name (str | None) – name of the release, e.g. ‘pontos 1.0.0’

• target_commitish (str | None) – Only needed when tag is not there yet

• draft (bool) – If the release is a draft. False by default.

• prerelease (bool) – If the release is a pre release. False by default.

Raises:

httpx.HTTPStatusError – If the request was invalid

Return type:

Release

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.releases.create(
        "foo/bar",
        "v1.2.3",
        body="A new release",
        name="Bar Release 1.2.3",
    )

async exists(repo, tag)

Check wether a GitHub release exists by tag

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• tag (str) – The git tag for the release

Returns:

True if the release exists

Return type:

bool

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    exists = await = api.releases.exists("foo/bar", "v1.2.3")

async get(repo, tag)

Get data of a GitHub release by tag

https://docs.github.com/en/rest/releases/releases#get-a-release-by-tag-name

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• tag (str) – The git tag for the release

Raises:

httpx.HTTPStatusError – If the request was invalid

Returns:

Information about the release

Return type:

Release

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    release = await api.releases.get("foo/bar", "v1.2.3)
    print(release)

download_release_tarball(repo, tag)

Download a release tarball (tar.gz) file

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• tag (str) – The git tag for the release

Raises:

HTTPStatusError – If the request was invalid

Return type:

AsyncContextManager[AsyncDownloadProgressIterable[bytes]]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api, async with api.releases.download_release_tarball(
    "foo/bar", "v1.0.0"
) as download:
    file_path = Path("a.file.tar.gz")
    with file_path.open("wb") as f:
        async for content, progress in download:
            f.write(content)
            print(progress)

download_release_zip(repo, tag)

Download a release zip file

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• tag (str) – The git tag for the release

Raises:

HTTPStatusError – If the request was invalid

Return type:

AsyncContextManager[AsyncDownloadProgressIterable[bytes]]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api, async with api.releases.download_release_zip(
    "foo/bar", "v1.0.0"
) as download:
    file_path = Path("a.file.zip")
    with file_path.open("wb") as f:
        async for content, progress in download:
            f.write(content)
            print(progress)

async download_release_assets(repo, tag, *, match_pattern=None)

Download release assets

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• tag (str) – The git tag for the release

• match_pattern (str | None) – Optional pattern which the name of the available artifact must match. For example “*.zip”. Allows to download only specific artifacts.

Raises:

HTTPStatusError – If the request was invalid

Return type:

AsyncIterator[Tuple[str, AsyncContextManager[AsyncDownloadProgressIterable[bytes]]]]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async def download_asset(name: str, download_cm) -> Path:
        async with download_cm as iterator:
            file_path = Path(name)
            with file_path.open("wb") as f:
                async for content, progress in iterator:
                    f.write(content)
                    print(name, progress)
            return file_path


    tasks = []
    async for name, download_cm in api.releases.download_release_assets(
        "foo/bar, "v1.2.3",
    ):
        tasks.append(asyncio.create_task(
            download_asset(name, download_cm)
        )

    file_paths = await asyncio.gather(*tasks)

async upload_release_assets(repo, tag, files)

Upload release assets asynchronously

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• tag (str) – The git tag for the release

• files (Iterable[Path | Tuple[Path, str]]) – An iterable of file paths or an iterable of tuples containing a file path and content types to upload as an asset

Returns:

yields each file after its upload is finished

Raises:

HTTPStatusError – If an upload request was invalid

Return type:

AsyncIterator[Path]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:

    files = (Path("foo.txt"), Path("bar.txt"),)
    async for uploaded_file in api.releases.upload_release_assets(
        "foo/bar", "1.2.3", files
    ):
        print(f"Uploaded: {uploaded_file}")

    files = [
        (Path("foo.txt"), "text/ascii"),
        (Path("bar.pdf"), "application/pdf"),
    ]
    async for uploaded_file in api.releases.upload_release_assets(
        "foo/bar", "1.2.3", files
    ):
        print(f"Uploaded: {uploaded_file}")

class pontos.github.api.GitHubAsyncRESTRepositories(client)

async get(repo)

Get a repository

https://docs.github.com/en/rest/repos/repos#get-a-repository

Parameters:

repo (str) – GitHub repository (owner/name) to request

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

Information about the repository

Return type:

Repository

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    repo = await api.repositories.get("foo/bar")
    print(repo)

async delete(repo)

Delete a repository

Parameters:

repo (str) – GitHub repository (owner/name) to delete

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.repositories.delete("foo/bar")

async create(organization, name, *, description=None, homepage=None, private=False, has_issues=True, has_projects=True, has_wiki=True, has_downloads=True, is_template=False, team_id=None, auto_init=False, gitignore_template=None, license_template=None, allow_squash_merge=True, allow_merge_commit=True, allow_rebase_merge=True, allow_auto_merge=False, allow_update_branch=False, delete_branch_on_merge=False, squash_merge_commit_title=None, squash_merge_commit_message=None, merge_commit_title=None, merge_commit_message=None)

Create a new repository at GitHub

https://docs.github.com/en/rest/repos/repos#create-an-organization-repository

Parameters:

• organization (str) – Name of the GitHub organization where to create the new repository.

• name (str) – Name of the GitHub repository.

• description (str | None) – Description of the GitHub repository.

• homepage (str | None) – A URL with more information about the repository.

• private (bool | None) – Whether the repository is private. Default: False.

• has_issues (bool | None) – Either True to enable issues for this repository or False to disable them. Default: True

• has_projects (bool | None) – Either True to enable projects for this repository or False to disable them. Note: If you’re creating a repository in an organization that has disabled repository projects, the default is false, and if you pass true, the API returns an error. Default: true.

• has_wiki (bool | None) – Either True to enable the wiki for this repository or False to disable it. Default: True.

• has_downloads (bool | None) – Whether downloads are enabled. Default: True.

• is_template (bool | None) – Either True to make this repo available as a template repository or False to prevent it. Default: False.

• team_id (SupportsStr | None) – The id of the team that will be granted access to this repository. This is only valid when creating a repository in an organization.

• auto_init (bool | None) – Pass True to create an initial commit with empty README. Default: False.

• gitignore_template (GitIgnoreTemplate | str | None) – Desired language or platform .gitignore template to apply. Use the name of the template without the extension. For example, “Haskell”.

• license_template (LicenseType | str | None) – Choose an open source license template that best suits your needs, and then use the license keyword as the license_template string. For example, “mit” or “mpl-2.0”.

• allow_squash_merge (bool | None) – Either true to allow squash-merging pull requests, or false to prevent squash-merging. Default: True

• allow_merge_commit (bool | None) – Either True to allow merging pull requests with a merge commit, or False to prevent merging pull requests with merge commits. Default: True.

• allow_rebase_merge (bool | None) – Either True to allow rebase-merging pull requests, or False to prevent rebase-merging. Default: True.

• allow_auto_merge (bool | None) – Either True to allow auto-merge on pull requests, or False to disallow auto-merge. Default: False.

• allow_update_branch (bool | None) – Either True to always allow a pull request head branch, that is behind its base branch, to be updated, even if it is not required to be up to date before merging, or False otherwise. Default: False.

• delete_branch_on_merge (bool | None) – Either True to allow automatically deleting head branches when pull requests are merged, or False to prevent automatic deletion. Default: False.

• squash_merge_commit_title (SquashMergeCommitTitle | str | None) –

  The default value for a squash merge commit title:

  • ”PR_TITLE” - default to the pull request’s title.

  • ”COMMIT_OR_PR_TITLE” - default to the commit’s title (if

    only one commit) or the pull request’s title (when more than one commit).

  Can be one of: “PR_TITLE”, “COMMIT_OR_PR_TITLE”

• squash_merge_commit_message (SquashMergeCommitMessage | str | None) –

  The default value for a squash merge commit message:

  • ”PR_BODY” - default to the pull request’s body.

  • ”COMMIT_MESSAGES” - default to the branch’s commit messages.

  • ”BLANK” - default to a blank commit message.

  Can be one of: “PR_BODY”, “COMMIT_MESSAGES”, “BLANK”

• merge_commit_title (MergeCommitTitle | str | None) –

  The default value for a merge commit title.

  • ”PR_TITLE” - default to the pull request’s title.

  • ”MERGE_MESSAGE” - default to the classic title for a merge

    message (e.g., Merge pull request #123 from branch-name).

  Can be one of: “PR_TITLE”, “MERGE_MESSAGE”

• merge_commit_message (MergeCommitMessage | str | None) –

  The default value for a merge commit message.

  • ”PR_TITLE” - default to the pull request’s title.

  • ”PR_BODY” - default to the pull request’s body.

  • ”BLANK” - default to a blank commit message.

  Can be one of: “PR_BODY”, “PR_TITLE”, “BLANK”

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Return type:

Repository

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    repo = await api.repositories.create(
        "foo/bar",
        "baz",
        description="A new baz repository",
        private=True,
        allow_squash_merge=True,
        allow_merge_commit=False,
        allow_rebase_merge=True,
        allow_auto_merge=True,
        allow_update_branch=True,
        delete_branch_on_merge=True,
    )

async archive(repo)

Archive a GitHub repository

WARNING: It is not possible to unarchive a repository via the API.

Parameters:

repo (str) – GitHub repository (owner/name) to update

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.repositories.archive("foo/bar")

async update(repo, *, name=None, description=None, homepage=None, private=False, has_issues=True, has_projects=True, has_wiki=True, is_template=False, default_branch=None, allow_squash_merge=True, allow_merge_commit=True, allow_rebase_merge=True, allow_auto_merge=False, allow_update_branch=False, delete_branch_on_merge=False, squash_merge_commit_title=None, squash_merge_commit_message=None, merge_commit_title=None, merge_commit_message=None, allow_forking=False, web_commit_signoff_required=False)

Create a new repository at GitHub

https://docs.github.com/en/rest/repos/repos#update-a-repository

Parameters:

• repo (str) – GitHub repository (owner/name) to update

• name (str | None) – New name of the GitHub repository.

• description (str | None) – Description of the GitHub repository.

• homepage (str | None) – A URL with more information about the repository.

• private (bool | None) – Whether the repository is private. Default: False.

• has_issues (bool | None) – Either True to enable issues for this repository or False to disable them. Default: True

• has_projects (bool | None) – Either True to enable projects for this repository or False to disable them. Note: If you’re creating a repository in an organization that has disabled repository projects, the default is false, and if you pass true, the API returns an error. Default: true.

• has_wiki (bool | None) – Either True to enable the wiki for this repository or False to disable it. Default: True.

• is_template (bool | None) – Either True to make this repo available as a template repository or False to prevent it. Default: False.

• default_branch (str | None) – Updates the default branch for this repository.

• allow_squash_merge (bool | None) – Either true to allow squash-merging pull requests, or false to prevent squash-merging. Default: True

• allow_merge_commit (bool | None) – Either True to allow merging pull requests with a merge commit, or False to prevent merging pull requests with merge commits. Default: True.

• allow_rebase_merge (bool | None) – Either True to allow rebase-merging pull requests, or False to prevent rebase-merging. Default: True.

• allow_auto_merge (bool | None) – Either True to allow auto-merge on pull requests, or False to disallow auto-merge. Default: False.

• allow_update_branch (bool | None) – Either True to always allow a pull request head branch that is behind its base branch to be updated even if it is not required to be up to date before merging, or False otherwise. Default: False.

• delete_branch_on_merge (bool | None) – Either True to allow automatically deleting head branches when pull requests are merged, or False to prevent automatic deletion. Default: False.

• squash_merge_commit_title (SquashMergeCommitTitle | str | None) –

  The default value for a squash merge commit title:

  • ”PR_TITLE” - default to the pull request’s title.

  • ”COMMIT_OR_PR_TITLE” - default to the commit’s title (if

    only one commit) or the pull request’s title (when more than one commit).

  Can be one of: “PR_TITLE”, “COMMIT_OR_PR_TITLE”

• squash_merge_commit_message (SquashMergeCommitMessage | str | None) –

  The default value for a squash merge commit message:

  • ”PR_BODY” - default to the pull request’s body.

  • ”COMMIT_MESSAGES” - default to the branch’s commit messages.

  • ”BLANK” - default to a blank commit message.

  Can be one of: “PR_BODY”, “COMMIT_MESSAGES”, “BLANK”

• merge_commit_title (MergeCommitTitle | str | None) –

  The default value for a merge commit title.

  • ”PR_TITLE” - default to the pull request’s title.

  • ”MERGE_MESSAGE” - default to the classic title for a merge

    message (e.g., Merge pull request #123 from branch-name).

  Can be one of: “PR_TITLE”, “MERGE_MESSAGE”

• merge_commit_message (MergeCommitMessage | str | None) –

  The default value for a merge commit message.

  • ”PR_TITLE” - default to the pull request’s title.

  • ”PR_BODY” - default to the pull request’s body.

  • ”BLANK” - default to a blank commit message.

  Can be one of: “PR_BODY”, “PR_TITLE”, “BLANK”

• allow_forking (bool | None) – Either True to allow private forks, or False to prevent private forks. Default: False.

• web_commit_signoff_required (bool | None) – Either True to require contributors to sign off on web-based commits, or False to not require contributors to sign off on web-based commits. Default: False.

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

The updated repository

Return type:

Repository

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    repo = await api.repositories.update(
        "foo/bar",
        allow_squash_merge=True,
        allow_merge_commit=False,
        allow_rebase_merge=True,
        allow_auto_merge=True,
        allow_update_branch=True,
        delete_branch_on_merge=True,
    )

async topics(repo)

List all topics of a repository

Parameters:

repo (str) – GitHub repository (owner/name) to list the topics for

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

An iterable of topics as string

Return type:

Iterable[str]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    topics = await api.repositories.topics("foo/bar")

async update_topics(repo, new_topics)

Replace all topics of a repository

Parameters:

• repo (str) – GitHub repository (owner/name) to update the topics for

• new_topics (Iterable[str]) – Iterable of new topics to set on the repository

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

An iterable of topics as string

Return type:

Iterable[str]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    topics = await api.repositories.update_topics(
        "foo/bar", ["foo", "bar"]
    )

class pontos.github.api.GitHubAsyncRESTSearch(client)

async repositories(*, keywords, qualifiers, order=SortOrder.DESC, sort=None)

Search for repositories

https://docs.github.com/en/rest/search#search-repositories

https://docs.github.com/en/search-github/searching-on-github/searching-for-repositories

Parameters:

• keywords (Iterable[str]) – List of keywords to search for.

• qualifiers (Iterable[Qualifier]) – List of qualifiers.

• order (str | SortOrder) – Sort order either ‘asc’ or ‘desc’. Default is ‘desc’.

• sort (str | RepositorySort | None) – Sort the found repositories by this criteria.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Returns:

An async iterator yielding repositories

Return type:

AsyncIterator[Repository]

Example

from pontos.github.api import GitHubAsyncRESTApi
from pontos.github.models import (
    InReadmeQualifier,
    InTopicsQualifier,
)

async with GitHubAsyncRESTApi(token) as api:
    # search for keywords in repo topics and READMEs
    async for repo in api.search(
        keywords=["utils", "search", "golang"],
        qualifier=[
            InTopicsQualifier(),
            InReadmeQualifier(),
        ],
    )

class pontos.github.api.GitHubAsyncRESTTags(client)

async create(repo, tag, message, name, email, git_object, *, git_object_type=GitObjectType.COMMIT, date=None)

Create a new Git tag

https://docs.github.com/en/rest/git/tags#create-a-tag-object

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• tag (str) – The tag’s name. This is typically a version (e.g., “v0.0.1”).

• message (str) – The tag message.

• name (str) – The name of the author of the tag

• email (str) – The email of the author of the tag

• git_object (str) – The SHA of the git object this is tagging.

• git_object_type (GitObjectType | str | None) – The type of the object we’re tagging. Normally this is a commit type but it can also be a tree or a blob.

• date (datetime | None) – When this object was tagged.

Raises:

HTTPStatusError – If the request was invalid

Returns:

A new git tag

Return type:

Tag

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    tag = await api.tags.create(
        "foo/bar",
        "v1.2.3",
        "Create tag v1.2.3",
        "John Doe",
        "john@doe.com",
        e746420,
    )
    print(tag)

async create_tag_reference(repo, tag, sha)

Create git tag reference (A real tag in git).

https://docs.github.com/en/rest/git/refs#create-a-reference

Parameters:

• repo (str) – The name of the repository. The name is not case sensitive.

• tag (str) – Github tag name.

• sha (str) – The SHA1 value for this Github tag.

Raises:

HTTPStatusError – If the request was invalid

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.tags.create_tag_reference(
        "foo/bar",
        "v1.2.3",
        e746420,
    )

async get(repo, tag_sha)

Get information about a git tag

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• tag_sha (str) – SHA of the git tag object

Raises:

HTTPStatusError – If the request was invalid

Return type:

Tag

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    tag = await api.tags.get("foo/bar", "e746420")
    print(tag)

async get_all(repo)

Get information about all git tags

Parameters:

repo (str) – GitHub repository (owner/name) to use

Raises:

HTTPStatusError – If the request was invalid

Return type:

AsyncIterator[RepositoryTag]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for tag in api.tags.get_all(
        "foo/bar"
    ):
        print(tag)

class pontos.github.api.GitHubAsyncRESTTeams(client)

async get_all(organization)

Get information about teams of an organization.

https://docs.github.com/en/rest/teams/teams#list-teams

Parameters:

organization (str) – GitHub organization to use

Raises:

httpx.HTTPStatusError – If there was an error in the request

Returns:

An async iterator yielding teams

Return type:

AsyncIterator[Team]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for team in api.teams.get_all("foo"):
        print(team)

async create(organization, name, *, description=None, maintainers=None, repo_names=None, privacy=None, parent_team_id=None)

Create a new team in an organization

https://docs.github.com/en/rest/teams/teams#create-a-team

Parameters:

• organization (str) – GitHub organization to use

• name (str) – The name of the new team.

• description (str | None) – The description of the team.

• maintainers (Iterable[str] | None) – List GitHub IDs for organization members who will become team maintainers.

• repo_names (Iterable[str] | None) – The full name (e.g., “organization-name/repository-name” ) of repositories to add the team to.

• privacy (TeamPrivacy | str | None) –

  The level of privacy this team should have. The options are:

  For a non-nested team:

  • secret - only visible to organization owners and members

    of this team.

  • closed - visible to all members of this organization.

  Default: secret

  For a parent or child team:

  • closed - visible to all members of this organization.

  Default for child team: closed

• parent_team_id (str | None) – The ID of a team to set as the parent team.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Returns:

A new team

Return type:

Team

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    team = await api.teams.create("foo", "devops")
    print(team)

async get(organization, team)

Gets a team using the team’s slug. GitHub generates the slug from the team name.

https://docs.github.com/en/rest/teams/teams#get-a-team-by-name

Parameters:

• organization (str) – GitHub organization to use

• team (str) – The team slug of the team.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Returns:

Information about the team

Return type:

Team

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    team = await api.teams.get("foo", "devops")
    print(team)

async update(organization, team, *, name, description=None, privacy=None, parent_team_id=None)

Update team information in an organization

https://docs.github.com/en/rest/teams/teams#update-a-team

Parameters:

• organization (str) – GitHub organization to use

• team (str) – The slug of the team name.

• name (str) – The name of the team.

• description (str | None) – The description of the team.

• privacy (TeamPrivacy | str | None) –

  The level of privacy this team should have. The options are:

  For a non-nested team:

  • secret - only visible to organization owners and members

    of this team.

  • closed - visible to all members of this organization.

  Default: secret

  For a parent or child team:

  • closed - visible to all members of this organization.

  Default for child team: closed

• parent_team_id (str | None) – The ID of a team to set as the parent team.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Returns:

The updated team

Return type:

Team

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    team = await api.teams.update(
        "foo", "devops", name="DevSecOps"
    )

async delete(organization, team)

Delete a new team of an organization

https://docs.github.com/en/rest/teams/teams#delete-a-team

Parameters:

• organization (str) – GitHub organization to use

• team (str) – The slug of the team name.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    await api.teams.delete("foo", "bar")

async members(organization, team)

Get all members of a team. Team members will include the members of child teams.

https://docs.github.com/en/rest/teams/members#list-team-members

Parameters:

• organization (str) – GitHub organization to use

• team (str) – The slug of the team name.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Returns:

An async iterator yielding users

Return type:

AsyncIterator[User]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for user in api.teams.members("foo", "bar):
        print(user)

async update_member(organization, team, username, *, role=TeamRole.MEMBER)

Add or update a member of a team.

https://docs.github.com/en/rest/teams/members#add-or-update-team-membership-for-a-user

Parameters:

• organization (str) – GitHub organization to use

• team (str) – The slug of the team name.

• username (str) – The handle for the GitHub user account.

• role (TeamRole | str) – The role that this user should have in the team. Default: member. Can be one of: member, maintainer.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Example

from pontos.github.api import GitHubAsyncRESTApi
from pontos.github.models import TeamRole

async with GitHubAsyncRESTApi(token) as api:
    await api.teams.update_member(
        "foo",
        "bar",
        "a_user",
        role=TeamRole.MAINTAINER,
    )

async add_member(organization, team, username, *, role=TeamRole.MEMBER)

Add or update a member of a team.

https://docs.github.com/en/rest/teams/members#add-or-update-team-membership-for-a-user

Parameters:

• organization (str) – GitHub organization to use

• team (str) – The slug of the team name.

• username (str) – The handle for the GitHub user account.

• role (TeamRole | str) – The role that this user should have in the team. Default: member. Can be one of: member, maintainer.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Example

from pontos.github.api import GitHubAsyncRESTApi
from pontos.github.models import TeamRole

async with GitHubAsyncRESTApi(token) as api:
    await api.teams.update_member(
        "foo",
        "bar",
        "a_user",
        role=TeamRole.MAINTAINER,
    )

async remove_member(organization, team, username)

Remove a member from a team.

https://docs.github.com/en/rest/teams/members#remove-team-membership-for-a-user

Parameters:

• organization (str) – GitHub organization to use

• team (str) – The slug of the team name.

• username (str) – The handle for the GitHub user account.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Example

from pontos.github.api import GitHubAsyncRESTApi
from pontos.github.models import TeamRole

async with GitHubAsyncRESTApi(token) as api:
    await api.teams.remove_member(
        "foo",
        "bar",
        "a_user",
    )

async repositories(organization, team)

Lists a team’s repositories visible to the authenticated user.

https://docs.github.com/en/rest/teams/teams#list-team-repositories

Parameters:

• organization (str) – GitHub organization to use

• team (str) – The slug of the team name.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Returns:

An async iterator yielding repositories

Return type:

AsyncIterator[Repository]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for repo in api.teams.repositories("foo", "bar"):
        print(repo)

async update_permission(organization, team, repository, permission)

Add or update team repository permissions

Parameters:

• organization (str) – GitHub organization to use

• team (str) – The slug of the team name.

• repository (str) – GitHub repository (only name) to add or change permissions on.

• permission (Permission | str) – The permission to grant the team on the repository.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Example

from pontos.github.api import GitHubAsyncRESTApi
from pontos.github.models import Permission

async with GitHubAsyncRESTApi(token) as api:
    await api.teams.update_permission(
        "foo",
        "bar",
        "baz",
        Permission.MAINTAIN,
    )

async add_permission(organization, team, repository, permission)

Add or update team repository permissions

Parameters:

• organization (str) – GitHub organization to use

• team (str) – The slug of the team name.

• repository (str) – GitHub repository (only name) to add or change permissions on.

• permission (Permission | str) – The permission to grant the team on the repository.

Raises:

httpx.HTTPStatusError – If there was an error in the request

Example

from pontos.github.api import GitHubAsyncRESTApi
from pontos.github.models import Permission

async with GitHubAsyncRESTApi(token) as api:
    await api.teams.update_permission(
        "foo",
        "bar",
        "baz",
        Permission.MAINTAIN,
    )

class pontos.github.api.GitHubAsyncRESTWorkflows(client)

get_all(repo)

List all workflows of a repository

https://docs.github.com/en/rest/actions/workflows#list-repository-workflows

Parameters:

repo (str) – GitHub repository (owner/name) to use

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

An async iterator yielding workflows

Return type:

AsyncIterator[Workflow]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for workflow in api.workflows.get_all("foo/bar"):
        print(workflow)

async get(repo, workflow)

Get the information for the given workflow

https://docs.github.com/en/rest/actions/workflows#get-a-workflow

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• workflow (str | int) – ID of the workflow or workflow file name. For example main.yml.

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

Information about the workflow

Return type:

Workflow

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    workflow = await api.workflows.get("foo/bar", "ci.yml")
    print(workflow)

async create_workflow_dispatch(repo, workflow, *, ref, inputs=None)

Create a workflow dispatch event to manually trigger a GitHub Actions workflow run.

https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• workflow (str | int) – ID of the workflow or workflow file name. For example main.yml.

• ref (str) – The git reference for the workflow. The reference can be a branch or tag name.

• inputs (Dict[str, str] | None) – Input keys and values configured in the workflow file. Any default properties configured in the workflow file will be used when inputs are omitted.

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Example

from pontos.github.api import GitHubAsyncRESTApi

with GitHubAsyncRESTApi(token) as api:
    await api.workflows.create_workflow_dispatch(
        "foo/bar", "ci.yml", ref="main"
    )

get_workflow_runs(repo, workflow=None, *, actor=None, branch=None, event=None, status=None, created=None, exclude_pull_requests=None)

List all workflow runs of a repository or of a specific workflow.

https://docs.github.com/en/rest/actions/workflow-runs#list-workflow-runs-for-a-repository https://docs.github.com/en/rest/actions/workflow-runs#list-workflow-runs-for-a-workflow

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• workflow (str | int | None) – Optional ID of the workflow or workflow file name. For example main.yml.

• actor (str | None) – Only return workflow runs of this user ID.

• branch (str | None) – Only return workflow runs for a specific branch.

• event (Event | str | None) – Only return workflow runs triggered by the event specified. For example, push, pull_request or issue. For more information, see https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows.

• status (WorkflowRunStatus | str | None) – Only return workflow runs with the check run status or conclusion that specified. For example, a conclusion can be success or a status can be in_progress. Can be one of: completed, action_required, cancelled, failure, neutral, skipped, stale, success, timed_out, in_progress, queued, requested, waiting.

• created (str | None) – Only returns workflow runs created within the given date-time range. For more information on the syntax, see https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#query-for-dates

• exclude_pull_requests (bool | None) – If true pull requests are omitted from the response.

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

An async iterator yielding workflow runs

Return type:

AsyncIterator[WorkflowRun]

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    async for run in api.workflows.get_workflow_runs(
        "foo/bar",
        "ci.yml"
    ):
        print(run)

async get_workflow_run(repo, run)

Get information about a single workflow run

https://docs.github.com/en/rest/actions/workflow-runs#get-a-workflow-run

Parameters:

• repo (str) – GitHub repository (owner/name) to use

• run (str | int) – The ID of the workflow run

Raises:

HTTPStatusError – A httpx.HTTPStatusError is raised if the request failed.

Returns:

Information about the workflow run

Return type:

WorkflowRun

Example

from pontos.github.api import GitHubAsyncRESTApi

async with GitHubAsyncRESTApi(token) as api:
    run = await api.workflows.get_workflow_run("foo/bar", 123)
    print(run)