Update docstrings for consistency in rendered API (#173)

stefanvanburen · web-flow · commit 9ae34550af7b · 2026-03-18T09:07:12.000-04:00
Signed-off-by: Stefan VanBuren &lt;svanburen@buf.build&gt;
diff --git a/src/connectrpc/_client_async.py b/src/connectrpc/_client_async.py
@@ -105,15 +105,16 @@ def __init__(
 
         Args:
             address: The address of the server to connect to, including scheme.
-            proto_json: Whether to use JSON for the protocol
+            proto_json: Whether to use JSON for the protocol.
+            protocol: The [ProtocolType][] to use for requests.
             accept_compression: Compression algorithms to accept from the server. If unset,
                                 defaults to gzip. If set to empty, disables response compression.
             send_compression: Compression algorithm to use for sending requests. If unset,
                               defaults to gzip. If set to None, disables request compression.
-            timeout_ms: The timeout for requests in milliseconds
-            read_max_bytes: The maximum number of bytes to read from the response
-            interceptors: A list of interceptors to apply to requests
-            http_client: A pyqwest Client to use for requests
+            timeout_ms: The timeout for requests in milliseconds.
+            read_max_bytes: The maximum number of bytes to read from the response.
+            interceptors: A list of interceptors to apply to requests.
+            http_client: A pyqwest Client to use for requests.
         """
         self._address = address
         self._codec = get_proto_json_codec() if proto_json else get_proto_binary_codec()
diff --git a/src/connectrpc/_client_sync.py b/src/connectrpc/_client_sync.py
@@ -95,15 +95,16 @@ def __init__(
 
         Args:
             address: The address of the server to connect to, including scheme.
-            proto_json: Whether to use JSON for the protocol
+            proto_json: Whether to use JSON for the protocol.
+            protocol: The [ProtocolType][] to use for requests.
             accept_compression: Compression algorithms to accept from the server. If unset,
                                 defaults to gzip. If set to empty, disables response compression.
             send_compression: Compression algorithm to use for sending requests. If unset,
                               defaults to gzip. If set to None, disables request compression.
-            timeout_ms: The timeout for requests in milliseconds
-            read_max_bytes: The maximum number of bytes to read from the response
-            interceptors: A list of interceptors to apply to requests
-            http_client: A pyqwest SyncClient to use for requests
+            timeout_ms: The timeout for requests in milliseconds.
+            read_max_bytes: The maximum number of bytes to read from the response.
+            interceptors: A list of interceptors to apply to requests.
+            http_client: A pyqwest SyncClient to use for requests.
         """
         self._address = address
         self._codec = get_proto_json_codec() if proto_json else get_proto_binary_codec()
diff --git a/src/connectrpc/_compression.py b/src/connectrpc/_compression.py
@@ -26,7 +26,7 @@ def decompress(self, data: bytes | bytearray | memoryview) -> bytes:
 _identity = IdentityCompression()
 
 _gzip = GzipCompression()
-_default_compressions = {"gzip": _gzip, "identity": _identity}
+_default_compressions: dict[str, Compression] = {"gzip": _gzip, "identity": _identity}
 
 
 def resolve_compressions(
diff --git a/src/connectrpc/_interceptor_async.py b/src/connectrpc/_interceptor_async.py
@@ -126,13 +126,13 @@ class MetadataInterceptor(Protocol[T]):
     access to metadata such as headers and trailers.
 
     To access request and response bodies of a method, instead use an interceptor
-    corresponding to the type of method such as UnaryInterceptor.
+    corresponding to the type of method such as [UnaryInterceptor][].
     """
 
     async def on_start(self, ctx: RequestContext) -> T:
-        """Called when the RPC starts. The return value will be passed to on_end as-is.
+        """Called when the RPC starts. The return value will be passed to [on_end][] as-is.
         For example, if measuring RPC invocation time, on_start may return the current
-        time. If a return value isn't needed or on_end won't be used, return None.
+        time. If a return value isn't needed or [on_end][] won't be used, return None.
         """
         ...
 
diff --git a/src/connectrpc/_interceptor_sync.py b/src/connectrpc/_interceptor_sync.py
@@ -126,13 +126,13 @@ class MetadataInterceptorSync(Protocol[T]):
     access to metadata such as headers and trailers.
 
     To access request and response bodies of a method, instead use an interceptor
-    corresponding to the type of method such as UnaryInterceptorSync.
+    corresponding to the type of method such as [UnaryInterceptorSync][].
     """
 
     def on_start_sync(self, ctx: RequestContext) -> T:
-        """Called when the RPC starts. The return value will be passed to on_end as-is.
-        For example, if measuring RPC invocation time, on_start may return the current
-        time. If a return value isn't needed or on_end won't be used, return None.
+        """Called when the RPC starts. The return value will be passed to [on_end_sync][] as-is.
+        For example, if measuring RPC invocation time, on_start_sync may return the current
+        time. If a return value isn't needed or [on_end_sync][] won't be used, return None.
         """
         ...
 
diff --git a/src/connectrpc/_server_async.py b/src/connectrpc/_server_async.py
@@ -95,7 +95,9 @@ def __init__(
 
         Args:
             service: The service instance or async generator that yields the service during lifespan.
-            endpoints: A mapping of URL paths to endpoints resolved from service.
+            endpoints: A callable that takes the service instance and returns a mapping of URL
+                paths to endpoints. Typically provided directly by generated code from the
+                Connect Python plugin.
             interceptors: A sequence of interceptors to apply to the endpoints.
             read_max_bytes: Maximum size of request messages.
             compressions: Supported compression algorithms. If unset, defaults to gzip.
diff --git a/src/connectrpc/_server_shared.py b/src/connectrpc/_server_shared.py
@@ -21,7 +21,7 @@ class Endpoint(Generic[REQ, RES]):
     Represents an endpoint in a service.
 
     Attributes:
-        method: The method to map the the RPC function.
+        method: The method to map to the RPC function.
     """
 
     method: MethodInfo[REQ, RES]
@@ -83,7 +83,7 @@ class EndpointSync(Generic[REQ, RES]):
     Represents a sync endpoint in a service.
 
     Attributes:
-        method: The method to map the RPC function.
+        method: The method to map to the RPC function.
     """
 
     method: MethodInfo[REQ, RES]
diff --git a/src/connectrpc/_server_sync.py b/src/connectrpc/_server_sync.py
@@ -98,15 +98,14 @@ def _process_headers(headers: dict) -> Headers:
 def prepare_response_headers(
     base_headers: dict[str, list[str]], selected_encoding: str
 ) -> dict[str, list[str]]:
-    """Prepare response headers and determine if compression should be used.
+    """Prepare response headers with the selected compression encoding.
 
     Args:
-        base_headers: Base response headers
-        selected_encoding: Selected compression encoding
-        compressed_size: Size of compressed content (if compression was attempted)
+        base_headers: Base response headers.
+        selected_encoding: Selected compression encoding.
 
     Returns:
-        tuple[dict, bool]: Final headers and whether to use compression
+        The final response headers with content-encoding set.
     """
     headers = base_headers.copy()
 
@@ -173,7 +172,8 @@ def __init__(
         """Initialize the WSGI application.
 
         Args:
-            endpoints: A mapping of URL paths to service endpoints.
+            endpoints: A mapping of URL paths to endpoints. Typically provided directly
+                by generated code from the Connect Python plugin.
             interceptors: A sequence of interceptors to apply to the endpoints.
             read_max_bytes: Maximum size of request messages.
             compressions: Supported compression algorithms. If unset, defaults to gzip.
diff --git a/src/connectrpc/compression/__init__.py b/src/connectrpc/compression/__init__.py
@@ -11,10 +11,12 @@ class Compression(Protocol):
 
     By default, gzip compression is used. Other compression methods can be
     used by specifying implementations of this protocol. We provide standard
-    implementations for
+    implementations for:
 
-    - br (connectrpc.compression.brotli.BrotliCompression) - requires the `brotli` dependency
-    - zstd (connectrpc.compression.zstd.ZstdCompression) - requires the `zstandard` dependency
+    - br ([BrotliCompression][connectrpc.compression.brotli.BrotliCompression]) -
+      requires the `brotli` dependency.
+    - zstd ([ZstdCompression][connectrpc.compression.zstd.ZstdCompression]) -
+      requires the `zstandard` dependency.
     """
 
     def name(self) -> str:
diff --git a/src/connectrpc/errors.py b/src/connectrpc/errors.py
@@ -21,7 +21,7 @@ class ConnectError(Exception):
     If a server raises a ConnectError, the same exception content will be
     raised on the client as well. Errors surfacing on the client side such as
     timeouts will also be raised as a ConnectError with an appropriate
-    code.
+    [Code][].
     """
 
     def __init__(
diff --git a/src/connectrpc/method.py b/src/connectrpc/method.py
@@ -70,4 +70,4 @@ class MethodInfo(Generic[REQ, RES]):
     """The output message type of the method."""
 
     idempotency_level: IdempotencyLevel
-    """The idempotency level of the method."""
+    """The [IdempotencyLevel][] of the method."""
diff --git a/src/connectrpc/protocol.py b/src/connectrpc/protocol.py
@@ -4,13 +4,13 @@
 
 
 class ProtocolType(Enum):
-    """A protocol supported by Connect"""
+    """A protocol supported by Connect."""
 
     CONNECT = 1
-    """The Connect protocol"""
+    """The Connect protocol."""
 
     GRPC = 2
-    """The gRPC protocol"""
+    """The gRPC protocol."""
 
     GRPC_WEB = 3
-    """The gRPC-Web protocol"""
+    """The gRPC-Web protocol."""
diff --git a/src/connectrpc/request.py b/src/connectrpc/request.py
@@ -63,11 +63,7 @@ def http_method(self) -> str:
         return self._http_method
 
     def request_headers(self) -> Headers:
-        """
-        Returns the request headers associated with the context.
-
-        :return: A mapping of header keys to lists of header values.
-        """
+        """Returns the request headers associated with the context."""
         return self._request_headers
 
     def response_headers(self) -> Headers:
@@ -87,12 +83,7 @@ def response_trailers(self) -> Headers:
         return self._response_trailers
 
     def timeout_ms(self) -> float | None:
-        """
-        Returns the remaining time until the timeout.
-
-        Returns:
-            float | None: The remaining time in milliseconds, or None if no timeout is set.
-        """
+        """Returns the remaining time until the timeout in milliseconds, or None if no timeout is set."""
         if self._end_time is None:
             return None
         return (self._end_time - time.monotonic()) * 1000.0
diff --git a/zensical.toml b/zensical.toml
@@ -28,7 +28,7 @@ alternate_style = true
 
 [project.plugins.mkdocstrings.handlers.python]
 inventories = ["https://docs.python.org/3/objects.inv"]
-paths = ["."]
+paths = ["src"]
 
 [project.plugins.mkdocstrings.handlers.python.options]
 docstring_options = { ignore_init_summary = true }
