Add Typeshare support for Python

[hculea]

This PR is adding initial support for Python in Typeshare (gated by a feature flag, like Go).

See @MOmarMiraj 's comment for a high-level description of the design considerations behind this work.

This was made possible thanks to the prior work of @adriangb: #25.

[Lucretiel]

Doing some review, sorry for the delay. I'd like to ask for a high-level description in this MR for how this integration works, with especial focus on how structs are handled (in particular how the JSON <-> struct boundary is handled).

[MOmarMiraj]

Hey @Lucretiel,

For the Python TS integration, we focused on incorporating Pydantic as our primary method for data validation and JSON serialization/deserialization.

Some reasons on why I chose pydantic over other famous packages are:

Active Support and Maintenance: The Pydantic package is well-supported and actively maintained, ensuring we can rely on its features and updates over time.

Robust Data Validation: Pydantic provides a strong data validation framework that allows us to define and enforce data types and structures in Python. This guarantees that the data types, number of fields, and overall structure align with our defined schema.

Seamless JSON Handling: The serialization and deserialization of JSON with Pydantic are incredibly smooth. It allows us to effortlessly convert our models to JSON while preserving their types and formatting, and it also validates incoming JSON data. This capability is something we currently utilize in our SDKs.(link to the SDKs doesn't work here lol)

Also, while newer Python versions are increasingly adopting advanced type hinting and validation features, Pydantic enables us to maintain compatibility with older Python versions that may not support these new features.

To serialize in pydantic is quite simple lets take a look below as an example:

from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    email: str
    friends: Optional[List[str]] = []

In here we have a pydantic model that defines a couple of fields and pydantic will now serialize/deserialize according to this schema. We can serialize data in two ways, one by dumping it into a Dict or a str.

# We create our user
user = User(id=1, name='Alice', email='alice@example.com', friends=['Bob', 'Charlie'])

# Option 1 to serialize  as a str
user_json = user.model_dump_json()
print(user_json) -> {"id":1,"name":"Alice","email":"alice@example.com","friends":["Bob","Charlie"]}

# Option 2 to serialize as a dict
user_dict = user.model_dump()
print(user_dict) -> {'id': 1, 'name': 'Alice', 'email': 'alice@example.com', 'friends': ['Bob', 'Charlie']}

We can also add different arguments such as excluding fields or including only specific fields in the output and many more which can be found here:

# Exclude the 'friends' field
user_dict_excluded = user.model_dump(exclude={"friends"})
print(user_dict_excluded) -> {'id': 1, 'name': 'Alice', 'email': 'alice@example.com'}

# Include only the 'name' and 'email' fields
user_dict_filtered = user.model_dump(include={"name", "email"})
print(user_dict_filtered) -> {'name': 'Alice', 'email': 'alice@example.com'}

For deserialization, we can deserialize according to the schema as follows:

user_json = {'id': 1, 'name': 'Jeff', 'email': 'jeff@jeff.com', 'friends': ['jeff', 'Charlie']}
let new_user = User.model_validate_json(user_json)

This will ensure that the JSON received matches against the schema and if not throws a pretty PydanticValidationError

bonus: Pydantic 2.x was written completely in Rust :)

[MOmarMiraj]

Forgot to mention but we currently do not support generics as we have yet to figure out on an ideal/idiomatic way to handle them in Python so we left it out of this PR.

[hculea]

Thanks for the mention @MOmarMiraj 😄 That should be okay while Python support is still experimental (FWIW, Go doesn't support generics either)

[hculea]

@Lucretiel does @MOmarMiraj 's comment above answer to your high-level description request? Otherwise, we're happy to provide more context on the choices that were made here. Thanks!