Update doc strings

Author: jessemyers-lettuce

src/bot/cli.py

@@ -48,6 +48,7 @@ def read(
     repo_path: Path,
     sha: str,
 ) -> None:
+    """Read a commit from a local git repo and print it."""
     repo = read_repo(repo_path)
     commit = read_commit(repo, sha)
 
@@ -100,6 +101,7 @@ def write(
     repo_path: Path,
     ref: str,
 ) -> None:
+    """Read a commit from a local git repo and write it to GitHub."""
     basic_config(level=INFO)
 
     repo = read_repo(repo_path)

src/bot/local.py

@@ -13,12 +13,17 @@
 
 
 def extract_repo_name(repo: Repo, remote: str = "origin") -> str:
+    """Extract the GitHub organization and repository name.
+
+    Assumes that the local repo has an appropriately configured remote named `origin`.
+    """
     origin = repo.remote("origin")
     parsed_url = urlparse(origin.url)
     return parsed_url.path.rsplit(":", 1)[-1].removesuffix(".git")
 
 
 def iter_blobs(item: Diff) -> Generator[BlobDTO, None, None]:
+    """Iterate through diff items and produce blobs."""
     match (item.change_type):
         case "A":
             # File added
@@ -80,7 +85,17 @@ def iter_blobs(item: Diff) -> Generator[BlobDTO, None, None]:
 
 
 def build_trees(blobs: list[BlobDTO]) -> TreeDTO:
-    """Build the tree structure from a list of blobs."""
+    """Build the tree structure from a list of blobs.
+
+    Technically, this function is not needed because the GitHub API supports
+    creating a nested tree in a single operation (and we use this feature).
+
+    However, this API detail was not obvious from documentation so the original
+    implementation created trees recursively and the DTOs still reflect this
+    possibility. Since these DTOs are more-or-less faithful to git's own object
+    model, removing the `Tree` structure would make the DTOs a bit less clear,
+    even if it removed a step.
+    """
     trees: dict[Path, TreeDTO] = {}
 
     # Create the root tree
@@ -108,6 +123,7 @@ def build_trees(blobs: list[BlobDTO]) -> TreeDTO:
 
 
 def find_parent(commit: Commit) -> Commit:
+    """Find the parent of a commit."""
     if not commit.parents:
         raise ValueError("Cannot create a repo's initial commit.")
 
@@ -118,17 +134,20 @@ def find_parent(commit: Commit) -> Commit:
 
 
 def extract_message(commit: Commit) -> str:
+    """Extract the commit message of a commit."""
     if isinstance(commit.message, str):
         return commit.message
     else:
         return commit.message.decode("utf-8")
 
 
 def read_repo(repo_path: Path) -> Repo:
+    """Read a repo from a path."""
     return Repo(repo_path)
 
 
 def read_commit(repo: Repo, ref: str) -> CommitDTO:
+    """Read a local commit into a DTO representaiton."""
     # Find the commit at the given ref in the local repo.
     commit = repo.commit(ref)
 

src/bot/remote.py

@@ -13,14 +13,17 @@
 
 
 def authenticate_app(app_id: int, private_key: str) -> Github:
+    """Create a Github instance with for a GitHub app (bot)."""
     auth = AppAuth(app_id, private_key)
     integration = GithubIntegration(auth=auth)
     installation = integration.get_installations()[0]
     return installation.get_github_for_installation()  # type: ignore
 
 
 def make_tree_blob_element(blob: Blob) -> InputGitTreeElement:
+    """Create a tree element for a blob."""
     if blob.sha:
+        # Add
         with blob.path.open() as infile:
             return InputGitTreeElement(
                 path=str(blob.path),
@@ -29,6 +32,7 @@ def make_tree_blob_element(blob: Blob) -> InputGitTreeElement:
                 content=infile.read(),
             )
     else:
+        # Remove
         return InputGitTreeElement(
             path=str(blob.path),
             mode=Mode.FILE.value,
@@ -38,6 +42,7 @@ def make_tree_blob_element(blob: Blob) -> InputGitTreeElement:
 
 
 def iter_tree_blob_element(tree: Tree) -> Generator[InputGitTreeElement, None, None]:
+    """Collapse the tree structure into blob elements."""
     for child in tree.trees:
         yield from iter_tree_blob_element(child)
 
@@ -46,6 +51,7 @@ def iter_tree_blob_element(tree: Tree) -> Generator[InputGitTreeElement, None, N
 
 
 def write_tree(repo: Repository, tree: Tree, base_tree: GitTree) -> GitTree:
+    """Write a git tree."""
     logger = get_logger("GitTree")
 
     tree_blob_elements = list(iter_tree_blob_element(tree))
@@ -60,6 +66,7 @@ def write_tree(repo: Repository, tree: Tree, base_tree: GitTree) -> GitTree:
 
 
 def write_commit(repo: Repository, commit: Commit) -> GitCommit:
+    """Write a git commit."""
     logger = get_logger("GitCommit")
 
     parent_git_commit = repo.get_git_commit(commit.parents[0])