github3-utils¶
Handy utilities for github3.py
Installation¶
python3 -m pip install github3-utils --user
First add the required channels
conda config --add channels https://conda.anaconda.org/conda-forge
conda config --add channels https://conda.anaconda.org/domdfcoding
Then install
conda install github3-utils
python3 -m pip install git+https://github.com/domdfcoding/github3-utils@master --user
Contents¶
github3_utils
¶
Handy utilities for github3.py.
Classes:
|
Context manager to make commits as a specific user. |
Exceptions:
|
Custom exception class to indicate the GitHub rate limit has been exceeded and no further requests should be made. |
Functions:
|
Contextmanager to echo the GitHub API rate limit before and after making a series of requests. |
|
Returns an iterator over the user or organisation’s repositories. |
|
Retrieve a |
|
Returns an iterator over the repositories belonging to all |
|
Enable force push protection and configure status check enforcement. |
-
class
Impersonate
(name, email)[source]¶ 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
Attributes:
-
exception
RateLimitExceeded
(reset_time)[source]¶ Bases:
RuntimeError
Custom exception class to indicate the GitHub rate limit has been exceeded and no further requests should be made.
-
echo_rate_limit
(github, verbose=True)[source]¶ Contextmanager to echo the GitHub API rate limit before and after making a series of requests.
-
get_repos
(user_or_org, full=False)[source]¶ 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
) – IfTrue
yieldsRepository
objects. Otherwise, yieldsShortRepository
objects. DefaultFalse
.
- Return type
- Overloads
get_repos
(user_or_org, full:Literal
[True
] ) ->Iterator
[Repository
]get_repos
(user_or_org, full:Literal
[False
] = … ) ->Iterator
[ShortRepository
]
-
get_user
(github)[source]¶ Retrieve a
github3.users.User
object for the authenticated user.
-
iter_repos
(github, users=(), orgs=())[source]¶ Returns an iterator over the repositories belonging to all
users
and allorgs
.New in version 0.5.0.
github3_utils.apps
¶
Functions and classes for GitHub apps.
Classes:
|
Class to aid switching contexts between the app itself and its installations. |
Functions:
|
Returns an iterator over all repositories the app is installed for. |
|
Create markdown footer links for a GitHub app. |
-
class
ContextSwitcher
(client, private_key_pem, app_id)[source]¶ Bases:
object
Class to aid switching contexts between the app itself and its installations.
- Parameters
Attributes:
The integer identifier for this GitHub App.
The bytes of the private key for this GitHub App.
Methods:
Login as the GitHub app.
login_as_org_installation
(organization)Login as an organization installation of a GitHub app, and return its installation ID.
login_as_repo_installation
(owner, repository)Login as a repository installation of a GitHub app, and return its installation ID.
login_as_user_installation
(username)Login as a user installation of a GitHub app, and return its installation ID.
-
login_as_org_installation
(organization)[source]¶ Login as an organization installation of a GitHub app, and return its installation ID.
New in version 0.5.0.
-
login_as_repo_installation
(owner, repository)[source]¶ Login as a repository installation of a GitHub app, and return its installation ID.
-
iter_installed_repos
(*, context_switcher=None, client=None, private_key_pem=None, app_id=None)[source]¶ Returns an iterator over all repositories the app is installed for.
- Parameters
context_switcher (
Optional
[ContextSwitcher
]) – AContextSwitcher
used to switch contexts between the app itself and its installations. DefaultNone
.client (
Optional
[GitHub
]) – The bytes of the private key for this GitHub App. DefaultNone
.private_key_pem (
Optional
[bytes
]) – The bytes of the private key for this GitHub App. DefaultNone
.app_id (
Optional
[int
]) – The integer identifier for this GitHub App. DefaultNone
.
Either
context_switcher
or all ofclient
,private_key_pem
andapp_id
must be provided.
Create markdown footer links for a GitHub app.
- Parameters
owner (
str
) – The owner of the repository.name (
str
) – The name of the repository.event_date (
Optional
[date
]) – The date on which the footer is being created. Determines the emoji shown. DefaultNone
.type (
Literal
['marketplace'
,'app'
]) – Whether the footer is for a GitHub app or an item in the marketplace. Default'marketplace'
.docs_url (
Optional
[str
]) – The URL of the app’s documentation. IfNone
no link will be shown. DefaultNone
.
New in version 0.3.0.
- Return type
github3_utils.check_labels
¶
Helpers for creating labels to mark pull requests with which tests are failing.
New in version 0.4.0.
Classes:
|
Represents the sets of status checks returned by |
|
Represents an issue or pull request label. |
Data:
Labels corresponding to failing pull request checks. |
Functions:
|
Returns a |
|
Labels the given pull request to indicate which checks are failing. |
-
namedtuple
Checks
(successful, failing, running, skipped, neutral)[source]¶ Bases:
NamedTuple
Represents the sets of status checks returned by
get_checks_for_pr()
.- Fields
-
__repr__
()¶ Return a nicely formatted representation string
-
class
Label
(name, color, description=None)[source]¶ Bases:
object
Represents an issue or pull request label.
- Parameters
Methods:
__repr__
()Return a string representation of the
Label
.__str__
()Return
str(self)
.create
(repo)Create this label on the given repository.
to_dict
()Return the
Label
as a dictionary.Attributes:
The background colour of the label.
A short description of the label.
The text of the label.
-
create
(repo)[source]¶ Create this label on the given repository.
- Parameters
repo (
Repository
)- Return type
-
check_status_labels
= {'failure: Linux': Label(name='failure: Linux', color='#F6BDC0', description='The Linux tests are failing.'), 'failure: Windows': Label(name='failure: Windows', color='#F07470', description='The Windows tests are failing.'), 'failure: docs': Label(name='failure: docs', color='#EA4C46', description='The docs check is failing.'), 'failure: flake8': Label(name='failure: flake8', color='#B60205', description='The Flake8 check is failing.'), 'failure: mypy': Label(name='failure: mypy', color='#DC1C13', description='The mypy check is failing.')}¶ -
Labels corresponding to failing pull request checks.
-
get_checks_for_pr
(pull)[source]¶ Returns a
Checks
object containing sets of check names grouped by their status.- Parameters
pull (
Union
[PullRequest
,ShortPullRequest
]) – The pull request to obtain checks for.- Return type
-
label_pr_failures
(pull)[source]¶ Labels the given pull request to indicate which checks are failing.
- Parameters
pull (
Union
[PullRequest
,ShortPullRequest
])- Return type
- Returns
The new labels set for the pull request.
github3_utils.click
¶
Extensions for click.
New in version 0.2.0.
Functions:
|
Creates a |
github3_utils.secrets
¶
Functions for setting and updating GitHub Actions secrets.
Classes:
|
Functions:
|
Returns the URL via which secrets can be checked and set. |
|
Encrypt a GitHub Actions secret. |
|
Returns the public key used to encrypt secrets for the given repository. |
|
Returns a list of secret names for the given repository. |
|
Set the value of the given secret. |
-
typeddict
PublicKey
[source]¶ typing.TypedDict
representing the return type ofget_public_key()
.
-
build_secrets_url
(repo)[source]¶ Returns the URL via which secrets can be checked and set.
- Parameters
repo (
Repository
) – The repository to check/set secrets for.- Return type
-
encrypt_secret
(public_key, secret_value)[source]¶ Encrypt a GitHub Actions secret.
If the key has been obtained with
get_secrets()
thenpublic_key
will be:get_secrets(repo)['key']
- Return type
-
get_public_key
(repo)[source]¶ Returns the public key used to encrypt secrets for the given repository.
- Parameters
repo (
Repository
) – The repository the secrets are to be set for.- Return type
-
get_secrets
(repo)[source]¶ Returns a list of secret names for the given repository.
- Parameters
repo (
Repository
)- Return type
github3_utils.testing
¶
Fixtures for pytest.
Attention
This module has the following additional requirements:
betamax>=0.8.1 pytest>=6.0.0
These can be installed as follows:
python -m pip install github3-utils[testing]
New in version 0.2.0.
To use this module you need to add, at a minimum, the following to your conftest.py
:
from betamax import Betamax
pytest_plugins = ("github3_utils.testing", )
with Betamax.configure() as config:
config.cassette_library_dir = "<path to cassettes directory>"
Functions:
|
Provides a Betamax cassette scoped to the test function which record and plays back interactions with the GitHub API. |
Provides an instance of |
|
|
Provides a Betamax cassette scoped to the test module which record and plays back interactions with the GitHub API. |
-
fixture
cassette
[source]¶ Scope: function
Provides a Betamax cassette scoped to the test function which record and plays back interactions with the GitHub API.
-
fixture
github_client
[source]¶ Scope: function
Provides an instance of
github3.github.GitHub
, using a fake token to authenticate.- Return type
Contributing¶
github3-utils
uses tox to automate testing and packaging,
and pre-commit to maintain code quality.
Install pre-commit
with pip
and install the git hook:
python -m pip install pre-commit
pre-commit install
Coding style¶
formate is used for code formatting.
It can be run manually via pre-commit
:
pre-commit run formate -a
Or, to run the complete autoformatting suite:
pre-commit run -a
Automated tests¶
Tests are run with tox
and pytest
.
To run tests for a specific Python version, such as Python 3.6:
tox -e py36
To run tests for all Python versions, simply run:
tox
Build documentation locally¶
The documentation is powered by Sphinx. A local copy of the documentation can be built with tox
:
tox -e docs
Downloading source code¶
The github3-utils
source code is available on GitHub,
and can be accessed from the following URL: https://github.com/domdfcoding/github3-utils
If you have git
installed, you can clone the repository with the following command:
git clone https://github.com/domdfcoding/github3-utils
Cloning into 'github3-utils'...
remote: Enumerating objects: 47, done.
remote: Counting objects: 100% (47/47), done.
remote: Compressing objects: 100% (41/41), done.
remote: Total 173 (delta 16), reused 17 (delta 6), pack-reused 126
Receiving objects: 100% (173/173), 126.56 KiB | 678.00 KiB/s, done.
Resolving deltas: 100% (66/66), done.

Downloading a ‘zip’ file of the source code¶
Building from source¶
The recommended way to build github3-utils
is to use tox:
tox -e build
The source and wheel distributions will be in the directory dist
.
If you wish, you may also use pep517.build or another PEP 517-compatible build tool.
License¶
github3-utils
is licensed under the MIT License
A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.
Permissions | Conditions | Limitations |
---|---|---|
|
|
Copyright (c) 2020-2022 Dominic Davis-Foster
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.
View the Function Index or browse the Source Code.