status-im/PyGithub
1
0
Fork 0
mirror of https://github.com/status-im/PyGithub.git synced 2026-09-01 19:31:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge MainClass.pyi and __init__.pyi back to source (#2692)

Browse Source
This commit is contained in:
Trim21
2023-09-07 10:05:00 +02:00
committed by GitHub
parent 8dee53a833
commit f7c0a21ea5
4 changed files with 233 additions and 405 deletions
Download Patch File Download Diff File Expand all files Collapse all files
github/MainClass.py
+192 -214
View File
@@ -47,38 +47,59 @@
# along with PyGithub. If not, see <http://www.gnu.org/licenses/>. #
# #
################################################################################
from __future__ import annotations
import pickle
import warnings
from datetime import datetime
from typing import List
from typing import TYPE_CHECKING, Any, BinaryIO, TypeVar
import urllib3
from urllib3.util import Retry
import github.ApplicationOAuth
import github.Auth
import github.AuthenticatedUser
import github.Enterprise
import github.Event
import github.Gist
import github.GithubObject
import github.GithubApp
import github.GithubIntegration
import github.GithubRetry
import github.GitignoreTemplate
import github.License
import github.NamedUser
import github.PaginatedList
import github.Topic
from github import Auth
from github import Consts
from github.GithubIntegration import GithubIntegration
from github.GithubObject import GithubObject, NotSet, Opt, is_defined
from github.GithubRetry import GithubRetry
from github.HookDelivery import HookDelivery, HookDeliverySummary
from github.HookDescription import HookDescription
from github.PaginatedList import PaginatedList
from github.RateLimit import RateLimit
from github.Requester import Requester
from . import (
AuthenticatedUser,
Consts,
GithubApp,
GithubRetry,
GitignoreTemplate,
HookDelivery,
HookDescription,
RateLimit,
Repository,
)
from .HookDelivery import HookDeliverySummary
from .Requester import Requester
if TYPE_CHECKING:
from github.AppAuthentication import AppAuthentication
from github.ApplicationOAuth import ApplicationOAuth
from github.AuthenticatedUser import AuthenticatedUser
from github.Commit import Commit
from github.ContentFile import ContentFile
from github.Event import Event
from github.Gist import Gist
from github.GithubApp import GithubApp
from github.GitignoreTemplate import GitignoreTemplate
from github.Issue import Issue
from github.License import License
from github.NamedUser import NamedUser
from github.Organization import Organization
from github.Project import Project
from github.ProjectColumn import ProjectColumn
from github.Repository import Repository
from github.Topic import Topic
TGithubObject = TypeVar("TGithubObject", bound=GithubObject)
class Github:
@@ -86,7 +107,9 @@ class Github:
This is the main class you instantiate to access the Github API v3. Optional parameters allow different authentication methods.
"""
default_retry = GithubRetry.GithubRetry()
__requester: Requester
default_retry = GithubRetry()
# keep non-deprecated arguments in-sync with Requester
# v3: remove login_or_token, password, jwt and app_auth
@@ -95,21 +118,21 @@ class Github:
# allows to reorder / add new arguments / remove deprecated arguments without breaking user code
def __init__(
self,
login_or_token=None,
password=None,
jwt=None,
app_auth=None,
base_url=Consts.DEFAULT_BASE_URL,
timeout=Consts.DEFAULT_TIMEOUT,
user_agent=Consts.DEFAULT_USER_AGENT,
per_page=Consts.DEFAULT_PER_PAGE,
verify=True,
retry=default_retry,
pool_size=None,
seconds_between_requests=Consts.DEFAULT_SECONDS_BETWEEN_REQUESTS,
seconds_between_writes=Consts.DEFAULT_SECONDS_BETWEEN_WRITES,
auth=None,
):
login_or_token: str | None = None,
password: str | None = None,
jwt: str | None = None,
app_auth: AppAuthentication | None = None,
base_url: str = Consts.DEFAULT_BASE_URL,
timeout: int = Consts.DEFAULT_TIMEOUT,
user_agent: str = Consts.DEFAULT_USER_AGENT,
per_page: int = Consts.DEFAULT_PER_PAGE,
verify: bool | str = True,
retry: int | Retry | None = default_retry,
pool_size: int | None = None,
seconds_between_requests: float | None = Consts.DEFAULT_SECONDS_BETWEEN_REQUESTS,
seconds_between_writes: float | None = Consts.DEFAULT_SECONDS_BETWEEN_WRITES,
auth: github.Auth.Auth | None = None,
) -> None:
"""
:param login_or_token: string deprecated, use auth=github.Auth.Login(...) or auth=github.Auth.Token(...) instead
:param password: string deprecated, use auth=github.Auth.Login(...) instead
@@ -141,7 +164,7 @@ class Github:
assert pool_size is None or isinstance(pool_size, int), pool_size
assert seconds_between_requests is None or seconds_between_requests >= 0
assert seconds_between_writes is None or seconds_between_writes >= 0
assert auth is None or isinstance(auth, Auth.Auth), auth
assert auth is None or isinstance(auth, github.Auth.Auth), auth
if password is not None:
warnings.warn(
@@ -149,13 +172,13 @@ class Github:
"auth=github.Auth.Login(...) instead",
category=DeprecationWarning,
)
auth = Auth.Login(login_or_token, password)
auth = github.Auth.Login(login_or_token, password) # type: ignore
elif login_or_token is not None:
warnings.warn(
"Argument login_or_token is deprecated, please use " "auth=github.Auth.Token(...) instead",
category=DeprecationWarning,
)
auth = Auth.Token(login_or_token)
auth = github.Auth.Token(login_or_token)
elif jwt is not None:
warnings.warn(
"Argument jwt is deprecated, please use "
@@ -163,7 +186,7 @@ class Github:
"auth=github.Auth.AppAuthToken(...) instead",
category=DeprecationWarning,
)
auth = Auth.AppAuthToken(jwt)
auth = github.Auth.AppAuthToken(jwt)
elif app_auth is not None:
warnings.warn(
"Argument app_auth is deprecated, please use " "auth=github.Auth.AppInstallationAuth(...) instead",
@@ -195,44 +218,36 @@ class Github:
"""
self.__requester.close()
def __enter__(self) -> "Github":
def __enter__(self) -> Github:
return self
def __exit__(self, exc_type, exc_val, exc_tb) -> None:
def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
self.close()
@property
def FIX_REPO_GET_GIT_REF(self):
"""
:type: bool
"""
def FIX_REPO_GET_GIT_REF(self) -> bool:
return self.__requester.FIX_REPO_GET_GIT_REF
@FIX_REPO_GET_GIT_REF.setter
def FIX_REPO_GET_GIT_REF(self, value):
def FIX_REPO_GET_GIT_REF(self, value: bool) -> None:
self.__requester.FIX_REPO_GET_GIT_REF = value
# v3: Remove this property? Why should it be necessary to read/modify it after construction
@property
def per_page(self):
"""
:type: int
"""
def per_page(self) -> int:
return self.__requester.per_page
@per_page.setter
def per_page(self, value):
def per_page(self, value: int) -> None:
self.__requester.per_page = value
# v3: Provide a unified way to access values of headers of last response
# v3: (and add/keep ad hoc properties for specific useful headers like rate limiting, oauth scopes, etc.)
# v3: Return an instance of a class: using a tuple did not allow to add a field "resettime"
@property
def rate_limiting(self):
def rate_limiting(self) -> tuple[int, int]:
"""
First value is requests remaining, second value is request limit.
:type: (int, int)
"""
remaining, limit = self.__requester.rate_limiting
if limit < 0:
@@ -240,76 +255,67 @@ class Github:
return self.__requester.rate_limiting
@property
def rate_limiting_resettime(self):
def rate_limiting_resettime(self) -> int:
"""
Unix timestamp indicating when rate limiting will reset.
:type: int
"""
if self.__requester.rate_limiting_resettime == 0:
self.get_rate_limit()
return self.__requester.rate_limiting_resettime
def get_rate_limit(self):
def get_rate_limit(self) -> RateLimit:
"""
Rate limit status for different resources (core/search/graphql).
:calls: `GET /rate_limit <https://docs.github.com/en/rest/reference/rate-limit>`_
:rtype: :class:`github.RateLimit.RateLimit`
"""
headers, data = self.__requester.requestJsonAndCheck("GET", "/rate_limit")
return RateLimit.RateLimit(self.__requester, headers, data["resources"], True)
return RateLimit(self.__requester, headers, data["resources"], True)
@property
def oauth_scopes(self):
def oauth_scopes(self) -> list[str] | None:
"""
:type: list of string
"""
return self.__requester.oauth_scopes
def get_license(self, key=github.GithubObject.NotSet):
def get_license(self, key: Opt[str] = NotSet) -> License:
"""
:calls: `GET /license/{license} <https://docs.github.com/en/rest/reference/licenses#get-a-license>`_
:param key: string
:rtype: :class:`github.License.License`
"""
assert isinstance(key, str), key
headers, data = self.__requester.requestJsonAndCheck("GET", f"/licenses/{key}")
return github.License.License(self.__requester, headers, data, completed=True)
def get_licenses(self):
def get_licenses(self) -> PaginatedList[License]:
"""
:calls: `GET /licenses <https://docs.github.com/en/rest/reference/licenses#get-all-commonly-used-licenses>`_
:rtype: :class:`github.PaginatedList.PaginatedList` of :class:`github.License.License`
"""
url_parameters = dict()
url_parameters: dict[str, Any] = {}
return github.PaginatedList.PaginatedList(github.License.License, self.__requester, "/licenses", url_parameters)
return PaginatedList(github.License.License, self.__requester, "/licenses", url_parameters)
def get_events(self):
def get_events(self) -> PaginatedList[Event]:
"""
:calls: `GET /events <https://docs.github.com/en/rest/reference/activity#list-public-events>`_
:rtype: :class:`github.PaginatedList.PaginatedList` of :class:`github.Event.Event`
"""
return github.PaginatedList.PaginatedList(github.Event.Event, self.__requester, "/events", None)
return PaginatedList(github.Event.Event, self.__requester, "/events", None)
def get_user(self, login=github.GithubObject.NotSet):
def get_user(self, login: Opt[str] = NotSet) -> NamedUser | AuthenticatedUser:
"""
:calls: `GET /users/{user} <https://docs.github.com/en/rest/reference/users>`_ or `GET /user <https://docs.github.com/en/rest/reference/users>`_
:param login: string
:rtype: :class:`github.NamedUser.NamedUser` or :class:`github.AuthenticatedUser.AuthenticatedUser`
"""
assert login is github.GithubObject.NotSet or isinstance(login, str), login
if login is github.GithubObject.NotSet:
return AuthenticatedUser.AuthenticatedUser(self.__requester, {}, {"url": "/user"}, completed=False)
assert login is NotSet or isinstance(login, str), login
if login is NotSet:
return github.AuthenticatedUser.AuthenticatedUser(self.__requester, {}, {"url": "/user"}, completed=False)
else:
headers, data = self.__requester.requestJsonAndCheck("GET", f"/users/{login}")
return github.NamedUser.NamedUser(self.__requester, headers, data, completed=True)
def get_user_by_id(self, user_id):
def get_user_by_id(self, user_id: int) -> NamedUser:
"""
:calls: `GET /user/{id} <https://docs.github.com/en/rest/reference/users>`_
:param user_id: int
@@ -319,48 +325,40 @@ class Github:
headers, data = self.__requester.requestJsonAndCheck("GET", f"/user/{user_id}")
return github.NamedUser.NamedUser(self.__requester, headers, data, completed=True)
def get_users(self, since=github.GithubObject.NotSet):
def get_users(self, since: Opt[int] = NotSet) -> PaginatedList[NamedUser]:
"""
:calls: `GET /users <https://docs.github.com/en/rest/reference/users>`_
:param since: integer
:rtype: :class:`github.PaginatedList.PaginatedList` of :class:`github.NamedUser.NamedUser`
"""
assert since is github.GithubObject.NotSet or isinstance(since, int), since
assert since is NotSet or isinstance(since, int), since
url_parameters = dict()
if since is not github.GithubObject.NotSet:
if since is not NotSet:
url_parameters["since"] = since
return github.PaginatedList.PaginatedList(
github.NamedUser.NamedUser, self.__requester, "/users", url_parameters
)
return PaginatedList(github.NamedUser.NamedUser, self.__requester, "/users", url_parameters)
def get_organization(self, login):
def get_organization(self, login: str) -> Organization:
"""
:calls: `GET /orgs/{org} <https://docs.github.com/en/rest/reference/orgs>`_
:param login: string
:rtype: :class:`github.Organization.Organization`
"""
assert isinstance(login, str), login
headers, data = self.__requester.requestJsonAndCheck("GET", f"/orgs/{login}")
return github.Organization.Organization(self.__requester, headers, data, completed=True)
def get_organizations(self, since=github.GithubObject.NotSet):
def get_organizations(self, since: Opt[int] = NotSet) -> PaginatedList[Organization]:
"""
:calls: `GET /organizations <https://docs.github.com/en/rest/reference/orgs#list-organizations>`_
:param since: integer
:rtype: :class:`github.PaginatedList.PaginatedList` of :class:`github.Organization.Organization`
"""
assert since is github.GithubObject.NotSet or isinstance(since, int), since
assert since is NotSet or isinstance(since, int), since
url_parameters = dict()
if since is not github.GithubObject.NotSet:
if since is not NotSet:
url_parameters["since"] = since
return github.PaginatedList.PaginatedList(
return PaginatedList(
github.Organization.Organization,
self.__requester,
"/organizations",
url_parameters,
)
def get_enterprise(self, enterprise):
def get_enterprise(self, enterprise: str) -> github.Enterprise.Enterprise:
"""
:calls: `GET /enterprises/{enterprise} <https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin>`_
:param enterprise: string
@@ -370,58 +368,56 @@ class Github:
# There is no native "/enterprises/{enterprise}" api, so this function is a hub for apis that start with "/enterprise/{enterprise}".
return github.Enterprise.Enterprise(self.__requester, enterprise)
def get_repo(self, full_name_or_id, lazy=False):
def get_repo(self, full_name_or_id: int | str, lazy: bool = False) -> Repository:
"""
:calls: `GET /repos/{owner}/{repo} <https://docs.github.com/en/rest/reference/repos>`_ or `GET /repositories/{id} <https://docs.github.com/en/rest/reference/repos>`_
:rtype: :class:`github.Repository.Repository`
"""
assert isinstance(full_name_or_id, (str, int)), full_name_or_id
url_base = "/repositories/" if isinstance(full_name_or_id, int) else "/repos/"
url = f"{url_base}{full_name_or_id}"
if lazy:
return Repository.Repository(self.__requester, {}, {"url": url}, completed=False)
return github.Repository.Repository(self.__requester, {}, {"url": url}, completed=False)
headers, data = self.__requester.requestJsonAndCheck("GET", url)
return Repository.Repository(self.__requester, headers, data, completed=True)
return github.Repository.Repository(self.__requester, headers, data, completed=True)
def get_repos(self, since=github.GithubObject.NotSet, visibility=github.GithubObject.NotSet):
def get_repos(
self,
since: Opt[int] = NotSet,
visibility: Opt[str] = NotSet,
) -> PaginatedList[Repository]:
"""
:calls: `GET /repositories <https://docs.github.com/en/rest/reference/repos#list-public-repositories>`_
:param since: integer
:param visibility: string ('all','public')
:rtype: :class:`github.PaginatedList.PaginatedList` of :class:`github.Repository.Repository`
"""
assert since is github.GithubObject.NotSet or isinstance(since, int), since
url_parameters = dict()
if since is not github.GithubObject.NotSet:
assert since is NotSet or isinstance(since, int), since
url_parameters: dict[str, Any] = {}
if since is not NotSet:
url_parameters["since"] = since
if visibility is not github.GithubObject.NotSet:
if visibility is not NotSet:
assert visibility in ("public", "all"), visibility
url_parameters["visibility"] = visibility
return github.PaginatedList.PaginatedList(
return PaginatedList(
github.Repository.Repository,
self.__requester,
"/repositories",
url_parameters,
)
def get_project(self, id):
def get_project(self, id: int) -> Project:
"""
:calls: `GET /projects/{project_id} <https://docs.github.com/en/rest/reference/projects#get-a-project>`_
:rtype: :class:`github.Project.Project`
:param id: integer
"""
headers, data = self.__requester.requestJsonAndCheck(
"GET",
"/projects/%d" % (id),
f"/projects/{id:d}",
headers={"Accept": Consts.mediaTypeProjectsPreview},
)
return github.Project.Project(self.__requester, headers, data, completed=True)
def get_project_column(self, id):
def get_project_column(self, id: int) -> ProjectColumn:
"""
:calls: `GET /projects/columns/{column_id} <https://docs.github.com/en/rest/reference/projects#get-a-project-column>`_
:rtype: :class:`github.ProjectColumn.ProjectColumn`
:param id: integer
"""
headers, data = self.__requester.requestJsonAndCheck(
"GET",
@@ -430,49 +426,44 @@ class Github:
)
return github.ProjectColumn.ProjectColumn(self.__requester, headers, data, completed=True)
def get_gist(self, id):
def get_gist(self, id: str) -> Gist:
"""
:calls: `GET /gists/{id} <https://docs.github.com/en/rest/reference/gists>`_
:param id: string
:rtype: :class:`github.Gist.Gist`
"""
assert isinstance(id, str), id
headers, data = self.__requester.requestJsonAndCheck("GET", f"/gists/{id}")
return github.Gist.Gist(self.__requester, headers, data, completed=True)
def get_gists(self, since=github.GithubObject.NotSet):
def get_gists(self, since: Opt[datetime] = NotSet) -> PaginatedList[Gist]:
"""
:calls: `GET /gists/public <https://docs.github.com/en/rest/reference/gists>`_
:param since: datetime format YYYY-MM-DDTHH:MM:SSZ
:rtype: :class:`github.PaginatedList.PaginatedList` of :class:`github.Gist.Gist`
"""
assert since is github.GithubObject.NotSet or isinstance(since, datetime), since
assert since is NotSet or isinstance(since, datetime), since
url_parameters = dict()
if since is not github.GithubObject.NotSet:
if is_defined(since):
url_parameters["since"] = since.strftime("%Y-%m-%dT%H:%M:%SZ")
return github.PaginatedList.PaginatedList(github.Gist.Gist, self.__requester, "/gists/public", url_parameters)
return PaginatedList(github.Gist.Gist, self.__requester, "/gists/public", url_parameters)
def search_repositories(
self,
query,
sort=github.GithubObject.NotSet,
order=github.GithubObject.NotSet,
**qualifiers,
):
query: str,
sort: Opt[str] = NotSet,
order: Opt[str] = NotSet,
**qualifiers: Any,
) -> PaginatedList[Repository]:
"""
:calls: `GET /search/repositories <https://docs.github.com/en/rest/reference/search>`_
:param query: string
:param sort: string ('stars', 'forks', 'updated')
:param order: string ('asc', 'desc')
:param qualifiers: keyword dict query qualifiers
:rtype: :class:`github.PaginatedList.PaginatedList` of :class:`github.Repository.Repository`
"""
assert isinstance(query, str), query
url_parameters = dict()
if sort is not github.GithubObject.NotSet: # pragma no branch (Should be covered)
if sort is not NotSet: # pragma no branch (Should be covered)
assert sort in ("stars", "forks", "updated"), sort
url_parameters["sort"] = sort
if order is not github.GithubObject.NotSet: # pragma no branch (Should be covered)
if order is not NotSet: # pragma no branch (Should be covered)
assert order in ("asc", "desc"), order
url_parameters["order"] = order
@@ -486,7 +477,7 @@ class Github:
url_parameters["q"] = " ".join(query_chunks)
assert url_parameters["q"], "need at least one qualifier"
return github.PaginatedList.PaginatedList(
return PaginatedList(
github.Repository.Repository,
self.__requester,
"/search/repositories",
@@ -495,25 +486,25 @@ class Github:
def search_users(
self,
query,
sort=github.GithubObject.NotSet,
order=github.GithubObject.NotSet,
**qualifiers,
):
query: str,
sort: Opt[str] = NotSet,
order: Opt[str] = NotSet,
**qualifiers: Any,
) -> PaginatedList[NamedUser]:
"""
:calls: `GET /search/users <https://docs.github.com/en/rest/reference/search>`_
:param query: string
:param sort: string ('followers', 'repositories', 'joined')
:param order: string ('asc', 'desc')
:param qualifiers: keyword dict query qualifiers
:rtype: :class:`github.PaginatedList.PaginatedList` of :class:`github.NamedUser.NamedUser`
:rtype: :class:`PaginatedList` of :class:`github.NamedUser.NamedUser`
"""
assert isinstance(query, str), query
url_parameters = dict()
if sort is not github.GithubObject.NotSet:
if sort is not NotSet:
assert sort in ("followers", "repositories", "joined"), sort
url_parameters["sort"] = sort
if order is not github.GithubObject.NotSet:
if order is not NotSet:
assert order in ("asc", "desc"), order
url_parameters["order"] = order
@@ -527,7 +518,7 @@ class Github:
url_parameters["q"] = " ".join(query_chunks)
assert url_parameters["q"], "need at least one qualifier"
return github.PaginatedList.PaginatedList(
return PaginatedList(
github.NamedUser.NamedUser,
self.__requester,
"/search/users",
@@ -536,25 +527,25 @@ class Github:
def search_issues(
self,
query,
sort=github.GithubObject.NotSet,
order=github.GithubObject.NotSet,
**qualifiers,
):
query: str,
sort: Opt[str] = NotSet,
order: Opt[str] = NotSet,
**qualifiers: Any,
) -> PaginatedList[Issue]:
"""
:calls: `GET /search/issues <https://docs.github.com/en/rest/reference/search>`_
:param query: string
:param sort: string ('comments', 'created', 'updated')
:param order: string ('asc', 'desc')
:param qualifiers: keyword dict query qualifiers
:rtype: :class:`github.PaginatedList.PaginatedList` of :class:`github.Issue.Issue`
:rtype: :class:`PaginatedList` of :class:`github.Issue.Issue`
"""
assert isinstance(query, str), query
url_parameters = dict()
if sort is not github.GithubObject.NotSet:
if sort is not NotSet:
assert sort in ("comments", "created", "updated"), sort
url_parameters["sort"] = sort
if order is not github.GithubObject.NotSet:
if order is not NotSet:
assert order in ("asc", "desc"), order
url_parameters["order"] = order
@@ -568,18 +559,16 @@ class Github:
url_parameters["q"] = " ".join(query_chunks)
assert url_parameters["q"], "need at least one qualifier"
return github.PaginatedList.PaginatedList(
github.Issue.Issue, self.__requester, "/search/issues", url_parameters
)
return PaginatedList(github.Issue.Issue, self.__requester, "/search/issues", url_parameters)
def search_code(
self,
query,
sort=github.GithubObject.NotSet,
order=github.GithubObject.NotSet,
highlight=False,
**qualifiers,
):
query: str,
sort: Opt[str] = NotSet,
order: Opt[str] = NotSet,
highlight: bool = False,
**qualifiers: Any,
) -> PaginatedList[ContentFile]:
"""
:calls: `GET /search/code <https://docs.github.com/en/rest/reference/search>`_
:param query: string
@@ -587,14 +576,14 @@ class Github:
:param order: string ('asc', 'desc')
:param highlight: boolean (True, False)
:param qualifiers: keyword dict query qualifiers
:rtype: :class:`github.PaginatedList.PaginatedList` of :class:`github.ContentFile.ContentFile`
:rtype: :class:`PaginatedList` of :class:`github.ContentFile.ContentFile`
"""
assert isinstance(query, str), query
url_parameters = dict()
if sort is not github.GithubObject.NotSet: # pragma no branch (Should be covered)
if sort is not NotSet: # pragma no branch (Should be covered)
assert sort in ("indexed",), sort
url_parameters["sort"] = sort
if order is not github.GithubObject.NotSet: # pragma no branch (Should be covered)
if order is not NotSet: # pragma no branch (Should be covered)
assert order in ("asc", "desc"), order
url_parameters["order"] = order
@@ -610,7 +599,7 @@ class Github:
headers = {"Accept": Consts.highLightSearchPreview} if highlight else None
return github.PaginatedList.PaginatedList(
return PaginatedList(
github.ContentFile.ContentFile,
self.__requester,
"/search/code",
@@ -620,25 +609,25 @@ class Github:
def search_commits(
self,
query,
sort=github.GithubObject.NotSet,
order=github.GithubObject.NotSet,
**qualifiers,
):
query: str,
sort: Opt[str] = NotSet,
order: Opt[str] = NotSet,
**qualifiers: Any,
) -> PaginatedList[Commit]:
"""
:calls: `GET /search/commits <https://docs.github.com/en/rest/reference/search>`_
:param query: string
:param sort: string ('author-date', 'committer-date')
:param order: string ('asc', 'desc')
:param qualifiers: keyword dict query qualifiers
:rtype: :class:`github.PaginatedList.PaginatedList` of :class:`github.Commit.Commit`
:rtype: :class:`PaginatedList` of :class:`github.Commit.Commit`
"""
assert isinstance(query, str), query
url_parameters = dict()
if sort is not github.GithubObject.NotSet:
if sort is not NotSet:
assert sort in ("author-date", "committer-date"), sort
url_parameters["sort"] = sort
if order is not github.GithubObject.NotSet:
if order is not NotSet:
assert order in ("asc", "desc"), order
url_parameters["order"] = order
@@ -652,7 +641,7 @@ class Github:
url_parameters["q"] = " ".join(query_chunks)
assert url_parameters["q"], "need at least one qualifier"
return github.PaginatedList.PaginatedList(
return PaginatedList(
github.Commit.Commit,
self.__requester,
"/search/commits",
@@ -660,12 +649,12 @@ class Github:
headers={"Accept": Consts.mediaTypeCommitSearchPreview},
)
def search_topics(self, query, **qualifiers):
def search_topics(self, query: str, **qualifiers: Any) -> PaginatedList[Topic]:
"""
:calls: `GET /search/topics <https://docs.github.com/en/rest/reference/search>`_
:param query: string
:param qualifiers: keyword dict query qualifiers
:rtype: :class:`github.PaginatedList.PaginatedList` of :class:`github.Topic.Topic`
:rtype: :class:`PaginatedList` of :class:`github.Topic.Topic`
"""
assert isinstance(query, str), query
url_parameters = dict()
@@ -680,7 +669,7 @@ class Github:
url_parameters["q"] = " ".join(query_chunks)
assert url_parameters["q"], "need at least one qualifier"
return github.PaginatedList.PaginatedList(
return PaginatedList(
github.Topic.Topic,
self.__requester,
"/search/topics",
@@ -688,7 +677,7 @@ class Github:
headers={"Accept": Consts.mediaTypeTopicsPreview},
)
def render_markdown(self, text, context=github.GithubObject.NotSet):
def render_markdown(self, text: str, context: Opt[Repository] = NotSet) -> str:
"""
:calls: `POST /markdown <https://docs.github.com/en/rest/reference/markdown>`_
:param text: string
@@ -696,78 +685,68 @@ class Github:
:rtype: string
"""
assert isinstance(text, str), text
assert context is github.GithubObject.NotSet or isinstance(context, github.Repository.Repository), context
assert context is NotSet or isinstance(context, github.Repository.Repository), context
post_parameters = {"text": text}
if context is not github.GithubObject.NotSet:
if is_defined(context):
post_parameters["mode"] = "gfm"
post_parameters["context"] = context._identity
status, headers, data = self.__requester.requestJson("POST", "/markdown", input=post_parameters)
return data
def get_hook(self, name):
def get_hook(self, name: str) -> HookDescription:
"""
:calls: `GET /hooks/{name} <https://docs.github.com/en/rest/reference/repos#webhooks>`_
:param name: string
:rtype: :class:`github.HookDescription.HookDescription`
"""
assert isinstance(name, str), name
headers, attributes = self.__requester.requestJsonAndCheck("GET", f"/hooks/{name}")
return HookDescription.HookDescription(self.__requester, headers, attributes, completed=True)
return HookDescription(self.__requester, headers, attributes, completed=True)
def get_hooks(self):
def get_hooks(self) -> list[HookDescription]:
"""
:calls: `GET /hooks <https://docs.github.com/en/rest/reference/repos#webhooks>`_
:rtype: list of :class:`github.HookDescription.HookDescription`
"""
headers, data = self.__requester.requestJsonAndCheck("GET", "/hooks")
return [
HookDescription.HookDescription(self.__requester, headers, attributes, completed=True)
for attributes in data
]
return [HookDescription(self.__requester, headers, attributes, completed=True) for attributes in data]
def get_hook_delivery(self, hook_id: int, delivery_id: int) -> HookDelivery:
"""
:calls: `GET /hooks/{hook_id}/deliveries/{delivery_id} <https://docs.github.com/en/rest/reference/repos#webhooks>`_
:param hook_id: integer
:param delivery_id: integer
:rtype: :class:`github.HookDelivery.HookDelivery`
:rtype: :class:`HookDelivery`
"""
assert isinstance(hook_id, int), hook_id
assert isinstance(delivery_id, int), delivery_id
headers, attributes = self.__requester.requestJsonAndCheck("GET", f"/hooks/{hook_id}/deliveries/{delivery_id}")
return HookDelivery.HookDelivery(self.__requester, headers, attributes, completed=True)
return HookDelivery(self.__requester, headers, attributes, completed=True)
def get_hook_deliveries(self, hook_id: int) -> List[HookDeliverySummary]:
def get_hook_deliveries(self, hook_id: int) -> list[HookDeliverySummary]:
"""
:calls: `GET /hooks/{hook_id}/deliveries <https://docs.github.com/en/rest/reference/repos#webhooks>`_
:param hook_id: integer
:rtype: list of :class:`github.HookDelivery.HookDeliverySummary`
:rtype: list of :class:`HookDeliverySummary`
"""
assert isinstance(hook_id, int), hook_id
headers, data = self.__requester.requestJsonAndCheck("GET", f"/hooks/{hook_id}/deliveries")
return [
HookDelivery.HookDeliverySummary(self.__requester, headers, attributes, completed=True)
for attributes in data
]
return [HookDeliverySummary(self.__requester, headers, attributes, completed=True) for attributes in data]
def get_gitignore_templates(self):
def get_gitignore_templates(self) -> list[str]:
"""
:calls: `GET /gitignore/templates <https://docs.github.com/en/rest/reference/gitignore>`_
:rtype: list of string
"""
headers, data = self.__requester.requestJsonAndCheck("GET", "/gitignore/templates")
return data
def get_gitignore_template(self, name):
def get_gitignore_template(self, name: str) -> GitignoreTemplate:
"""
:calls: `GET /gitignore/templates/{name} <https://docs.github.com/en/rest/reference/gitignore>`_
:rtype: :class:`github.GitignoreTemplate.GitignoreTemplate`
"""
assert isinstance(name, str), name
headers, attributes = self.__requester.requestJsonAndCheck("GET", f"/gitignore/templates/{name}")
return GitignoreTemplate.GitignoreTemplate(self.__requester, headers, attributes, completed=True)
return github.GitignoreTemplate.GitignoreTemplate(self.__requester, headers, attributes, completed=True)
def get_emojis(self):
def get_emojis(self) -> dict[str, str]:
"""
:calls: `GET /emojis <https://docs.github.com/en/rest/reference/emojis>`_
:rtype: dictionary of type => url for emoji`
@@ -775,19 +754,24 @@ class Github:
headers, attributes = self.__requester.requestJsonAndCheck("GET", "/emojis")
return attributes
def create_from_raw_data(self, klass, raw_data, headers={}):
def create_from_raw_data(
self, klass: type[TGithubObject], raw_data: dict[str, Any], headers: dict[str, str | int] | None = None
) -> TGithubObject:
"""
Creates an object from raw_data previously obtained by :attr:`github.GithubObject.GithubObject.raw_data`,
and optionally headers previously obtained by :attr:`github.GithubObject.GithubObject.raw_headers`.
Creates an object from raw_data previously obtained by :attr:`GithubObject.raw_data`,
and optionally headers previously obtained by :attr:`GithubObject.raw_headers`.
:param klass: the class of the object to create
:param raw_data: dict
:param headers: dict
:rtype: instance of class ``klass``
"""
if headers is None:
headers = {}
return klass(self.__requester, headers, raw_data, completed=True)
def dump(self, obj, file, protocol=0):
def dump(self, obj: GithubObject, file: BinaryIO, protocol: int = 0) -> None:
"""
Dumps (pickles) a PyGithub object to a file-like object.
Some effort is made to not pickle sensitive information like the Github credentials used in the :class:`Github` instance.
@@ -799,7 +783,7 @@ class Github:
"""
pickle.dump((obj.__class__, obj.raw_data, obj.raw_headers), file, protocol)
def load(self, f):
def load(self, f: BinaryIO) -> Any:
"""
Loads (unpickles) a PyGithub object from a file-like object.
@@ -808,7 +792,7 @@ class Github:
"""
return self.create_from_raw_data(*pickle.load(f))
def get_oauth_application(self, client_id, client_secret):
def get_oauth_application(self, client_id: str, client_secret: str) -> ApplicationOAuth:
return github.ApplicationOAuth.ApplicationOAuth(
self.__requester,
headers={},
@@ -816,15 +800,13 @@ class Github:
completed=False,
)
def get_app(self, slug=github.GithubObject.NotSet):
def get_app(self, slug: Opt[str] = NotSet) -> GithubApp:
"""
:calls: `GET /apps/{slug} <https://docs.github.com/en/rest/reference/apps>`_ or `GET /app <https://docs.github.com/en/rest/reference/apps>`_
:param slug: string
:rtype: :class:`github.GithubApp.GithubApp`
"""
assert slug is github.GithubObject.NotSet or isinstance(slug, str), slug
assert slug is NotSet or isinstance(slug, str), slug
if slug is github.GithubObject.NotSet:
if slug is NotSet:
# with no slug given, calling /app returns the authenticated app,
# including the actual /apps/{slug}
warnings.warn(
@@ -835,8 +817,4 @@ class Github:
return GithubIntegration(**self.__requester.kwargs).get_app()
else:
# with a slug given, we can lazily load the GithubApp
return GithubApp.GithubApp(self.__requester, {}, {"url": f"/apps/{slug}"}, completed=False)
# Retrocompatibility
GithubIntegration = github.GithubIntegration
return github.GithubApp.GithubApp(self.__requester, {}, {"url": f"/apps/{slug}"}, completed=False)