Merge branch 'main' into action-secrets

.github/pull_request_template.md

@@ -12,7 +12,7 @@ Please provide:
 
 - The version of pip you used to install github3.py
 
-- The version of github3.py, requests, uritemplate, and dateutil installed
+- The version of github3.py, requests, uritemplate, and python-dateutil installed
 
 ## Minimum Reproducible Example
 

.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+---
+name: Check documentation
+
+"on":
+  schedule:
+    - cron: "0 1 * * *" # everyday at 1am
+  push:
+    paths:
+      - "**.rst"
+      - "docs/**"
+  pull_request:
+    paths:
+      - "**.rst"
+      - "docs/**"
+
+jobs:
+  docs:
+    name: Build documentation & check links
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+
+      - name: Upgrade pip
+        run: |
+          pip install -U pip
+          pip --version
+
+      - name: Install Tox
+        run: |
+          pip install tox
+          tox --version
+
+      - name: Build documentation
+        run: tox
+        env:
+          TOXENV: docs
+
+      - name: Upload documentation
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: docs/build

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.6.0
     hooks:
     - id: check-added-large-files
     - id: check-toml
@@ -13,31 +13,33 @@ repos:
     - id: trailing-whitespace
       types: [text]
       stages: [commit, push, manual]
-  - repo: https://github.com/asottile/reorder-python-imports
-    rev: v3.10.0
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.13.2
     hooks:
-    - id: reorder-python-imports
-      args: [--application-directories, '.:src', --py37-plus]
+    - id: isort
   - repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 24.4.0
     hooks:
     - id: black
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.7.0
+    rev: v3.15.2
     hooks:
     - id: pyupgrade
       args: [--py37-plus]
-  #- repo: https://github.com/pre-commit/mirrors-mypy
-  #  rev: v0.910
-  #  hooks:
-  #  - id: mypy
-  #    exclude: ^(docs/|tests/)
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.9.0
+    hooks:
+    - id: mypy
+      additional_dependencies:
+      - types-python-dateutil
+      - types-requests
+      exclude: ^(docs/|tests/)
   - repo: https://github.com/jorisroovers/gitlint
     rev: v0.19.1
     hooks:
     - id: gitlint
   - repo: https://github.com/asottile/setup-cfg-fmt
-    rev: v2.3.0
+    rev: v2.5.0
     hooks:
     - id: setup-cfg-fmt
       args: [--min-py3-version, '3.7']

.readthedocs.yml

@@ -0,0 +1,12 @@
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+sphinx:
+  configuration: docs/source/conf.py
+formats: all
+python:
+  install:
+    - requirements: docs/source/requirements.txt
+    - path: .

AUTHORS.rst

@@ -224,3 +224,5 @@ Contributors
 - Chris R (@offbyone)
 
 - Thomas Buchner (@MrBatschner)
+
+- Chris Cotter (@ccotter)

docs/source/requirements.txt

@@ -1,2 +1,3 @@
 sphinx>=4.2.0
 docutils!=0.18
+sphinx_rtd_theme

pyproject.toml

@@ -70,7 +70,6 @@ Source = "https://github.com/sigmavirus24/github3.py"
 [tool.black]
 line-length = 78
 target-version = ['py37']
-safe = true
 exclude = '''
 (
   /(
@@ -83,6 +82,19 @@ exclude = '''
     | _build
     | build
     | dist
+    | venv
   )/
 )
 '''
+
+[tool.mypy]
+files = ["."]
+exclude = [
+    "^docs/",
+    "^tests/",
+]
+
+[tool.isort]
+profile = "black"
+line_length = 78
+force_single_line = true

src/github3/__about__.py

@@ -1,4 +1,5 @@
 """The module that holds much of the metadata about github3.py."""
+
 __package_name__ = "github3.py"
 __title__ = "github3"
 __author__ = "Ian Stapleton Cordasco"

src/github3/__init__.py

@@ -8,6 +8,7 @@
 :license: Modified BSD, see LICENSE for more details
 
 """
+
 from .__about__ import __author__
 from .__about__ import __author_email__
 from .__about__ import __copyright__

src/github3/api.py

@@ -6,6 +6,7 @@
 :license: Modified BSD, see LICENSE for more details
 
 """
+
 from .github import GitHub
 from .github import GitHubEnterprise
 

src/github3/apps.py

@@ -2,6 +2,7 @@
 
 https://developer.github.com/apps/building-github-apps/
 """
+
 import time
 
 import jwt

src/github3/auths.py

@@ -1,4 +1,5 @@
 """This module contains the Authorization object."""
+
 from .decorators import requires_basic_auth
 from .models import GitHubCore
 

src/github3/checks.py

@@ -1,4 +1,5 @@
 """This module contains all the classes relating to Checks."""
+
 from json import dumps
 
 from . import decorators
@@ -45,7 +46,7 @@ def _update_attributes(self, pull):
     def _repr(self):
         return f"<CheckPullRequest [#{self.number}]>"
 
-    def to_pull(self):
+    def to_pull(self, conditional: bool = False):
         """Retrieve a full PullRequest object for this CheckPullRequest.
 
         :returns:
@@ -119,7 +120,7 @@ def _repr(self):
             self.name, str(self.owner["login"])
         )
 
-    def to_app(self):
+    def to_app(self, conditional: bool = False) -> models.GitHubCore:
         """Retrieve a full App object for this CheckApp.
 
         :returns:

src/github3/decorators.py

@@ -1,4 +1,5 @@
 """This module provides decorators to the rest of the library."""
+
 import os
 from functools import wraps
 from io import BytesIO as StringIO

src/github3/events.py

@@ -1,4 +1,5 @@
 """This module contains the classes related to Events."""
+
 import copy
 
 from . import models
@@ -41,7 +42,7 @@ def _update_attributes(self, user):
         self.login = user["login"]
         self._api = self.url = user["url"]
 
-    def to_user(self):
+    def to_user(self, conditional: bool = False) -> models.GitHubCore:
         """Retrieve a full User object for this EventUser.
 
         :returns:
@@ -93,7 +94,7 @@ def _update_attributes(self, org):
         self.login = org["login"]
         self._api = self.url = org["url"]
 
-    def to_org(self):
+    def to_org(self, conditional: bool = False) -> models.GitHubCore:
         """Retrieve a full Organization object for this EventOrganization.
 
         :returns:
@@ -148,7 +149,7 @@ def _update_attributes(self, pull):
         self.locked = pull["locked"]
         self._api = self.url = pull["url"]
 
-    def to_pull(self):
+    def to_pull(self, conditional: bool = False) -> models.GitHubCore:
         """Retrieve a full PullRequest object for this EventPullRequest.
 
         :returns:
@@ -258,7 +259,9 @@ def _update_attributes(self, comment):
         self.updated_at = self._strptime(comment["updated_at"])
         self.user = users.ShortUser(comment["user"], self)
 
-    def to_review_comment(self):
+    def to_review_comment(
+        self, conditional: bool = False
+    ) -> models.GitHubCore:
         """Retrieve a full ReviewComment object for this EventReviewComment.
 
         :returns:
@@ -269,7 +272,7 @@ def to_review_comment(self):
         from . import pulls
 
         comment = self._json(self._get(self._api), 200)
-        return pulls.ReviewComment(comment, self)
+        return pulls.ReviewComment(comment, self.session)
 
     refresh = to_review_comment
 
@@ -285,7 +288,7 @@ def _update_attributes(self, issue):
         self.locked = issue["locked"]
         self._api = self.url = issue["url"]
 
-    def to_issue(self):
+    def to_issue(self, conditional: bool = False) -> models.GitHubCore:
         """Retrieve a full Issue object for this EventIssue."""
         from . import issues
 
@@ -352,7 +355,9 @@ def _update_attributes(self, comment):
         self.updated_at = self._strptime(comment["updated_at"])
         self.user = users.ShortUser(comment["user"], self)
 
-    def to_issue_comment(self):
+    def to_issue_comment(
+        self, conditional: bool = False
+    ) -> models.GitHubCore:
         """Retrieve the full IssueComment object for this comment.
 
         :returns:

src/github3/gists/__init__.py

@@ -12,6 +12,7 @@
 
 See also: http://developer.github.com/v3/gists/
 """
+
 from .gist import Gist
 from .gist import ShortGist
 

src/github3/gists/comment.py

@@ -1,4 +1,5 @@
 """Module containing the logic for a GistComment."""
+
 from .. import decorators
 from .. import models
 from .. import users

src/github3/gists/file.py

@@ -1,4 +1,5 @@
 """Module containing the GistFile object."""
+
 from .. import models
 
 

src/github3/gists/gist.py

@@ -1,12 +1,14 @@
 """This module contains the Gist, ShortGist, and GistFork objects."""
+
+import typing as t
 from json import dumps
 
-from . import comment
-from . import file as gistfile
-from . import history
 from .. import models
 from .. import users
 from ..decorators import requires_auth
+from . import comment
+from . import file as gistfile
+from . import history
 
 
 class _Gist(models.GitHubCore):
@@ -31,7 +33,9 @@ class _Gist(models.GitHubCore):
     """
 
     class_name = "_Gist"
-    _file_class = gistfile.ShortGistFile
+    _file_class: t.Type[
+        t.Union[gistfile.ShortGistFile, gistfile.GistFile]
+    ] = gistfile.ShortGistFile
 
     def _update_attributes(self, gist):
         self.comments_count = gist["comments"]
@@ -265,7 +269,7 @@ def _update_attributes(self, fork):
     def _repr(self):
         return f"<GistFork [{self.id}]>"
 
-    def to_gist(self):
+    def to_gist(self, conditional: bool = False) -> models.GitHubCore:
         """Retrieve the full Gist representation of this fork.
 
         :returns:

src/github3/gists/history.py

@@ -1,4 +1,5 @@
 """Module containing the GistHistory object."""
+
 from .. import models
 from .. import users
 
@@ -51,7 +52,7 @@ class GistHistory(models.GitHubCore):
     def _update_attributes(self, history) -> None:
         self.url = self._api = history["url"]
         self.version = history["version"]
-        self.user = users.ShortUser(history["user"], self)
+        self.user = users.ShortUser(history["user"], self.session)
         self.change_status = history["change_status"]
         self.additions = self.change_status.get("additions")
         self.deletions = self.change_status.get("deletions")