Metadata-Version: 2.4
Name: bonsai-sgen
Version: 0.10.0rc1
Summary: Pydantic base classes for types generated by Bonsai.Sgen.
License-Expression: MIT
Project-URL: Documentation, https://bonsai-rx.org/sgen
Project-URL: Repository, https://github.com/bonsai-rx/sgen
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.10
Requires-Dist: typing-extensions>=4.6.1
Dynamic: license-file

# bonsai-sgen

`bonsai-sgen` provides pydantic base classes for data types shared with the [Bonsai visual reactive programming language](https://bonsai-rx.org). Models derived from these classes export JSON schemas from which [`Bonsai.Sgen`](https://www.nuget.org/packages/Bonsai.Sgen) generates matching C# types and serialization operators.

Each release of `bonsai-sgen` matches the release of `Bonsai.Sgen` with the same version number, and exports schemas following the conventions of that release.

## How to Use

1. Install the package:

    ```cmd
    pip install bonsai-sgen
    ```

2. Define the models in a module, `person_and_discriminated_pets.py`, that declares the namespace of the generated types:

    ```python
    from abc import ABC
    from typing import Annotated, Literal

    from pydantic import Field
    from typing_extensions import TypeAliasType

    from bonsai.sgen import SchemaModel

    SGEN_NAMESPACE = "PersonAndDiscriminatedPets"


    class PetBase(SchemaModel, ABC):
        age: int | None = None


    class Cat(PetBase):
        pet_type: Literal["cat"] = "cat"
        can_meow: bool = True


    class Dog(PetBase):
        pet_type: Literal["dog"] = "dog"
        can_bark: bool | None = True


    Pet = TypeAliasType("Pet", Annotated[Cat | Dog, Field(discriminator="pet_type")])


    class PersonAndPet(SchemaModel):
        owner: str
        pet: Pet | None = None
    ```

3. Write the schema of the models to a file named after the namespace:

    ```cmd
    bonsai-sgen export person_and_discriminated_pets -o schemas
    ```

4. Generate the C# types with the release of `Bonsai.Sgen` matching the installed version of `bonsai-sgen`:

    ```cmd
    dotnet bonsai.sgen schemas/PersonAndDiscriminatedPets.json -o Extensions --serializer json yaml
    ```

## Additional Documentation

For additional documentation and examples, refer to the [official Bonsai.Sgen documentation](https://bonsai-rx.org/sgen).

## Feedback & Contributing

`bonsai-sgen` is released as open source under the [MIT license](https://github.com/bonsai-rx/sgen/blob/main/LICENSE). Bug reports and contributions are welcome at [the GitHub repository](https://github.com/bonsai-rx/sgen).
