Skip to content
Genotype

Python Target Overview

Genotype generates idiomatic Python code that can be used directly in the application or published as a package.

This overview shows how Genotype types translate to Python, target-specific features and configuration options.

See the Quick Genotype Language Tour for the language overview and Python Configuration for detailed configuration reference.

Translation

Section titled “Translation”

The following examples give an overview of how Genotype translates into Python.

Complete Module

Section titled “Complete Module”

This source combines an object, a literal field, an optional field, a record, and any:

Book: {
  kind: "book",
  displayTitle: string,
  subtitle?: string,
  ratings: { []: int },
  extra: any,
}

The generated module includes its type definitions and imports:

from __future__ import annotations


from typing import Literal, Optional, Any
from pydantic import Field
from genotype import Model


class Book(Model):
    kind: Literal["book"]
    display_title: str = Field(alias="displayTitle")
    subtitle: Optional[str] = None
    ratings: dict[str, int]
    extra: Any

Unions

Section titled “Unions”

Genotype unions translate into Python union types. Legacy output uses Union[...].

Value: string | int
type Value = str | int

Primitives

Section titled “Primitives”

Numeric Types

Section titled “Numeric Types”
number
Section titled “number”

Genotype number translates into the Python float type.

Amount: number
type Amount = float
int
Section titled “int”

Genotype int translates directly to the Python int type.

Count: int
type Count = int
float
Section titled “float”

Genotype float translates directly to the Python float type.

Ratio: float
type Ratio = float
Sized Numeric Types
Section titled “Sized Numeric Types”

Sized Genotype integers translate into Python int, and sized floating-point types translate into float.

SmallCount: i16
PreciseRatio: f32
LargeCount: i128
type SmallCount = int


type PreciseRatio = float


type LargeCount = int

Booleans

Section titled “Booleans”

Genotype boolean translates into the Python bool type.

Ready: boolean
type Ready = bool

Strings

Section titled “Strings”

Genotype string translates into the Python str type.

Title: string
type Title = str

Literal Types

Section titled “Literal Types”

Genotype literal types translate into Python Literal types, preserving their exact values.

Category: "fiction"
type Category = Literal["fiction"]

Null

Section titled “Null”

Genotype null translates into Python Literal[None].

Empty: null
type Empty = Literal[None]

Branded Primitives

Section titled “Branded Primitives”

Genotype branded primitives translate into Python NewType definitions. Type checkers distinguish them; runtime values retain the underlying primitive.

BookId: @string
BookId = NewType("BookId", str)

Composite Types

Section titled “Composite Types”

Objects

Section titled “Objects”

Genotype objects translate into classes extending the Genotype runtime’s Pydantic-based Model. Nested objects become separate model classes.

Book: { title: string }
class Book(Model):
    title: str

Use Book.model_validate(data) to validate incoming data and book.model_dump() to serialize it. Field names use snake_case, with aliases preserving their original names in serialized data.

Optional Object Fields
Section titled “Optional Object Fields”

Optional Genotype object fields translate into Python Optional[T] fields, defaulting to None.

Draft: { subtitle?: string }
class Draft(Model):
    subtitle: Optional[str] = None
Object Extensions
Section titled “Object Extensions”

Genotype object extensions translate into Python model inheritance.

Named: { name: string }
NamedBook: { ...Named, pages: int }
class Named(Model):
    name: str


class NamedBook(Named, Model):
    pages: int

Arrays

Section titled “Arrays”

Genotype arrays translate into Python list[T] types. Legacy output uses List[T].

Titles: [string]
type Titles = list[str]

Tuples

Section titled “Tuples”

Genotype tuples translate into Python tuple types. Legacy output uses Tuple[...].

Point: (float, float)
type Point = tuple[float, float]

Records

Section titled “Records”

Genotype records translate into Python dict[K, V] types. Legacy output uses Dict[K, V]. An omitted key type means string keys.

Scores: { []: int }
type Scores = dict[str, int]

Special Data Types

Section titled “Special Data Types”

Any Type

Section titled “Any Type”

Genotype any translates into Python typing.Any.

Payload: any
type Payload = Any

Generic Types

Section titled “Generic Types”

Genotype generic types translate into Python generic models or aliases. You can specialize this model as Envelope[Book].

Envelope<Body>: { body: Body }
class Envelope[Body](Model):
    body: Body

Recursive Types

Section titled “Recursive Types”

Genotype recursive types translate into Python recursive types with forward references where needed.

LinkedNode: { value: string, next?: LinkedNode }
class LinkedNode(Model):
    value: str
    next: Optional[LinkedNode] = None

Annotations

Section titled “Annotations”

The discriminator annotation adds metadata to a union’s JSON Schema:

#[discriminator = "status"]
Result: Success | Failure


Success: { status: "ok", body: string }
Failure: { status: "error", message: string }

The generated union includes Pydantic field metadata identifying status as the discriminator. This adds schema metadata; it doesn’t configure Pydantic’s discriminated-union validation.

Configuration

Section titled “Configuration”

Use [py] in genotype.toml to configure Python. See the Python Configuration Reference for more details.

See Genotype Configuration for global settings and Common Target Options.