nanosdk.params

Field markers that say where a request-model field goes on the wire.

Use them with typing.Annotated on fields of a pydantic request model:

class GetRepo(BaseModel):
    owner: Annotated[str, Path()]
    repo: Annotated[str, Path()]
    per_page: Annotated[int, Query(alias="per-page")] = 30
    trace_id: Annotated[str | None, Header()] = None

Unmarked fields are placed automatically:

• a field whose name matches a {placeholder} in the route path goes in the path
• on GET / DELETE / HEAD / OPTIONS, in the query string
• on POST / PUT / PATCH, as a key in the JSON object body

Wire names follow the model's pydantic aliases (Field(alias=...), serialization_alias, alias_generator); a marker's own alias overrides them.

Path dataclass

Path(alias: str | None = None, location: Location = PATH)

Bases: Param

Substituted into the matching {name} placeholder of the route path, URL-encoded.

Only needed when the field name doesn't match the placeholder: user_id: Annotated[int, Path(alias="userId")] fills /users/{userId}.

Query dataclass

Query(alias: str | None = None, location: Location = QUERY)

Bases: Param

Sent as a query-string parameter.

None values are omitted, lists and tuples repeat the key (?tag=a&tag=b) and booleans become true / false. Use it to put a field of a POST/PUT/PATCH route in the query instead of the body.

Header dataclass

Header(
    alias: str | None = None, location: Location = HEADER
)

Bases: Param

Sent as a request header; None values are omitted.

Without an alias, underscores become dashes: x_trace_id is sent as x-trace-id.

Json dataclass

Json(alias: str | None = None, location: Location = JSON)

Bases: Param

A key inside the JSON object body.

This is already the default for unmarked fields on POST / PUT / PATCH; use it to rename a key (Json(alias="body")) or to send JSON on another method.

Body dataclass

Body(alias: str | None = None, location: Location = BODY)

Bases: Param

This field is the entire request body.

Models, lists and dicts are sent as JSON; str and bytes are sent as-is. At most one field per request model can be Body(), and it can't be combined with Json() fields.

Form dataclass

Form(alias: str | None = None, location: Location = FORM)

Bases: Param

Sent as a form field.

The body is application/x-www-form-urlencoded, or multipart/form-data when the model also has File fields.

File dataclass

File(alias: str | None = None, location: Location = FILE)

Bases: Param

Sent as a file in a multipart/form-data body.

The field's value is anything httpx accepts as a file: bytes, a binary file object, or a tuple (filename, content) / (filename, content, content_type).

Param dataclass

Param(alias: str | None = None, location: Location = QUERY)

Base class of all field markers.

Parameters:

Name	Type	Description	Default
alias	str | None	Name to use on the wire instead of the field's (alias) name.	None
location	Location	Where the field is sent; fixed by each subclass.	QUERY

Location

Bases: StrEnum

Where a request-model field is sent.