Add more missing docstrings

dulwich/client.py

@@ -831,8 +831,10 @@ class GitClient:
           thin_packs: Whether or not thin packs should be retrieved
           report_activity: Optional callback for reporting transport
             activity.
+          quiet: Whether to suppress output
           include_tags: send annotated tags when sending the objects they point
             to
+          **kwargs: Additional keyword arguments
         """
         self._report_activity = report_activity
         self._report_status_parser: Optional[ReportStatusParser] = None
@@ -1273,6 +1275,12 @@ class TraditionalGitClient(GitClient):
     DEFAULT_ENCODING = "utf-8"
 
     def __init__(self, path_encoding=DEFAULT_ENCODING, **kwargs) -> None:
+        """Initialize a TraditionalGitClient.
+
+        Args:
+            path_encoding: Encoding for paths (default: utf-8)
+            **kwargs: Additional arguments passed to parent class
+        """
         self._remote_path_encoding = path_encoding
         super().__init__(**kwargs)
 
@@ -2435,6 +2443,11 @@ class StrangeHostname(Exception):
     """Refusing to connect to strange SSH hostname."""
 
     def __init__(self, hostname) -> None:
+        """Initialize StrangeHostname exception.
+
+        Args:
+            hostname: The strange hostname that was rejected
+        """
         super().__init__(hostname)
 
 
@@ -2452,6 +2465,21 @@ class SubprocessSSHVendor(SSHVendor):
         ssh_command=None,
         protocol_version: Optional[int] = None,
     ):
+        """Run a git command over SSH.
+
+        Args:
+            host: SSH host to connect to
+            command: Git command to run
+            username: Optional username
+            port: Optional port number
+            password: Optional password (not supported)
+            key_filename: Optional SSH key file
+            ssh_command: Optional custom SSH command
+            protocol_version: Optional Git protocol version
+
+        Returns:
+            Tuple of (subprocess.Popen, Protocol, stderr_stream)
+        """
         if password is not None:
             raise NotImplementedError(
                 "Setting password not supported by SubprocessSSHVendor."
@@ -2505,6 +2533,21 @@ class PLinkSSHVendor(SSHVendor):
         ssh_command=None,
         protocol_version: Optional[int] = None,
     ):
+        """Run a git command over SSH using PLink.
+
+        Args:
+            host: SSH host to connect to
+            command: Git command to run
+            username: Optional username
+            port: Optional port number
+            password: Optional password
+            key_filename: Optional SSH key file
+            ssh_command: Optional custom SSH command
+            protocol_version: Optional Git protocol version
+
+        Returns:
+            Tuple of (subprocess.Popen, Protocol, stderr_stream)
+        """
         if ssh_command:
             import shlex
 
@@ -2574,6 +2617,8 @@ get_ssh_vendor: Callable[[], SSHVendor] = SubprocessSSHVendor
 
 
 class SSHGitClient(TraditionalGitClient):
+    """Git client that connects over SSH."""
+
     def __init__(
         self,
         host,
@@ -3314,6 +3359,8 @@ def _wrap_urllib3_exceptions(func):
 
 
 class Urllib3HttpGitClient(AbstractHttpGitClient):
+    """Git client that uses urllib3 for HTTP(S) connections."""
+
     def __init__(
         self,
         base_url,

dulwich/index.py

@@ -333,6 +333,11 @@ class TreeExtension(IndexExtension):
     """Tree cache extension."""
 
     def __init__(self, entries: list[tuple[bytes, bytes, int]]) -> None:
+        """Initialize TreeExtension.
+
+        Args:
+            entries: List of tree cache entries (path, sha, flags)
+        """
         self.entries = entries
         super().__init__(TREE_EXTENSION, b"")
 
@@ -363,6 +368,11 @@ class ResolveUndoExtension(IndexExtension):
     """Resolve undo extension for recording merge conflicts."""
 
     def __init__(self, entries: list[tuple[bytes, list[tuple[int, bytes]]]]) -> None:
+        """Initialize ResolveUndoExtension.
+
+        Args:
+            entries: List of (path, stages) where stages is a list of (stage, sha) tuples
+        """
         self.entries = entries
         super().__init__(REUC_EXTENSION, b"")
 
@@ -393,6 +403,11 @@ class UntrackedExtension(IndexExtension):
     """Untracked cache extension."""
 
     def __init__(self, data: bytes) -> None:
+        """Initialize UntrackedExtension.
+
+        Args:
+            data: Raw untracked cache data
+        """
         super().__init__(UNTR_EXTENSION, data)
 
     @classmethod
@@ -524,6 +539,13 @@ class ConflictedIndexEntry:
         this: Optional[IndexEntry] = None,
         other: Optional[IndexEntry] = None,
     ) -> None:
+        """Initialize ConflictedIndexEntry.
+
+        Args:
+            ancestor: The common ancestor entry
+            this: The current branch entry
+            other: The other branch entry
+        """
         self.ancestor = ancestor
         self.this = this
         self.other = other

dulwich/objects.py

@@ -298,6 +298,11 @@ class FixedSha:
     __slots__ = ("_hexsha", "_sha")
 
     def __init__(self, hexsha: Union[str, bytes]) -> None:
+        """Initialize FixedSha with a fixed SHA value.
+
+        Args:
+            hexsha: Hex SHA value as string or bytes
+        """
         if isinstance(hexsha, str):
             hexsha = hexsha.encode("ascii")
         if not isinstance(hexsha, bytes):
@@ -679,6 +684,7 @@ class Blob(ShaFile):
     _chunked_text: list[bytes]
 
     def __init__(self) -> None:
+        """Initialize a new Blob object."""
         super().__init__()
         self._chunked_text = []
         self._needs_serialization = False
@@ -863,6 +869,7 @@ class Tag(ShaFile):
     _tagger: Optional[bytes]
 
     def __init__(self) -> None:
+        """Initialize a new Tag object."""
         super().__init__()
         self._tagger = None
         self._tag_time = None
@@ -1115,6 +1122,7 @@ def parse_tree(text: bytes, strict: bool = False) -> Iterator[tuple[bytes, int,
 
     Args:
       text: Serialized text to parse
+      strict: If True, enforce strict validation
     Returns: iterator of tuples of (name, mode, sha)
 
     Raises:
@@ -1205,6 +1213,7 @@ def pretty_format_tree_entry(
       name: Name of the directory entry
       mode: Mode of entry
       hexsha: Hexsha of the referenced object
+      encoding: Character encoding for the name
     Returns: string describing the tree entry
     """
     if mode & stat.S_IFDIR:
@@ -1223,6 +1232,12 @@ class SubmoduleEncountered(Exception):
     """A submodule was encountered while resolving a path."""
 
     def __init__(self, path: bytes, sha: ObjectID) -> None:
+        """Initialize SubmoduleEncountered exception.
+
+        Args:
+            path: Path where the submodule was encountered
+            sha: SHA of the submodule
+        """
         self.path = path
         self.sha = sha
 

dulwich/porcelain.py

@@ -334,7 +334,7 @@ def parse_timezone_format(tz_str):
 
 
 def get_user_timezones():
-    """Retrieve local timezone as described in https://raw.githubusercontent.com/git/git/v2.3.0/Documentation/date-formats.txt
+    """Retrieve local timezone as described in https://raw.githubusercontent.com/git/git/v2.3.0/Documentation/date-formats.txt.
 
     Returns: A tuple containing author timezone, committer timezone.
     """
@@ -408,6 +408,7 @@ def path_to_tree_path(
     Args:
       repopath: Repository path, absolute or relative to the cwd
       path: A path, absolute or relative to the cwd
+      tree_encoding: Encoding to use for tree paths
     Returns: A path formatted for use in e.g. an index
     """
     # Resolve might returns a relative path on Windows
@@ -570,6 +571,7 @@ def commit(
       author_timezone: Author timestamp timezone
       committer: Optional committer name and email
       commit_timezone: Commit timestamp timezone
+      encoding: Encoding to use for commit message
       no_verify: Skip pre-commit and commit-msg hooks
       signoff: GPG Sign the commit (bool, defaults to False,
         pass True to use default GPG key,
@@ -664,6 +666,7 @@ def commit_tree(
     Args:
       repo: Path to repository
       tree: An existing tree object
+      message: Commit message
       author: Optional author name and email
       committer: Optional committer name and email
     """
@@ -729,10 +732,8 @@ def clone(
       protocol_version: desired Git protocol version. By default the highest
         mutually supported protocol version will be used.
       recurse_submodules: Whether to initialize and clone submodules
-
-    Keyword Args:
-      refspecs: refspecs to fetch. Can be a bytestring, a string, or a list of
-        bytestring/string.
+      **kwargs: Additional keyword arguments including refspecs to fetch.
+        Can be a bytestring, a string, or a list of bytestring/string.
 
     Returns: The new repository
     """
@@ -977,6 +978,7 @@ def remove(repo: Union[str, os.PathLike, Repo] = ".", paths=None, cached=False)
     Args:
       repo: Repository for the files
       paths: Paths to remove. Can be absolute or relative to the repository root.
+      cached: Only remove from index, not from working directory
     """
     with open_repo_closing(repo) as r:
         index = r.open_index()