Prisma Client Python

A custom Prisma generator in Python is implemented by subclassing BaseGenerator and performing two distinct steps:

1. Metadata: Providing information about the generator (like its name and default output location) using the get_manifest() method which returns a Manifest object.
2. Generation: Processing the Prisma Schema AST (represented as DMMF) during the generate() step. The schema data is passed to this method via a Data object (or DefaultData).

Note that changes to the DMMF structure are not considered breaking changes by the library.

from prisma.generator import BaseGenerator, Manifest, DefaultData

class MyGenerator(BaseGenerator):
    def get_manifest(self) -> Manifest:
        return Manifest(
            name='My Generator',
            default_output='output.txt',
        )

    def generate(self, data: DefaultData) -> None:
        # Access schema via data.dmmf
        pass

The Mypy plugin improves type safety for included relations:

• Non-optional relations: If a relational field is explicitly passed via include, the plugin removes the Optional type from that field on the returned model. Note that if no records are found, the field will be an empty list rather than None.
• Optional relations: If a relation is defined as optional in your Prisma schema, the field will still be typed as Optional even when explicitly included.
• Limitation: Dynamic include values (e.g., building an include dictionary at runtime) are not currently supported by the plugin and will trigger a parsing warning.

# Example of non-optional relation being correctly typed after include
user = await db.user.find_unique(
    where={
        'id': 'user_id',
    },
    include={
        'posts': True
    }
)
# user.posts is not treated as Optional here
print(f'User {user.name} has {len(user.posts)} posts')

Experimental Feature: Automatic Relation Fetching

To avoid explicitly specifying include in every query, you can define a custom model where a one-to-many relation is defined as a non-optional type. When you run a query using this custom model, Prisma Client Python will automatically fetch that relation.

Warning: This feature is experimental. Use it sparingly as automatic relational lookups can significantly impact performance if used unnecessarily.

Limitations:

• Currently only works for one-to-many relations.
• Does not work for one-to-one relational fields.

from typing import List
from prisma.models import Character
from prisma.bases import BaseUser

class UserWithCharacters(BaseUser):
  id: str
  name: str
  characters: List[Character]

# This query will automatically include the 'characters' relation
user = await UserWithCharacters.prisma().find_unique(
  where={
    'id': '<user id>',
  },
)
print(user.name)
print(user.characters[0].strength)

Every project starts with a schema.prisma file. To use Prisma Client Python, you must include a generator block with the provider set to prisma-client-py. The schema also requires a datasource block to define your database connection and model blocks to define your application data models.

Key configuration options for the generator:

• provider: Must be set to "prisma-client-py".
• recursive_type_depth: (Optional) Controls the depth of recursive types.
• output: (Optional) Defines where the client will be generated. By default, it is generated into the same location where the package was installed.

datasource db {
  provider = "sqlite"
  url      = "file:database.db"
}

generator client {
  provider             = "prisma-client-py"
  recursive_type_depth = 5
}

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  views     Int     @default(0)
  published Boolean @default(false)
  author    User?   @relation(fields: [author_id], references: [id])
  author_id Int?
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

Prisma Client Python allows you to create 'partial models' at generation time. These are specialized versions of your schema-defined models that contain only a subset of fields, with custom requirements for whether those fields are optional or required. This is useful for creating specific data shapes for different parts of your application (e.g., a UserSummary vs a UserFullProfile).

Partial types are generated using the create_partial static method on a model class. You define the shape by specifying which fields to include or exclude, which to make required or optional, and how to handle relations.

class Model:
  @staticmethod
  def create_partial(
      name: str,
      include: Optional[Iterable['{{ model }}Keys']] = None,
      exclude: Optional[Iterable['{{ model }}Keys']] = None,
      required: Optional[Iterable['{{ model }}Keys']] = None,
      optional: Optional[Iterable['{{ model }}Keys']] = None,
      relations: Optional[Mapping['{{ model }}RelationalKeys', str]] = None,
      exclude_relational_fields: bool = False,
  ) -> None:
      ...