TSP → Python conversions

[mauriciogardini]

TSP → Python conversions

This document reflects the current implementation proposed in #8966.

These conversion patterns aim to cover Python 3.11+.

---

Models with arbitrary number of properties (Record spreads)

Status: ❌ NOT IMPLEMENTED

Due to limitations on how to handle a dynamic number of properties, Record-based models are currently not supported.

Record model

TSP:

model Person is Record<T>;

Python:

# Throws error:
# "Models with additional properties (Record[…]) are not supported"

Model with is operator to Record

TSP:

model Person is Record<string> {
  name: string;
}

Python:

# Throws error:
# "Models with additional properties (Record[…]) are not supported"

Model that extends a Record

TSP:

model Person extends Record<string> {
  name: string;
}

Python:

# Throws error:
# "Models with additional properties (Record[…]) are not supported"

Model that has a spread to a Record

TSP:

model Person {
  name: string;
  ...Record<string>;
}

Python:

# Throws error:
# "Models with additional properties (Record[…]) are not supported"

---

Basic Models

Model

TSP:

model User {
  id: int32;
  name: string;
}

Python:

from dataclasses import dataclass

@dataclass(kw_only=True)
class User:
    id: int
    name: str

Model with a field that can be null

TSP:

model Person {
  age: int32;
  address: string | null;
}

Python:

from dataclasses import dataclass

@dataclass(kw_only=True)
class Person:
    age: int
    address: str | None

Model with an optional field

TSP:

model User {
  id: int32;
  name?: string;
}

Python:

from dataclasses import dataclass
from typing import Optional

@dataclass(kw_only=True)
class User:
    id: int
    name: Optional[str] = None

Note: Optional fields (?) without an explicit default value automatically get = None in Python dataclasses, unless omitNone is provided.

Model with a field that has a default

TSP:

model User {
  id: int32;
  name: string = "John";
}

Python:

from dataclasses import dataclass

@dataclass(kw_only=True)
class User:
    id: int
    name: str = "John"

Model with an optional field that can be null

TSP:

model User {
  id: int32;
  name?: string | null;
}

Python:

from dataclasses import dataclass
from typing import Optional

@dataclass(kw_only=True)
class User:
    id: int
    name: Optional[str] = None

Note: When a field is both optional (?) and nullable (| null), Python represents this with Optional[T] and a default value of None.

Model with literal union types

TSP:

model Response {
  status: "success" | "error";
  code: 200 | 404 | 500;
  active: true | false;
}

Python:

from dataclasses import dataclass
from typing import Literal

@dataclass(kw_only=True)
class Response:
    status: Literal["success", "error"]
    code: Literal[200, 404, 500]
    active: Literal[True, False]

---

Never Type

Model with never-typed property

TSP:

model Widget {
  property: never;
}

Python:

from dataclasses import dataclass
from typing import Never

@dataclass(kw_only=True)
class Widget:
    property: Never

Generic model instantiated with never (using 'is')

TSP:

model Address<TState> {
  state: TState;
  city: string;
  street: string;
}

model CanadaAddress is Address<never>;

Python:

from dataclasses import dataclass
from typing import Generic, Never, TypeVar

TState = TypeVar("TState")

@dataclass(kw_only=True)
class Address(Generic[TState]):
    state: TState
    city: str
    street: str

@dataclass(kw_only=True)
class CanadaAddress:
    state: Never
    city: str
    street: str

Generic model instantiated with never (using 'extends')

TSP:

model Address<TState> {
  state: TState;
  city: string;
}

model CanadaAddress extends Address<never> {
  street: string;
}

Python:

from dataclasses import dataclass
from typing import Generic, Never, TypeVar

TState = TypeVar("TState")

@dataclass(kw_only=True)
class Address(Generic[TState]):
    state: TState
    city: str

@dataclass(kw_only=True)
class CanadaAddress(Address[Never]):
    street: str

---

Model Inheritance

Model Inheritance - Extends

TSP:

model Animal {
  species: string;
}

model Dog extends Animal {
  age: int32;
}

Python:

from dataclasses import dataclass

@dataclass(kw_only=True)
class Animal:
    species: str

@dataclass(kw_only=True)
class Dog(Animal):
    age: int

Model Inheritance - Spreads

TSP:

model Animal {
  species: string;
}

model Dog {
  ...Animal;
  age: int32;
}

Python:

from dataclasses import dataclass

@dataclass(kw_only=True)
class Animal:
    species: str

@dataclass(kw_only=True)
class Dog:
    species: str
    age: int

Model Inheritance - Is

TSP:

model Container<T> {
  value: T;
}

model StringContainer is Container<string>;

Python:

from dataclasses import dataclass
from typing import Generic, TypeVar

T = TypeVar("T")

@dataclass(kw_only=True)
class Container(Generic[T]):
    value: T

@dataclass(kw_only=True)
class StringContainer:
    value: str

Note: Using is with a generic model flattens the properties instead of using inheritance.

Model Inheritance - Extends with generic

TSP:

model Response<T> {
  data: T;
  status: string;
}

model ConcreteResponse extends Response<string> {
  timestamp: string;
}

Python:

from dataclasses import dataclass
from typing import Generic, TypeVar

T = TypeVar("T")

@dataclass(kw_only=True)
class Response(Generic[T]):
    data: T
    status: str

@dataclass(kw_only=True)
class ConcreteResponse(Response[str]):
    timestamp: str

---

Special Model Types

Model with Array base (is Array)

TSP:

model StringArray is Array<string>;

Python (using TypeDeclaration):

from typing import TypeAlias

string_array: TypeAlias = list[str]

Python (using ClassDeclaration):

class StringArray(list[str]):
    pass

Note: When using TypeDeclaration, array models are emitted as type aliases. When using ClassDeclaration, they become classes that inherit from list.

---

Unions

TSP:

union Pet {
  dog: Dog,
  cat: Cat,
}

Python:

from typing import TypeAlias

Pet: TypeAlias = Dog | Cat

---

Multiple Model Spreads

TSP:

model Animal {
  species: string;
}

model Pet {
  name: string;
}

model Dog {
  ...Animal;
  ...Pet;
}

Python:

from dataclasses import dataclass

@dataclass(kw_only=True)
class Animal:
    species: str

@dataclass(kw_only=True)
class Pet:
    name: str

@dataclass(kw_only=True)
class Dog:
    species: str
    name: str

---

Arrays and Records in properties

Arrays and Records in properties

TSP:

model Person {
  tags: string[];
  metadata: Record<string>;
}

Python:

from dataclasses import dataclass

@dataclass(kw_only=True)
class Person:
    tags: list[str]
    metadata: dict[str, str]

---

Interfaces

Interface

TSP:

interface Drawable {
  draw(): void;
}

Python:

from abc import ABC, abstractmethod
from dataclasses import dataclass

@dataclass(kw_only=True)
class Drawable(ABC):
    @abstractmethod
    def draw(self) -> None:
        pass

Interface with inheritance

TSP:

interface Shape {
  getArea(): float64;
}

interface Drawable extends Shape {
  draw(): void;
}

Python:

from abc import ABC, abstractmethod
from dataclasses import dataclass

@dataclass(kw_only=True)
class Shape(ABC):
    @abstractmethod
    def get_area(self) -> float:
        pass

@dataclass(kw_only=True)
class Drawable(ABC):
    @abstractmethod
    def get_area(self) -> float:
        pass
    
    @abstractmethod
    def draw(self) -> None:
        pass

Note: TypeSpec flattens interface inheritance. The Python emitter doesn't use inheritance (class Drawable(Shape, ABC)); instead, it includes all methods from parent interfaces directly in the child interface.

---

Operations

Note: The examples below show how operations would be emitted as standalone type aliases using TypeAliasDeclaration. In practice, operations are typically used within interfaces where they become abstract methods (see Interfaces section).

Operation

TSP:

@delete op delete(): void;

Python:

from typing import TypeAlias
from collections.abc import Callable

delete: TypeAlias = Callable[[], None]

Named operation reference

TSP:

@delete op delete(): void;

op deletePet is delete;

Python:

from typing import TypeAlias
from collections.abc import Callable

delete: TypeAlias = Callable[[], None]
delete_pet = delete

---

Enums

Enum with integer values

TSP:

enum Priority {
  Low: 1,
  Medium: 2,
  High: 3,
}

Python:

from enum import IntEnum

class Priority(IntEnum):
    LOW = 1
    MEDIUM = 2
    HIGH = 3

Enum with string values

TSP:

enum Direction {
  North: "North",
  East: "East",
  South: "South",
  West: "West",
}

Python:

from enum import StrEnum

class Direction(StrEnum):
    NORTH = "North"
    EAST = "East"
    SOUTH = "South"
    WEST = "West"

Enum extension

TSP:

enum Direction {
  North: "North",
  East: "East",
  South: "South",
  West: "West",
}

enum DirectionExt {
  ...Direction,
  NorthEast: "North East",
  NorthWest: "North West",
  SouthEast: "South East",
  SouthWest: "South West",
}

Python:

from enum import StrEnum

class Direction(StrEnum):
    NORTH = "North"
    EAST = "East"
    SOUTH = "South"
    WEST = "West"

class DirectionExt(StrEnum):
    NORTH = "North"
    EAST = "East"
    SOUTH = "South"
    WEST = "West"
    NORTH_EAST = "North East"
    NORTH_WEST = "North West"
    SOUTH_EAST = "South East"
    SOUTH_WEST = "South West"

Union as Enum

TSP:

union Status {
  active: "active",
  pending: "pending",
  deleted: "deleted",
}

Python:

from enum import StrEnum

class Status(StrEnum):
    ACTIVE = "active"
    PENDING = "pending"
    DELETED = "deleted"

Note: This conversion requires explicitly using <EnumDeclaration type={Status} />. By default, unions are emitted as type aliases.

---

Protocols (Alternative Interface Representation)

Note: By default, interfaces are emitted as ABC classes (see Interfaces section above). The Protocol pattern shown here is an alternative representation using ProtocolDeclaration component.

Operation as Protocol callback

When using ProtocolDeclaration for operations:

TSP:

op GetName(id: string): string;

Python:

from typing import Protocol

class GetName(Protocol):
    def __call__(self, id: str) -> str:
        ...

Interface as Protocol

When using ProtocolDeclaration for interfaces:

TSP:

interface WidgetOperations {
  getName(id: string): string;
  getAge(id: string): int32;
}

Python:

from typing import Protocol

class WidgetOperations(Protocol):
    def get_name(self, id: str) -> str:
        ...
    
    def get_age(self, id: str) -> int:
        ...

---

Tuples

Tuple type

TSP:

model Coordinates {
  position: [int32, int32];
}

Python:

from dataclasses import dataclass
from typing import Tuple

@dataclass(kw_only=True)
class Coordinates:
    position: Tuple[int, int]

---

Template Constraints (Bounded TypeVars)

Template parameter with upper bound constraint

TSP:

model Container<T extends string> {
  value: T;
}

Python:

from dataclasses import dataclass
from typing import Generic, TypeVar

t = TypeVar("T", bound=str)

@dataclass(kw_only=True)
class Container(Generic[T]):
    value: T

Multiple template parameters with mixed constraints

TSP:

model Result<T extends string, E> {
  value: T;
  error: E;
}

Python:

from dataclasses import dataclass
from typing import Generic, TypeVar

T = TypeVar("T", bound=str)
E = TypeVar("E")

@dataclass(kw_only=True)
class Result(Generic[T, E]):
    value: T
    error: E

[lmazuel]

My two cents:

Record

Using TypedDict is a good idea, but it relies on extra_items being available, which is PEP728 and it won't be a thing before at least Python 3.15 in October 2026 (we may get it sooner with typing-extensions, but that's an external dependency).

Also we could argue that for things like:

model Person is Record<string> {
  name: string;
}

This is more a model with extra items, than this is a record with a forced key. IOW, that it should be a dataclass (or whatever we're using for models). Making the whole model a TypedDict because it's also a record, feels like losing information, and potential breaking changes over time (adding a record later would shape the model entirely differently).

Model as dataclass

Dataclass may be limited compared to framework like Pydantic, in terms of expressing some TypeSpec features (visibility, XML annotations, wire name VS property name, etc.). The serialization and deserialization is quite weak, and will require extensive runtime implementation. I feel at this point, the community chose Pydantic for model, but it's an external dependency (and potentially an heavy one).

Nullability VS optionality

I see right now the proposal is to use NotRequired for optional (?), and Optional (aka | None) for nullable. First, NotRequired cannot be used outside of TypedDict, so the current proposal as it is wouldn't work. But mostly, it doesn't solve the runtime problem of what we expose to users. Let's say a receive a JSON without a key, or with null. What do I expose as received? None is not enough.
We solved this problem in Azure with considering that None means Optional, which is consistent with the definition of Optional being literally | None, and we treat nullability with a sentinel value (a constant in runtime called NULL. For instance, the code would look like:

import corehttp # runtime for generated code

m = callmethod()
assert m.foo is None # The key `foo` was not received
assert m.bar is corehttp.serialization.NULL # We received the `null` value

Default

Default value is server side in TypeSpec. So if you generated server code, it's fair to use default of dataclass. But if you generate client code, you don't want to do that. I'm not sure I have a clear answer here, since that's one of the TypeSpec feature that is difficult to model in Python without the context in which you're emitting.

Generic

It makes sense to me to map TypeSpec template to generic.

Inheritance and spreead

Makes sense to just use the Python inheritance for extends, and to spread the model. If wee want to get fancy, we could consider a mixin approach for the spread, that feels very Pythonic in intent.

Union

Model union as TypeAlias makes sense to me. For named union, I don't see the value in creating the Breed enumI don't see why users would use it, and it's not used for the type checker. Just because it's a named union in TypeSpec, shouldn't mean we need to create something special in Python.

I'm curious about what is planned for:

union Breed {
  beagle: "Beagle",
  shepherd: "GermanShepherd",
  retriever: "GoldenRetriever",
  string
}

We call that an "extensible enum" in the Azure world, meaning "If something is typed Breed, those are the known values, but there may be more.

Interface

Implementing interface as Protocol feels very server generation oriented. For client generation, we would want to generate actual code. I'm not sure how to deal with that in alloy, to consider both server and client generation.

I wonder if there is a gap here. Interface doesn't really mean in TypeSpec what we use it in usual object languages. Interface is a group of operations, so if we plan to generate operation a certain way, a group of operations should look like a generation of a group of operation (not sure I'm explaining this right :D).
IOW, interface in TypeSpec is not an abstract class.

Operation signature

Makes all sense to me.

Enum

Makes all sense to me.

[annatisch]

To add to some of @lmazuel's points...
(My thoughts are largely around client-side code)

Record, TypedDict and Dataclass

It looks like extra_items has already been ported to typing-extensions - so I think this would be safe. As far as external dependencies go, I consider this library to be generally equivalent to being the stdlib. I doubt things would be broken by this dependency.

I would agree here that dataclasses don't really have much built in de/serialization. While it offers ways to extend fields to add customizations - you'd basically end up re-implementing a good chunk of Pydantic on top of dataclasses.

Other disadvantages include:

• Potentially more difficult to patch the models for client-side customizations and conveniences.
• The dataclasses module and dataclass instances already have a number of utilities (e.g. asdict) that we would be unable to customize.

Having said that - I also wouldn't advocate building directly on top of Pydantic as a dependency. Maybe there's a middle ground - for example, Pydantic offers utils for creating a models from TypedDict and NamedTuple definitions - so if we give customers the framework they need to adopt Pydantic if they wish, maybe that could work?

TypedDicts could potentially make use of typing.Annotated - but then we're back at the same issues in using dataclasses in that we'd have to re-implement a de/serialization runtime, and they would be difficult (impossible?) to patch in client code.

Enums and Union

The named union example definitely feels on the complicated side. Though I'm not entirely sure from this example what the ultimate goal of the code we're trying to generate here. Do you have any links to specs making use of this pattern so I could see it in practice? I'm hoping we could find something simpler that would get the job done.

Regarding intersections, are we losing information here by only presenting the merged model? In other words, would a client need to know that this model is a combination? And if not - do the other ingredient classes still need to be public/generated?

The extensible enum scenario has definitely come up many times in Azure SDKs - as (at least by Azure REST API standards), adding a value to an enum is not a breaking change and can even happen without a version bump. So we need to make sure that not only was the generated client code resilient to this, but also that consumers of that client code would also be resilient. We ultimately landed on generating enums, that were also instances of str, with a metaclass that made them interchangeable with str.
This is pretty much now available in the stdlib as enum.StrEnum as of 3.11 (also IntEnum could be useful for similar reasons).
This wasn't perfect though, and we ended up with lots of Union typing.... but I think this problem definitely warrants some consideration.

Operations

Union return types can be difficult to use, as it forces a client to do an isinstance check to know what to do next.
This particular example though is not a pattern we'd hope to see in Python, as we prefer error cases to result in Exceptions being raised.
Where an API returns multiple potential responses we tend to prefer a literal discriminator pattern to determine what the returned object was rather than a type check.
Though the code presented in the example is really all we can do with the spec snippet provided - though I haven't seen many APIs using this pattern.

[mauriciogardini]

Thanks for all the discussion: the result of the discussions above (and others more) resulted on the Python Emitter Framework implementation that was landed yesterday in the Typespec repo: https://github.com/microsoft/typespec/tree/main/packages/emitter-framework/src/python