allow for passing Installation instance to GitHub API clients (#30)

Author: joshuadavidthomas

CHANGELOG.md

@@ -18,6 +18,10 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ## [Unreleased]
 
+### Changed
+
+- `AsyncGitHubAPI` and `SyncGitHubAPI` clients can now take an instance of `Installation` using the `installation` kwarg, in addition to the previous behavior of providing the `installation_id`. One or the other must be used for authenticated requests, not both.
+
 ## [0.3.0]
 
 ### Added

README.md

@@ -266,6 +266,14 @@ async def create_comment(repo_full_name: str):
             f"/repos/{repo_full_name}/issues/1/comments",
             data={"body": "Hello!"}
         )
+    
+    # You can either provide the `installation_id` as above, or the `Installation` instance
+    # itself
+    async with AsyncGitHubAPI(installation=installation) as gh:
+        await gh.post(
+            f"/repos/{repo_full_name}/issues/1/comments",
+            data={"body": "World!"}
+        )
 ```
 
 #### `SyncGitHubAPI`
@@ -291,6 +299,14 @@ def create_comment_sync(repo_full_name: str):
             f"/repos/{repo_full_name}/issues/1/comments",
             data={"body": "Hello!"}
         )
+
+    # You can either provide the `installation_id` as above, or the `Installation` instance
+    # itself
+    with SyncGitHubAPI(installation=installation) as gh:
+        gh.post(
+            f"/repos/{repo_full_name}/issues/1/comments",
+            data={"body": "World!"}
+        )
 ```
 
 ### Models

src/django_github_app/github.py

@@ -6,6 +6,7 @@
 from dataclasses import dataclass
 from enum import Enum
 from types import TracebackType
+from typing import TYPE_CHECKING
 from typing import Any
 from urllib.parse import urlencode
 
@@ -20,6 +21,9 @@
 from ._sync import async_to_sync_method
 from ._typing import override
 
+if TYPE_CHECKING:
+    from .models import Installation
+
 cache: cachetools.LRUCache[Any, Any] = cachetools.LRUCache(maxsize=500)
 # need to create an ssl_context in the main thread, see:
 # - https://github.com/pallets/flask/discussions/5387#discussioncomment-10835348
@@ -32,24 +36,31 @@ class AsyncGitHubAPI(gh_abc.GitHubAPI):
     def __init__(
         self,
         *args: Any,
+        installation: Installation | None = None,
         installation_id: int | None = None,
         **kwargs: Any,
     ) -> None:
+        if installation is not None and installation_id is not None:
+            raise ValueError("Must use only one of installation or installation_id")
+
+        self.installation = installation
         self.installation_id = installation_id
+        self.oauth_token = None
         self._client = httpx.AsyncClient(verify=ssl_context)
         super().__init__(*args, cache=cache, **kwargs)
 
     async def __aenter__(self) -> AsyncGitHubAPI:
         from .models import Installation
 
-        if self.installation_id:
+        if self.installation or self.installation_id:
             try:
-                installation = await Installation.objects.aget(
+                installation = self.installation or await Installation.objects.aget(
                     installation_id=self.installation_id
                 )
                 self.oauth_token = await installation.aget_access_token(self)
             except (Installation.DoesNotExist, gidgethub.BadRequest):
-                self.oauth_token = None
+                pass
+
         return self
 
     async def __aexit__(

tests/test_github.py

@@ -13,14 +13,35 @@
 @pytest.mark.asyncio
 @pytest.mark.django_db
 class TestAsyncGitHubAPI:
+    async def test_init_with_two_installation_kwargs(self, ainstallation):
+        installation = await ainstallation
+
+        with pytest.raises(ValueError):
+            AsyncGitHubAPI(
+                "test",
+                installation=installation,
+                installation_id=installation.installation_id,
+            )
+
     async def test_request(self, httpx_mock):
         httpx_mock.add_response(json={"foo": "bar"})
 
         async with AsyncGitHubAPI("test") as gh:
             response = await gh.getitem("/foo")
             assert response == {"foo": "bar"}
 
-    async def test_oauth_token(self, ainstallation, monkeypatch):
+    async def test_oauth_token_installation(self, ainstallation, monkeypatch):
+        async def mock_aget_access_token(*args, **kwargs):
+            return "ABC123"
+
+        monkeypatch.setattr(Installation, "aget_access_token", mock_aget_access_token)
+
+        installation = await ainstallation
+
+        async with AsyncGitHubAPI("test", installation=installation) as gh:
+            assert gh.oauth_token == "ABC123"
+
+    async def test_oauth_token_installation_id(self, ainstallation, monkeypatch):
         async def mock_aget_access_token(*args, **kwargs):
             return "ABC123"
 
@@ -37,7 +58,7 @@ async def test_oauth_token_installation_doesnotexist(self):
         async with AsyncGitHubAPI("test", installation_id=1234) as gh:
             assert gh.oauth_token is None
 
-    async def test_oauth_token_no_installation_id(self):
+    async def test_oauth_token_no_kwargs(self):
         async with AsyncGitHubAPI("test") as gh:
             assert gh.oauth_token is None
 
@@ -52,7 +73,42 @@ async def test_sleep(self):
         assert (stop - start) > datetime.timedelta(seconds=delay)
 
 
+@pytest.mark.django_db
 class TestSyncGitHubAPI:
+    def test_init_with_two_installation_kwargs(self, installation):
+        with pytest.raises(ValueError):
+            SyncGitHubAPI(
+                "test",
+                installation=installation,
+                installation_id=installation.installation_id,
+            )
+
+    def test_oauth_token_installation(self, installation, monkeypatch):
+        async def mock_aget_access_token(*args, **kwargs):
+            return "ABC123"
+
+        monkeypatch.setattr(Installation, "aget_access_token", mock_aget_access_token)
+
+        with SyncGitHubAPI("test", installation=installation) as gh:
+            assert gh.oauth_token == "ABC123"
+
+    def test_oauth_token_installation_id(self, installation, monkeypatch):
+        async def mock_aget_access_token(*args, **kwargs):
+            return "ABC123"
+
+        monkeypatch.setattr(Installation, "aget_access_token", mock_aget_access_token)
+
+        with SyncGitHubAPI("test", installation_id=installation.installation_id) as gh:
+            assert gh.oauth_token == "ABC123"
+
+    def test_oauth_token_installation_doesnotexist(self):
+        with SyncGitHubAPI("test", installation_id=1234) as gh:
+            assert gh.oauth_token is None
+
+    def test_oauth_token_no_kwargs(self):
+        with SyncGitHubAPI("test") as gh:
+            assert gh.oauth_token is None
+
     def test_getitem(self, httpx_mock):
         httpx_mock.add_response(json={"foo": "bar"})