TSP → Python conversions

[mauriciogardini]

TSP → Python conversions

We are writing this simple doc in an effort to try to imagine the main conversion scenarios we need to take into consideration for the emitter-framework Python implementation.

These conversion patterns aim to cover Python 3.10+.

---

Models with arbitrary number of properties (Record spreads)

Due to limitations on how to handle a dynamic number of properties, we should use TypedDicts for these scenarios exclusively.

Record model

TSP	Python
model Person is Record<T>;	from typing_extensions import TypedDict class Person((TypedDict, extra_items=T)):     pass

Model with is operator to Record

TSP	Python
model Person is Record<string> {   name: string; }	from typing_extensions import TypedDict class Person(TypedDict, extra_items=str):     name: str

Model that extends a Record

TSP	Python
model Person extends Record<string> {   name: string; }	from typing_extensions import TypedDict class Person(TypedDict, extra_items=str):     name: str

Model that has a spread to a Record

TSP	Python
model Person {   age: int32;   ...Record<string>; }	from typing_extensions import TypedDict class Person(TypedDict, extra_items=str):     age: int

---

Models (Non-Record)

For these, use dataclasses.

Model

TSP	Python
model User {   id: int32;   name?: string; }	from dataclasses import dataclass from typing import NotRequired @dataclass class User:     id: int     name: NotRequired[str]

Model with a field that can be null

TSP	Python
model Person {   age: int32;   address: string | null; }	from dataclasses import dataclass @dataclass class Person:     age: int     address: str | None

Model with an optional field

TSP	Python
model Person {   age: int32;   address?: string; }	from dataclasses import dataclass from typing import NotRequired @dataclass class Person:     age: int     address: NotRequired[str]

Model with a field that has a default

TSP	Python
model Person {   age: int32;   address?: string = "N/A"; }	from dataclasses import dataclass from typing import NotRequired @dataclass class Person:     age: int     address: NotRequired[str] = "N/A"

Model with an optional field that can be null

TSP	Python
model Person {   age: int32;   address?: str | null; }	from dataclasses import dataclass from typing import NotRequired @dataclass class Person:     age: int     address: NotRequired[str | None]

Model with a special property type - never

TSP	Python
model Address<TState> {   state: TState;   city: string;   street: string; } model UKAddress is Address<never>;	from dataclasses import dataclass from typing import Generic, TypeVar TState = TypeVar('TState') @dataclass class Address(Generic[TState]):     state: TState     city: str     street: str @dataclass class UKAddress:     city: str     street: str

Model that extends a generic with never

TSP

Python

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

from dataclasses import dataclass, field from typing import Literal, TypeVar, Generic, Never TState = TypeVar('TState') @dataclass class Address(Generic[TState]):     state: TState     city: str @dataclass class UKAddress(Address[Never]):     state: Never = field(init=False, repr=False, compare=False)     street: str # Examples address = Address(“CA”, “San Francisco”) yields Address(state='CA', city='San Francisco') ukAddress = UKAddress(“London”, “221B Baker Street”) yields UKAddress(city='London', street='221B Baker Street')

Model Inheritance - Extends

TSP	Python
model Identified {   id: int32; } model Admin extends Identified {   role: "admin"; }	from dataclasses import dataclass from typing import Literal @dataclass class Identified:     id: int @dataclass class Admin(Identified):     role: Literal["admin"]

Model Inheritance - Spreads

TSP	Python
model Animal {   species: string; } model Dog {   ...Animal;   age: int32; }	from dataclasses import dataclass @dataclass class Animal:     species: str @dataclass class Dog:     species: str     age: int

Model Inheritance - Is

TSP	Python
model Thing<T> {   property: T; } model StringThing is Thing<string>;	from dataclasses import dataclass from typing import Generic, TypeVar T = TypeVar('T') @dataclass class Thing(Generic[T]):     property: T @dataclass class StringThing:     property: str

---

Other

Union

TSP	Python
model Dog {   kind: "dog";   barkDb: int32; } model Cat {   kind: "cat";   lives: int32; } alias Pet = Dog | Cat;	from dataclasses import dataclass from typing import TypeAlias, Literal @dataclass class Dog:     kind: Literal["dog"]     barkDb: int @dataclass class Cat:     kind: Literal["cat"]     lives: int Pet: TypeAlias = Dog | Cat

Named unions

TSP

Python

model Beagle {   name: string; } model GermanShepherd {   name: string; } model GoldenRetriever {   name: string; } union Breed {   beagle: Beagle,   shepherd: GermanShepherd,   retriever: GoldenRetriever, }

from enum import Enum, EnumMeta from typing import TYPE_CHECKING, TypeAlias # NamedUnion "Framework" class NamedUnionMeta(EnumMeta):     def __getattribute__(self, name):         attr = super().__getattribute__(name)         return attr.value if isinstance(attr, self) else attr if TYPE_CHECKING:     class NamedUnion: ... else:     class NamedUnion(Enum, metaclass=NamedUnionMeta): ... class Beagle: ... class GermanShepherd: ... class GoldenRetriever: ... class Breed(NamedUnion):     beagle = Beagle     shepherd = GermanShepherd     retriever = GoldenRetriever BreedUnion: TypeAlias = Beagle | GermanShepherd | GoldenRetriever def takes_value(a: BreedUnion):     print(repr(a)) def takes_type(a):     print(repr(a)) takes_value(Beagle()) takes_type(Beagle) takes_value(GermanShepherd()) takes_type(GermanShepherd) takes_value(Breed.beagle()) takes_type(Breed.beagle) takes_value(Breed.shepherd()) takes_type(Breed.shepherd)

Intersections

TSP	Python
model Animal {   species: string; } model Pet {   name: string; } alias Dog = Animal & Pet;	from dataclasses import dataclass @dataclass class Animal:     species: str @dataclass class Pet:     name: str @dataclass class Dog:     species: str     name: str

Arrays and Records

TSP	Python
model Inventory {   items: Item[];   labels: Record<string>; } model Item {   sku: string;   qty: int32; }	from dataclasses import dataclass @dataclass class Item:     sku: str     qty: int @dataclass class Inventory:     items: list[Item]     labels: dict[str, str]

Interface

TSP	Python
interface Storage {   get(id: string): Item;   put(item: Item): void; }	from typing import Protocol class Storage(Protocol):     @staticmethod     def get(id: str) -> Item: ...     @staticmethod     def put(item: Item) -> None: ...

Interface with inheritance

TSP	Python
interface A {   a(): string; } interface B {   b(): string; } interface C extends A, B {   c(): string; }	from typing import Protocol class A(Protocol):     @staticmethod     def a() -> str: ... class B(Protocol):     @staticmethod     def b() -> str: ... class C(A, B, Protocol):     @staticmethod     def c() -> str: ...

Operation

TSP	Python
op ping(): void;	def ping() -> None:     pass

Operations with params spread

TSP	Python
model CommonParams {   time: string;   amount: int32; } op feedDog(...CommonParams, name: string): void;	def feed_dog(time: str, amount: int, name: str) -> None:     pass

Operations with Union return type

TSP	Python
model DogNotFound {   error: "Not Found"; } op getDog(name: string): Dog | DogNotFound;	from dataclasses import dataclass from typing import Union @dataclass class DogNotFound:     error: str = "Not Found" def get_dog(name: str) -> Union[Dog, DogNotFound]:     pass

Operation reuse

TSP	Python
op Delete(id: string): void; op deletePet is Delete;	def delete(id: str) -> None:     pass deletePet = delete

Basic Enum

TSP	Python
enum Direction {   North,   East,   South,   West, }	from enum import Enum class Direction(Enum):     NORTH = "North"     EAST = "East"     SOUTH = "South"     WEST = "West"

With values

TSP	Python
enum Foo {   One: 1,   Ten: 10,   Hundred: 100,   Thousand: 1000, }	from enum import Enum class Foo(Enum):     ONE = 1     TEN = 10     HUNDRED = 100     THOUSAND = 1000

Enum with spread Enum

TSP	Python
enum Direction {   North,   East,   South,   West, } enum DirectionExt {   ...Direction,   North East,   North West,   South East,   South West, }	from enum import Enum class Direction(Enum):     NORTH = "North"     EAST = "East"     SOUTH = "South"     WEST = "West" class DirectionExt(Enum):     NORTH = "North"     EAST = "East"     SOUTH = "South"     WEST = "West"     NORTH_EAST = "North East"     NORTH_WEST = "North West"     SOUTH_EAST = "South East"     SOUTH_WEST = "South West"

[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.