github3_utils

Handy utilities for github3.py.

Classes:

Impersonate(name, email)

Context manager to make commits as a specific user.

Exceptions:

RateLimitExceeded(reset_time)

Custom exception class to indicate the GitHub rate limit has been exceeded and no further requests should be made.

Functions:

echo_rate_limit(github[, verbose])	Contextmanager to echo the GitHub API rate limit before and after making a series of requests.
get_repos(user_or_org[, full])	Returns an iterator over the user or organisation's repositories.
get_user(github)	Retrieve a github3.users.User object for the authenticated user.
iter_repos(github[, users, orgs])	Returns an iterator over the repositories belonging to all users and all orgs.
protect_branch(branch[, status_checks])	Enable force push protection and configure status check enforcement.

class Impersonate(name, email)

Bases: object

Context manager to make commits as a specific user.

Sets the following environment variables:

• GIT_COMMITTER_NAME

• GIT_COMMITTER_EMAIL

• GIT_AUTHOR_NAME

• GIT_AUTHOR_EMAIL

Attention

Any changes to environment variables made during the scope of the context manager will be reset on exit.

Example:

name = "repo-helper[bot]"
email = f"74742576+{name}@users.noreply.github.com"

commit_as_bot = Impersonate(name=name, email=email)

with commit_as_bot():
    ...

Parameters

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

• email (str) – The email address of the committer.

Attributes:

email	The email address of the committer.
name	The name of the committer.

email

Type:    str

The email address of the committer.

name

Type:    str

The name of the committer.

exception RateLimitExceeded(reset_time)

Bases: RuntimeError

Custom exception class to indicate the GitHub rate limit has been exceeded and no further requests should be made.

Parameters

reset_time (datetime) – The time at which the rate limit will be reset.

Attributes:

reset_time

The time at which the rate limit will be reset.

reset_time

Type:    datetime

The time at which the rate limit will be reset.

echo_rate_limit(github, verbose=True)

Contextmanager to echo the GitHub API rate limit before and after making a series of requests.

Parameters

• github (GitHub)

• verbose (bool) – If False no output will be printed. Default True.

Raises

click.Abort if the rate limit has been exceeded.

Return type

Iterator[GitHub]

get_repos(user_or_org, full=False)

Returns an iterator over the user or organisation’s repositories.

New in version 0.5.0.

Parameters

• user_or_org (Union[User, Organization])

• full (bool) – If True yields Repository objects. Otherwise, yields ShortRepository objects. Default False.

Return type

Union[Iterator[Repository], Iterator[ShortRepository]]

Overloads

• get_repos(user_or_org, full: Literal[True] ) -> Iterator[Repository]

• get_repos(user_or_org, full: Literal[False] = … ) -> Iterator[ShortRepository]

get_user(github)

Retrieve a github3.users.User object for the authenticated user.

Parameters

github (GitHub)

Return type

User

iter_repos(github, users=(), orgs=())

Returns an iterator over the repositories belonging to all users and all orgs.

New in version 0.5.0.

Parameters

• github (GitHub)

• users (Iterable[str]) – An iterable of usernames to fetch the repositories for. Default ().

• orgs (Iterable[str]) – An iterable of organization names to fetch the repositories for. Default ().

Return type

Iterator[ShortRepository]

protect_branch(branch, status_checks=None)

Enable force push protection and configure status check enforcement.

Parameters

• branch (Branch) – The branch to enable protection for.

• status_checks (Optional[List[str]]) – A list of strings naming status checks which must pass before merging. Use None or omit to use the already associated value. Default None.

Return type

bool

Returns

True if successful, False otherwise.