[Proposal] Improve type safety with potential Pydantic adoption

[Apricot-S]

[Apricot-S]

I've created a first draft implementation of the basic input models using Pydantic.
This covers the two core structures: Tiles136 and Tiles34.

from typing import Annotated

from pydantic import BaseModel, Field
from typing_extensions import TypeAliasType

_Tile136 = TypeAliasType("_Tile136", Annotated[int, Field(ge=0, lt=136)])


class Tiles136(BaseModel):
    ids: Annotated[set[_Tile136], Field(max_length=136)]


_Tile34 = TypeAliasType("_Tile34", Annotated[int, Field(ge=0, le=4)])


class Tiles34(BaseModel):
    counts: Annotated[list[_Tile34], Field(min_length=34, max_length=34)]


def main():
    tiles136_0 = Tiles136(ids={0, 1})
    tiles136_1 = Tiles136(ids=[0, 1, 0])  # Duplicate elements are removed by Pydantic
    tiles136_2 = Tiles136(ids=range(2))
    assert tiles136_0 == tiles136_1
    assert tiles136_0 == tiles136_2

    tiles34_1 = Tiles34(counts=[0] * 34)
    tiles34_2 = Tiles34(counts=(0 for _ in range(34)))
    assert tiles34_1 == tiles34_2

    print("Hello from pydantic-example!")


if __name__ == "__main__":
    main()

• Tiles136 ensures values are within 0-135 and automatically deduplicates when using a set.
• Tiles34 enforces exactly 34 entries with counts in the range 0-4.

This is just an exploratory step, but it demonstrates how Pydantic could help us enforce constraints at the boundary of the library.

[Nihisil]

_Tile136 = TypeAliasType("_Tile136", Annotated[int, Field(ge=0, lt=136)]) maybe can be simplified to Tile136ID = Annotated[int, Field(ge=0, lt=136)] (need to check if that is going to work)

I'm still not sure if we need to introduce Pydantic and strict type validation, maybe it is not necessary for that library. It is definitely good to have it in general code, but for this specific library, using simple types might be an advantage. The disadvantage is that we do not have a self-documented API, but this can probably be solved with dataclasses. So, I am still trying to figure out what to do here and how we can improve it

[Apricot-S]

Thanks for the suggestion! Just to clarify: starting with Python 3.12, the recommended way to define type aliases is via the new type statement (PEP 695). This syntax is essentially sugar for creating a TypeAliasType instance. The older TypeAlias approach is deprecated in 3.12.

Since this library supports Python 3.10+, the correct forward-compatible way is to use TypeAliasType from typing_extensions. That way, the code works consistently on 3.10–3.11, and in 3.12+ it naturally aligns with the new type statement.

For example:

from typing import Annotated

from pydantic import Field
from typing_extensions import TypeAliasType

Tile136ID = TypeAliasType("Tile136ID", Annotated[int, Field(ge=0, lt=136)])

Reference: https://docs.python.org/3.14/library/typing.html#typing.TypeAlias