standardize docstrings

Author: filipchristiansen

src/gitingest/clone.py

@@ -65,7 +65,7 @@ async def clone_repo(config: CloneConfig, token: str | None = None) -> None:
 
     clone_cmd = ["git"]
     if token and is_github_host(url):
-        clone_cmd += ["-c", create_git_auth_header(token, url)]
+        clone_cmd += ["-c", create_git_auth_header(token, url=url)]
 
     clone_cmd += ["clone", "--single-branch"]
     # TODO: Re-enable --recurse-submodules when submodule support is needed

src/gitingest/entrypoint.py

@@ -83,7 +83,7 @@ async def ingest_async(
 
     repo_cloned = False
     try:
-        await _clone_if_remote(query, token)
+        await _clone_if_remote(query, token=token)
         repo_cloned = bool(query.url)
 
         summary, tree, content = ingest_query(query)
@@ -183,7 +183,7 @@ async def _clone_if_remote(query: IngestionQuery, token: str | None) -> None:
     query : IngestionQuery
         The query to clone.
     token : str | None
-        The token to use for the query.
+        GitHub personal access token (PAT) for accessing private repositories.
 
     Raises
     ------

src/gitingest/output_formatter.py

@@ -118,8 +118,8 @@ def _gather_file_contents(node: FileSystemNode) -> str:
 
 def _create_tree_structure(
     query: IngestionQuery,
-    node: FileSystemNode,
     *,
+    node: FileSystemNode,
     prefix: str = "",
     is_last: bool = True,
 ) -> str:

src/gitingest/utils/auth.py

@@ -11,7 +11,7 @@ def resolve_token(token: str | None) -> str | None:
     Parameters
     ----------
     token : str | None
-        The token to use for the query.
+        GitHub personal access token (PAT) for accessing private repositories.
 
     Returns
     -------

src/gitingest/utils/git_utils.py

@@ -253,7 +253,7 @@ async def fetch_remote_branch_list(url: str, token: str | None = None) -> list[s
 
     # Add authentication if needed
     if token and is_github_host(url):
-        fetch_branches_command += ["-c", create_git_auth_header(token, url)]
+        fetch_branches_command += ["-c", create_git_auth_header(token, url=url)]
 
     fetch_branches_command += ["ls-remote", "--heads", url]
 
@@ -274,18 +274,18 @@ def create_git_command(base_cmd: list[str], local_path: str, url: str, token: st
     Parameters
     ----------
     base_cmd : list[str]
-        The base git command to start with
+        The base git command to start with.
     local_path : str
-        The local path where the git command should be executed
+        The local path where the git command should be executed.
     url : str
-        The repository URL to check if it's a GitHub repository
+        The repository URL to check if it's a GitHub repository.
     token : str | None
-        GitHub personal access token for authentication
+        GitHub personal access token (PAT) for accessing private repositories.
 
     Returns
     -------
     list[str]
-        The git command with authentication if needed
+        The git command with authentication if needed.
 
     """
     cmd = [*base_cmd, "-C", local_path]
@@ -301,15 +301,15 @@ def create_git_auth_header(token: str, url: str = "https://github.com") -> str:
     Parameters
     ----------
     token : str
-        GitHub personal access token
+        GitHub personal access token (PAT) for accessing private repositories.
     url : str
         The GitHub URL to create the authentication header for.
         Defaults to "https://github.com" if not provided.
 
     Returns
     -------
     str
-        The git config command for setting the authentication header
+        The git config command for setting the authentication header.
 
     """
     hostname = urlparse(url).hostname
@@ -323,12 +323,12 @@ def validate_github_token(token: str) -> None:
     Parameters
     ----------
     token : str
-        The GitHub token to validate
+        GitHub personal access token (PAT) for accessing private repositories.
 
     Raises
     ------
     InvalidGitHubTokenError
-        If the token format is invalid
+        If the token format is invalid.
 
     """
     if not re.match(GITHUB_PAT_PATTERN, token):

src/gitingest/utils/os_utils.py

@@ -9,12 +9,12 @@ async def ensure_directory(path: Path) -> None:
     Parameters
     ----------
     path : Path
-        The path to ensure exists
+        The path to ensure exists.
 
     Raises
     ------
     OSError
-        If the directory cannot be created
+        If the directory cannot be created.
 
     """
     try:

src/server/models.py

@@ -22,7 +22,7 @@ class QueryForm(BaseModel):
     pattern : str
         Glob/regex pattern string.
     token : str | None
-        GitHub personal-access token (``None`` if omitted).
+        GitHub personal access token (PAT) for accessing private repositories.
 
     """
 
@@ -54,7 +54,7 @@ def as_form(
         pattern : StrForm
             Glob/regex pattern string.
         token : OptStrForm
-            GitHub personal-access token (``None`` if omitted).
+            GitHub personal access token (PAT) for accessing private repositories.
 
         Returns
         -------

src/server/query_processor.py

@@ -52,7 +52,7 @@ async def process_query(
     is_index : bool
         Flag indicating whether the request is for the index page (default: ``False``).
     token : str | None
-        GitHub personal-access token (PAT). Needed when the repository is private.
+        GitHub personal access token (PAT) for accessing private repositories.
 
     Returns
     -------

src/server/server_utils.py

@@ -83,7 +83,7 @@ async def _remove_old_repositories(
     Parameters
     ----------
     base_path : Path
-        The path to the base directory where repositories are stored (default: ``TMP_BASE_PATH``)
+        The path to the base directory where repositories are stored (default: ``TMP_BASE_PATH``).
     scan_interval : int
         The number of seconds between scans (default: 60).
     delete_after : int

tests/test_cli.py

@@ -36,8 +36,8 @@
 def test_cli_writes_file(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
-    cli_args: list[str],
     *,
+    cli_args: list[str],
     expect_file: bool,
 ) -> None:
     """Run the CLI and verify that the SARIF file is created (or not)."""