standardize docstrings

Author: filipchristiansen

src/gitingest/cli.py

@@ -53,7 +53,7 @@ class _CLIArgs(TypedDict):
     envvar="GITHUB_TOKEN",
     default=None,
     help=(
-        "GitHub personal access token for accessing private repositories. "
+        "GitHub personal access token (PAT) for accessing private repositories. "
         "If omitted, the CLI will look for the GITHUB_TOKEN environment variable."
     ),
 )
@@ -81,9 +81,9 @@ async def _async_main(
 ) -> None:
     """Analyze a directory or repository and create a text dump of its contents.
 
-    This command analyzes the contents of a specified source directory or repository, applies custom include and
-    exclude patterns, and generates a text summary of the analysis which is then written to an output file
-    or printed to stdout.
+    This command scans the specified ``source`` (a local directory or Git repo),
+    applies custom include and exclude patterns, and generates a text summary of
+    the analysis.  The summary is written to an output file or printed to ``stdout``.
 
     Parameters
     ----------
@@ -96,20 +96,20 @@ async def _async_main(
     include_pattern : tuple[str, ...] | None
         Glob patterns for including files in the output.
     branch : str | None
-        Git branch to ingest. If *None*, the repository's default branch is used.
+        Git branch to ingest. If ``None``, the repository's default branch is used.
     include_gitignored : bool
-        If *True*, also ingest files matched by ``.gitignore`` or ``.gitingestignore`` (default: ``False``).
+        If ``True``, also ingest files matched by ``.gitignore`` or ``.gitingestignore`` (default: ``False``).
     token : str | None
-        GitHub personal-access token (PAT). Needed when the repository is private.
-        Can also be set via the ``GITHUB_TOKEN`` env var.
+        GitHub personal access token (PAT) for accessing private repositories.
+        Can also be set via the ``GITHUB_TOKEN`` environment variable.
     output : str | None
-        Destination file path. If *None*, the output is written to ``<repo_name>.txt`` in the current directory.
-        Use ``"-"`` to write to *stdout*.
+        Destination file path. If ``None``, the output is written to ``<repo_name>.txt`` in the current directory.
+        Use ``"-"`` to write to ``stdout``.
 
     Raises
     ------
     click.Abort
-        If there is an error during the execution of the command, this exception is raised to abort the process.
+        Raised if an error occurs during execution and the command must be aborted.
 
     """
     try:

src/gitingest/clone.py

@@ -35,8 +35,8 @@ async def clone_repo(config: CloneConfig, token: str | None = None) -> None:
     config : CloneConfig
         The configuration for cloning the repository.
     token : str | None
-        GitHub personal-access token (PAT). Needed when the repository is private.
-        Can also be set via the `GITHUB_TOKEN` env var.
+        GitHub personal access token (PAT) for accessing private repositories.
+        Can also be set via the ``GITHUB_TOKEN`` environment variable.
 
     Raises
     ------

src/gitingest/config.py

@@ -3,10 +3,10 @@
 import tempfile
 from pathlib import Path
 
-MAX_FILE_SIZE = 10 * 1024 * 1024  # 10 MB
+MAX_FILE_SIZE = 10 * 1024 * 1024  # Maximum size of a single file to process (10 MB)
 MAX_DIRECTORY_DEPTH = 20  # Maximum depth of directory traversal
 MAX_FILES = 10_000  # Maximum number of files to process
-MAX_TOTAL_SIZE_BYTES = 500 * 1024 * 1024  # 500 MB
+MAX_TOTAL_SIZE_BYTES = 500 * 1024 * 1024  # Maximum size of output file (500 MB)
 DEFAULT_TIMEOUT = 60  # seconds
 
 OUTPUT_FILE_NAME = "digest.txt"

src/gitingest/entrypoint.py

@@ -9,7 +9,7 @@
 from pathlib import Path
 
 from gitingest.clone import clone_repo
-from gitingest.config import TMP_BASE_PATH
+from gitingest.config import MAX_FILE_SIZE, TMP_BASE_PATH
 from gitingest.ingestion import ingest_query
 from gitingest.query_parser import IngestionQuery, parse_query
 from gitingest.utils.async_compat import to_thread
@@ -20,7 +20,7 @@
 async def ingest_async(
     source: str,
     *,
-    max_file_size: int = 10 * 1024 * 1024,  # 10 MB
+    max_file_size: int = MAX_FILE_SIZE,  # 10 MB
     include_patterns: str | set[str] | None = None,
     exclude_patterns: str | set[str] | None = None,
     branch: str | None = None,
@@ -41,19 +41,20 @@ async def ingest_async(
     max_file_size : int
         Maximum allowed file size for file ingestion. Files larger than this size are ignored (default: 10 MB).
     include_patterns : str | set[str] | None
-        Pattern or set of patterns specifying which files to include. If *None*, all files are included.
+        Pattern or set of patterns specifying which files to include. If ``None``, all files are included.
     exclude_patterns : str | set[str] | None
-        Pattern or set of patterns specifying which files to exclude. If *None*, no files are excluded.
+        Pattern or set of patterns specifying which files to exclude. If ``None``, no files are excluded.
     branch : str | None
-        The branch to clone and ingest. If *None*, the default branch is used.
+        The branch to clone and ingest (default: the default branch).
     include_gitignored : bool
-        If *True*, include files ignored by ``.gitignore`` and ``.gitingestignore`` (default: ``False``).
+        If ``True``, include files ignored by ``.gitignore`` and ``.gitingestignore`` (default: ``False``).
     token : str | None
-        GitHub personal-access token (PAT). Needed when the repository is private.
-        Can also be set via the ``GITHUB_TOKEN`` env var.
+        GitHub personal access token (PAT) for accessing private repositories.
+        Can also be set via the ``GITHUB_TOKEN`` environment variable.
     output : str | None
-        File path where the summary and content should be written. If *"-"* (dash), the results are written to stdout.
-        If *None*, the results are not written to a file.
+        File path where the summary and content should be written.
+        If ``"-"`` (dash), the results are written to ``stdout``.
+        If ``None``, the results are not written to a file.
 
     Returns
     -------
@@ -99,7 +100,7 @@ async def ingest_async(
 def ingest(
     source: str,
     *,
-    max_file_size: int = 10 * 1024 * 1024,  # 10 MB
+    max_file_size: int = MAX_FILE_SIZE,
     include_patterns: str | set[str] | None = None,
     exclude_patterns: str | set[str] | None = None,
     branch: str | None = None,
@@ -120,19 +121,20 @@ def ingest(
     max_file_size : int
         Maximum allowed file size for file ingestion. Files larger than this size are ignored (default: 10 MB).
     include_patterns : str | set[str] | None
-        Pattern or set of patterns specifying which files to include. If *None*, all files are included.
+        Pattern or set of patterns specifying which files to include. If ``None``, all files are included.
     exclude_patterns : str | set[str] | None
-        Pattern or set of patterns specifying which files to exclude. If *None*, no files are excluded.
+        Pattern or set of patterns specifying which files to exclude. If ``None``, no files are excluded.
     branch : str | None
         The branch to clone and ingest (default: the default branch).
     include_gitignored : bool
-        If *True*, include files ignored by ``.gitignore`` and ``.gitingestignore`` (default: ``False``).
+        If ``True``, include files ignored by ``.gitignore`` and ``.gitingestignore`` (default: ``False``).
     token : str | None
-        GitHub personal-access token (PAT). Needed when the repository is private.
-        Can also be set via the ``GITHUB_TOKEN`` env var.
+        GitHub personal access token (PAT) for accessing private repositories.
+        Can also be set via the ``GITHUB_TOKEN`` environment variable.
     output : str | None
-        File path where the summary and content should be written. If *"-"* (dash), the results are written to stdout.
-        If *None*, the results are not written to a file.
+        File path where the summary and content should be written.
+        If ``"-"`` (dash), the results are written to ``stdout``.
+        If ``None``, the results are not written to a file.
 
     Returns
     -------
@@ -162,7 +164,7 @@ def ingest(
 
 
 def _apply_gitignores(query: IngestionQuery) -> None:
-    """Update `query.ignore_patterns` in-place.
+    """Update ``query.ignore_patterns`` in-place.
 
     Parameters
     ----------
@@ -187,7 +189,7 @@ async def _clone_if_remote(query: IngestionQuery, token: str | None) -> None:
     Raises
     ------
     TypeError
-        If `clone_repo` does not return a coroutine.
+        If ``clone_repo`` does not return a coroutine.
 
     """
     if not query.url:  # local path ingestion
@@ -207,7 +209,7 @@ async def _clone_if_remote(query: IngestionQuery, token: str | None) -> None:
 
 
 async def _write_output(tree: str, content: str, target: str | None) -> None:
-    """Write combined output to *target* (`'-'` ⇒ stdout).
+    """Write combined output to ``target`` (``"-"`` ⇒ stdout).
 
     Parameters
     ----------
@@ -216,7 +218,7 @@ async def _write_output(tree: str, content: str, target: str | None) -> None:
     content : str
         The content of the files in the repository or directory.
     target : str | None
-        The path to the output file. If *None*, the results are not written to a file.
+        The path to the output file. If ``None``, the results are not written to a file.
 
     """
     if target == "-":

src/gitingest/output_formatter.py

@@ -179,7 +179,7 @@ def _format_token_count(text: str) -> str | None:
     Returns
     -------
     str | None
-        The formatted number of tokens as a string (e.g., ``1.2k``, ``1.2M``), or ``None`` if an error occurs.
+        The formatted number of tokens as a string (e.g., ``"1.2k"``, ``"1.2M"``), or ``None`` if an error occurs.
 
     """
     try:

src/gitingest/query_parser.py

@@ -48,8 +48,8 @@ async def parse_query(
     ignore_patterns : set[str] | str | None
         Patterns to ignore. Can be a set of strings or a single string.
     token : str | None
-        GitHub personal-access token (PAT). Needed when the repository is private.
-        Can also be set via the `GITHUB_TOKEN` env var.
+        GitHub personal access token (PAT) for accessing private repositories.
+        Can also be set via the ``GITHUB_TOKEN`` environment variable.
 
     Returns
     -------
@@ -99,17 +99,17 @@ async def _parse_remote_repo(source: str, token: str | None = None) -> Ingestion
     """Parse a repository URL into a structured query dictionary.
 
     If source is:
-      - A fully qualified URL (`https://gitlab.com/...`), parse & verify that domain
-      - A URL missing `https://` (`gitlab.com/...`), add `https://` and parse
-      - A `slug` (`pandas-dev/pandas`), attempt known domains until we find one that exists.
+      - A fully qualified URL ('https://gitlab.com/...'), parse & verify that domain
+      - A URL missing 'https://' ('gitlab.com/...'), add 'https://' and parse
+      - A *slug* ('pandas-dev/pandas'), attempt known domains until we find one that exists.
 
     Parameters
     ----------
     source : str
         The URL or domain-less slug to parse.
     token : str | None
-        GitHub personal-access token (PAT). Needed when the repository is private.
-        Can also be set via the ``GITHUB_TOKEN`` env var.
+        GitHub personal access token (PAT) for accessing private repositories.
+        Can also be set via the ``GITHUB_TOKEN`` environment variable.
 
     Returns
     -------
@@ -300,8 +300,8 @@ async def try_domains_for_user_and_repo(user_name: str, repo_name: str, token: s
     repo_name : str
         The name of the repository.
     token : str | None
-        GitHub personal-access token (PAT). Needed when the repository is private.
-        Can also be set via the ``GITHUB_TOKEN`` env var.
+        GitHub personal access token (PAT) for accessing private repositories.
+        Can also be set via the ``GITHUB_TOKEN`` environment variable.
 
     Returns
     -------

src/gitingest/schemas/ingestion.py

@@ -101,7 +101,7 @@ def extract_clone_config(self) -> CloneConfig:
         Raises
         ------
         ValueError
-            If the `url` parameter is not provided.
+            If the ``url`` parameter is not provided.
 
         """
         if not self.url:

src/gitingest/utils/async_compat.py

@@ -21,14 +21,14 @@
     async def to_thread(func: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs) -> R:
         """Back-port :func:`asyncio.to_thread` for Python < 3.9.
 
-        Run `func` in the default thread-pool executor and return the result.
+        Run ``func`` in the default thread-pool executor and return the result.
         """
         loop = asyncio.get_running_loop()
         ctx = contextvars.copy_context()
         func_call = functools.partial(ctx.run, func, *args, **kwargs)
         return await loop.run_in_executor(None, func_call)
 
-    # Patch stdlib so that *existing* imports of ``asyncio`` see the shim.
+    # Patch stdlib so that *existing* imports of asyncio see the shim.
     if not hasattr(asyncio, "to_thread"):
         asyncio.to_thread = to_thread
 

src/gitingest/utils/exceptions.py

@@ -26,7 +26,7 @@ def __init__(self, pattern: str) -> None:
 class AsyncTimeoutError(Exception):
     """Exception raised when an async operation exceeds its timeout limit.
 
-    This exception is used by the `async_timeout` decorator to signal that the wrapped
+    This exception is used by the ``async_timeout`` decorator to signal that the wrapped
     asynchronous function has exceeded the specified time limit for execution.
     """
 

src/gitingest/utils/file_utils.py

@@ -44,7 +44,7 @@ def _read_chunk(path: Path) -> bytes | None:
     Returns
     -------
     bytes | None
-        The first *_CHUNK_SIZE* bytes of *path*, or None on any `OSError`.
+        The first ``_CHUNK_SIZE`` bytes of ``path``, or ``None`` on any ``OSError``.
 
     """
     try:
@@ -55,7 +55,7 @@ def _read_chunk(path: Path) -> bytes | None:
 
 
 def _decodes(chunk: bytes, encoding: str) -> bool:
-    """Return *True* if *chunk* decodes cleanly with *encoding*.
+    """Return ``True`` if ``chunk`` decodes cleanly with ``encoding``.
 
     Parameters
     ----------
@@ -67,7 +67,7 @@ def _decodes(chunk: bytes, encoding: str) -> bool:
     Returns
     -------
     bool
-        True if the chunk decodes cleanly with the encoding, False otherwise.
+        ``True`` if the chunk decodes cleanly with the encoding, ``False`` otherwise.
 
     """
     try: