lazy-github 0.1__tar.gz

lazy_github-0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Christopher Chapline
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lazy_github-0.1/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.1
+Name: lazy-github
+Version: 0.1
+Summary: A terminal UI for interacting with Github
+Author-email: Chris Chapline <gizmo385@users.noreply.github.com>
+Maintainer-email: Chris Chapline <gizmo385@users.noreply.github.com>
+License: MIT License
+        
+        Copyright (c) 2024 Christopher Chapline
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyGithub
+Requires-Dist: httpx
+Requires-Dist: hishel
+Requires-Dist: pydantic
+Requires-Dist: textual
+Requires-Dist: textual-dev
+
+# LazyGithub
+
+This is a **WIP** terminal UI client for interacting with [GitHub](https://github.com). It draws heavy
+inspiration from the [lazygit](https://github.com/jesseduffield/lazygit) project and uses
+[Textual](https://textual.textualize.io/) to drive the terminal UI interactions. Currently, it
+supports the following:
+
+- Listing the repositories associated with your account 
+- Listing the issues and pull requests on those repositories
+- Listing the details, diff, and reviews on any of those pull requests
+
+Planned features:
+- Local caching, improving reload times and making it easier to use within a terminal or editor
+  environment.
+- A more wholeistic summary view for the currently selected repository
+- The ability to list, view, and trigger actions on a repository
+- More fleshed out PR interactions, including commenting and eventually submitting full PR reviews
+  from within your terminal.
+- Detailed issue views, including conversation participation
+
+
+## Running Locally
+
+I'm not currently automatically pushing LazyGithub up to [PyPi](https://pypi.org/) (although I plan
+to in the future), so for the time being you can run this locally via the `./start.sh` script.

lazy_github-0.1/README.md

@@ -0,0 +1,25 @@
+# LazyGithub
+
+This is a **WIP** terminal UI client for interacting with [GitHub](https://github.com). It draws heavy
+inspiration from the [lazygit](https://github.com/jesseduffield/lazygit) project and uses
+[Textual](https://textual.textualize.io/) to drive the terminal UI interactions. Currently, it
+supports the following:
+
+- Listing the repositories associated with your account 
+- Listing the issues and pull requests on those repositories
+- Listing the details, diff, and reviews on any of those pull requests
+
+Planned features:
+- Local caching, improving reload times and making it easier to use within a terminal or editor
+  environment.
+- A more wholeistic summary view for the currently selected repository
+- The ability to list, view, and trigger actions on a repository
+- More fleshed out PR interactions, including commenting and eventually submitting full PR reviews
+  from within your terminal.
+- Detailed issue views, including conversation participation
+
+
+## Running Locally
+
+I'm not currently automatically pushing LazyGithub up to [PyPi](https://pypi.org/) (although I plan
+to in the future), so for the time being you can run this locally via the `./start.sh` script.

lazy_github-0.1/lazy_github/__main__.py

@@ -0,0 +1,9 @@
+from lazy_github.ui.app import app
+
+
+def main():
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

lazy_github-0.1/lazy_github/lib/config.py

@@ -0,0 +1,66 @@
+import json
+from contextlib import contextmanager
+from datetime import timedelta
+from pathlib import Path
+from typing import Generator, List, Literal, Self
+
+from pydantic import BaseModel
+
+from lazy_github.lib.constants import CONFIG_FOLDER
+
+_CONFIG_FILE_LOCATION = CONFIG_FOLDER / "config.json"
+
+PR_STATE_FILTER = Literal["all"] | Literal["open"] | Literal["closed"]
+
+
+class ApiConfig(BaseModel):
+    base_url: str = "https://api.github.com"
+
+
+class PullRequestSettings(BaseModel):
+    state_filter: PR_STATE_FILTER = "all"
+
+
+class RepositorySettings(BaseModel):
+    favorites: List[str] = []
+
+
+class CacheSettings(BaseModel):
+    cache_directory: Path = CONFIG_FOLDER / ".cache"
+    default_ttl: int = int(timedelta(minutes=10).total_seconds())
+    list_repos_ttl: int = int(timedelta(days=1).total_seconds())
+    list_issues_ttl: int = int(timedelta(hours=1).total_seconds())
+
+
+class AppearenceSettings(BaseModel):
+    dark_mode: bool = True
+
+
+class Config(BaseModel):
+    appearence: AppearenceSettings = AppearenceSettings()
+    repositories: RepositorySettings = RepositorySettings()
+    pull_requests: PullRequestSettings = PullRequestSettings()
+    cache: CacheSettings = CacheSettings()
+    api: ApiConfig = ApiConfig()
+
+    @classmethod
+    def load_config(cls) -> Self:
+        if _CONFIG_FILE_LOCATION.exists():
+            return cls(**json.loads(_CONFIG_FILE_LOCATION.read_text()))
+        else:
+            return cls()
+
+    def save(self) -> None:
+        CONFIG_FOLDER.mkdir(parents=True, exist_ok=True)
+        _CONFIG_FILE_LOCATION.write_text(self.model_dump_json(indent=4))
+
+    @classmethod
+    @contextmanager
+    def to_edit(cls) -> Generator[Self, None, None]:
+        current_config = cls.load_config()
+        yield current_config
+        current_config.save()
+
+
+if __name__ == "__main__":
+    print(Config.load_config().model_dump_json(indent=4))

lazy_github-0.1/lazy_github/lib/constants.py

@@ -0,0 +1,27 @@
+from pathlib import Path
+
+# Content types
+DIFF_CONTENT_ACCEPT_TYPE = "application/vnd.github.diff"
+JSON_CONTENT_ACCEPT_TYPE = "application/vnd.github+json"
+
+# App access information
+LAZY_GITHUB_CLIENT_ID = "Iv23limdG8Bl3Cu5FOcT"
+DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code"
+
+# Symbols used in various UI tables
+IS_FAVORITED = "[green]★[/green]"
+IS_NOT_FAVORITED = "☆"
+IS_PRIVATE = "✔"
+IS_PUBLIC = "✘"
+
+CONFIG_FOLDER = Path.home() / ".config/lazy-github"
+
+
+def favorite_string(favorite: bool) -> str:
+    """Helper function to return the right string to indicate if something is favorited"""
+    return IS_FAVORITED if favorite else IS_NOT_FAVORITED
+
+
+def private_string(private: bool) -> str:
+    """Helper function to return the right string to indicate if something is private"""
+    return IS_PRIVATE if private else IS_PUBLIC

lazy_github-0.1/lazy_github/lib/github/auth.py

@@ -0,0 +1,101 @@
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+import httpx
+
+from lazy_github.lib.constants import CONFIG_FOLDER
+from lazy_github.lib.constants import DEVICE_CODE_GRANT_TYPE, LAZY_GITHUB_CLIENT_ID
+
+# Auth and client globals
+_AUTHENTICATION_CACHE_LOCATION = CONFIG_FOLDER / "auth.text"
+_AUTH_TOKEN: Optional[str] = None
+
+
+@dataclass
+class DeviceCodeResponse:
+    device_code: str
+    verification_uri: str
+    user_code: str
+    polling_interval: int
+    expires_at: int
+
+
+@dataclass
+class AccessTokenResponse:
+    token: Optional[str]
+    error: Optional[str]
+
+
+class GithubAuthenticationRequired(Exception):
+    pass
+
+
+async def get_device_code() -> DeviceCodeResponse:
+    """
+    Authenticates this device with the Github API. This will require the user to go enter the provided device code on
+    the Github UI to authenticate the LazyGithub app.
+    """
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            "https://github.com/login/device/code",
+            data={"client_id": LAZY_GITHUB_CLIENT_ID},
+            headers={"Accept": "application/json"},
+        )
+
+    response.raise_for_status()
+    body = response.json()
+    expires_at = time.time() + body["expires_in"]
+    return DeviceCodeResponse(
+        body["device_code"],
+        body["verification_uri"],
+        body["user_code"],
+        body["interval"],
+        expires_at,
+    )
+
+
+async def get_access_token(device_code: DeviceCodeResponse) -> AccessTokenResponse:
+    """Given a device code, retrieves the oauth access token that can be used to send requests to the GIthub API"""
+    async with httpx.AsyncClient() as client:
+        # TODO: This should specify an accept
+        access_token_res = await client.post(
+            "https://github.com/login/oauth/access_token",
+            data={
+                "client_id": LAZY_GITHUB_CLIENT_ID,
+                "grant_type": DEVICE_CODE_GRANT_TYPE,
+                "device_code": device_code.device_code,
+            },
+        )
+    access_token_res.raise_for_status()
+    pairs = access_token_res.text.split("&")
+    access_token_data = dict(pair.split("=") for pair in pairs)
+    return AccessTokenResponse(
+        access_token_data.get("access_token"),
+        access_token_data.get("error"),
+    )
+
+
+def save_access_token(access_token: AccessTokenResponse) -> None:
+    """Writes the returned access token to the config location"""
+    if not access_token.token:
+        raise ValueError("Invalid access token response! Cannot save")
+
+    # Create the parent directories for our cache if it's present
+    _AUTHENTICATION_CACHE_LOCATION.parent.mkdir(parents=True, exist_ok=True)
+    _AUTHENTICATION_CACHE_LOCATION.write_text(access_token.token)
+
+
+def token() -> str:
+    """
+    Helper function which loads the token from the file on disk. If the file does not exist, it raises a
+    GithubAuthenticationRequired exception that the caller should handle by triggering the auth flow
+    """
+    global _AUTH_TOKEN
+    if _AUTH_TOKEN is not None:
+        return _AUTH_TOKEN
+
+    if not _AUTHENTICATION_CACHE_LOCATION.exists():
+        raise GithubAuthenticationRequired()
+    _AUTH_TOKEN = _AUTHENTICATION_CACHE_LOCATION.read_text().strip()
+    return _AUTH_TOKEN

lazy_github-0.1/lazy_github/lib/github/client.py

@@ -0,0 +1,32 @@
+from typing import Optional
+
+import hishel
+
+from lazy_github.lib.config import Config
+from lazy_github.lib.constants import JSON_CONTENT_ACCEPT_TYPE
+from lazy_github.models.github import User
+
+
+class GithubClient(hishel.AsyncCacheClient):
+    def __init__(self, config: Config, access_token: str) -> None:
+        storage = hishel.AsyncFileStorage(base_path=config.cache.cache_directory)
+        super().__init__(storage=storage, base_url=config.api.base_url)
+        self.config = config
+        self.access_token = access_token
+        self._user: User | None = None
+
+    def headers_with_auth_accept(
+        self, accept: str = JSON_CONTENT_ACCEPT_TYPE, cache_duration: Optional[int] = None
+    ) -> dict[str, str]:
+        """Helper function to build a request with specific headers"""
+        headers = {"Accept": accept, "Authorization": f"Bearer {self.access_token}"}
+        max_age = cache_duration or self.config.cache.default_ttl
+        headers["Cache-Control"] = f"max-age={max_age}"
+        return headers
+
+    async def user(self) -> User:
+        """Returns the authed user for this client"""
+        if self._user is None:
+            response = await self.get("/user", headers=self.headers_with_auth_accept())
+            self._user = User(**response.json())
+        return self._user

lazy_github-0.1/lazy_github/lib/github/issues.py

@@ -0,0 +1,40 @@
+from functools import partial
+from typing import Literal
+
+from lazy_github.lib.github.client import GithubClient
+from lazy_github.models.github import Issue, IssueComment, PartialPullRequest, Repository
+
+IssueStateFilter = Literal["open"] | Literal["closed"] | Literal["all"]
+
+
+async def _list(client: GithubClient, repo: Repository, state: IssueStateFilter) -> list[Issue]:
+    query_params = {"state": state}
+    headers = client.headers_with_auth_accept(cache_duration=client.config.cache.list_issues_ttl)
+    response = await client.get(f"/repos/{repo.owner.login}/{repo.name}/issues", headers=headers, params=query_params)
+    response.raise_for_status()
+    result: list[Issue] = []
+    for issue in response.json():
+        if "draft" in issue:
+            result.append(PartialPullRequest(**issue, repo=repo))
+        else:
+            result.append(Issue(**issue, repo=repo))
+    return result
+
+
+list_open_issues = partial(_list, state="open")
+list_closed_issues = partial(_list, state="closed")
+list_all_issues = partial(_list, state="all")
+
+
+async def get_comments(client: GithubClient, issue: Issue) -> list:
+    response = await client.get(issue.comments_url, headers=client.headers_with_auth_accept())
+    response.raise_for_status()
+    return response.json()
+
+
+async def create_comment(client: GithubClient, repo: Repository, issue: Issue, comment_body: str) -> IssueComment:
+    url = f"/repos/{repo.owner.login}/{repo.name}/issues/{issue.number}/comments"
+    body = {"body": comment_body}
+    response = await client.post(url, json=body, headers=client.headers_with_auth_accept())
+    response.raise_for_status()
+    return IssueComment(**response.json())

lazy_github-0.1/lazy_github/lib/github/pull_requests.py

@@ -0,0 +1,111 @@
+from lazy_github.lib.github.client import GithubClient
+from lazy_github.lib.constants import DIFF_CONTENT_ACCEPT_TYPE
+from lazy_github.lib.github.issues import list_all_issues
+from lazy_github.models.github import (
+    FullPullRequest,
+    Issue,
+    PartialPullRequest,
+    Repository,
+    Review,
+    ReviewComment,
+)
+
+
+async def list_for_repo(client: GithubClient, repo: Repository) -> list[PartialPullRequest]:
+    """Lists the pull requests associated with the specified repo"""
+    issues = await list_all_issues(client, repo)
+    return [i for i in issues if isinstance(i, PartialPullRequest)]
+
+
+async def get_full_pull_request(client: GithubClient, partial_pr: PartialPullRequest) -> FullPullRequest:
+    """Converts a partial pull request into a full pull request"""
+    user = await client.user()
+    url = f"/repos/{user.login}/{partial_pr.repo.name}/pulls/{partial_pr.number}"
+    response = await client.get(url, headers=client.headers_with_auth_accept())
+    response.raise_for_status()
+    return FullPullRequest(**response.json(), repo=partial_pr.repo)
+
+
+async def get_diff(client: GithubClient, pr: FullPullRequest) -> str:
+    """Fetches the raw diff for an individual pull request"""
+    headers = client.headers_with_auth_accept(DIFF_CONTENT_ACCEPT_TYPE)
+    response = await client.get(pr.diff_url, headers=headers, follow_redirects=True)
+    response.raise_for_status()
+    return response.text
+
+
+async def get_review_comments(client: GithubClient, pr: FullPullRequest, review: Review) -> list[ReviewComment]:
+    user = await client.user()
+    url = f"/repos/{user.login}/{pr.repo.name}/pulls/{pr.number}/reviews/{review.id}/comments"
+    response = await client.get(url, headers=client.headers_with_auth_accept())
+    response.raise_for_status()
+    return [ReviewComment(**c) for c in response.json()]
+
+
+async def get_reviews(client: GithubClient, pr: FullPullRequest, with_comments: bool = True) -> list[Review]:
+    user = await client.user()
+    url = url = f"/repos/{user.login}/{pr.repo.name}/pulls/{pr.number}/reviews"
+    response = await client.get(url, headers=client.headers_with_auth_accept())
+    response.raise_for_status()
+    reviews: list[Review] = []
+    for raw_review in response.json():
+        review = Review(**raw_review)
+        if with_comments:
+            review.comments = await get_review_comments(client, pr, review)
+        reviews.append(review)
+    return reviews
+
+
+async def reply_to_review_comment(
+    client: GithubClient, repo: Repository, issue: Issue, comment: ReviewComment, comment_body: str
+) -> ReviewComment:
+    url = f"/repos/{repo.owner.login}/{repo.name}/pulls/{issue.number}/comments/{comment.id}/replies"
+    response = await client.post(url, headers=client.headers_with_auth_accept(), json={"body": comment_body})
+    response.raise_for_status()
+    return ReviewComment(**response.json())
+
+
+class ReviewCommentNode:
+    def __init__(self, comment: ReviewComment) -> None:
+        self.children: list["ReviewCommentNode"] = []
+        self.comment = comment
+
+
+def reconstruct_review_conversation_hierarchy(reviews: list[Review]) -> dict[int, ReviewCommentNode]:
+    """
+    Given a list of PR reviews, this rebuilds a the comment hierarchy as a tree of connected comment nodes. The return
+    value of this function is a mapping between the comment IDs and the associated ReviewCommentNode for the top level
+    comments ONLY. Any subsequent comments will be included as children in one of the review comment nodes.
+
+    An important disclaimer is that this function does NOT take into account the body associated with the review itself,
+    which is present in some reviews. When generating UI from this function, the body of review itself should be
+    included prior to printing the review comments themselves.
+
+    Given a variable `hierarchy` generated from a list `reviews` of PR reviews, the output of this can be properly
+    unpacked like so:
+    ```python
+    for review in reviews:
+        if review.body:
+            # Output the root review body
+            print(review.body)
+
+            # Output the review comments that are top level (i.e. their ids are in the hierarchy map)
+            for comment in review.comments:
+                if comment.id in hierarchy:
+                    # Call
+                    comment_review_node_handler(hierarchy[comment.id])
+    ```
+    """
+    comment_nodes_by_review_id: dict[int, ReviewCommentNode] = {}
+    # Create review nodes for all of the comments in each of the reviews
+    for review in reviews:
+        for comment in review.comments:
+            comment_nodes_by_review_id[comment.id] = ReviewCommentNode(comment)
+
+    # Build a tree that represents the conversational flow between individual comments in the threads
+    for review_node in comment_nodes_by_review_id.values():
+        in_reply_to_id = review_node.comment.in_reply_to_id
+        if in_reply_to_id is not None and in_reply_to_id in comment_nodes_by_review_id:
+            comment_nodes_by_review_id[in_reply_to_id].children.append(review_node)
+
+    return {r.comment.id: r for r in comment_nodes_by_review_id.values() if r.comment.in_reply_to_id is None}

lazy_github-0.1/lazy_github/lib/github/repositories.py

@@ -0,0 +1,30 @@
+from functools import partial
+from typing import Literal
+
+from lazy_github.lib.github.client import GithubClient
+from lazy_github.models.github import Repository
+
+RepoTypeFilter = Literal["all"] | Literal["owner"] | Literal["member"]
+SortDirection = Literal["asc"] | Literal["desc"]
+RepositorySortKey = Literal["created"] | Literal["updated"] | Literal["pushed"] | Literal["full_name"]
+
+
+async def _list(
+    client: GithubClient,
+    repo_types: RepoTypeFilter,
+    sort: RepositorySortKey = "full_name",
+    direction: SortDirection = "asc",
+    page: int = 1,
+    per_page: int = 50,
+) -> list[Repository]:
+    """Retrieves Github repos matching the specified criteria"""
+    headers = client.headers_with_auth_accept(cache_duration=client.config.cache.list_repos_ttl)
+    query_params = {"type": repo_types, "direction": direction, "sort": sort, "page": page, "per_page": per_page}
+    response = await client.get("/user/repos", headers=headers, params=query_params)
+    response.raise_for_status()
+    return [Repository(**r) for r in response.json()]
+
+
+list_all = partial(_list, repo_types="all")
+list_owned = partial(_list, repo_types="owner")
+list_member_of = partial(_list, repo_types="member")

lazy_github-0.1/lazy_github/lib/messages.py

@@ -0,0 +1,51 @@
+from functools import cached_property
+
+from textual.message import Message
+
+from lazy_github.models.github import Issue, PartialPullRequest, Repository
+
+
+class RepoSelected(Message):
+    """
+    A message indicating that a particular user repo has been selected.
+
+    This message is used to trigger follow-up contextual actions based on the selected repo, such as loading pull
+    requests, issues, actions, etc.
+    """
+
+    def __init__(self, repo: Repository) -> None:
+        self.repo = repo
+        super().__init__()
+
+
+class PullRequestSelected(Message):
+    """
+    A message indicating that the user is looking for additional information on a particular pull request.
+    """
+
+    def __init__(self, pr: PartialPullRequest) -> None:
+        self.pr = pr
+        super().__init__()
+
+
+class IssuesAndPullRequestsFetched(Message):
+    """
+    Since issues and pull requests are both represented on the Github API as issues, we want to pull issues once and
+    then send that message to both sections of the UI.
+    """
+
+    def __init__(self, issues_and_pull_requests: list[Issue]) -> None:
+        self.issues_and_pull_requests = issues_and_pull_requests
+        super().__init__()
+
+    @cached_property
+    def pull_requests(self) -> list[PartialPullRequest]:
+        return [pr for pr in self.issues_and_pull_requests if isinstance(pr, PartialPullRequest)]
+
+    @cached_property
+    def issues(self) -> list[Issue]:
+        return [
+            issue
+            for issue in self.issues_and_pull_requests
+            if isinstance(issue, Issue) and not isinstance(issue, PartialPullRequest)
+        ]

lazy_github-0.1/lazy_github/lib/string_utils.py

@@ -0,0 +1,16 @@
+def pluralize(count: int, singular: str, plural: str):
+    """
+    Helper function for correctly pluralizing strings in the UI. This is simple but gets messy when written many times
+    across the UI code.
+    """
+    return f"{count} {singular}" if count == 1 else f"{count} {plural}"
+
+
+def bold(s: str) -> str:
+    """Wraps the given text in Rich bold tags"""
+    return f"[bold]{s}[/bold]"
+
+
+def link(link_text: str, url: str) -> str:
+    """Formats a link in Rich-style markup"""
+    return f"[link={url}]{link_text}[/link]"