Automatic binding of request data
mainBlackSheep can automatically bind request data to handler parameters using type annotations and specialized classes like FromJSON and FromQuery.
JSON Body Binding
Use FromJSON[T] to automatically parse the JSON payload into a dataclass or Pydantic model.
Route Parameter Binding
Parameters in the handler function that match names in the route path (e.g., /:name) are automatically extracted.
Query Parameter Binding
- Implicit: If a parameter name does not match a route parameter, it is automatically treated as a query string parameter.
- Explicit: Use
FromQuery[T]to explicitly define how query parameters should be read and provide default values.
from dataclasses import dataclass
from blacksheep import Application, FromJSON, FromQuery, get, post
app = Application()
@dataclass
class CreateCatInput:
name: str
@post("/api/cats")
async def example(data: FromJSON[CreateCatInput]):
# data is bound from JSON payload
...
@get("/:culture_code/:area")
async def home(culture_code, area):
# parameters obtained from route matching names
return f"Request for: {culture_code} {area}"
@get("/api/products")
def get_products(
page: int = 1,
size: int = 30,
search: str = "",
):
# implicit query parameters with default values
...
@get("/api/products2")
def get_products2(
page: FromQuery[int] = FromQuery(1),
size: FromQuery[int] = FromQuery(30),
search: FromQuery[str] = FromQuery(""),
):
# explicit query parameters with default values
...