Parameters¶
A marker sets the source of a handler argument and adds limits and documentation.
Put the marker in Annotated, or use it as the default of the argument.
For a task-based introduction, see Requests.
django_bolt.param_functions has the same functions. django_bolt.Depends is the same class as django_bolt.params.Depends.
Example
from typing import Annotated
from django_bolt import BoltAPI
from django_bolt.params import Query
api = BoltAPI()
@api.get("/search")
async def search(
q: Annotated[str, Query(min_length=2, max_length=50, description="Text to find", example="django")],
sort: Annotated[str, Query(pattern=r"^-?(created_at|title)$")] = "-created_at",
) -> dict:
return {"q": q, "sort": sort}
Rules for each marker¶
- The first argument of a marker is
default.Query("x")sets a default, not an alias. ...as the default makes the argument required.- In
Annotated, write the default after=. Adefaultin the marker raisesTypeErrorwhen you register the route. - As the default of the argument, for example
page: int = Query(1, ge=1), thedefaultof the marker is the default of the argument. - The OpenAPI document shows
description,exampleanddeprecated.
Query()¶
Query(default=..., *, alias=None, gt=None, ge=None, lt=None, le=None, min_length=None,
max_length=None, pattern=None, description=None, example=None, deprecated=False)
Read the argument from the query string.
| Parameter | Type | Default | Description |
|---|---|---|---|
default |
Any |
... |
The value when the key is missing. ... makes the key required. |
alias |
str \| None |
None |
The key to read, in place of the argument name. |
gt |
float \| None |
None |
The value must be greater than this number. |
ge |
float \| None |
None |
The value must be greater than or equal to this number. |
lt |
float \| None |
None |
The value must be less than this number. |
le |
float \| None |
None |
The value must be less than or equal to this number. |
min_length |
int \| None |
None |
The minimum length of a string or a list. |
max_length |
int \| None |
None |
The maximum length of a string or a list. |
pattern |
str \| None |
None |
A regular expression that a string must match. |
description |
str \| None |
None |
The description in the OpenAPI document. |
example |
Any |
None |
The example in the OpenAPI document. |
deprecated |
bool |
False |
Mark the parameter as deprecated in the OpenAPI document. |
A value outside a limit gets a 422 response. A msgspec.Struct type reads each of its fields from the query string. See Group parameters in a model.
Path()¶
Path(default=..., *, alias=None, gt=None, ge=None, lt=None, le=None, min_length=None,
max_length=None, pattern=None, description=None, example=None, deprecated=False)
Read the argument from the path. An argument with the name of a path parameter needs no marker. Use Path() to add limits.
The parameters are the parameters of Query().
Errors
ValueError:defaultis not.... A path parameter is always required.
from django_bolt.params import Path
@api.get("/articles/{article_id}")
async def get_article(article_id: Annotated[int, Path(ge=1)]) -> dict:
return {"id": article_id}
Body()¶
Read the argument from the JSON body.
| Parameter | Type | Default | Description |
|---|---|---|---|
default |
Any |
... |
The value when the request has no body. With embed=True, also the value when the object has no key for the argument. |
alias |
str \| None |
None |
With embed=True, the key to read, in place of the argument name. Without embed, it has no effect. |
embed |
bool |
False |
Read the value at the key of the argument name in a JSON object. A body that is not an object gets a 422 response. |
description |
str \| None |
None |
The description of the request body in the OpenAPI document. |
example |
Any |
None |
The example of the request body in the OpenAPI document. |
A GET, HEAD, DELETE or OPTIONS route with a Body() argument raises TypeError when you register it.
Header()¶
Read the argument from a request header. Without alias, the header name is the argument name in lower case, with - for each _. The match is not case-sensitive.
| Parameter | Type | Default | Description |
|---|---|---|---|
default |
Any |
... |
The value when the header is missing. |
alias |
str \| None |
None |
The header name. |
description |
str \| None |
None |
The description in the OpenAPI document. |
example |
Any |
None |
The example in the OpenAPI document. |
deprecated |
bool |
False |
Mark the parameter as deprecated in the OpenAPI document. |
To add a limit, put msgspec.Meta in Annotated, for example Annotated[int, Header(), msgspec.Meta(le=100)].
Cookie()¶
Read the argument from a request cookie. Without alias, the cookie name is the argument name.
The parameters are the parameters of Header().
This marker reads a cookie. To set a cookie on a response, see Set and delete cookies.
Form()¶
Read the argument from a URL-encoded or multipart form body.
| Parameter | Type | Default | Description |
|---|---|---|---|
default |
Any |
... |
The value when the field is missing. |
alias |
str \| None |
None |
The field name. |
description |
str \| None |
None |
The description of the field in the OpenAPI document. |
example |
Any |
None |
The example of the field in the OpenAPI document. |
A msgspec.Struct type reads each of its fields from the form. A field can be an UploadFile.
File()¶
File(default=..., *, alias=None, description=None, max_size=None, min_size=None,
allowed_types=None, max_files=None)
Read the argument from a file field of a multipart body. The type of the argument can be UploadFile, bytes, or a list of one of them.
| Parameter | Type | Default | Description |
|---|---|---|---|
default |
Any |
... |
The value when the field is missing. |
alias |
str \| None |
None |
The field name. |
description |
str \| None |
None |
The description in the OpenAPI document. |
max_size |
int \| None |
None |
The maximum size of each file, in bytes. An int of 0 or more. |
min_size |
int \| None |
None |
The minimum size of each file, in bytes. An int of 0 or more, not above max_size. |
allowed_types |
Iterable[str] \| None |
None |
The allowed content types. "image/*" matches each image type. None allows each type. |
max_files |
int \| None |
None |
The maximum number of files for a list argument. An int of 1 or more. |
Errors
TypeError: a limit is not anint, for examplemax_size="10MB". Aboolis not aninthere.TypeError:allowed_typesis astr, or has an item that is not astr.ValueError: a limit is out of range,min_sizeis abovemax_size, orallowed_typesis empty.
These errors occur when you call File().
A file that fails a check gets a 422 response with the type file_missing, file_too_large, file_too_small, file_invalid_content_type or file_too_many.
The BOLT_MAX_UPLOAD_SIZE setting limits the whole body before these checks. See the settings reference.
from django_bolt import FileSize, UploadFile
from django_bolt.params import File
@api.post("/articles/{article_id}/cover")
async def upload_cover(
article_id: int,
cover: Annotated[UploadFile, File(max_size=FileSize.MB_2, allowed_types=["image/png", "image/jpeg"])],
) -> dict:
return {"article_id": article_id, "filename": cover.filename, "size": cover.size}
FileSize¶
django_bolt.FileSize is an IntEnum of sizes in bytes, for max_size and min_size.
The members are MB_1 to MB_10 in steps of 1, and MB_20 to MB_100 in steps of 10. One MB is 1,048,576 bytes.
Depends()¶
Give the argument the return value of a function. The function can take request values as a handler does.
| Parameter | Type | Default | Description |
|---|---|---|---|
dependency |
Callable \| None |
None |
The function to call. It can be sync or async. Depends() with no function raises TypeError when you register the route. |
use_cache |
bool |
True |
Call the function one time for each request, also when more than one argument needs it. False calls it for each argument. |
import msgspec
from django_bolt import Depends
class Pagination(msgspec.Struct):
page: int
page_size: int
async def pagination(page: int = 1, page_size: Annotated[int, Query(le=100)] = 20) -> Pagination:
return Pagination(page=page, page_size=page_size)
@api.get("/articles")
async def list_articles(paging: Annotated[Pagination, Depends(pagination)]) -> dict:
return {"page": paging.page, "page_size": paging.page_size}
See Dependencies.
Param¶
Param is the frozen dataclass that each marker function returns. Its fields are source, default, the arguments of the marker functions, and multiple_of.
You do not need to make a Param yourself.
UploadFile¶
The value of an UploadFile argument. Bolt makes it. Do not make one yourself.
| Attribute | Type | Description |
|---|---|---|
filename |
str |
The file name that the client sent. |
content_type |
str |
The content type of the part. The default is "application/octet-stream". |
size |
int |
The size in bytes. |
headers |
dict[str, str] |
The headers of the multipart part. |
file |
django.core.files.File |
A Django File of the content. Assign it to a FileField or an ImageField. |
raw_file |
file object | The file object that holds the content. |
rolled_to_disk |
bool |
True when the content is in a temporary file. |
| Method | Description |
|---|---|
await read(size=-1) |
Read size bytes, or all the bytes for -1. |
await seek(offset, whence=0) |
Move the position. Return the new position. |
await write(data) |
Write bytes. Return the number of bytes. |
await close() |
Close the file. |
A file larger than the BOLT_MEMORY_SPOOL_THRESHOLD setting is in a temporary file. The async methods then run the file operation in a thread.
Bolt closes each UploadFile and removes its temporary file after the response.