📝 Add docstrings.

Author: rafalkrupinski

src/lapidary/runtime/annotations.py

@@ -10,19 +10,51 @@
 
 
 class WebArg(abc.ABC):
-    pass
+    """Base class for web-processed parameters."""
 
 
 @dc.dataclass
 class Body(WebArg):
+    """
+    Link content type headers with a python type.
+    When used with a method parameter, it tells lapidary what content-type header to send for a given body type.
+    When used in return annotation, it tells lapidary the type to process the response body as.
+
+    Example use with parameter:
+
+    ```python
+    body: Body({'application/json': BodyModel})
+    ```
+    """
+
     content: Mapping[MimeType, type]
 
 
 class Metadata(WebArg):
-    """Annotation for models that hold other WebArg fields"""
+    """
+    Annotation for models that hold other WebArg fields.
+    Can be used to group request parameters as an alternative to passing parameters directly.
+
+    Example:
+    ```python
+    class RequestMetadata(pydantic.BaseModel):
+        my_header: typing.Annotated[
+            str,
+            Header('my-header'),
+        ]
+
+    class Client(ApiClient):
+    @get(...)
+    async def my_method(
+        headers: Annotated[RequestMetadata, Metadata]
+    ):
+    ```
+    """
 
 
 class Param(WebArg, abc.ABC):
+    """Base class for web parameters (headers, query and path parameters, including cookies)"""
+
     style: typing.Any
     alias: typing.Optional[str]
 
@@ -31,13 +63,19 @@ def __init__(self, alias: typing.Optional[str], /) -> None:
 
 
 class Header(Param):
+    """Mark parameter as HTTP Header"""
+
     def __init__(
         self,
         alias: typing.Optional[str] = None,
         /,
         *,
         style: type[MultimapSerializationStyle] = SimpleMultimap,
     ) -> None:
+        """
+        :param alias: Header name, if different than the name of the annotated parameter
+        :param style: Serialization style
+        """
         super().__init__(alias)
         self.style = style
 
@@ -50,6 +88,10 @@ def __init__(
         *,
         style: type[MultimapSerializationStyle] = FormExplode,
     ) -> None:
+        """
+        :param alias: Cookie name, if different than the name of the annotated parameter
+        :param style: Serialization style
+        """
         super().__init__(alias)
         self.style = style
 
@@ -62,6 +104,10 @@ def __init__(
         *,
         style: type[StringSerializationStyle] = SimpleString,
     ) -> None:
+        """
+        :param alias: Path parameter name, if different than the name of the annotated parameter
+        :param style: Serialization style
+        """
         super().__init__(alias)
         self.style = style
 
@@ -74,6 +120,10 @@ def __init__(
         *,
         style: type[MultimapSerializationStyle] = FormExplode,
     ) -> None:
+        """
+        :param alias: Query parameter name, if different than the name of the annotated parameter
+        :param style: Serialization style
+        """
         super().__init__(alias)
         self.style = style
 
@@ -95,4 +145,28 @@ class Response:
 
 @dc.dataclass
 class Responses(WebArg):
+    """
+    Mapping between response code, headers, media type and body type.
+    The simplified structure is:
+
+        response code => (
+            body: content type => body model type
+            headers model
+        )
+
+    The structure follows OpenAPI 3.
+    """
+
     responses: Mapping[StatusCodeRange, Response]
+    """
+    Map of status code match to Response.
+    Key may be:
+
+    - any HTTP status code
+    - HTTP status code range, i.e. 1XX, 2XX, etc
+    - "default"
+
+    The most specific value takes precedence.
+
+    Value is [Body][lapidary.runtime.Body]
+    """

src/lapidary/runtime/client_base.py

@@ -26,13 +26,21 @@ def lapidary_user_agent() -> str:
 
 
 class ClientBase(abc.ABC):
+    """Base for Client classes"""
+
     def __init__(
         self,
         security: Iterable[SecurityRequirements] | None = None,
         session_factory: SessionFactory = httpx.AsyncClient,
         middlewares: Sequence[HttpxMiddleware] = (),
         **httpx_kwargs: typing.Unpack[ClientArgs],
     ) -> None:
+        """
+        :param security: Security requirements as a mapping of name => list of scopes
+        :param session_factory: `httpx.AsyncClient` or a subclass type
+        :param middlewares: list of middlewares to process HTTP requests and responses
+        :param httpx_kwargs: keyword arguments to pass to session_factory
+        """
         self._client = session_factory(**httpx_kwargs)
         if USER_AGENT not in self._client.headers:
             self._client.headers[USER_AGENT] = lapidary_user_agent()
@@ -53,7 +61,10 @@ async def __aexit__(
         return await self._client.__aexit__(exc_type, exc_value, traceback)
 
     def lapidary_authenticate(self, *auth_args: NamedAuth, **auth_kwargs: httpx.Auth) -> None:
-        """Register named Auth instances for future use with methods that require authentication."""
+        """
+        Register named Auth instances for future use with methods that require authentication.
+        Accepts named [`Auth`][httpx.Auth] as tuples name, auth or as named arguments
+        """
         if auth_args:
             # make python complain about duplicate names
             self.lapidary_authenticate(**dict(auth_args), **auth_kwargs)

src/lapidary/runtime/middleware.py

@@ -7,9 +7,19 @@
 
 
 class HttpxMiddleware(Generic[State]):
+    """
+    Base class for HTTP middleware.
+    """
+
     @abc.abstractmethod
     async def handle_request(self, request: httpx.Request) -> State:
-        pass
+        """Called for each request after it's generated for a method call but before it's sent to the remote server.
+        Any returned value will be passed back to handle_response.
+        """
 
     async def handle_response(self, response: httpx.Response, request: httpx.Request, state: State) -> None:
-        pass
+        """Called for each response after it's been received from the remote server and before it's converted to the return type as defined
+        in the python method.
+
+        state is the value returned by handle_request
+        """

src/lapidary/runtime/model/error.py

@@ -37,7 +37,7 @@ def __init__(self, status_code: int, headers: Headers, body: Body):
 
 
 class UnexpectedResponse(LapidaryResponseError):
-    """Base error class for undeclared responses"""
+    """Raised when the remote server responded with code and content-type pair that wasn't declared in the method return annotation"""
 
     def __init__(self, response: httpx.Response):
         self.response = response

src/lapidary/runtime/paging.py

@@ -14,7 +14,7 @@ def iter_pages(
     get_cursor: Callable[[R], Optional[C]],
 ) -> Callable[P, AsyncIterable[R]]:
     """
-    Create a function that returns an async iterator over pages from the async operation function :param:`fn`.
+    Take a function that returns a pageg response and return a function that returns an async iterator that iterates over the pages.
 
     The returned function can be called with the same parameters as :param:`fn` (except for the cursor parameter),
     and returns an async iterator that yields results from :param:`fn`, handling pagination automatically.
@@ -24,19 +24,19 @@ def iter_pages(
 
     **Example:**
 
-    .. code:: python
-
-        async for page in iter_pages(client.fn, 'cursor', extractor_fn)(parameter=value):
-            # Process page
+    ```python
+    async for page in iter_pages(client.fn, 'cursor', extractor_fn)(parameter=value):
+        # Process page
+    ```
 
     Typically, an API will use the same paging pattern for all operations supporting it, so it's a good idea to write a shortcut function:
 
-    .. code:: python
-
-        from lapidary.runtime import iter_pages as _iter_pages
+    ```python
+    from lapidary.runtime import iter_pages as _iter_pages
 
-        def iter_pages[P, R](fn: Callable[P, Awaitable[R]]) -> Callable[P, AsyncIterable[R]]:
-            return _iter_pages(fn, 'cursor', lambda result: ...)
+    def iter_pages[P, R](fn: Callable[P, Awaitable[R]]) -> Callable[P, AsyncIterable[R]]:
+        return _iter_pages(fn, 'cursor', lambda result: ...)
+    ```
 
     :param fn: An async function that retrieves a page of data.
     :param cursor_param_name: The name of the cursor parameter in :param:`fn`.