Skip to content

# Usage

The main functionality this library intends to provide is a means to automatically generate Pydantic models based on Django ORM model definitions. Most of the Pydantic model properties are expected to work with the generated model schemas.

In addition to this, the model schemas provide a `from_orm` method for loading Django object instance data to be used with Pydantic's model export methods.

## Creating a model schema

The `ModelSchema` class can be used to generate a Pydantic model that maps to a Django model's fields automatically, and they also support customization using type annotations and field configurations.

Consider the following model definition for a user in Django:

    from django.db import models

    class User(models.Model):
        """
        A user of the application.
        """
        first_name = models.CharField(max_length=50)
        last_name = models.CharField(max_length=50, null=True, blank=True)
        email = models.EmailField(unique=True)
        created_at = models.DateTimeField(auto_now_add=True)
        updated_at = models.DateTimeField(auto_now=True)

A custom `ModelSchema` class could then be configured for this model:

    from djantic import ModelSchema
    from myapp.models import User

    class UserSchema(ModelSchema):
        class Config:
            model = User

Once defined, the `UserSchema` can be used to perform various functions on the underlying Django model object, such as generating JSON schemas or exporting serialized instance data.

### Basic schema usage

The `UserSchema` above can be used to generate a JSON schema using Pydantic's schema method:

    print(UserSchema.schema())

Output:

    {
            "title": "UserSchema",
            "description": "A user of the application.",
            "type": "object",
            "properties": {
                "profile": {"title": "Profile", "description": "None", "type": "integer"},
                "id": {"title": "Id", "description": "id", "type": "integer"},
                "first_name": {
                    "title": "First Name",
                    "description": "first_name",
                    "maxLength": 50,
                    "type": "string",
                },
                "last_name": {
                    "title": "Last Name",
                    "description": "last_name",
                    "maxLength": 50,
                    "type": "string",
                },
                "email": {
                    "title": "Email",
                    "description": "email",
                    "maxLength": 254,
                    "type": "string",
                },
                "created_at": {
                    "title": "Created At",
                    "description": "created_at",
                    "type": "string",
                    "format": "date-time",
                },
                "updated_at": {
                    "title": "Updated At",
                    "description": "updated_at",
                    "type": "string",
                    "format": "date-time",
                },
            },
            "required": ["first_name", "email", "created_at", "updated_at"],
        }

By default, all of the fields in a Django model will be included in the model schema produced using the details of each field's configuration.

### Customizing the schema

By default, the docstrings and help text of the Django model definition is used to populate the various titles and descriptive text and constraints in the schema outputs.

However, the model schema class itself can be used to override this behaviour:

    from pydantic import Field, constr
    from djantic import ModelSchema
    from myapp.models import User

    class UserSchema(ModelSchema):
        """
        My custom model schema.
        """
        first_name: str = Field(
            None,
            title="The user's first name",
            description="This is the user's first name",
        )
        last_name: constr(strip_whitespace=True)

        class Config:
            model = User
            title = "My user schema"

Output:

    {
        "title": "My user schema",
        "description": "My custom model schema.",
        "type": "object",
        "properties": {
            "id": {"title": "Id", "description": "id", "type": "integer"},
            "first_name": {
                "title": "The user's first name",
                "description": "This is the user's first name",
                "type": "string",
            },
            "last_name": {"title": "Last Name", "type": "string"},
            "email": {
                "title": "Email",
                "description": "email",
                "maxLength": 254,
                "type": "string",
            },
            "created_at": {
                "title": "Created At",
                "description": "created_at",
                "type": "string",
                "format": "date-time",
            },
            "updated_at": {
                "title": "Updated At",
                "description": "updated_at",
                "type": "string",
                "format": "date-time",
            },
        },
        "required": ["first_name", "last_name", "email", "created_at", "updated_at"],
    }

Model schemas also support using standard Python type annotations and field inclusion/exclusion configurations to customize the schemas beyond the definitions inferred from the Django model.

For example, the `last_name` field in the Django model is considered optional because of the `null=True` and `blank=True` parameters in the field definition, and the `first_name` field is required.

These details can be modified by defining specific field rules using type annotations, and the schema fields can limited using the `include` (or `exclude`) configuration setting:

    class UserSchema(ModelSchema):
        first_name: Optional[str]
        last_name: str

        class Config:
            model = User
            include = ["first_name", "last_name"]

Output:

    {
        "description": "A user of the application.",
        "properties": {
            "first_name": {"title": "First Name", "type": "string"},
            "last_name": {"title": "Last Name", "type": "string"},
        },
        "required": ["last_name"],
        "title": "UserSchema",
        "type": "object",
    }

## Handling related objects

Database relations (many to one, one to one, many to many) are also supported in the schema definition. Generic relations are also supported, but not extensively tested.

Consider the initial `User` model in creating a schema, but with the addition of a `Profile` model containing a one to one relationship:

    from django.db import models

    class User(models.Model):
        """
        A user of the application.
        """
        first_name = models.CharField(max_length=50)
        last_name = models.CharField(max_length=50, null=True, blank=True)
        email = models.EmailField(unique=True)
        created_at = models.DateTimeField(auto_now_add=True)
        updated_at = models.DateTimeField(auto_now=True)

    class Profile(models.Model):
        """
        A user's profile.
        """
        user = models.OneToOneField(User, on_delete=models.CASCADE, related_name="profile")
        website = models.URLField(default="", blank=True)
        location = models.CharField(max_length=100, default="", blank=True)

The new `Profile` relationship would be available to the generated model schema:

    from djantic import ModelSchema
    from myapp.models import User

    class UserSchema(ModelSchema):
        class Config:
            model = User
            include = ["id", "email", "profile"]

    print(UserSchema.schema())

Output:

    {
        "title": "UserSchema",
        "description": "A user of the application.",
        "type": "object",
        "properties": {
            "profile": {"title": "Profile", "description": "id", "type": "integer"},
            "id": {"title": "Id", "description": "id", "type": "integer"},
            "email": {
                "title": "Email",
                "description": "email",
                "maxLength": 254,
                "type": "string",
            },
        },
        "required": ["email"],
    }

Note: The initial `UserSchema` example in creating a schema could be used without modification. The `include` list here is used to reduce the example output and is not required for relations support.

#### Related schema models

The auto-generated `profile` definition can be expanded using an additional model schema set on the user schema:

    class ProfileSchema(ModelSchema):
        class Config:
            model = Profile

    class UserSchema(ModelSchema):
        profile: ProfileSchema

        class Config:
            model = User
            include = ["id", "profile"]

    print(UserSchema.schema())

Output:

    {
        "title": "UserSchema",
        "description": "A user of the application.",
        "type": "object",
        "properties": {
            "profile": {"$ref": "#/definitions/ProfileSchema"},
            "id": {"title": "Id", "description": "id", "type": "integer"},
        },
        "required": ["profile"],
        "definitions": {
            "ProfileSchema": {
                "title": "ProfileSchema",
                "description": "A user's profile.",
                "type": "object",
                "properties": {
                    "id": {"title": "Id", "description": "id", "type": "integer"},
                    "user": {"title": "User", "description": "id", "type": "integer"},
                    "website": {
                        "title": "Website",
                        "description": "website",
                        "default": "",
                        "maxLength": 200,
                        "type": "string",
                    },
                    "location": {
                        "title": "Location",
                        "description": "location",
                        "default": "",
                        "maxLength": 100,
                        "type": "string",
                    },
                },
                "required": ["user"],
            }
        },
    }

These schema relationships also work in reverse:

    class UserSchema(ModelSchema):
        class Config:
            model = User
            include = ["id", "email"]

    class ProfileSchemaWithUser(ModelSchema):
        user: UserSchema

        class Config:
            model = Profile
            include = ["id", "user"]

    print(ProfileSchemaWithUser.schema())

Output:

    {
        "title": "ProfileSchemaWithUser",
        "description": "A user's profile.",
        "type": "object",
        "properties": {
            "id": {"title": "Id", "description": "id", "type": "integer"},
            "user": {"$ref": "#/definitions/UserSchema"},
        },
        "required": ["user"],
        "definitions": {
            "UserSchema": {
                "title": "UserSchema",
                "description": "A user of the application.",
                "type": "object",
                "properties": {
                    "id": {"title": "Id", "description": "id", "type": "integer"},
                    "email": {
                        "title": "Email",
                        "description": "email",
                        "maxLength": 254,
                        "type": "string",
                    },
                },
                "required": ["email"],
            }
        },
    }

The above behaviour works similarly to one to many and many to many relations. You can see more examples in the tests.

## Exporting model data

Model schemas support a `from_orm` method that allows loading Django model instances for export using the generated schema. This method is similar to Pydantic's builtin from_orm, but very specific to Django's ORM.

It is intended to provide support for all of Pydantic's model export methods.

### Basic export usage

Create one or more Django model instances to be used when populating the model schema:

    user = User.objects.create(
        first_name="Jordan", last_name="Eremieff", email="jordan@eremieff.com"
    )
    profile = Profile.objects.create(user=user, website="https://github.com", location="AU")

Then use the `from_orm` method to load this object:

    from djantic import ModelSchema
    from myapp.models import User

    class ProfileSchema(ModelSchema):
        class Config:
            model = Profile
            exclude = ["user"]

    class UserSchema(ModelSchema):
        profile: ProfileSchema

        class Config:
            model = User

    user = User.objects.get(id=1)
    obj = UserSchema.from_orm(user)

Now that the instance is loaded, it can be used with the various export methods to produce different outputs according to the schema definition. These outputs will be validated against the schema rules:

#### model.dict()

    print(obj.dict())

Output:

        {
        "profile": {"id": 1, "website": "https://github.com", "location": "AU"},
        "id": 1,
        "first_name": "Jordan",
        "last_name": "Eremieff",
        "email": "jordan@eremieff.com",
        "created_at": datetime.datetime(2021, 4, 4, 8, 47, 39, 567410, tzinfo=<UTC>),
        "updated_at": datetime.datetime(2021, 4, 4, 8, 47, 39, 567455, tzinfo=<UTC>)
    }

#### model.json()

    print(obj.json(indent=2))

Output:

    {
      "profile": {
        "id": 1,
        "website": "https://github.com",
        "location": "AU"
      },
      "id": 1,
      "first_name": "Jordan",
      "last_name": "Eremieff",
      "email": "jordan@eremieff.com",
      "created_at": "2021-04-04T08:47:39.567410+00:00",
      "updated_at": "2021-04-04T08:47:39.567455+00:00"
    }