Expand documentation

[surenkov]

The docs we have at the moment only cover essential use cases, with lots of details missing. This indeed should be expanded. What should be added, to my knowledge:

• [x] Specify a minimal required python version.
• [ ] Explicitly state supported pydantic features.
• [ ] Describe field internal behavior, demonstrating behavior of model wrapping.
• [ ] Also describe model's config resolution, as maybe it's not what you expect to see.
• [ ] Add Working with migrations section -- I had to introdice some internal machinery to support Generic Aliases.
• [ ] Expand DRF support section. At the moment it contains almost only code samples.

[taobojlen]

hi @surenkov, thank you for this library! i was looking for something exactly like this, so it was very cool to find your project.

i'm curious about migrations -- do you have a high-level overview of how to handle these, e.g. adding a new required field to a pydantic model? i'd be happy to write up some more formal docs as a PR if you can point me in the right direction!

[surenkov]

@taobojlen thank you, glad you've found that library useful!

Speaking of migrations -- it is arguable question whether non-relational data structures need migrations at all. A common approach I saw in the wild is to leave old data as it is, and expand type annotations with versioning. Thus, such schemes could be described with union types:

import typing
import pydantic
from django.db import models

class SchemaV1(pydantic.BaseModel):
    version: typing.Literal[1] = 1  # fall back for the initial schema if not specified
    foo: str

class SchemaV2(pydantic.BaseModel):
    version: typing.Literal[2]  # should be explicitly specified in the raw data
    foo: str
    bar: int

class DjangoModel(models.Model):
   schema_field: SchemaV1 | SchemaV2 = SchemaField()

With this approach, we can rely on both existing and new structures, preserve flexibility of NoSQL storage, and still have some type guarantees.