📝 Update documentation.

Author: rafalkrupinski

.config/mkdocs.yaml

@@ -24,6 +24,7 @@ nav:
   - usage/operation.md
   - usage/auth.md
   - usage/middleware.md
+  - usage/paging.md
 - API reference: reference/api.md
 - Lapidary Render: https://lapidary.dev/lapidary-render
 

docs/index.md

@@ -24,12 +24,11 @@ poetry add lapidary
 
 ## Usage
 
-With Lapidary, you define an API client by creating a class that mirrors the API structure, akin to OpenAPI but through
-decorated and annotated Python methods. Calling these method handles making HTTP requests and transforming the responses
-back into Python objects.
+With Lapidary, user creates an API client by writing a class that mirrors the API itself, in a similar manner to OpenAPI, except
+decorated and annotated Python methods are used. These methods handle making HTTP requests and transforming the
+responses back into Python objects.
 
 ```python
-from collections.abc import Awaitable
 from typing import Annotated, Self
 from lapidary.runtime import *
 
@@ -48,7 +47,7 @@ class CatClient:
         *,
         id: Annotated[int, Path],
     ) -> Annotated[
-        Awaitable[Cat],
+        tuple[Cat, None],
         Responses({'2XX': Response(Body({'application/json': Cat}))}),
     ]:
         pass
@@ -63,8 +62,8 @@ import httpx
 
 async def main():
     async with httpx.AsyncClient() as http:
-        client = lapidary.runtime.client.for_api(CatClient, http, 'http://localhost:8080/api')
-        cat = await client.cat_get(id=7)
+        client = lapidary.runtime.client.for_api(CatClient, http, 'https://example.com/api')
+        cat = await client.ops.cat_get(id=7)
 ```
 
 See [this test file](https://github.com/python-lapidary/lapidary/blob/develop/tests/test_client.py) for a working

docs/usage/auth.md

@@ -18,6 +18,15 @@ from lapidary.runtime.auth import HeaderApiKey
 from typing import Self, Annotated
 
 
+class LoginRequest(ModelBase):
+    username: str
+    password: str
+
+
+class LoginResponse(ModelBase):
+    token: str
+
+
 class MyClient:
     @get('/api/operation')
     async def my_op(self: Self) -> ...:
@@ -26,9 +35,12 @@ class MyClient:
     @post('/api/login')
     async def login(
         self: Self,
-        user: Annotated[str, ...],
-        password: Annotated[str, ...],
-    ) -> ...:
+        *,
+        body: Annotated[LoginRequest, Body({'application/json': LoginRequest})],
+    ) -> Annotated[
+        tuple[LoginResponse, None],
+        Responses({'2XX': Response(Body({'application/json': LoginResponse}))}),
+    ]:
         pass
 
 
@@ -37,8 +49,8 @@ async def main():
     async with httpx.AsyncClient() as http:
         client = lapidary.runtime.client.for_api(MyClient, http, 'https://example.com/')
 
-        token = (await client.ops.login('username', 'secret')).token
-        client_w_auth = client.with_auth(client, HeaderApiKey(token))
+        response, _ = await client.ops.login(body=LoginRequest(username='user', password='secret'))
+        client_w_auth = client.with_auth(HeaderApiKey(response.token))
 
         await client_w_auth.ops.my_op()
 ```

docs/usage/client.md

@@ -3,18 +3,14 @@
 The core of the Lapidary API client is a single class that declares all the methods. Pass it to `for_api()`
 along with an `httpx.AsyncClient` instance and a base URL to get an `APIClient`. Operations are then accessed via `.ops`.
 
-Example usage:
-
 ```python
-class CatClient:
-    # operation mothods
-    ...
-
 async with httpx.AsyncClient() as http:
     client = lapidary.runtime.client.for_api(CatClient, http, 'https://example.com')
-    # call client methods via client.ops
+    result, _ = await client.ops.some_operation()
 ```
 
+`for_api()` also accepts `auth` (see [Authentication](auth.md)) and `middlewares` (see [Middleware](middleware.md)).
+
 ## Additional HTTP headers
 
 HTTP request headers can be added using the standard httpx API. It's recommended to add User-Agent header.

docs/usage/operation.md

@@ -116,8 +116,18 @@ await client.ops.list_cats(version='2')
 
 results in the execution of a GET request that includes the header `version: 2`.
 
-Note: The Cookie, Header, Param, and Query annotations all accept parameters such as name, style, and explode as defined
-by OpenAPI.
+HTTP headers conventionally use kebab-case names, which are not valid Python identifiers. Pass the actual header name as the first argument to `Header`:
+
+```python
+@get('/cats')
+async def list_cats(
+    self: Self,
+    x_request_id: Annotated[str, Header('X-Request-Id')],
+):
+    pass
+```
+
+The same applies to `Query` and `Cookie` — pass the wire name as the first argument when it differs from the Python parameter name.
 
 ### Cookie headers
 
@@ -143,6 +153,22 @@ await client.ops.list_cats(cookie_key='value')
 
 will send a GET request that includes the header Cookie: key=value.
 
+## Optional parameters
+
+Query, header, and cookie parameters can all be made optional by using `T | None` and a default of `None`. Parameters set to `None` are omitted from the request entirely.
+
+```python
+@get('/cats')
+async def list_cats(
+    self: Self,
+    *,
+    color: Annotated[str | None, Query] = None,
+    x_request_id: Annotated[str | None, Header('X-Request-Id')] = None,
+    session: Annotated[str | None, Cookie('session_id')] = None,
+):
+    pass
+```
+
 ## Request body
 
 To mark a parameter for serialization into the HTTP body, annotate it with RequestBody. Each method can include only one
@@ -192,10 +218,10 @@ Example:
 async def list_cats(
     self: Self,
 ) -> Annotated[
-    tuple[List[Cat], None],
+    tuple[list[Cat], None],
     Responses(
         {
-            '2XX': Response(Body({'application/json': List[Cat]})),
+            '2XX': Response(Body({'application/json': list[Cat]})),
         }
     ),
 ]:
@@ -240,7 +266,7 @@ class CatClient:
 async with httpx.AsyncClient() as http:
     client = lapidary.runtime.client.for_api(CatClient, http, 'https://example.com')
     cats_body, cats_meta = await client.ops.list_cats()
-    assert cats_body.body == [Cat(...)]
+    assert cats_body == [Cat(...)]
     assert cats_meta.count == 1
     assert cats_meta.status_code == 200
 ```
@@ -259,7 +285,7 @@ class ErrorModel(ModelBase):
 async def list_cats(
     self: Self,
 ) -> Annotated[
-    tuple[List[Cat], None],
+    tuple[list[Cat], None],
     Responses(
         {
             '2XX': Response(...),
@@ -282,6 +308,7 @@ except HttpErrorResponse as e:
 ```
 
 Any responses not declared in the response map, regardless of their status code, raise `UnexpectedResponse`.
+`UnexpectedResponse` is also raised if the response body cannot be decoded into the declared model type.
 
 ```python
 try:

docs/usage/paging.md

@@ -0,0 +1,34 @@
+# Paging
+
+`iter_pages` wraps an operation method and returns a function that, when called, yields successive pages as an async iterator.
+
+```python
+from lapidary.runtime import iter_pages
+
+
+async def get_cursor(result: tuple[list[Cat], None]) -> str | None:
+    body, _ = result
+    return body.next_cursor if body.next_cursor else None
+
+
+paginated = iter_pages(client.ops.list_cats, 'cursor', get_cursor)
+
+async for page in paginated(color='black'):
+    body, _ = page
+    process(body)
+```
+
+The wrapped function is called first without the cursor parameter. After each call, `get_cursor` is invoked on the result. Iteration stops when `get_cursor` returns `None`.
+
+
+## Shortcut
+
+Since an API typically uses the same paging pattern for all its operations, it's practical to define a project-level helper:
+
+```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: result[0].next_cursor or None)
+```

src/lapidary/runtime/annotations.py

@@ -22,9 +22,9 @@ class Body(WebArg):
 
     Example use with parameter:
 
-    ```python
+    .. code-block:: python
+
     body: Body({'application/json': BodyModel})
-    ```
     """
 
     content: Mapping[MimeType, type]
@@ -36,19 +36,20 @@ class Metadata(WebArg):
     Can be used to group request parameters as an alternative to passing parameters directly.
 
     Example:
-    ```python
+
+    .. code-block:: 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]
-    ):
-    ```
+        @get(...)
+        async def my_method(
+            headers: Annotated[RequestMetadata, Metadata]
+        ):
     """
 
 
@@ -139,8 +140,23 @@ class StatusCode(WebArg):
 
 @dc.dataclass
 class Response:
+    """
+    Declare the expected body and headers for a single HTTP response status code.
+
+    Used as a value inside the :class:`Responses` mapping.
+
+    Example:
+
+    .. code-block:: python
+
+    Response(Body({'application/json': Cat}))
+
+    Response(Body({'application/json': Cat}), CatListMeta)
+    """
+
     body: Body
     headers: type[pydantic.BaseModel] | None = None
+    """Pydantic model to deserialize response headers into. Fields must be annotated with :class:`Header` or :class:`StatusCode`."""
 
 
 @dc.dataclass

src/lapidary/runtime/client.py

@@ -23,6 +23,15 @@ def for_api(
     middlewares: Sequence[HttpxMiddleware] = (),
     auth: httpx.Auth | None = None,
 ) -> APIClient[API_T]:
+    """
+    Create an :class:`APIClient` for the given API descriptor class.
+
+    :param api: The API descriptor class — a plain class whose methods are decorated with :func:`get`, :func:`post`, etc.
+    :param client: The underlying :class:`httpx.AsyncClient` used to send requests.
+    :param base_url: Base URL prepended to all operation paths.
+    :param middlewares: Optional sequence of :class:`HttpxMiddleware` instances applied to every request.
+    :param auth: Optional :class:`httpx.Auth` instance used to authenticate requests.
+    """
     api_model = APIModel(api)
     return APIClient(api_model, client, base_url, auth=auth, middlewares=middlewares)
 

src/lapidary/runtime/model/__init__.py

@@ -2,6 +2,8 @@
 
 
 class ModelBase(pydantic.BaseModel):
+    """A simple base class for request and response models. Pydantic's BaseModel with defaults suitable for typical cases."""
+
     model_config = pydantic.ConfigDict(
         extra='allow',
         populate_by_name=True,

src/lapidary/runtime/paging.py

@@ -22,21 +22,10 @@ def iter_pages(
     The function :param:`fn` will be called initially without the cursor parameter and then called with the cursor parameter
     as long as :param:`get_cursor` can extract a cursor from the result.
 
-    **Example:**
+    Example::
 
-    ```python
-    async for page in iter_pages(client.fn, 'cursor', extractor_fn)(parameter=value):
+    async for page in iter_pages(client.ops.fn, 'cursor', get_cursor_from_response)(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:
-
-    ```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: ...)
-    ```
 
     :param fn: An async function that retrieves a page of data.
     :param cursor_param_name: The name of the cursor parameter in :param:`fn`.