This project extends Django Rest Framework to allow use of Python's type annotations for automatically validating and casting view parameters. This pattern makes for code that is easier to read and write. View inputs are individually declared, not buried inside all-encompassing request
objects. Meanwhile, you get even more out of type annotations: they can replace repetitive validation/sanitization code.
More features:
- Pydantic models and Marshmallow schemas are compatible types for view parameters. Annotate your POST/PUT functions with them to automatically validate incoming request bodies.
- Advanced validators for more than just the type:
min_value
/max_value
for numbers - Validate string formats:
email
,uuid
andipv4/6
; use Python's nativeEnum
for "choices" validation
Quick example:
from rest_typed_views import typed_api_view
@typed_api_view(["GET"])
def get_users(registered_on: date = None, groups: List[int] = None, is_staff: bool = None):
print(registered_on, groups, is_staff)
GET /users/registered/?registered_on=2019-03-03&groups=4,5&is_staff=yes
Status Code: 200
date(2019, 3, 3) [4, 5] True
GET /users/?registered_on=9999&groups=admin&is_staff=maybe
๐ซ Status Code: 400 ValidationError raised
{
"registered_on": "'9999' is not a valid date",
"groups": "'admin' is not a valid integer",
"is_staff": "'maybe' is not a valid boolean"
}
- Install & Decorators
- How It Works: Simple Usage
- How It Works: Advanced Usage
- Enabling Marshmallow, Pydantic Schemas
- Request Element Classes
- Supported Types/Validator Rules
- Change Log
- Motivation & Inspiration
pip install drf-typed-views
You can add type annotation-enabled features to either ViewSet
methods or function-based views using the typed_action
and typed_api_view
decorators. They take the exact same arguments as Django REST's api_view
and action
decorators.
For many cases, you can rely on implicit behavior for how different parts of the request (URL path variables, query parameters, body) map to the parameters of a view function/method.
The value of a view parameter will come from...
- the URL path if the path variable and the view argument have the same name, or:
- the request body if the view argument is annotated using a class from a supported library for complex object validation (Pydantic, MarshMallow), or:
- a query parameter with the same name
Unless a default value is given, the parameter is required and a ValidationError
will be raised if not set.
urlpatterns = [
url(r"^(?P<city>[\w+])/restaurants/", search_restaurants)
]
from rest_typed_views import typed_api_view
# Example request: /chicago/restaurants?delivery=yes
@typed_api_view(["GET"])
def search_restaurants(city: str, rating: float = None, offers_delivery: bool = None):
restaurants = Restaurant.objects.filter(city=city)
if rating is not None:
restaurants = restaurants.filter(rating__gte=rating)
if offers_delivery is not None:
restaurants = restaurants.filter(delivery=offers_delivery)
In this example, city
is required and must be its string. Its value comes from the URL path variable with the same name. The other parameters, rating
and offers_delivery
, are not part of the path parameters and are assumed to be query parameters. They both have a default value, so they are optional.
# urls.py
urlpatterns = [url(r"^(?P<city>[\w+])/bookings/", create_booking)]
# settings.py
DRF_TYPED_VIEWS = {"schema_packages": ["pydantic"]}
# views.py
from pydantic import BaseModel
from rest_typed_views import typed_api_view
class RoomEnum(str, Enum):
double = 'double'
twin = 'twin'
single = 'single'
class BookingSchema(BaseModel):
start_date: date
end_date: date
room: RoomEnum = RoomEnum.double
include_breakfast: bool = False
# Example request: /chicago/bookings/
@typed_api_view(["POST"])
def create_booking(city: str, booking: BookingSchema):
# do something with the validated booking...
In this example, city
will again be populated using the URL path variable. The booking
parameter is annotated using a supported complex schema class (Pydantic), so it's assumed to come from the request body, which will be read in as JSON, used to hydrate the Pydantic BookingSchema
and then validated. If validation fails a ValidationError
will be raised.
For more advanced use cases, you can explicitly declare how each parameter's value is sourced from the request -- from the query parameters, path, body or headers -- as well as define additional validation rules. You import a class named after the request element that is expected to hold the value and assign it to the parameter's default.
from rest_typed_views import typed_api_view, Query, Path
@typed_api_view(["GET"])
def list_documents(year: date = Path(), title: str = Query(default=None)):
# ORM logic here...
In this example, year
is required and must come from the URL path and title
is an optional query parameter because the default
is set. This is similar to Django REST's serializer fields: passing a default implies that the filed is not required.
from rest_typed_views import typed_api_view, Header
@typed_api_view(["GET"])
def get_cache_header(cache: str = Header()):
# ORM logic here...
In this example, cache
is required and must come from the headers.
You can use the request element class (Query
, Path
, Body
, Header
) to set additional validation constraints. You'll find that these keywords are consistent with Django REST's serializer fields.
from rest_typed_views import typed_api_view, Query, Path
@typed_api_view(["GET"])
def search_restaurants(
year: date = Path(),
rating: int = Query(default=None, min_value=1, max_value=5)
):
# ORM logic here...
@typed_api_view(["GET"])
def get_document(id: str = Path(format="uuid")):
# ORM logic here...
@typed_api_view(["GET"])
def search_users(
email: str = Query(default=None, format="email"),
ip_address: str = Query(default=None, format="ip"),
):
# ORM logic here...
View a full list of supported types and additional validation rules.
Similar to how source
is used in Django REST to control field mappings during serialization, you can use it to specify the exact path to the request data.
from pydantic import BaseModel
from rest_typed_views import typed_api_view, Query, Path
class Document(BaseModel):
title: str
body: str
"""
POST
{
"strict": false,
"data": {
"title": "A Dark and Stormy Night",
"body": "Once upon a time"
}
}
"""
@typed_api_view(["POST"])
def create_document(
strict_mode: bool = Body(source="strict"),
item: Document = Body(source="data")
):
# ORM logic here...
You can also use dot-notation to source data multiple levels deep in the JSON payload.
For the basic case of list validation - validating types within a comma-delimited string - declare the type to get automatic validation/coercion:
from rest_typed_views import typed_api_view, Query
@typed_api_view(["GET"])
def search_movies(item_ids: List[int] = [])):
print(item_ids)
# GET /movies?items_ids=41,64,3
# [41, 64, 3]
But you can also specify min_length
and max_length
, as well as the delimiter
and specify additional rules for the child items -- think Django REST's ListField.
Import the generic Param
class and use it to set the rules for the child
elements:
from rest_typed_views import typed_api_view, Query, Param
@typed_api_view(["GET"])
def search_outcomes(
scores: List[int] = Query(delimiter="|", child=Param(min_value=0, max_value=100))
):
# ORM logic ...
@typed_api_view(["GET"])
def search_message(
recipients: List[str] = Query(min_length=1, max_length=10, child=Param(format="email"))
):
# ORM logic ...
You probably won't need to access the request
object directly, as this package will provide its relevant properties as view arguments. However, you can include it as a parameter annotated with its type and it will be injected:
from rest_framework.request import Request
from rest_typed_views import typed_api_view
@typed_api_view(["GET"])
def search_documens(request: Request, q: str = None):
# ORM logic ...
Often, it's useful to validate a combination of query parameters - for instance, a start_date
shouldn't come after an end_date
. You can use complex schema object (Pydantic or Marshmallow) for this scenario. In the example below, Query(source="*")
is instructing an instance of SearchParamsSchema
to be populated/validated using all of the query parameters together: request.query_params.dict()
.
from marshmallow import Schema, fields, validates_schema, ValidationError
from rest_typed_views import typed_api_view
class SearchParamsSchema(Schema):
start_date = fields.Date()
end_date = fields.Date()
@validates_schema
def validate_numbers(self, data, **kwargs):
if data["start_date"] >= data["end_date"]:
raise ValidationError("end_date must come after start_date")
@typed_api_view(["GET"])
def search_documens(search_params: SearchParamsSchema = Query(source="*")):
# ORM logic ...
You can apply some very basic access control by applying some validation rules to a view parameter sourced from the CurrentUser
request element class. In the example below, a ValidationError
will be raised if the request.user
is not a member of either super_users
or admins
.
from my_pydantic_schemas import BookingSchema
from rest_typed_views import typed_api_view, CurrentUser
@typed_api_view(["POST"])
def create_booking(
booking: BookingSchema,
user: User = CurrentUser(member_of_any=["super_users", "admins"])
):
# Do something with the request.user
Read more about the Current User
request element class.
As an alternative to Django REST's serializers, you can annotate views with Pydantic models or Marshmallow schemas to have their parameters automatically validated and pass an instance of the Pydantic/Marshmallow class to your method/function.
To enable support for third-party libraries for complex object validation, modify your settings:
DRF_TYPED_VIEWS = {
"schema_packages": ["pydantic", "marshmallow"]
}
These third-party packages must be installed in your virtual environment/runtime.
You can specify the part of the request that holds each view parameter by using default function arguments, for example:
from rest_typed_views import Body, Query
@typed_api_view(["PUT"])
def update_user(
user: UserSchema = Body(),
optimistic_update: bool = Query(default=False)
):
The user
parameter will come from the request body and is required because no default is provided. Meanwhile, optimistic_update
is not required and will be populated from a query parameter with the same name.
The core keyword arguments to these classes are:
default
the default value for the parameter, which is required unless setsource
if the view parameter has a different name than its key embedded in the request
Passing keywords for additional validation constraints is a powerful capability that gets you almost the same feature set as Django REST's flexible serializer fields. See a complete list of validation keywords.
Use the source
argument to alias the parameter value and pass keywords to set additional constraints. For example, your query parameters can have dashes, but be mapped to a parameter that have underscores:
from rest_typed_views import typed_api_view, Query
@typed_api_view(["GET"])
def search_events(
starting_after: date = Query(source="starting-after"),
available_tickets: int = Query(default=0, min_value=0)
):
# ORM logic here...
By default, the entire request body is used to populate parameters marked with this class (source="*"
):
from rest_typed_views import typed_api_view, Body
from my_pydantic_schemas import ResidenceListing
@typed_api_view(["POST"])
def create_listing(residence: ResidenceListing = Body()):
# ORM logic ...
However, you can also specify nested fields in the request body, with support for dot notation.
"""
POST /users/
{
"first_name": "Homer",
"last_name": "Simpson",
"contact": {
"phone" : "800-123-456",
"fax": "13235551234"
}
}
"""
from rest_typed_views import typed_api_view, Body
@typed_api_view(["POST"])
def create_user(
first_name: str = Body(source="first_name"),
last_name: str = Body(source="last_name"),
phone: str = Body(source="contact.phone", min_length=10, max_length=20)
):
# ORM logic ...
Use the source
argument to alias a view parameter name. More commonly, though, you can set additional validation rules for parameters coming from the URL path.
from rest_typed_views import typed_api_view, Query
@typed_api_view(["GET"])
def retrieve_event(id: int = Path(min_value=0, max_value=1000)):
# ORM logic here...
Use the Header
request element class to automatically retrieve a value from a header. Underscores in variable names are automatically converted to dashes.
from rest_typed_views import typed_api_view, Header
@typed_api_view(["GET"])
def retrieve_event(id: int, cache_control: str = Header(default="no-cache")):
# ORM logic here...
If you prefer, you can explicitly specify the exact header key:
from rest_typed_views import typed_api_view, Header
@typed_api_view(["GET"])
def retrieve_event(id: int, cache_control: str = Header(source="cache-control", default="no-cache")):
# ORM logic here...
Use this class to have a view parameter populated with the current user of the request. You can even extract fields from the current user using the source
option.
from my_pydantic_schemas import BookingSchema
from rest_typed_views import typed_api_view, CurrentUser
@typed_api_view(["POST"])
def create_booking(booking: BookingSchema, user: User = CurrentUser()):
# Do something with the request.user
@typed_api_view(["GET"])
def retrieve_something(first_name: str = CurrentUser(source="first_name")):
# Do something with the request.user's first name
You can also pass some additional parameters to the CurrentUser
request element class to implement simple access control:
member_of
(str) Validates that the currentrequest.user
is a member of a group with this namemember_of_any
(List[str]) Validates that the currentrequest.user
is a member of one of these groups
Using these keyword validators assumes that your User
model has a many-to-many relationship with django.contrib.auth.models.Group
via user.groups
.
An example:
from django.contrib.auth.models import User
from rest_typed_views import typed_api_view, CurrentUser
@typed_api_view(["GET"])
def do_something(user: User = CurrentUser(member_of="admin")):
# now have a user instance (assuming ValidationError wasn't raised)
The following native Python types are supported. Depending on the type, you can pass additional validation rules to the request element class (Query
, Path
, Body
). You can think of the type combining with the validation rules to create a Django REST serializer field on the fly -- in fact, that's what happens behind the scenes.
Additional arguments:
max_length
Validates that the input contains no more than this number of characters.min_length
Validates that the input contains no fewer than this number of characters.trim_whitespace
(bool; defaultTrue
) Whether to trim leading and trailing white space.format
Validates that the string matches a common format; supported values:email
validates the text to be a valid e-mail address.slug
validates the input against the pattern[a-zA-Z0-9_-]+
.uuid
validates the input is a valid UUID stringurl
validates fully qualified URLs of the formhttp://<host>/<path>
ip
validates input is a valid IPv4 or IPv6 stringipv4
validates input is a valid IPv4 stringipv6
validates input is a valid IPv6 stringfile_path
validates that the input corresponds to filenames in a certain directory on the filesystem; allows all the same keyword arguments as Django REST'sFilePathField
Some examples:
from rest_typed_views import typed_api_view, Query
@typed_api_view(["GET"])
def search_users(email: str = Query(format='email')):
# ORM logic here...
return Response(data)
@typed_api_view(["GET"])
def search_shared_links(url: str = Query(default=None, format='url')):
# ORM logic here...
return Response(data)
@typed_api_view(["GET"])
def search_request_logs(ip_address: str = Query(default=None, format='ip')):
# ORM logic here...
return Response(data)
Additional arguments:
max_value
Validate that the number provided is no greater than this value.min_value
Validate that the number provided is no less than this value.
An example:
from rest_typed_views import typed_api_view, Query
@typed_api_view(["GET"])
def search_products(inventory: int = Query(min_value=0)):
# ORM logic here...
Additional arguments:
max_value
Validate that the number provided is no greater than this value.min_value
Validate that the number provided is no less than this value.
An example:
from rest_typed_views import typed_api_view, Query
@typed_api_view(["GET"])
def search_products(price: float = Query(min_value=0)):
# ORM logic here...
Additional arguments:
max_value
Validate that the number provided is no greater than this value.min_value
Validate that the number provided is no less than this value.- .. even more ... accepts the same arguments as Django REST's
DecimalField
View parameters annotated with this type will validate and coerce the same values as Django REST's BooleanField
, including but not limited to the following:
true_values = ["yes", 1, "on", "y", "true"]
false_values = ["no", 0, "off", "n", "false"]
Additional arguments:
input_formats
A list of input formats which may be used to parse the date-time, defaults to Django'sDATETIME_INPUT_FORMATS
settings, which defaults to['iso-8601']
default_timezone
Apytz.timezone
of the timezone. If not specified, falls back to Django'sUSE_TZ
setting.
Additional arguments:
input_formats
A list of input formats which may be used to parse the date, defaults to Django'sDATETIME_INPUT_FORMATS
settings, which defaults to['iso-8601']
Additional arguments:
input_formats
A list of input formats which may be used to parse the time, defaults to Django'sTIME_INPUT_FORMATS
settings, which defaults to['iso-8601']
Validates strings of the format '[DD] [HH:[MM:]]ss[.uuuuuu]'
and converts them to a datetime.timedelta
instance.
Additional arguments:
max_value
Validate that the input duration is no greater than this value.min_value
Validate that the input duration is no less than this value.
Validates strings of the format '[DD] [HH:[MM:]]ss[.uuuuuu]'
and converts them to a datetime.timedelta
instance.
Additional arguments:
min_length
Validates that the list contains no fewer than this number of elements.max_length
Validates that the list contains no more than this number of elements.child
Pass keyword constraints via aParam
instance to to validate the members of the list.
An example:
from rest_typed_views import typed_api_view, Param, Query
@typed_api_view(["GET"])
def search_contacts(emails: List[str] = Query(max_length=10, child=Param(format="email"))):
# ORM logic here...
Validates that the value of the input is one of a limited set of choices. Think of this as mapping to a Django REST ChoiceField
.
An example:
from rest_typed_views import typed_api_view, Query
class Straws(str, Enum):
paper = "paper"
plastic = "plastic"
@typed_api_view(["GET"])
def search_straws(type: Straws = None):
# ORM logic here...
You can annotate view parameters with Marshmallow schemas to validate request data and pass an instance of the schema to the view.
from marshmallow import Schema, fields
from rest_typed_views import typed_api_view, Query
class ArtistSchema(Schema):
name = fields.Str()
class AlbumSchema(Schema):
title = fields.Str()
release_date = fields.Date()
artist = fields.Nested(ArtistSchema())
"""
POST
{
"title": "Michael Scott's Greatest Hits",
"release_date": "2019-03-03",
"artist": {
"name": "Michael Scott"
}
}
"""
@typed_api_view(["POST"])
def create_album(album: AlbumSchema):
# now have an album instance (assuming ValidationError wasn't raised)
You can annotate view parameters with Pydantic models to validate request data and pass an instance of the model to the view.
from pydantic import BaseModel
from rest_typed_views import typed_api_view, Query
class User(BaseModel):
id: int
name: str
signup_ts: datetime = None
friends: List[int] = []
"""
POST
{
"id": 24529782,
"name": "Michael Scott",
"friends": [24529782]
}
"""
@typed_api_view(["POST"])
def create_user(user: User):
# now have a user instance (assuming ValidationError wasn't raised)
- June 7, 2020
- Fixes compatability with DRF decorator. Thanks @sjquant!
- Makes Django's QueryDict work with Marshmallow and Pydantic validators. Thanks @filwaline!
- February 2, 2020: Adds support for
Header
request parameter. Thanks @bbkgh!
While REST Framework's ModelViewSets and ModelSerializers are very productive when building out CRUD resources, I've felt less productive in the framework when developing other types of operations. Serializers are a powerful and flexible way to validate incoming request data, but are not as self-documenting as type annotations. Furthermore, the Django ecosystem is hugely productive and I see no reason why REST Framework cannot take advantage of more Python 3 features.
I first came across type annotations for validation in API Star, which has since evolved into an OpenAPI toolkit. This pattern has also been offered by Hug and Molten (I believe in that order). Furthermore, I've borrowed ideas from FastAPI, specifically its use of default values to declare additional validation rules. Finally, this blog post from Instagram's engineering team showed me how decorators can be used to implement these features on view functions.