diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 07c65962dd..f25eeccb7d 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -34,6 +34,13 @@ repos: - id: codespell additional_dependencies: [tomli] + - repo: https://github.com/PyCQA/docformatter + rev: v1.7.5 + hooks: + - id: docformatter + additional_dependencies: [tomli] + args: ["--in-place"] + - repo: https://github.com/psf/black rev: 23.12.0 hooks: diff --git a/github/AdvisoryCredit.py b/github/AdvisoryCredit.py index 3d36d643f9..a21df3d873 100644 --- a/github/AdvisoryCredit.py +++ b/github/AdvisoryCredit.py @@ -49,7 +49,10 @@ class SimpleCredit(TypedDict): class AdvisoryCredit(NonCompletableGithubObject): """ This class represents a credit that is assigned to a SecurityAdvisory. - The reference can be found here https://docs.github.com/en/rest/security-advisories/repository-advisories + + The reference can be found here + https://docs.github.com/en/rest/security-advisories/repository-advisories + """ @property diff --git a/github/AdvisoryCreditDetailed.py b/github/AdvisoryCreditDetailed.py index 2b1c289cf7..550f024b91 100644 --- a/github/AdvisoryCreditDetailed.py +++ b/github/AdvisoryCreditDetailed.py @@ -48,7 +48,10 @@ class AdvisoryCreditDetailed(NonCompletableGithubObject): """ This class represents a credit that is assigned to a SecurityAdvisory. - The reference can be found here https://docs.github.com/en/rest/security-advisories/repository-advisories + + The reference can be found here + https://docs.github.com/en/rest/security-advisories/repository-advisories + """ @property diff --git a/github/AdvisoryVulnerability.py b/github/AdvisoryVulnerability.py index 511d17053f..46f16eeb61 100644 --- a/github/AdvisoryVulnerability.py +++ b/github/AdvisoryVulnerability.py @@ -63,7 +63,10 @@ class SimpleAdvisoryVulnerability(TypedDict): class AdvisoryVulnerability(NonCompletableGithubObject): """ This class represents a package that is vulnerable to a parent SecurityAdvisory. - The reference can be found here https://docs.github.com/en/rest/security-advisories/repository-advisories + + The reference can be found here + https://docs.github.com/en/rest/security-advisories/repository-advisories + """ @property diff --git a/github/AdvisoryVulnerabilityPackage.py b/github/AdvisoryVulnerabilityPackage.py index a1a747f87d..812e85985b 100644 --- a/github/AdvisoryVulnerabilityPackage.py +++ b/github/AdvisoryVulnerabilityPackage.py @@ -49,7 +49,10 @@ class AdvisoryVulnerabilityPackage(NonCompletableGithubObject): """ This class represents an identifier for a package that is vulnerable to a parent SecurityAdvisory. - The reference can be found here https://docs.github.com/en/rest/security-advisories/repository-advisories + + The reference can be found here + https://docs.github.com/en/rest/security-advisories/repository-advisories + """ def _initAttributes(self) -> None: diff --git a/github/ApplicationOAuth.py b/github/ApplicationOAuth.py index da346c3009..b846361648 100644 --- a/github/ApplicationOAuth.py +++ b/github/ApplicationOAuth.py @@ -44,7 +44,10 @@ class ApplicationOAuth(NonCompletableGithubObject): """ This class is used for identifying and authorizing users for Github Apps. - The reference can be found at https://docs.github.com/en/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps + + The reference can be found at + https://docs.github.com/en/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps + """ def _initAttributes(self) -> None: @@ -85,7 +88,9 @@ def get_login_url( state: str | None = None, login: str | None = None, ) -> str: - """Return the URL you need to redirect a user to in order to authorize your App.""" + """ + Return the URL you need to redirect a user to in order to authorize your App. + """ parameters = {"client_id": self.client_id} if redirect_uri is not None: assert isinstance(redirect_uri, str), redirect_uri diff --git a/github/Artifact.py b/github/Artifact.py index ee5171ef3c..bd5c580d76 100644 --- a/github/Artifact.py +++ b/github/Artifact.py @@ -54,7 +54,7 @@ class Artifact(NonCompletableGithubObject): """ - This class represents an Artifact of Github Run + This class represents an Artifact of Github Run. """ def _initAttributes(self) -> None: diff --git a/github/Auth.py b/github/Auth.py index 5fc1e3fa78..607d317144 100644 --- a/github/Auth.py +++ b/github/Auth.py @@ -56,7 +56,9 @@ class Auth(abc.ABC): def token_type(self) -> str: """ The type of the auth token as used in the HTTP Authorization header, e.g. Bearer or Basic. + :return: token type + """ @property @@ -64,7 +66,9 @@ def token_type(self) -> str: def token(self) -> str: """ The auth token as used in the HTTP Authorization header. + :return: token + """ @@ -72,12 +76,16 @@ class HTTPBasicAuth(Auth, abc.ABC): @property @abc.abstractmethod def username(self) -> str: - """The username.""" + """ + The username. + """ @property @abc.abstractmethod def password(self) -> str: - """The password""" + """ + The password. + """ @property def token_type(self) -> str: @@ -137,7 +145,9 @@ def token(self) -> str: class JWT(Auth, ABC): """ This class is the base class to authenticate with a JSON Web Token (JWT). + https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app + """ @property @@ -148,7 +158,9 @@ def token_type(self) -> str: class AppAuth(JWT): """ This class is used to authenticate as a GitHub App. + https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app + """ def __init__( @@ -193,10 +205,12 @@ def get_installation_auth( ) -> "AppInstallationAuth": """ Creates a github.Auth.AppInstallationAuth instance for an installation. + :param installation_id: installation id :param token_permissions: optional permissions :param requester: optional requester with app authentication :return: + """ return AppInstallationAuth(self, installation_id, token_permissions, requester) @@ -227,7 +241,9 @@ def create_jwt(self, expiration: Optional[int] = None) -> str: class AppAuthToken(JWT): """ This class is used to authenticate as a GitHub App with a single constant JWT. + https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app + """ def __init__(self, token: str): @@ -243,7 +259,9 @@ def token(self) -> str: class AppInstallationAuth(Auth, WithRequester["AppInstallationAuth"]): """ This class is used to authenticate as a GitHub App Installation. + https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation + """ # used to fetch live access token when calling self.token @@ -323,7 +341,9 @@ def _get_installation_authorization(self) -> InstallationAuthorization: class AppUserAuth(Auth, WithRequester["AppUserAuth"]): """ This class is used to authenticate as a GitHub App on behalf of a user. + https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user + """ _client_id: str diff --git a/github/Authorization.py b/github/Authorization.py index 77038f124d..c8c8b85ed8 100644 --- a/github/Authorization.py +++ b/github/Authorization.py @@ -50,7 +50,11 @@ class Authorization(github.GithubObject.CompletableGithubObject): """ - This class represents Authorizations. The reference can be found here https://docs.github.com/en/enterprise-server@3.0/rest/reference/oauth-authorizations + This class represents Authorizations. + + The reference can be found here + https://docs.github.com/en/enterprise-server@3.0/rest/reference/oauth-authorizations + """ def _initAttributes(self) -> None: diff --git a/github/AuthorizationApplication.py b/github/AuthorizationApplication.py index cc241fc401..4b2e78035a 100644 --- a/github/AuthorizationApplication.py +++ b/github/AuthorizationApplication.py @@ -40,7 +40,7 @@ class AuthorizationApplication(CompletableGithubObject): """ - This class represents AuthorizationApplications + This class represents AuthorizationApplications. """ def _initAttributes(self) -> None: diff --git a/github/Autolink.py b/github/Autolink.py index 7a349d70e8..f80ba61030 100644 --- a/github/Autolink.py +++ b/github/Autolink.py @@ -44,7 +44,10 @@ class Autolink(NonCompletableGithubObject): """ This class represents Repository autolinks. - The reference can be found here https://docs.github.com/en/rest/repos/autolinks?apiVersion=2022-11-28 + + The reference can be found here + https://docs.github.com/en/rest/repos/autolinks?apiVersion=2022-11-28 + """ def _initAttributes(self) -> None: diff --git a/github/Branch.py b/github/Branch.py index 985658322d..c0fdcb42cd 100644 --- a/github/Branch.py +++ b/github/Branch.py @@ -78,7 +78,11 @@ class Branch(NonCompletableGithubObject): """ - This class represents Branches. The reference can be found here https://docs.github.com/en/rest/reference/repos#branches + This class represents Branches. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#branches + """ def __repr__(self) -> str: diff --git a/github/BranchProtection.py b/github/BranchProtection.py index 1cae51d90a..a9238cf6ec 100644 --- a/github/BranchProtection.py +++ b/github/BranchProtection.py @@ -49,7 +49,11 @@ class BranchProtection(github.GithubObject.CompletableGithubObject): """ - This class represents Branch Protection. The reference can be found here https://docs.github.com/en/rest/reference/repos#get-branch-protection + This class represents Branch Protection. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#get-branch-protection + """ def __repr__(self) -> str: diff --git a/github/CVSS.py b/github/CVSS.py index 7f8694c4cd..2341281040 100644 --- a/github/CVSS.py +++ b/github/CVSS.py @@ -45,7 +45,10 @@ class CVSS(NonCompletableGithubObject): """ This class represents a CVSS. - The reference can be found here + + The reference can be found here + + """ def _initAttributes(self) -> None: diff --git a/github/CWE.py b/github/CWE.py index 6397c192cf..10915f916f 100644 --- a/github/CWE.py +++ b/github/CWE.py @@ -45,7 +45,10 @@ class CWE(CompletableGithubObject): """ This class represents a CWE. - The reference can be found here https://docs.github.com/en/rest/security-advisories/repository-advisories + + The reference can be found here + https://docs.github.com/en/rest/security-advisories/repository-advisories + """ def _initAttributes(self) -> None: diff --git a/github/CheckRun.py b/github/CheckRun.py index c899c504f3..e9ade82274 100644 --- a/github/CheckRun.py +++ b/github/CheckRun.py @@ -57,7 +57,10 @@ class CheckRun(CompletableGithubObject): """ This class represents check runs. - The reference can be found here https://docs.github.com/en/rest/reference/checks#check-runs + + The reference can be found here + https://docs.github.com/en/rest/reference/checks#check-runs + """ def _initAttributes(self) -> None: diff --git a/github/CheckRunAnnotation.py b/github/CheckRunAnnotation.py index 5271c4c259..ce6658cdc4 100644 --- a/github/CheckRunAnnotation.py +++ b/github/CheckRunAnnotation.py @@ -32,7 +32,9 @@ class CheckRunAnnotation(NonCompletableGithubObject): """ This class represents check run annotations. + The reference can be found here: https://docs.github.com/en/rest/reference/checks#list-check-run-annotations + """ def _initAttributes(self) -> None: diff --git a/github/CheckRunOutput.py b/github/CheckRunOutput.py index 2a9f258a13..0fff1fd0c5 100644 --- a/github/CheckRunOutput.py +++ b/github/CheckRunOutput.py @@ -41,7 +41,9 @@ class CheckRunOutput(NonCompletableGithubObject): - """This class represents the output of check run.""" + """ + This class represents the output of check run. + """ def _initAttributes(self) -> None: self._annotations_count: Attribute[int] = NotSet diff --git a/github/CheckSuite.py b/github/CheckSuite.py index bb4f579a18..461593a23d 100644 --- a/github/CheckSuite.py +++ b/github/CheckSuite.py @@ -49,7 +49,11 @@ class CheckSuite(CompletableGithubObject): """ - This class represents check suites. The reference can be found here https://docs.github.com/en/rest/reference/checks#check-suites + This class represents check suites. + + The reference can be found here + https://docs.github.com/en/rest/reference/checks#check-suites + """ def _initAttributes(self) -> None: diff --git a/github/Clones.py b/github/Clones.py index 3dcbfbd83b..38c7ce0bed 100644 --- a/github/Clones.py +++ b/github/Clones.py @@ -44,7 +44,10 @@ class Clones(NonCompletableGithubObject): """ This class represents a popular Path for a GitHub repository. - The reference can be found here https://docs.github.com/en/rest/reference/repos#get-repository-clones + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#get-repository-clones + """ def _initAttributes(self) -> None: diff --git a/github/CodeScanAlert.py b/github/CodeScanAlert.py index f39314bc86..fa751433cc 100644 --- a/github/CodeScanAlert.py +++ b/github/CodeScanAlert.py @@ -40,7 +40,10 @@ class CodeScanAlert(NonCompletableGithubObject): """ This class represents alerts from code scanning. - The reference can be found here https://docs.github.com/en/rest/reference/code-scanning. + + The reference can be found here + https://docs.github.com/en/rest/reference/code-scanning. + """ def _initAttributes(self) -> None: @@ -110,7 +113,10 @@ def state(self) -> str: def get_instances(self) -> PaginatedList[github.CodeScanAlertInstance.CodeScanAlertInstance]: """ - :calls: `GET` on the URL for instances as provided by Github + Get instances. + + :calls: `GET` on the URL for instances as provided by Github. + """ return PaginatedList( github.CodeScanAlertInstance.CodeScanAlertInstance, diff --git a/github/CodeScanAlertInstance.py b/github/CodeScanAlertInstance.py index e9fb2b82f0..e838347546 100644 --- a/github/CodeScanAlertInstance.py +++ b/github/CodeScanAlertInstance.py @@ -37,7 +37,10 @@ class CodeScanAlertInstance(NonCompletableGithubObject): """ This class represents code scanning alert instances. - The reference can be found here https://docs.github.com/en/rest/reference/code-scanning. + + The reference can be found here + https://docs.github.com/en/rest/reference/code-scanning. + """ def _initAttributes(self) -> None: diff --git a/github/CodeScanAlertInstanceLocation.py b/github/CodeScanAlertInstanceLocation.py index 911e05212d..69e675262a 100644 --- a/github/CodeScanAlertInstanceLocation.py +++ b/github/CodeScanAlertInstanceLocation.py @@ -32,7 +32,10 @@ class CodeScanAlertInstanceLocation(NonCompletableGithubObject): """ This class represents code scanning alert instance locations. - The reference can be found here https://docs.github.com/en/rest/reference/code-scanning. + + The reference can be found here + https://docs.github.com/en/rest/reference/code-scanning. + """ def _initAttributes(self) -> None: diff --git a/github/CodeScanRule.py b/github/CodeScanRule.py index 47247ee881..991fca3e0a 100644 --- a/github/CodeScanRule.py +++ b/github/CodeScanRule.py @@ -46,7 +46,10 @@ class CodeScanRule(NonCompletableGithubObject): """ This class represents Alerts from code scanning. - The reference can be found here https://docs.github.com/en/rest/reference/code-scanning. + + The reference can be found here + https://docs.github.com/en/rest/reference/code-scanning. + """ def _initAttributes(self) -> None: diff --git a/github/CodeScanTool.py b/github/CodeScanTool.py index bd8c7597d3..b9d669b217 100644 --- a/github/CodeScanTool.py +++ b/github/CodeScanTool.py @@ -43,7 +43,10 @@ class CodeScanTool(NonCompletableGithubObject): """ This class represents code scanning tools. - The reference can be found here https://docs.github.com/en/rest/reference/code-scanning. + + The reference can be found here + https://docs.github.com/en/rest/reference/code-scanning. + """ def _initAttributes(self) -> None: diff --git a/github/Commit.py b/github/Commit.py index c003794fa2..0672a30f51 100644 --- a/github/Commit.py +++ b/github/Commit.py @@ -72,7 +72,11 @@ class Commit(CompletableGithubObject): """ - This class represents Commits. The reference can be found here https://docs.github.com/en/rest/reference/git#commits + This class represents Commits. + + The reference can be found here + https://docs.github.com/en/rest/reference/git#commits + """ def _initAttributes(self) -> None: diff --git a/github/CommitCombinedStatus.py b/github/CommitCombinedStatus.py index 7c66736f96..b840497930 100644 --- a/github/CommitCombinedStatus.py +++ b/github/CommitCombinedStatus.py @@ -47,7 +47,11 @@ class CommitCombinedStatus(NonCompletableGithubObject): """ - This class represents CommitCombinedStatuses. The reference can be found here https://docs.github.com/en/rest/reference/repos#statuses + This class represents CommitCombinedStatuses. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#statuses + """ def _initAttributes(self) -> None: diff --git a/github/CommitComment.py b/github/CommitComment.py index 34fe1a1e7a..387c634306 100644 --- a/github/CommitComment.py +++ b/github/CommitComment.py @@ -56,7 +56,11 @@ class CommitComment(CompletableGithubObject): """ - This class represents CommitComments. The reference can be found here https://docs.github.com/en/rest/reference/repos#comments + This class represents CommitComments. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#comments + """ def _initAttributes(self) -> None: diff --git a/github/Comparison.py b/github/Comparison.py index b59477ac48..5467a5052c 100644 --- a/github/Comparison.py +++ b/github/Comparison.py @@ -46,7 +46,7 @@ class Comparison(CompletableGithubObject): """ - This class represents Comparisons + This class represents Comparisons. """ def _initAttributes(self) -> None: diff --git a/github/ContentFile.py b/github/ContentFile.py index a26c56c996..703e9dc988 100644 --- a/github/ContentFile.py +++ b/github/ContentFile.py @@ -55,7 +55,11 @@ class ContentFile(CompletableGithubObject): """ - This class represents ContentFiles. The reference can be found here https://docs.github.com/en/rest/reference/repos#contents + This class represents ContentFiles. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#contents + """ def _initAttributes(self) -> None: diff --git a/github/DependabotAlert.py b/github/DependabotAlert.py index 614543faa6..8fe7ccdfc1 100644 --- a/github/DependabotAlert.py +++ b/github/DependabotAlert.py @@ -42,7 +42,10 @@ class DependabotAlert(NonCompletableGithubObject): """ This class represents a DependabotAlert. - The reference can be found here https://docs.github.com/en/rest/dependabot/alerts + + The reference can be found here + https://docs.github.com/en/rest/dependabot/alerts + """ def _initAttributes(self) -> None: diff --git a/github/DependabotAlertAdvisory.py b/github/DependabotAlertAdvisory.py index e5410d58e0..306f9c252e 100644 --- a/github/DependabotAlertAdvisory.py +++ b/github/DependabotAlertAdvisory.py @@ -35,7 +35,10 @@ class DependabotAlertAdvisory(github.AdvisoryBase.AdvisoryBase): """ This class represents a package flagged by a Dependabot alert that is vulnerable to a parent SecurityAdvisory. - The reference can be found here https://docs.github.com/en/rest/dependabot/alerts + + The reference can be found here + https://docs.github.com/en/rest/dependabot/alerts + """ def _initAttributes(self) -> None: diff --git a/github/DependabotAlertDependency.py b/github/DependabotAlertDependency.py index a59ed80c65..fe31144807 100644 --- a/github/DependabotAlertDependency.py +++ b/github/DependabotAlertDependency.py @@ -31,7 +31,10 @@ class DependabotAlertDependency(NonCompletableGithubObject): """ This class represents a DependabotAlertDependency. - The reference can be found here https://docs.github.com/en/rest/dependabot/alerts + + The reference can be found here + https://docs.github.com/en/rest/dependabot/alerts + """ def _initAttributes(self) -> None: diff --git a/github/Deployment.py b/github/Deployment.py index 6ac7b44472..bf6231ea8a 100644 --- a/github/Deployment.py +++ b/github/Deployment.py @@ -54,7 +54,11 @@ class Deployment(CompletableGithubObject): """ - This class represents Deployments. The reference can be found here https://docs.github.com/en/rest/reference/repos#deployments + This class represents Deployments. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#deployments + """ def _initAttributes(self) -> None: diff --git a/github/DeploymentStatus.py b/github/DeploymentStatus.py index c6ff57f429..d258265cf7 100644 --- a/github/DeploymentStatus.py +++ b/github/DeploymentStatus.py @@ -50,7 +50,11 @@ class DeploymentStatus(CompletableGithubObject): """ - This class represents Deployment Statuses. The reference can be found here https://docs.github.com/en/rest/reference/repos#deployments + This class represents Deployment Statuses. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#deployments + """ def _initAttributes(self) -> None: diff --git a/github/Download.py b/github/Download.py index a282344aa2..13e83c6f41 100644 --- a/github/Download.py +++ b/github/Download.py @@ -44,7 +44,11 @@ class Download(CompletableGithubObject): """ - This class represents Downloads. The reference can be found here https://docs.github.com/en/rest/reference/repos + This class represents Downloads. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos + """ def _initAttributes(self) -> None: diff --git a/github/Enterprise.py b/github/Enterprise.py index 26e0ada6cf..7f0043c43d 100644 --- a/github/Enterprise.py +++ b/github/Enterprise.py @@ -45,8 +45,12 @@ class Enterprise(NonCompletableGithubObject): """ - This class represents Enterprises. Such objects do not exist in the Github API, so this class merely collects all endpoints the start with /enterprises/{enterprise}/. See methods below for specific endpoints and docs. + This class represents Enterprises. + + Such objects do not exist in the Github API, so this class merely collects all endpoints the start with + /enterprises/{enterprise}/. See methods below for specific endpoints and docs. https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin?apiVersion=2022-11-28 + """ def __init__( diff --git a/github/EnterpriseConsumedLicenses.py b/github/EnterpriseConsumedLicenses.py index 14f1bd4f20..06a88b9bd5 100644 --- a/github/EnterpriseConsumedLicenses.py +++ b/github/EnterpriseConsumedLicenses.py @@ -45,7 +45,11 @@ class EnterpriseConsumedLicenses(CompletableGithubObject): """ - This class represents license consumed by enterprises. The reference can be found here https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin/license#list-enterprise-consumed-licenses + This class represents license consumed by enterprises. + + The reference can be found here + https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin/license#list-enterprise-consumed-licenses + """ def _initAttributes(self) -> None: diff --git a/github/Environment.py b/github/Environment.py index 69b95cde18..9599838d6b 100644 --- a/github/Environment.py +++ b/github/Environment.py @@ -57,7 +57,11 @@ class Environment(CompletableGithubObject): """ - This class represents Environment. The reference can be found here https://docs.github.com/en/rest/reference/deployments#environments + This class represents Environment. + + The reference can be found here + https://docs.github.com/en/rest/reference/deployments#environments + """ def _initAttributes(self) -> None: @@ -171,7 +175,7 @@ def create_secret(self, secret_name: str, unencrypted_value: str) -> Secret: def get_secrets(self) -> PaginatedList[Secret]: """ - Gets all repository secrets + Gets all repository secrets. """ return PaginatedList( Secret, @@ -218,8 +222,7 @@ def create_variable(self, variable_name: str, value: str) -> Variable: def get_variables(self) -> PaginatedList[Variable]: """ - Gets all repository variables - :rtype: :class:`PaginatedList` of :class:`Variable` + Gets all repository variables :rtype: :class:`PaginatedList` of :class:`Variable` """ return PaginatedList( Variable, diff --git a/github/EnvironmentDeploymentBranchPolicy.py b/github/EnvironmentDeploymentBranchPolicy.py index cf3bce2d55..8c5b2b1f73 100644 --- a/github/EnvironmentDeploymentBranchPolicy.py +++ b/github/EnvironmentDeploymentBranchPolicy.py @@ -30,7 +30,11 @@ class EnvironmentDeploymentBranchPolicy(NonCompletableGithubObject): """ - This class represents a deployment branch policy for an environment. The reference can be found here https://docs.github.com/en/rest/reference/deployments#environments + This class represents a deployment branch policy for an environment. + + The reference can be found here + https://docs.github.com/en/rest/reference/deployments#environments + """ def _initAttributes(self) -> None: diff --git a/github/EnvironmentProtectionRule.py b/github/EnvironmentProtectionRule.py index fcb7c2f1a6..59f62fde4b 100644 --- a/github/EnvironmentProtectionRule.py +++ b/github/EnvironmentProtectionRule.py @@ -50,7 +50,11 @@ class EnvironmentProtectionRule(NonCompletableGithubObject): """ - This class represents a protection rule for an environment. The reference can be found here https://docs.github.com/en/rest/reference/deployments#environments + This class represents a protection rule for an environment. + + The reference can be found here + https://docs.github.com/en/rest/reference/deployments#environments + """ def _initAttributes(self) -> None: diff --git a/github/EnvironmentProtectionRuleReviewer.py b/github/EnvironmentProtectionRuleReviewer.py index 9ef49af558..fbac7f5beb 100644 --- a/github/EnvironmentProtectionRuleReviewer.py +++ b/github/EnvironmentProtectionRuleReviewer.py @@ -47,7 +47,11 @@ class EnvironmentProtectionRuleReviewer(NonCompletableGithubObject): """ - This class represents a reviewer for an EnvironmentProtectionRule. The reference can be found here https://docs.github.com/en/rest/reference/deployments#environments + This class represents a reviewer for an EnvironmentProtectionRule. + + The reference can be found here + https://docs.github.com/en/rest/reference/deployments#environments + """ def _initAttributes(self) -> None: diff --git a/github/Event.py b/github/Event.py index 788e9f2b07..90c37c882f 100644 --- a/github/Event.py +++ b/github/Event.py @@ -49,7 +49,11 @@ class Event(NonCompletableGithubObject): """ - This class represents Events. The reference can be found here https://docs.github.com/en/rest/reference/activity#events + This class represents Events. + + The reference can be found here + https://docs.github.com/en/rest/reference/activity#events + """ def _initAttributes(self) -> None: diff --git a/github/File.py b/github/File.py index 2e796be62a..23e17507c7 100644 --- a/github/File.py +++ b/github/File.py @@ -43,7 +43,7 @@ class File(NonCompletableGithubObject): """ - This class represents Files + This class represents Files. """ def _initAttributes(self) -> None: diff --git a/github/Gist.py b/github/Gist.py index 15355ea67f..d5a7a12322 100644 --- a/github/Gist.py +++ b/github/Gist.py @@ -62,7 +62,11 @@ class Gist(CompletableGithubObject): """ - This class represents Gists. The reference can be found here https://docs.github.com/en/rest/reference/gists + This class represents Gists. + + The reference can be found here + https://docs.github.com/en/rest/reference/gists + """ def _initAttributes(self) -> None: diff --git a/github/GistComment.py b/github/GistComment.py index b1bc1a67b3..a57b73f322 100644 --- a/github/GistComment.py +++ b/github/GistComment.py @@ -48,7 +48,11 @@ class GistComment(CompletableGithubObject): """ - This class represents GistComments. The reference can be found here https://docs.github.com/en/rest/reference/gists#comments + This class represents GistComments. + + The reference can be found here + https://docs.github.com/en/rest/reference/gists#comments + """ def _initAttributes(self) -> None: diff --git a/github/GistFile.py b/github/GistFile.py index 20f2990cb2..731c6a7abf 100644 --- a/github/GistFile.py +++ b/github/GistFile.py @@ -40,7 +40,7 @@ class GistFile(NonCompletableGithubObject): """ - This class represents GistFiles + This class represents GistFiles. """ def _initAttributes(self) -> None: diff --git a/github/GistHistoryState.py b/github/GistHistoryState.py index f471d8f618..83c5dab305 100644 --- a/github/GistHistoryState.py +++ b/github/GistHistoryState.py @@ -48,7 +48,7 @@ class GistHistoryState(CompletableGithubObject): """ - This class represents GistHistoryStates + This class represents GistHistoryStates. """ def _initAttributes(self) -> None: diff --git a/github/GitAuthor.py b/github/GitAuthor.py index 923c1b5cd6..764e328e47 100644 --- a/github/GitAuthor.py +++ b/github/GitAuthor.py @@ -41,7 +41,7 @@ class GitAuthor(NonCompletableGithubObject): """ - This class represents GitAuthors + This class represents GitAuthors. """ def _initAttributes(self) -> None: diff --git a/github/GitBlob.py b/github/GitBlob.py index 39af80302a..c7efc781cc 100644 --- a/github/GitBlob.py +++ b/github/GitBlob.py @@ -41,7 +41,11 @@ class GitBlob(CompletableGithubObject): """ - This class represents GitBlobs. The reference can be found here https://docs.github.com/en/rest/reference/git#blobs + This class represents GitBlobs. + + The reference can be found here + https://docs.github.com/en/rest/reference/git#blobs + """ def _initAttributes(self) -> None: diff --git a/github/GitCommit.py b/github/GitCommit.py index f2b96401e2..e24c9840f8 100644 --- a/github/GitCommit.py +++ b/github/GitCommit.py @@ -47,7 +47,11 @@ class GitCommit(CompletableGithubObject): """ - This class represents GitCommits. The reference can be found here https://docs.github.com/en/rest/reference/git#commits + This class represents GitCommits. + + The reference can be found here + https://docs.github.com/en/rest/reference/git#commits + """ def _initAttributes(self) -> None: diff --git a/github/GitObject.py b/github/GitObject.py index be2b35628a..76830ea745 100644 --- a/github/GitObject.py +++ b/github/GitObject.py @@ -40,7 +40,7 @@ class GitObject(NonCompletableGithubObject): """ - This class represents GitObjects + This class represents GitObjects. """ def _initAttributes(self) -> None: diff --git a/github/GitRef.py b/github/GitRef.py index 474062268d..3ee1deb9d2 100644 --- a/github/GitRef.py +++ b/github/GitRef.py @@ -50,7 +50,11 @@ class GitRef(CompletableGithubObject): """ - This class represents GitRefs. The reference can be found here https://docs.github.com/en/rest/reference/git#references + This class represents GitRefs. + + The reference can be found here + https://docs.github.com/en/rest/reference/git#references + """ def _initAttributes(self) -> None: diff --git a/github/GitRelease.py b/github/GitRelease.py index 9b47e52d26..f8d6ed6acb 100644 --- a/github/GitRelease.py +++ b/github/GitRelease.py @@ -68,7 +68,11 @@ class GitRelease(CompletableGithubObject): """ - This class represents GitReleases. The reference can be found here https://docs.github.com/en/rest/reference/repos#releases + This class represents GitReleases. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#releases + """ def _initAttributes(self) -> None: @@ -250,11 +254,15 @@ def upload_asset_from_memory( content_type: Opt[str] = NotSet, label: str = "", ) -> github.GitReleaseAsset.GitReleaseAsset: - """Uploads an asset. Unlike ``upload_asset()`` this method allows you to pass in a file-like object to upload. + """ + Uploads an asset. + + Unlike ``upload_asset()`` this method allows you to pass in a file-like object to upload. Note that this method is more strict and requires you to specify the ``name``, since there's no file name to infer these from. :calls: `POST https:///repos/{owner}/{repo}/releases/{release_id}/assets `_ :param file_like: binary file-like object, such as those returned by ``open("file_name", "rb")``. At the very minimum, this object must implement ``read()``. :param file_size: int, size in bytes of ``file_like`` + """ assert isinstance(name, str), name assert isinstance(file_size, int), file_size diff --git a/github/GitReleaseAsset.py b/github/GitReleaseAsset.py index c405278484..0a512585b4 100644 --- a/github/GitReleaseAsset.py +++ b/github/GitReleaseAsset.py @@ -48,7 +48,11 @@ class GitReleaseAsset(CompletableGithubObject): """ - This class represents GitReleaseAssets. The reference can be found here https://docs.github.com/en/rest/reference/repos#releases + This class represents GitReleaseAssets. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#releases + """ def _initAttributes(self) -> None: diff --git a/github/GitTag.py b/github/GitTag.py index 32c851f0f1..70dfc345db 100644 --- a/github/GitTag.py +++ b/github/GitTag.py @@ -52,7 +52,11 @@ class GitTag(CompletableGithubObject): """ - This class represents GitTags. The reference can be found here https://docs.github.com/en/rest/reference/git#tags + This class represents GitTags. + + The reference can be found here + https://docs.github.com/en/rest/reference/git#tags + """ def _initAttributes(self) -> None: diff --git a/github/GitTree.py b/github/GitTree.py index 8f84be61e3..c41f8ebfec 100644 --- a/github/GitTree.py +++ b/github/GitTree.py @@ -48,7 +48,11 @@ class GitTree(CompletableGithubObject): """ - This class represents GitTrees. The reference can be found here https://docs.github.com/en/rest/reference/git#trees + This class represents GitTrees. + + The reference can be found here + https://docs.github.com/en/rest/reference/git#trees + """ def _initAttributes(self) -> None: diff --git a/github/GitTreeElement.py b/github/GitTreeElement.py index 79630b103a..9b73922ad2 100644 --- a/github/GitTreeElement.py +++ b/github/GitTreeElement.py @@ -40,7 +40,7 @@ class GitTreeElement(NonCompletableGithubObject): """ - This class represents GitTreeElements + This class represents GitTreeElements. """ def _initAttributes(self) -> None: diff --git a/github/GithubApp.py b/github/GithubApp.py index c2807af9ef..159a2a558b 100644 --- a/github/GithubApp.py +++ b/github/GithubApp.py @@ -51,7 +51,11 @@ class GithubApp(CompletableGithubObject): """ - This class represents github apps. The reference can be found here https://docs.github.com/en/rest/reference/apps + This class represents github apps. + + The reference can be found here + https://docs.github.com/en/rest/reference/apps + """ def _initAttributes(self) -> None: diff --git a/github/GithubException.py b/github/GithubException.py index 2171039e18..a043718693 100644 --- a/github/GithubException.py +++ b/github/GithubException.py @@ -41,9 +41,11 @@ class GithubException(Exception): """ - Error handling in PyGithub is done with exceptions. This class is the base of all exceptions raised by PyGithub (but :class:`github.GithubException.BadAttributeException`). + Error handling in PyGithub is done with exceptions. This class is the base of all exceptions raised by PyGithub + (but :class:`github.GithubException.BadAttributeException`). Some other types of exceptions might be raised by underlying libraries, for example for network-related issues. + """ def __init__( @@ -67,21 +69,21 @@ def message(self) -> Optional[str]: @property def status(self) -> int: """ - The status returned by the Github API + The status returned by the Github API. """ return self.__status @property def data(self) -> Any: """ - The (decoded) data returned by the Github API + The (decoded) data returned by the Github API. """ return self.__data @property def headers(self) -> Optional[Dict[str, str]]: """ - The headers returned by the Github API + The headers returned by the Github API. """ return self.__headers @@ -114,13 +116,15 @@ class UnknownObjectException(GithubException): class BadUserAgentException(GithubException): """ - Exception raised when request is sent with a bad user agent header (when Github API replies with a 403 bad user agent HTML status) + Exception raised when request is sent with a bad user agent header (when Github API replies with a 403 bad user + agent HTML status) """ class RateLimitExceededException(GithubException): """ - Exception raised when the rate limit is exceeded (when Github API replies with a 403 rate limit exceeded HTML status) + Exception raised when the rate limit is exceeded (when Github API replies with a 403 rate limit exceeded HTML + status) """ @@ -147,7 +151,7 @@ def __init__( @property def actual_value(self) -> Any: """ - The value returned by Github + The value returned by Github. """ return self.__actualValue @@ -161,25 +165,25 @@ def expected_type( List[Tuple[Type[str], Type[str]]], ]: """ - The type PyGithub expected + The type PyGithub expected. """ return self.__expectedType @property def transformation_exception(self) -> Optional[Exception]: """ - The exception raised when PyGithub tried to parse the value + The exception raised when PyGithub tried to parse the value. """ return self.__transformationException class TwoFactorException(GithubException): """ - Exception raised when Github requires a onetime password for two-factor authentication + Exception raised when Github requires a onetime password for two-factor authentication. """ class IncompletableObject(GithubException): """ - Exception raised when we can not request an object from Github because the data returned did not include a URL + Exception raised when we can not request an object from Github because the data returned did not include a URL. """ diff --git a/github/GithubIntegration.py b/github/GithubIntegration.py index 4365746b79..011135bc37 100644 --- a/github/GithubIntegration.py +++ b/github/GithubIntegration.py @@ -157,8 +157,8 @@ def __init__( ) def close(self) -> None: - """ - Close connections to the server. Alternatively, use the GithubIntegration object as a context manager: + """Close connections to the server. Alternatively, use the + GithubIntegration object as a context manager: .. code-block:: python @@ -241,9 +241,11 @@ def get_access_token( @deprecated.deprecated("Use get_repo_installation") def get_installation(self, owner: str, repo: str) -> Installation: """ - Deprecated by get_repo_installation + Deprecated by get_repo_installation. + + :calls: `GET /repos/{owner}/{repo}/installation + ` - :calls: `GET /repos/{owner}/{repo}/installation ` """ owner = urllib.parse.quote(owner) repo = urllib.parse.quote(repo) diff --git a/github/GithubObject.py b/github/GithubObject.py index ac121e488c..7d89574bb5 100644 --- a/github/GithubObject.py +++ b/github/GithubObject.py @@ -75,7 +75,9 @@ def value(self) -> T_co: def _datetime_from_http_date(value: str) -> datetime: """ Convert an HTTP date to a datetime object. + Raises ValueError for invalid dates. + """ dt = email.utils.parsedate_to_datetime(value) @@ -88,7 +90,9 @@ def _datetime_from_http_date(value: str) -> datetime: def _datetime_from_github_isoformat(value: str) -> datetime: """ Convert an GitHub API timestamps to a datetime object. + Raises ValueError for invalid timestamps. + """ # Github always returns YYYY-MM-DDTHH:MM:SSZ, so we can use the stdlib parser @@ -423,8 +427,8 @@ def __complete(self) -> None: def update(self, additional_headers: Optional[Dict[str, Any]] = None) -> bool: """ - Check and update the object with conditional request - :rtype: Boolean value indicating whether the object is changed + Check and update the object with conditional request :rtype: Boolean value indicating whether the object is + changed. """ conditionalRequestHeader = dict() if self.etag is not None: diff --git a/github/GithubRetry.py b/github/GithubRetry.py index 2fe04c49dd..9790db95e9 100644 --- a/github/GithubRetry.py +++ b/github/GithubRetry.py @@ -57,6 +57,7 @@ class GithubRetry(Retry): By default, all methods defined in `Retry.DEFAULT_ALLOWED_METHODS` are retried, plus GET and POST. This can be configured via the `allowed_methods` argument. + """ __logger: Optional[Logger] = None diff --git a/github/GitignoreTemplate.py b/github/GitignoreTemplate.py index 1f5fe0936e..b8bc0c41e5 100644 --- a/github/GitignoreTemplate.py +++ b/github/GitignoreTemplate.py @@ -41,7 +41,11 @@ class GitignoreTemplate(NonCompletableGithubObject): """ - This class represents GitignoreTemplates. The reference can be found here https://docs.github.com/en/rest/reference/gitignore + This class represents GitignoreTemplates. + + The reference can be found here + https://docs.github.com/en/rest/reference/gitignore + """ def _initAttributes(self) -> None: diff --git a/github/GlobalAdvisory.py b/github/GlobalAdvisory.py index cb59d7a15e..7f51d00d66 100644 --- a/github/GlobalAdvisory.py +++ b/github/GlobalAdvisory.py @@ -36,7 +36,9 @@ class GlobalAdvisory(AdvisoryBase): """ This class represents a GlobalAdvisory. + https://docs.github.com/en/rest/security-advisories/global-advisories + """ def _initAttributes(self) -> None: diff --git a/github/Hook.py b/github/Hook.py index 3ac66ab7c6..c169e39a6f 100644 --- a/github/Hook.py +++ b/github/Hook.py @@ -49,7 +49,11 @@ class Hook(CompletableGithubObject): """ - This class represents Hooks. The reference can be found here https://docs.github.com/en/rest/reference/repos#webhooks + This class represents Hooks. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#webhooks + """ def _initAttributes(self) -> None: diff --git a/github/HookDelivery.py b/github/HookDelivery.py index 3057006096..0a2f1201ba 100644 --- a/github/HookDelivery.py +++ b/github/HookDelivery.py @@ -32,7 +32,7 @@ class HookDeliverySummary(github.GithubObject.NonCompletableGithubObject): """ - This class represents a Summary of HookDeliveries + This class represents a Summary of HookDeliveries. """ def _initAttributes(self) -> None: @@ -129,7 +129,7 @@ def _useAttributes(self, attributes: Dict[str, Any]) -> None: class HookDeliveryRequest(github.GithubObject.NonCompletableGithubObject): """ - This class represents a HookDeliveryRequest + This class represents a HookDeliveryRequest. """ def _initAttributes(self) -> None: @@ -156,7 +156,7 @@ def _useAttributes(self, attributes: Dict[str, Any]) -> None: class HookDeliveryResponse(github.GithubObject.NonCompletableGithubObject): """ - This class represents a HookDeliveryResponse + This class represents a HookDeliveryResponse. """ def __repr__(self) -> str: @@ -183,7 +183,7 @@ def _useAttributes(self, attributes: Dict[str, Any]) -> None: class HookDelivery(HookDeliverySummary): """ - This class represents a HookDelivery + This class represents a HookDelivery. """ def _initAttributes(self) -> None: diff --git a/github/HookDescription.py b/github/HookDescription.py index a06e4a83d6..f0d3124c0e 100644 --- a/github/HookDescription.py +++ b/github/HookDescription.py @@ -43,7 +43,7 @@ class HookDescription(NonCompletableGithubObject): """ - This class represents HookDescriptions + This class represents HookDescriptions. """ def _initAttributes(self) -> None: diff --git a/github/HookResponse.py b/github/HookResponse.py index a8a84bf14d..a52be69f52 100644 --- a/github/HookResponse.py +++ b/github/HookResponse.py @@ -40,7 +40,7 @@ class HookResponse(NonCompletableGithubObject): """ - This class represents HookResponses + This class represents HookResponses. """ def _initAttributes(self) -> None: diff --git a/github/InputFileContent.py b/github/InputFileContent.py index 73b9a7fc83..7a216c3525 100644 --- a/github/InputFileContent.py +++ b/github/InputFileContent.py @@ -41,7 +41,7 @@ class InputFileContent: """ - This class represents InputFileContents + This class represents InputFileContents. """ def __init__(self, content: str, new_name: Opt[str] = NotSet): diff --git a/github/InputGitAuthor.py b/github/InputGitAuthor.py index 369c480073..a65ce5dd25 100644 --- a/github/InputGitAuthor.py +++ b/github/InputGitAuthor.py @@ -42,7 +42,7 @@ class InputGitAuthor: """ - This class represents InputGitAuthors + This class represents InputGitAuthors. """ def __init__(self, name: str, email: str, date: Opt[str] = NotSet): diff --git a/github/InputGitTreeElement.py b/github/InputGitTreeElement.py index ee025e6b13..29626f753a 100644 --- a/github/InputGitTreeElement.py +++ b/github/InputGitTreeElement.py @@ -40,7 +40,7 @@ class InputGitTreeElement: """ - This class represents InputGitTreeElements + This class represents InputGitTreeElements. """ def __init__( diff --git a/github/Installation.py b/github/Installation.py index 41a1b53142..d5401e574f 100644 --- a/github/Installation.py +++ b/github/Installation.py @@ -67,7 +67,11 @@ class Installation(NonCompletableGithubObject): """ - This class represents Installations. The reference can be found here https://docs.github.com/en/rest/reference/apps#installations + This class represents Installations. + + The reference can be found here + https://docs.github.com/en/rest/reference/apps#installations + """ def __init__( diff --git a/github/InstallationAuthorization.py b/github/InstallationAuthorization.py index 86c811ecbd..85839f6e86 100644 --- a/github/InstallationAuthorization.py +++ b/github/InstallationAuthorization.py @@ -51,7 +51,7 @@ class InstallationAuthorization(NonCompletableGithubObject): """ - This class represents InstallationAuthorizations + This class represents InstallationAuthorizations. """ def _initAttributes(self) -> None: diff --git a/github/Invitation.py b/github/Invitation.py index 89159f9437..c54f0c66d5 100644 --- a/github/Invitation.py +++ b/github/Invitation.py @@ -53,7 +53,11 @@ class Invitation(CompletableGithubObject): """ - This class represents repository invitations. The reference can be found here https://docs.github.com/en/rest/reference/repos#invitations + This class represents repository invitations. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#invitations + """ def _initAttributes(self) -> None: diff --git a/github/Issue.py b/github/Issue.py index b7295934f3..b89f18db03 100644 --- a/github/Issue.py +++ b/github/Issue.py @@ -100,7 +100,11 @@ class Issue(CompletableGithubObject): """ - This class represents Issues. The reference can be found here https://docs.github.com/en/rest/reference/issues + This class represents Issues. + + The reference can be found here + https://docs.github.com/en/rest/reference/issues + """ def _initAttributes(self) -> None: diff --git a/github/IssueComment.py b/github/IssueComment.py index d8dd9d78e8..b8d42524a3 100644 --- a/github/IssueComment.py +++ b/github/IssueComment.py @@ -58,7 +58,11 @@ class IssueComment(CompletableGithubObject): """ - This class represents IssueComments. The reference can be found here https://docs.github.com/en/rest/reference/issues#comments + This class represents IssueComments. + + The reference can be found here + https://docs.github.com/en/rest/reference/issues#comments + """ def _initAttributes(self) -> None: diff --git a/github/IssueEvent.py b/github/IssueEvent.py index e974004b9a..36fb9d9f27 100644 --- a/github/IssueEvent.py +++ b/github/IssueEvent.py @@ -52,7 +52,11 @@ class IssueEvent(CompletableGithubObject): """ - This class represents IssueEvents. The reference can be found here https://docs.github.com/en/rest/reference/issues#events + This class represents IssueEvents. + + The reference can be found here + https://docs.github.com/en/rest/reference/issues#events + """ def _initAttributes(self) -> None: diff --git a/github/IssuePullRequest.py b/github/IssuePullRequest.py index 42a1e69a1c..4d59bdbe4f 100644 --- a/github/IssuePullRequest.py +++ b/github/IssuePullRequest.py @@ -40,7 +40,7 @@ class IssuePullRequest(NonCompletableGithubObject): """ - This class represents IssuePullRequests + This class represents IssuePullRequests. """ def _initAttributes(self) -> None: diff --git a/github/Label.py b/github/Label.py index b8658e3316..7b5b6d1b58 100644 --- a/github/Label.py +++ b/github/Label.py @@ -47,7 +47,11 @@ class Label(CompletableGithubObject): """ - This class represents Labels. The reference can be found here https://docs.github.com/en/rest/reference/issues#labels + This class represents Labels. + + The reference can be found here + https://docs.github.com/en/rest/reference/issues#labels + """ def _initAttributes(self) -> None: diff --git a/github/License.py b/github/License.py index dfe8a95fc7..36bf673b7d 100644 --- a/github/License.py +++ b/github/License.py @@ -48,7 +48,11 @@ class License(CompletableGithubObject): """ - This class represents Licenses. The reference can be found here https://docs.github.com/en/rest/reference/licenses + This class represents Licenses. + + The reference can be found here + https://docs.github.com/en/rest/reference/licenses + """ def _initAttributes(self) -> None: diff --git a/github/MainClass.py b/github/MainClass.py index f90cdc56e0..37ed51c662 100644 --- a/github/MainClass.py +++ b/github/MainClass.py @@ -148,7 +148,10 @@ class Github: """ - This is the main class you instantiate to access the Github API v3. Optional parameters allow different authentication methods. + This is the main class you instantiate to access the Github API v3. + + Optional parameters allow different authentication methods. + """ __requester: Requester @@ -252,8 +255,8 @@ def __init__( ) def close(self) -> None: - """ - Close connections to the server. Alternatively, use the Github object as a context manager: + """Close connections to the server. Alternatively, use the Github + object as a context manager: .. code-block:: python @@ -311,7 +314,9 @@ def get_rate_limit(self) -> RateLimit: """ Rate limit status for different resources (core/search/graphql). - :calls: `GET /rate_limit `_ + :calls: `GET /rate_limit + `_ + """ headers, data = self.__requester.requestJsonAndCheck("GET", "/rate_limit") return RateLimit(self.__requester, headers, data["resources"], True) @@ -921,13 +926,14 @@ 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:`GithubObject.raw_data`, - and optionally headers previously obtained by :attr:`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 = {} @@ -936,13 +942,35 @@ def create_from_raw_data( 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. - But NO EFFORT is made to remove sensitive information from the object's attributes. - + 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. But NO EFFORT is made to remove + sensitive information from the object's attributes. + + :param obj: the object to pickle :param file: the file-like object to pickle to :param protocol: the + `pickling protocol `_ + :param obj: the object to pickle :param file: the file-like object to pickle to :param protocol: the + `pickling protocol `_ :param obj: the object to pickle :param file: the file-like object to pickle to :param + protocol: the + `pickling protocol `_ + :param obj: the object to pickle + :param file: the file-like object to pickle to + :param protocol: the `pickling protocol `_ + :param protocol: the `pickling protocol `_ + :param obj: the object to pickle + :param file: the file-like object to pickle to + :param protocol: the `pickling protocol `_ + """ pickle.dump((obj.__class__, obj.raw_data, obj.raw_headers), file, protocol) @@ -952,6 +980,7 @@ def load(self, f: BinaryIO) -> Any: :param f: the file-like object to unpickle from :return: the unpickled object + """ return self.create_from_raw_data(*pickle.load(f)) diff --git a/github/Membership.py b/github/Membership.py index 2b96defdf2..6ee475b930 100644 --- a/github/Membership.py +++ b/github/Membership.py @@ -54,7 +54,11 @@ class Membership(CompletableGithubObject): """ - This class represents Membership of an organization. The reference can be found here https://docs.github.com/en/rest/reference/orgs + This class represents Membership of an organization. + + The reference can be found here + https://docs.github.com/en/rest/reference/orgs + """ def _initAttributes(self) -> None: diff --git a/github/Migration.py b/github/Migration.py index 4da1b3f822..833a8c68fe 100644 --- a/github/Migration.py +++ b/github/Migration.py @@ -57,7 +57,11 @@ class Migration(CompletableGithubObject): """ - This class represents Migrations. The reference can be found here https://docs.github.com/en/rest/reference/migrations + This class represents Migrations. + + The reference can be found here + https://docs.github.com/en/rest/reference/migrations + """ def _initAttributes(self) -> None: diff --git a/github/Milestone.py b/github/Milestone.py index da984958e9..b90f6d4cd3 100644 --- a/github/Milestone.py +++ b/github/Milestone.py @@ -52,7 +52,11 @@ class Milestone(CompletableGithubObject): """ - This class represents Milestones. The reference can be found here https://docs.github.com/en/rest/reference/issues#milestones + This class represents Milestones. + + The reference can be found here + https://docs.github.com/en/rest/reference/issues#milestones + """ def _initAttributes(self) -> None: diff --git a/github/NamedEnterpriseUser.py b/github/NamedEnterpriseUser.py index 513efadbc1..866c90b7c2 100644 --- a/github/NamedEnterpriseUser.py +++ b/github/NamedEnterpriseUser.py @@ -28,7 +28,11 @@ class NamedEnterpriseUser(CompletableGithubObject): """ - This class represents NamedEnterpriseUsers. The reference can be found here https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin/license#list-enterprise-consumed-licenses + This class represents NamedEnterpriseUsers. + + The reference can be found here + https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin/license#list-enterprise-consumed-licenses + """ def _initAttributes(self) -> None: diff --git a/github/NamedUser.py b/github/NamedUser.py index 8de6a26cd1..269f8c91ab 100644 --- a/github/NamedUser.py +++ b/github/NamedUser.py @@ -82,7 +82,11 @@ class NamedUser(github.GithubObject.CompletableGithubObject): """ - This class represents NamedUsers. The reference can be found here https://docs.github.com/en/rest/reference/users#get-a-user + This class represents NamedUsers. + + The reference can be found here + https://docs.github.com/en/rest/reference/users#get-a-user + """ def _initAttributes(self) -> None: diff --git a/github/Notification.py b/github/Notification.py index 1af3cb93d5..2e881f2448 100644 --- a/github/Notification.py +++ b/github/Notification.py @@ -53,7 +53,11 @@ class Notification(CompletableGithubObject): """ - This class represents Notifications. The reference can be found here https://docs.github.com/en/rest/reference/activity#notifications + This class represents Notifications. + + The reference can be found here + https://docs.github.com/en/rest/reference/activity#notifications + """ def _initAttributes(self) -> None: diff --git a/github/NotificationSubject.py b/github/NotificationSubject.py index 6296cac0ce..216a15d287 100644 --- a/github/NotificationSubject.py +++ b/github/NotificationSubject.py @@ -44,7 +44,11 @@ class NotificationSubject(NonCompletableGithubObject): """ - This class represents Subjects of Notifications. The reference can be found here https://docs.github.com/en/rest/reference/activity#list-notifications-for-the-authenticated-user + This class represents Subjects of Notifications. + + The reference can be found here + https://docs.github.com/en/rest/reference/activity#list-notifications-for-the-authenticated-user + """ def _initAttributes(self) -> None: diff --git a/github/Organization.py b/github/Organization.py index 2f08f04d0e..22d22ac991 100644 --- a/github/Organization.py +++ b/github/Organization.py @@ -125,7 +125,11 @@ class Organization(CompletableGithubObject): """ - This class represents Organizations. The reference can be found here https://docs.github.com/en/rest/reference/orgs + This class represents Organizations. + + The reference can be found here + https://docs.github.com/en/rest/reference/orgs + """ def _initAttributes(self) -> None: @@ -621,9 +625,10 @@ def create_secret( def get_secrets(self, secret_type: str = "actions") -> PaginatedList[OrganizationSecret]: """ - Gets all organization secrets - :param secret_type: string options actions or dependabot - :rtype: :class:`PaginatedList` of :class:`github.OrganizationSecret.OrganizationSecret` + Gets all organization secrets :param secret_type: string options actions or dependabot :rtype: + + :class:`PaginatedList` of :class:`github.OrganizationSecret.OrganizationSecret` + """ assert secret_type in ["actions", "dependabot"], "secret_type should be actions or dependabot" return PaginatedList( @@ -746,8 +751,8 @@ def create_variable( def get_variables(self) -> PaginatedList[OrganizationVariable]: """ - Gets all organization variables - :rtype: :class:`PaginatedList` of :class:`github.OrganizationVariable.OrganizationVariable` + Gets all organization variables :rtype: :class:`PaginatedList` of + :class:`github.OrganizationVariable.OrganizationVariable` """ return PaginatedList( github.OrganizationVariable.OrganizationVariable, diff --git a/github/OrganizationDependabotAlert.py b/github/OrganizationDependabotAlert.py index 48e5bb57af..11717ca9d1 100644 --- a/github/OrganizationDependabotAlert.py +++ b/github/OrganizationDependabotAlert.py @@ -31,7 +31,11 @@ class OrganizationDependabotAlert(DependabotAlert): """ - This class represents a Dependabot alert on an organization. The reference can be found here https://docs.github.com/en/rest/dependabot/alerts#list-dependabot-alerts-for-an-organization + This class represents a Dependabot alert on an organization. + + The reference can be found here + https://docs.github.com/en/rest/dependabot/alerts#list-dependabot-alerts-for-an-organization + """ def _initAttributes(self) -> None: diff --git a/github/OrganizationSecret.py b/github/OrganizationSecret.py index f0c06086e2..97e1173cf6 100644 --- a/github/OrganizationSecret.py +++ b/github/OrganizationSecret.py @@ -32,7 +32,11 @@ class OrganizationSecret(Secret): """ - This class represents a org level GitHub secret. The reference can be found here https://docs.github.com/en/rest/actions/secrets + This class represents a org level GitHub secret. + + The reference can be found here + https://docs.github.com/en/rest/actions/secrets + """ def _initAttributes(self) -> None: diff --git a/github/OrganizationVariable.py b/github/OrganizationVariable.py index bea19fbb89..dcee4d196d 100644 --- a/github/OrganizationVariable.py +++ b/github/OrganizationVariable.py @@ -32,7 +32,11 @@ class OrganizationVariable(Variable): """ - This class represents a org level GitHub variable. The reference can be found here https://docs.github.com/en/rest/actions/variables + This class represents a org level GitHub variable. + + The reference can be found here + https://docs.github.com/en/rest/actions/variables + """ def _initAttributes(self) -> None: diff --git a/github/Path.py b/github/Path.py index ecf094bda9..c75b4fd65b 100644 --- a/github/Path.py +++ b/github/Path.py @@ -43,7 +43,10 @@ class Path(NonCompletableGithubObject): """ This class represents a popular Path for a GitHub repository. - The reference can be found here https://docs.github.com/en/rest/reference/repos#traffic + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#traffic + """ def _initAttributes(self) -> None: diff --git a/github/Permissions.py b/github/Permissions.py index e7bd6b573e..cd5d61645b 100644 --- a/github/Permissions.py +++ b/github/Permissions.py @@ -41,7 +41,7 @@ class Permissions(NonCompletableGithubObject): """ - This class represents Permissions + This class represents Permissions. """ def _initAttributes(self) -> None: diff --git a/github/Plan.py b/github/Plan.py index 34e948cb76..5c2b0f0e65 100644 --- a/github/Plan.py +++ b/github/Plan.py @@ -41,7 +41,7 @@ class Plan(NonCompletableGithubObject): """ - This class represents Plans + This class represents Plans. """ def _initAttributes(self) -> None: diff --git a/github/Project.py b/github/Project.py index 9e8f3ab2af..eed150cd7f 100644 --- a/github/Project.py +++ b/github/Project.py @@ -57,7 +57,11 @@ class Project(CompletableGithubObject): """ - This class represents Projects. The reference can be found here https://docs.github.com/en/rest/reference/projects + This class represents Projects. + + The reference can be found here + https://docs.github.com/en/rest/reference/projects + """ def _initAttributes(self) -> None: diff --git a/github/ProjectCard.py b/github/ProjectCard.py index 14caa34991..6b0a8d0d64 100644 --- a/github/ProjectCard.py +++ b/github/ProjectCard.py @@ -62,7 +62,11 @@ class ProjectCard(CompletableGithubObject): """ - This class represents Project Cards. The reference can be found here https://docs.github.com/en/rest/reference/projects#cards + This class represents Project Cards. + + The reference can be found here + https://docs.github.com/en/rest/reference/projects#cards + """ def _initAttributes(self) -> None: diff --git a/github/ProjectColumn.py b/github/ProjectColumn.py index 65b27cd5d2..a14a87ae44 100644 --- a/github/ProjectColumn.py +++ b/github/ProjectColumn.py @@ -60,7 +60,11 @@ class ProjectColumn(CompletableGithubObject): """ - This class represents Project Columns. The reference can be found here https://docs.github.com/en/rest/reference/projects#columns + This class represents Project Columns. + + The reference can be found here + https://docs.github.com/en/rest/reference/projects#columns + """ def _initAttributes(self) -> None: diff --git a/github/PublicKey.py b/github/PublicKey.py index 6c24a801c4..e117199048 100644 --- a/github/PublicKey.py +++ b/github/PublicKey.py @@ -48,7 +48,9 @@ def encrypt(public_key: str, secret_value: str) -> str: - """Encrypt a Unicode string using the public key.""" + """ + Encrypt a Unicode string using the public key. + """ pk = public.PublicKey(public_key.encode("utf-8"), encoding.Base64Encoder) sealed_box = public.SealedBox(pk) encrypted = sealed_box.encrypt(secret_value.encode("utf-8")) @@ -58,8 +60,12 @@ def encrypt(public_key: str, secret_value: str) -> str: class PublicKey(CompletableGithubObject): """ This class represents either an organization public key or a repository public key. - The reference can be found here https://docs.github.com/en/rest/reference/actions#get-an-organization-public-key - or here https://docs.github.com/en/rest/reference/actions#get-a-repository-public-key + + The reference can be found here + https://docs.github.com/en/rest/reference/actions#get-an-organization-public-key + or here + https://docs.github.com/en/rest/reference/actions#get-a-repository-public-key + """ def _initAttributes(self) -> None: diff --git a/github/PullRequest.py b/github/PullRequest.py index 741fbe6f61..377be11fc4 100644 --- a/github/PullRequest.py +++ b/github/PullRequest.py @@ -114,7 +114,11 @@ class ReviewComment(TypedDict): class PullRequest(CompletableGithubObject): """ - This class represents PullRequests. The reference can be found here https://docs.github.com/en/rest/reference/pulls + This class represents PullRequests. + + The reference can be found here + https://docs.github.com/en/rest/reference/pulls + """ def _initAttributes(self) -> None: diff --git a/github/PullRequestComment.py b/github/PullRequestComment.py index f809f3d677..274c94ed02 100644 --- a/github/PullRequestComment.py +++ b/github/PullRequestComment.py @@ -57,7 +57,11 @@ class PullRequestComment(CompletableGithubObject): """ - This class represents PullRequestComments. The reference can be found here https://docs.github.com/en/rest/reference/pulls#review-comments + This class represents PullRequestComments. + + The reference can be found here + https://docs.github.com/en/rest/reference/pulls#review-comments + """ def _initAttributes(self) -> None: diff --git a/github/PullRequestMergeStatus.py b/github/PullRequestMergeStatus.py index a858c16f94..2c0bc04830 100644 --- a/github/PullRequestMergeStatus.py +++ b/github/PullRequestMergeStatus.py @@ -43,7 +43,11 @@ class PullRequestMergeStatus(NonCompletableGithubObject): """ - This class represents PullRequestMergeStatuses. The reference can be found here https://docs.github.com/en/rest/reference/pulls#check-if-a-pull-request-has-been-merged + This class represents PullRequestMergeStatuses. + + The reference can be found here + https://docs.github.com/en/rest/reference/pulls#check-if-a-pull-request-has-been-merged + """ def _initAttributes(self) -> None: diff --git a/github/PullRequestPart.py b/github/PullRequestPart.py index ea98247c02..49f5977803 100644 --- a/github/PullRequestPart.py +++ b/github/PullRequestPart.py @@ -49,7 +49,7 @@ class PullRequestPart(NonCompletableGithubObject): """ - This class represents PullRequestParts + This class represents PullRequestParts. """ def _initAttributes(self) -> None: diff --git a/github/PullRequestReview.py b/github/PullRequestReview.py index abfaa8cce7..b1152f6a3c 100644 --- a/github/PullRequestReview.py +++ b/github/PullRequestReview.py @@ -52,7 +52,11 @@ class PullRequestReview(NonCompletableGithubObject): """ - This class represents PullRequestReviews. The reference can be found here https://docs.github.com/en/rest/reference/pulls#reviews + This class represents PullRequestReviews. + + The reference can be found here + https://docs.github.com/en/rest/reference/pulls#reviews + """ def _initAttributes(self) -> None: diff --git a/github/Rate.py b/github/Rate.py index 9e46ae75aa..24e7b588c8 100644 --- a/github/Rate.py +++ b/github/Rate.py @@ -44,7 +44,11 @@ class Rate(NonCompletableGithubObject): """ - This class represents Rates. The reference can be found here https://docs.github.com/en/rest/reference/rate-limit + This class represents Rates. + + The reference can be found here + https://docs.github.com/en/rest/reference/rate-limit + """ def _initAttributes(self) -> None: diff --git a/github/RateLimit.py b/github/RateLimit.py index af5e616416..bfc26df2dd 100644 --- a/github/RateLimit.py +++ b/github/RateLimit.py @@ -48,7 +48,11 @@ class RateLimit(NonCompletableGithubObject): """ - This class represents RateLimits. The reference can be found here https://docs.github.com/en/rest/reference/rate-limit + This class represents RateLimits. + + The reference can be found here + https://docs.github.com/en/rest/reference/rate-limit + """ def _initAttributes(self) -> None: @@ -62,9 +66,7 @@ def __repr__(self) -> str: @property def core(self) -> Rate: """ - Rate limit for the non-search-related API - - :type: class:`github.Rate.Rate` + Rate limit for the non-search-related API. """ return self._core.value @@ -72,8 +74,6 @@ def core(self) -> Rate: def search(self) -> Rate: """ Rate limit for the Search API. - - :type: class:`github.Rate.Rate` """ return self._search.value @@ -81,8 +81,6 @@ def search(self) -> Rate: def graphql(self) -> Rate: """ (Experimental) Rate limit for GraphQL API, use with caution. - - :type: class:`github.Rate.Rate` """ return self._graphql.value diff --git a/github/Reaction.py b/github/Reaction.py index 835d660842..8dd608a327 100644 --- a/github/Reaction.py +++ b/github/Reaction.py @@ -53,7 +53,11 @@ class Reaction(CompletableGithubObject): """ - This class represents Reactions. The reference can be found here https://docs.github.com/en/rest/reference/reactions + This class represents Reactions. + + The reference can be found here + https://docs.github.com/en/rest/reference/reactions + """ def _initAttributes(self) -> None: diff --git a/github/Referrer.py b/github/Referrer.py index 354e2863b8..6ce6671b6d 100644 --- a/github/Referrer.py +++ b/github/Referrer.py @@ -43,7 +43,10 @@ class Referrer(NonCompletableGithubObject): """ This class represents a popylar Referrer for a GitHub repository. - The reference can be found here https://docs.github.com/en/rest/reference/repos#traffic + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#traffic + """ def _initAttributes(self) -> None: diff --git a/github/Repository.py b/github/Repository.py index dbc2be7250..94379fb258 100644 --- a/github/Repository.py +++ b/github/Repository.py @@ -302,7 +302,11 @@ class Repository(CompletableGithubObject): """ - This class represents Repositories. The reference can be found here https://docs.github.com/en/rest/reference/repos + This class represents Repositories. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos + """ def __repr__(self) -> str: @@ -1226,8 +1230,8 @@ def create_git_tag_and_release( generate_release_notes: bool = False, ) -> GitRelease: """ - Convenience function that calls :meth:`Repository.create_git_tag` and - :meth:`Repository.create_git_release`. + Convenience function that calls :meth:`Repository.create_git_tag` and :meth:`Repository.create_git_release`. + :param tag: string :param tag_message: string :param release_name: string @@ -1239,6 +1243,7 @@ def create_git_tag_and_release( :param prerelease: bool :param generate_release_notes: bool :rtype: :class:`github.GitRelease.GitRelease` + """ self.create_git_tag(tag, tag_message, object, type, tagger) return self.create_git_release( @@ -1716,7 +1721,7 @@ def create_secret(self, secret_name: str, unencrypted_value: str) -> github.Secr def get_secrets(self) -> PaginatedList[github.Secret.Secret]: """ - Gets all repository secrets + Gets all repository secrets. """ return PaginatedList( github.Secret.Secret, @@ -1764,8 +1769,7 @@ def create_variable(self, variable_name: str, value: str) -> github.Variable.Var def get_variables(self) -> PaginatedList[github.Variable.Variable]: """ - Gets all repository variables - :rtype: :class:`PaginatedList` of :class:`github.Variable.Variable` + Gets all repository variables :rtype: :class:`PaginatedList` of :class:`github.Variable.Variable` """ return PaginatedList( github.Variable.Variable, @@ -2350,18 +2354,23 @@ def create_file( committer: Opt[InputGitAuthor] = NotSet, author: Opt[InputGitAuthor] = NotSet, ) -> dict[str, ContentFile | Commit]: - """Create a file in this repository. + """ + Create a file in this repository. - :calls: `PUT /repos/{owner}/{repo}/contents/{path} `_ + :calls: `PUT /repos/{owner}/{repo}/contents/{path} `_ :param path: string, (required), path of the file in the repository :param message: string, (required), commit message :param content: string, (required), the actual data in the file - :param branch: string, (optional), branch to create the commit on. Defaults to the default branch of the repository - :param committer: InputGitAuthor, (optional), if no information is given the authenticated user's information will be used. You must specify both a name and email. - :param author: InputGitAuthor, (optional), if omitted this will be filled in with committer information. If passed, you must specify both a name and email. - :rtype: { - 'content': :class:`ContentFile `:, - 'commit': :class:`Commit `} + :param branch: string, (optional), branch to create the commit on. Defaults to the default branch of the + repository + :param committer: InputGitAuthor, (optional), if no information is given the authenticated user's information + will be used. You must specify both a name and email. + :param author: InputGitAuthor, (optional), if omitted this will be filled in with committer information. If + passed, you must specify both a name and email. + :rtype: { 'content': :class:`ContentFile `:, 'commit': :class:`Commit + `} + """ assert isinstance(path, str) assert isinstance(message, str) @@ -2427,19 +2436,23 @@ def update_file( committer: Opt[InputGitAuthor] = NotSet, author: Opt[InputGitAuthor] = NotSet, ) -> dict[str, ContentFile | Commit]: - """This method updates a file in a repository + """ + This method updates a file in a repository. - :calls: `PUT /repos/{owner}/{repo}/contents/{path} `_ + :calls: `PUT /repos/{owner}/{repo}/contents/{path} `_ :param path: string, Required. The content path. :param message: string, Required. The commit message. :param content: string, Required. The updated file content, either base64 encoded, or ready to be encoded. :param sha: string, Required. The blob SHA of the file being replaced. :param branch: string. The branch name. Default: the repository’s default branch (usually master) - :param committer: InputGitAuthor, (optional), if no information is given the authenticated user's information will be used. You must specify both a name and email. - :param author: InputGitAuthor, (optional), if omitted this will be filled in with committer information. If passed, you must specify both a name and email. - :rtype: { - 'content': :class:`ContentFile `:, - 'commit': :class:`Commit `} + :param committer: InputGitAuthor, (optional), if no information is given the authenticated user's information + will be used. You must specify both a name and email. + :param author: InputGitAuthor, (optional), if omitted this will be filled in with committer information. If + passed, you must specify both a name and email. + :rtype: { 'content': :class:`ContentFile `:, 'commit': :class:`Commit + `} + """ assert isinstance(path, str) assert isinstance(message, str) @@ -2482,18 +2495,21 @@ def delete_file( committer: Opt[InputGitAuthor] = NotSet, author: Opt[InputGitAuthor] = NotSet, ) -> dict[str, Commit | _NotSetType]: - """This method deletes a file in a repository + """ + This method deletes a file in a repository. - :calls: `DELETE /repos/{owner}/{repo}/contents/{path} `_ + :calls: `DELETE /repos/{owner}/{repo}/contents/{path} `_ :param path: string, Required. The content path. :param message: string, Required. The commit message. :param sha: string, Required. The blob SHA of the file being replaced. :param branch: string. The branch name. Default: the repository’s default branch (usually master) - :param committer: InputGitAuthor, (optional), if no information is given the authenticated user's information will be used. You must specify both a name and email. - :param author: InputGitAuthor, (optional), if omitted this will be filled in with committer information. If passed, you must specify both a name and email. - :rtype: { - 'content': :class:`null `:, - 'commit': :class:`Commit `} + :param committer: InputGitAuthor, (optional), if no information is given the authenticated user's information + will be used. You must specify both a name and email. + :param author: InputGitAuthor, (optional), if omitted this will be filled in with committer information. If + passed, you must specify both a name and email. + :rtype: { 'content': :class:`null `:, 'commit': :class:`Commit `} + """ assert isinstance(path, str), "path must be str/unicode object" assert isinstance(message, str), "message must be str/unicode object" diff --git a/github/RepositoryAdvisory.py b/github/RepositoryAdvisory.py index da43c464f1..09b55e8b97 100644 --- a/github/RepositoryAdvisory.py +++ b/github/RepositoryAdvisory.py @@ -45,7 +45,10 @@ class RepositoryAdvisory(AdvisoryBase): """ This class represents a RepositoryAdvisory. - The reference can be found here https://docs.github.com/en/rest/security-advisories/repository-advisories + + The reference can be found here + https://docs.github.com/en/rest/security-advisories/repository-advisories + """ def _initAttributes(self) -> None: @@ -148,8 +151,10 @@ def offer_credit( ) -> None: """ Offers credit to a user for a vulnerability in a repository. + Unless you are giving credit to yourself, the user having credit offered will need to explicitly accept the credit. :calls: `PATCH /repos/{owner}/{repo}/security-advisories/:advisory_id ` + """ self.offer_credits([{"login": login_or_user, "type": credit_type}]) @@ -159,9 +164,11 @@ def offer_credits( ) -> None: """ Offers credit to a list of users for a vulnerability in a repository. + Unless you are giving credit to yourself, the user having credit offered will need to explicitly accept the credit. :calls: `PATCH /repos/{owner}/{repo}/security-advisories/:advisory_id ` :param credited: iterable of dict with keys "login" and "type" + """ assert isinstance(credited, Iterable), credited for credit in credited: @@ -275,7 +282,9 @@ def edit( def accept_report(self) -> None: """ Accepts the advisory reported from an external reporter via private vulnerability reporting. + :calls: `PATCH /repos/{owner}/{repo}/security-advisories/:advisory_id ` + """ patch_parameters = {"state": "draft"} headers, data = self._requester.requestJsonAndCheck( @@ -288,7 +297,9 @@ def accept_report(self) -> None: def publish(self) -> None: """ Publishes the advisory. + :calls: `PATCH /repos/{owner}/{repo}/security-advisories/:advisory_id ` + """ patch_parameters = {"state": "published"} headers, data = self._requester.requestJsonAndCheck( @@ -301,7 +312,9 @@ def publish(self) -> None: def request_cve(self) -> None: """ Requests a CVE for the advisory. + :calls: `POST /repos/{owner}/{repo}/security-advisories/{ghsa_id}/cve `_ + """ self._requester.requestJsonAndCheck( "POST", @@ -311,7 +324,9 @@ def request_cve(self) -> None: def close(self) -> None: """ Closes the advisory. + :calls: `PATCH /repos/{owner}/{repo}/security-advisories/:advisory_id ` + """ patch_parameters = {"state": "closed"} headers, data = self._requester.requestJsonAndCheck( diff --git a/github/RepositoryKey.py b/github/RepositoryKey.py index 4156c2a740..ed690b7477 100644 --- a/github/RepositoryKey.py +++ b/github/RepositoryKey.py @@ -49,7 +49,11 @@ class RepositoryKey(CompletableGithubObject): """ - This class represents RepositoryKeys. The reference can be found here https://docs.github.com/en/rest/reference/repos#deploy-keys + This class represents RepositoryKeys. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#deploy-keys + """ def _initAttributes(self) -> None: diff --git a/github/RepositoryPreferences.py b/github/RepositoryPreferences.py index 6f89ecad9e..a76c689ec6 100644 --- a/github/RepositoryPreferences.py +++ b/github/RepositoryPreferences.py @@ -49,7 +49,10 @@ class RepositoryPreferences(NonCompletableGithubObject): """ This class represents repository preferences. - The reference can be found here https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#update-repository-preferences-for-check-suites + + The reference can be found here + https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#update-repository-preferences-for-check-suites + """ def _initAttributes(self) -> None: diff --git a/github/Requester.py b/github/Requester.py index ccff91ea6e..baa912e8b5 100644 --- a/github/Requester.py +++ b/github/Requester.py @@ -344,8 +344,7 @@ def NEW_DEBUG_FRAME(self, requestHeader: Dict[str, str]) -> None: def DEBUG_ON_RESPONSE(self, statusCode: int, responseHeader: Dict[str, Union[str, int]], data: str) -> None: """ - Update current frame with response - Current frame index will be attached to responseHeader + Update current frame with response Current frame index will be attached to responseHeader. """ if self.DEBUG_FLAG: # pragma no branch (Flag always set in tests) self._frameBuffer[self._frameCount][1:4] = [ @@ -483,9 +482,8 @@ def close(self) -> None: @property def kwargs(self) -> Dict[str, Any]: """ - Returns arguments required to recreate this Requester with Requester.__init__, as well as - with MainClass.__init__ and GithubIntegration.__init__. - :return: + Returns arguments required to recreate this Requester with Requester.__init__, as well as with + MainClass.__init__ and GithubIntegration.__init__. """ return dict( auth=self.__auth, @@ -519,8 +517,10 @@ def auth(self) -> Optional["Auth"]: def withAuth(self, auth: Optional["Auth"]) -> "Requester": """ Create a new requester instance with identical configuration but the given authentication method. + :param auth: authentication method :return: new Requester implementation + """ kwargs = self.kwargs kwargs.update(auth=auth) diff --git a/github/RequiredPullRequestReviews.py b/github/RequiredPullRequestReviews.py index 9d50279da7..ce5329fa87 100644 --- a/github/RequiredPullRequestReviews.py +++ b/github/RequiredPullRequestReviews.py @@ -54,7 +54,11 @@ class RequiredPullRequestReviews(CompletableGithubObject): """ - This class represents Required Pull Request Reviews. The reference can be found here https://docs.github.com/en/rest/reference/repos#get-pull-request-review-protection + This class represents Required Pull Request Reviews. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#get-pull-request-review-protection + """ def _initAttributes(self) -> None: diff --git a/github/RequiredStatusChecks.py b/github/RequiredStatusChecks.py index bc974025eb..7411a18c27 100644 --- a/github/RequiredStatusChecks.py +++ b/github/RequiredStatusChecks.py @@ -45,7 +45,11 @@ class RequiredStatusChecks(CompletableGithubObject): """ - This class represents Required Status Checks. The reference can be found here https://docs.github.com/en/rest/reference/repos#get-status-checks-protection + This class represents Required Status Checks. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#get-status-checks-protection + """ def _initAttributes(self) -> None: diff --git a/github/Secret.py b/github/Secret.py index f9f3f983f2..db48376980 100644 --- a/github/Secret.py +++ b/github/Secret.py @@ -43,7 +43,11 @@ class Secret(CompletableGithubObject): """ - This class represents a GitHub secret. The reference can be found here https://docs.github.com/en/rest/actions/secrets + This class represents a GitHub secret. + + The reference can be found here + https://docs.github.com/en/rest/actions/secrets + """ def _initAttributes(self) -> None: diff --git a/github/SelfHostedActionsRunner.py b/github/SelfHostedActionsRunner.py index eab164e031..1b08c64dd4 100644 --- a/github/SelfHostedActionsRunner.py +++ b/github/SelfHostedActionsRunner.py @@ -43,8 +43,11 @@ class SelfHostedActionsRunner(NonCompletableGithubObject): """ - This class represents Self-hosted GitHub Actions Runners. The reference can be found at + This class represents Self-hosted GitHub Actions Runners. + + The reference can be found at https://docs.github.com/en/free-pro-team@latest/rest/reference/actions#self-hosted-runners + """ def _initAttributes(self) -> None: diff --git a/github/SourceImport.py b/github/SourceImport.py index 470b71d0fd..56c1163b54 100644 --- a/github/SourceImport.py +++ b/github/SourceImport.py @@ -39,7 +39,11 @@ class SourceImport(CompletableGithubObject): """ - This class represents SourceImports. The reference can be found here https://docs.github.com/en/rest/reference/migrations#source-imports + This class represents SourceImports. + + The reference can be found here + https://docs.github.com/en/rest/reference/migrations#source-imports + """ def _initAttributes(self) -> None: diff --git a/github/Stargazer.py b/github/Stargazer.py index 229187780d..8038a2340a 100644 --- a/github/Stargazer.py +++ b/github/Stargazer.py @@ -52,7 +52,11 @@ class Stargazer(NonCompletableGithubObject): """ - This class represents Stargazers. The reference can be found here https://docs.github.com/en/rest/reference/activity#starring + This class represents Stargazers. + + The reference can be found here + https://docs.github.com/en/rest/reference/activity#starring + """ def _initAttributes(self) -> None: diff --git a/github/StatsCodeFrequency.py b/github/StatsCodeFrequency.py index cf39d81917..26872efcbb 100755 --- a/github/StatsCodeFrequency.py +++ b/github/StatsCodeFrequency.py @@ -44,7 +44,10 @@ class StatsCodeFrequency(NonCompletableGithubObject): """ This class represents statistics of StatsCodeFrequencies. - The reference can be found here https://docs.github.com/en/rest/metrics/statistics?apiVersion=2022-11-28#get-the-weekly-commit-activity + + The reference can be found here + https://docs.github.com/en/rest/metrics/statistics?apiVersion=2022-11-28#get-the-weekly-commit-activity + """ def _initAttributes(self) -> None: diff --git a/github/StatsCommitActivity.py b/github/StatsCommitActivity.py index 78569649f5..3fff35323b 100755 --- a/github/StatsCommitActivity.py +++ b/github/StatsCommitActivity.py @@ -43,7 +43,11 @@ class StatsCommitActivity(github.GithubObject.NonCompletableGithubObject): """ - This class represents StatsCommitActivities. The reference can be found here https://docs.github.com/en/rest/reference/repos#get-the-last-year-of-commit-activity + This class represents StatsCommitActivities. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#get-the-last-year-of-commit-activity + """ def _initAttributes(self) -> None: diff --git a/github/StatsContributor.py b/github/StatsContributor.py index 792824988f..f44434bc4d 100755 --- a/github/StatsContributor.py +++ b/github/StatsContributor.py @@ -44,7 +44,11 @@ class StatsContributor(NonCompletableGithubObject): """ - This class represents StatsContributors. The reference can be found here https://docs.github.com/en/rest/reference/repos#get-all-contributor-commit-activity + This class represents StatsContributors. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#get-all-contributor-commit-activity + """ class Week(NonCompletableGithubObject): diff --git a/github/StatsParticipation.py b/github/StatsParticipation.py index d87c2d6f5d..7297f3703d 100755 --- a/github/StatsParticipation.py +++ b/github/StatsParticipation.py @@ -44,7 +44,11 @@ class StatsParticipation(NonCompletableGithubObject): """ - This class represents StatsParticipations. The reference can be found here https://docs.github.com/en/rest/reference/repos#get-the-weekly-commit-count + This class represents StatsParticipations. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#get-the-weekly-commit-count + """ def _initAttributes(self) -> None: diff --git a/github/StatsPunchCard.py b/github/StatsPunchCard.py index adcf2c9fa9..1797458120 100755 --- a/github/StatsPunchCard.py +++ b/github/StatsPunchCard.py @@ -43,13 +43,19 @@ class StatsPunchCard(github.GithubObject.NonCompletableGithubObject): """ - This class represents StatsPunchCards. The reference can be found here https://docs.github.com/en/rest/reference/repos#get-the-hourly-commit-count-for-each-day + This class represents StatsPunchCards. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#get-the-hourly-commit-count-for-each-day + """ _dict: Dict[Tuple[int, int], int] def get(self, day: int, hour: int) -> int: - """Get a specific element""" + """ + Get a specific element. + """ return self._dict[(day, hour)] def _initAttributes(self) -> None: diff --git a/github/Tag.py b/github/Tag.py index 61e4e70868..9933b6a3d5 100644 --- a/github/Tag.py +++ b/github/Tag.py @@ -50,7 +50,11 @@ class Tag(NonCompletableGithubObject): """ - This class represents Tags. The reference can be found here https://docs.github.com/en/rest/reference/repos#list-repository-tags + This class represents Tags. + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#list-repository-tags + """ def __repr__(self) -> str: diff --git a/github/Team.py b/github/Team.py index f91ad24679..766ff741b2 100644 --- a/github/Team.py +++ b/github/Team.py @@ -86,7 +86,11 @@ class Team(CompletableGithubObject): """ - This class represents Teams. The reference can be found here https://docs.github.com/en/rest/reference/teams + This class represents Teams. + + The reference can be found here + https://docs.github.com/en/rest/reference/teams + """ def _initAttributes(self) -> None: diff --git a/github/TeamDiscussion.py b/github/TeamDiscussion.py index 5746b93d92..a61e922b61 100644 --- a/github/TeamDiscussion.py +++ b/github/TeamDiscussion.py @@ -52,7 +52,11 @@ class TeamDiscussion(CompletableGithubObject): """ - This class represents TeamDiscussions. The reference can be found here https://docs.github.com/en/rest/reference/teams#discussions + This class represents TeamDiscussions. + + The reference can be found here + https://docs.github.com/en/rest/reference/teams#discussions + """ def _initAttributes(self) -> None: diff --git a/github/TimelineEvent.py b/github/TimelineEvent.py index 252dc711a4..7894ce71ab 100644 --- a/github/TimelineEvent.py +++ b/github/TimelineEvent.py @@ -52,7 +52,11 @@ class TimelineEvent(NonCompletableGithubObject): """ - This class represents IssueTimelineEvents. The reference can be found here https://docs.github.com/en/rest/reference/issues#timeline + This class represents IssueTimelineEvents. + + The reference can be found here + https://docs.github.com/en/rest/reference/issues#timeline + """ def _initAttributes(self) -> None: diff --git a/github/TimelineEventSource.py b/github/TimelineEventSource.py index 5ec1ecddf3..c86c8ed88c 100644 --- a/github/TimelineEventSource.py +++ b/github/TimelineEventSource.py @@ -48,7 +48,11 @@ class TimelineEventSource(NonCompletableGithubObject): """ - This class represents IssueTimelineEventSource. The reference can be found here https://docs.github.com/en/rest/reference/issues#timeline + This class represents IssueTimelineEventSource. + + The reference can be found here + https://docs.github.com/en/rest/reference/issues#timeline + """ def _initAttributes(self) -> None: diff --git a/github/UserKey.py b/github/UserKey.py index ce08c1b6b9..9c5f64c97f 100644 --- a/github/UserKey.py +++ b/github/UserKey.py @@ -44,7 +44,11 @@ class UserKey(github.GithubObject.CompletableGithubObject): """ - This class represents UserKeys. The reference can be found here https://docs.github.com/en/rest/reference/users#keys + This class represents UserKeys. + + The reference can be found here + https://docs.github.com/en/rest/reference/users#keys + """ def _initAttributes(self) -> None: diff --git a/github/Variable.py b/github/Variable.py index 6c431758fb..8dcdcd0305 100644 --- a/github/Variable.py +++ b/github/Variable.py @@ -32,7 +32,11 @@ class Variable(CompletableGithubObject): """ - This class represents a GitHub variable. The reference can be found here https://docs.github.com/en/rest/actions/variables + This class represents a GitHub variable. + + The reference can be found here + https://docs.github.com/en/rest/actions/variables + """ def _initAttributes(self) -> None: diff --git a/github/View.py b/github/View.py index 75a43213f7..74dd10fb99 100644 --- a/github/View.py +++ b/github/View.py @@ -44,7 +44,10 @@ class View(NonCompletableGithubObject): """ This class represents a popular Path for a GitHub repository. - The reference can be found here https://docs.github.com/en/rest/reference/repos#traffic + + The reference can be found here + https://docs.github.com/en/rest/reference/repos#traffic + """ def _initAttributes(self) -> None: diff --git a/github/Workflow.py b/github/Workflow.py index 320cb0cb5a..2f6fa58e44 100644 --- a/github/Workflow.py +++ b/github/Workflow.py @@ -56,7 +56,11 @@ class Workflow(CompletableGithubObject): """ - This class represents Workflows. The reference can be found here https://docs.github.com/en/rest/reference/actions#workflows + This class represents Workflows. + + The reference can be found here + https://docs.github.com/en/rest/reference/actions#workflows + """ def _initAttributes(self) -> None: diff --git a/github/WorkflowJob.py b/github/WorkflowJob.py index f2826e4969..c81c0b1783 100644 --- a/github/WorkflowJob.py +++ b/github/WorkflowJob.py @@ -35,7 +35,11 @@ class WorkflowJob(CompletableGithubObject): """ - This class represents Workflow Jobs. The reference can be found here https://docs.github.com/en/rest/reference/actions#workflow-jobs + This class represents Workflow Jobs. + + The reference can be found here + https://docs.github.com/en/rest/reference/actions#workflow-jobs + """ def _initAttributes(self) -> None: diff --git a/github/WorkflowRun.py b/github/WorkflowRun.py index accd09f269..ecb3afcfd0 100644 --- a/github/WorkflowRun.py +++ b/github/WorkflowRun.py @@ -55,7 +55,11 @@ class TimingData(NamedTuple): class WorkflowRun(CompletableGithubObject): """ - This class represents Workflow Runs. The reference can be found here https://docs.github.com/en/rest/reference/actions#workflow-runs + This class represents Workflow Runs. + + The reference can be found here + https://docs.github.com/en/rest/reference/actions#workflow-runs + """ def _initAttributes(self) -> None: diff --git a/github/WorkflowStep.py b/github/WorkflowStep.py index 24b1a83e4b..92ad2553b0 100644 --- a/github/WorkflowStep.py +++ b/github/WorkflowStep.py @@ -44,7 +44,11 @@ class WorkflowStep(CompletableGithubObject): """ - This class represents steps in a Workflow Job. The reference can be found here https://docs.github.com/en/rest/reference/actions#workflow-jobs + This class represents steps in a Workflow Job. + + The reference can be found here + https://docs.github.com/en/rest/reference/actions#workflow-jobs + """ def _initAttributes(self) -> None: diff --git a/github/__init__.py b/github/__init__.py index c03d0de7c3..546f7a6542 100644 --- a/github/__init__.py +++ b/github/__init__.py @@ -37,13 +37,13 @@ # along with PyGithub. If not, see . # # # ################################################################################ - """ -The primary class you will instantiate is :class:`github.MainClass.Github`. -From its ``get_``, ``create_`` methods, you will obtain instances of all Github objects -like :class:`github.NamedUser.NamedUser` or :class:`github.Repository.Repository`. +The primary class you will instantiate is :class:`github.MainClass.Github`. From its ``get_``, ``create_`` methods, you +will obtain instances of all Github objects like :class:`github.NamedUser.NamedUser` or +:class:`github.Repository.Repository`. All classes inherit from :class:`github.GithubObject.GithubObject`. + """ import logging @@ -75,15 +75,15 @@ def set_log_level(level: int) -> None: """ - Set the log level of the github logger, e.g. set_log_level(logging.WARNING) - :param level: log level + Set the log level of the github logger, e.g. set_log_level(logging.WARNING) :param level: log level. """ logger.setLevel(level) def enable_console_debug_logging() -> None: # pragma no cover (Function useful only outside test environment) """ - This function sets up a very simple logging configuration (log everything on standard output) that is useful for troubleshooting. + This function sets up a very simple logging configuration (log everything on standard output) that is useful for + troubleshooting. """ set_log_level(logging.DEBUG) diff --git a/pyproject.toml b/pyproject.toml index 6dd151b79d..5960b2567e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -67,6 +67,15 @@ warn_no_return = false # https://github.com/psf/black line-length = 120 +[tool.docformatter] +recursive = true +# some docstring start with r""" +wrap-summaries = 119 +wrap-descriptions = 120 +blank = true +pre-summary-newline = true +make-summary-multi-line = true + [tool.codespell] skip = 'tests/*' quiet-level = 3 diff --git a/tests/GlobalAdvisory.py b/tests/GlobalAdvisory.py index 5b8a26579b..70d4b001f2 100644 --- a/tests/GlobalAdvisory.py +++ b/tests/GlobalAdvisory.py @@ -133,7 +133,9 @@ def testAttributes(self): self.assertEqual(self.advisory.withdrawn_at, None) def testNewlyReleased(self): - """Test an advisory that was freshly released and does not have values for all fields.""" + """ + Test an advisory that was freshly released and does not have values for all fields. + """ self.advisory = self.g.get_global_advisory("GHSA-cx3j-qqxj-9597") self.assertListKeyEqual( self.advisory.credits,