Api

This section documents the Api class and related functionality from api.http.

BaseQueryConfig dataclass

Defines the base configuration for all API requests.

This class holds common configuration that applies to all requests made through the API, such as base URL and header preparation.

Attributes:

Name	Type	Description
base_url	str	The base URL for all API requests. If provided, this will be prepended to all request paths.
prepare_headers	Callable[[dict[str, str]], dict[str, str]]	A callable that takes and returns a headers dictionary. Use this to add authentication, content-type, or other headers to all requests.

Example

config = BaseQueryConfig(
    base_url="https://api.example.com/v1",
    prepare_headers=lambda headers: {
        **headers,
        "Authorization": f"Bearer {token}"
    }
)

Source code in src/pomdapi/api/http.py

@dataclass
class BaseQueryConfig:
    """Defines the base configuration for all API requests.

    This class holds common configuration that applies to all requests made through
    the API, such as base URL and header preparation.

    Attributes:
        base_url: The base URL for all API requests. If provided, this will be
                 prepended to all request paths.
        prepare_headers: A callable that takes and returns a headers dictionary.
                       Use this to add authentication, content-type, or other
                       headers to all requests.

    Example:
        ```python
        config = BaseQueryConfig(
            base_url="https://api.example.com/v1",
            prepare_headers=lambda headers: {
                **headers,
                "Authorization": f"Bearer {token}"
            }
        )
        ```
    """
    base_url: str 
    prepare_headers: Callable[[dict[str, str]], dict[str, str]] = field(
        default_factory=lambda: lambda header: header
    )

RequestDefinition dataclass

Defines a request for the API.

Attributes:

Name	Type	Description
method	Literal['GET', 'POST', 'PUT', 'PATCH', 'DELETE']	The HTTP method for the request.
path	str	The path for the request.
body	Any	The request body.
headers	dict[str, str]	The request headers.

example:

RequestDefinition(
    method="GET",
    path="/users",
    headers={"Authorization": "Bearer <token>"}
)

Source code in src/pomdapi/api/http.py

@dataclass
class RequestDefinition:
    """Defines a request for the API.

    Attributes:
        method: The HTTP method for the request.
        path: The path for the request.
        body: The request body.
        headers: The request headers.
    example:
        ```python
        RequestDefinition(
            method="GET",
            path="/users",
            headers={"Authorization": "Bearer <token>"}
        )
        ```
    """

    method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"] = field()
    path: str
    body: Any = None
    headers: dict[str, str] = field(default_factory=dict)