Package bonsai.sgen

Pydantic base classes for types generated by Bonsai.Sgen.

Classes

DiscriminatedUnion

Tags assigned by a union to each of its members, carried in the specified property.

Annotate the root of a SchemaUnion, or the value of a union alias, with an instance. The tag of each member is its class name, or its fully qualified type name when qualified is set, so the members do not declare the tag themselves. With qualified tags, the module of each member must declare its namespace before the union is defined. A member instance is resolved by its exact class, so an instance of another class with the same name is rejected.

The tag property follows the alias generator of the union members.

SchemaAlias

Marks a type alias of a discriminated union shared by every namespace referring to it.

Annotating the value of a union alias with an instance generates the union under the alias name in the namespace declared by the module of the alias. The alias is declared with the type statement, or with TypeAliasType before Python 3.12. Without the marker, the union is generated as a local union in each namespace referring to it.

SchemaEnum

The base class for enumerations generated by Bonsai.Sgen.

Type names follow the same rules as SchemaModel, including sgen_typename for a type defined elsewhere. The schema of an integer enumeration specifies the names of its values, with names in the upper case of the Python convention converted to PascalCase. For a string enumeration the names are derived directly from its values. To combine it with another enumeration base such as IntEnum or StrEnum, list SchemaEnum first.

SchemaModel

The base class for models generated as classes by Bonsai.Sgen.

A model is generated as the class of the same name in the namespace declared by the SGEN_NAMESPACE attribute of its module. Pass sgen_typename in the class definition to describe a type defined elsewhere, so that a schema refers to the existing type instead of defining a new one.

A model listing ABC among its direct bases is generated as an abstract class. Its subclasses are generated as concrete classes unless they also list ABC.

A discriminated union is declared as a type alias or as a SchemaUnion, so that it is generated under its own name. A generic model has no type name, so it is exported only as a local type. A concrete subclass of a generic model has a type name of its own.

The alias of a field is its key in the schema and in the generated code, so it is used for serialization, and the title of the field is the name of the generated property. Aliases are the camelCase form of field names, and data with either form is read.

SchemaUnion

The base class for discriminated unions generated by Bonsai.Sgen.

A union can be defined by subclassing SchemaUnion and annotating its root field with the member types, discriminated either by a constant tag declared by each member, through Field(discriminator=...), or by tags assigned by the union, through DiscriminatedUnion. The type name of the union follows the same rules as SchemaModel, and every member type must be a SchemaModel. The generated code wraps any member type that is generated elsewhere or belongs to another union.

SgenWarning

Warns that Bonsai.Sgen may not handle the exported schema correctly.

Functions

export_schema

Returns a schema document defining the specified models and every type they refer to.

The document has no root type, only definitions, including those of types from other namespaces. The code generated by Bonsai.Sgen defines only the types in the namespace being generated, and refers to any other types by their type names. A discriminated union without a type name, such as a type alias not marked with SchemaAlias, is generated as a local union in every namespace referring to it.

Union aliases annotated with SchemaAlias can be specified alongside models, so that a union is defined even if no model in its namespace refers to it.

Declaration

def export_schema(*models: SchemaType, allow_local_types: bool = False) -> JsonSchemaValue

Parameters

Type	Name	Description
SchemaType	*models	The models and union aliases to define.
bool	allow_local_types	True to allow types with no type name, such as plain pydantic models, dataclasses and enumerations, as local types; otherwise such types raise an error. Each namespace that refers to a local type defines its own copy of it.

Returns

Type	Description
JsonSchemaValue

Exceptions

Type

Condition

TypeError

If a specified model is not a schema type, or the schema refers to a type with no type name, such as a plain pydantic model or enumeration, and allow_local_types is not set. The error is also raised when the schema refers to a type that generated code cannot represent, such as a tuple, a union without a discriminator, or an anonymous discriminated union, when two definitions share a type name, which would define the same type twice, or when a field is read and written under different keys.

get_typename

Returns the fully qualified name of the type generated for a schema type.

The name is the one specified explicitly for the class or union alias, or else its name in the namespace declared by the SGEN_NAMESPACE attribute of its module. Only the class itself is consulted, so a subclass can never inherit the type name of its parent.

Declaration

def get_typename(schema_type: type | SchemaType) -> str

Parameters

Type	Name	Description
type | SchemaType	schema_type

Returns

Type	Description
str

Exceptions

Type	Condition
TypeError	If the type is not a subclass of SchemaModel, SchemaEnum or SchemaUnion, is a generic model, is a type alias not annotated with SchemaAlias, or has no explicit name and its module declares no namespace.

schema_types

Returns the models, unions and union aliases defined in a module, in declaration order.

Generic models are left out, since they have no type name.

Declaration

def schema_types(module: ModuleType) -> list[SchemaType]

Parameters

Type	Name	Description
ModuleType	module

Returns

Type	Description
list[SchemaType]

write_schema

Writes the schema of models in a single namespace to a file.

The schema file is named after the namespace. Bonsai.Sgen derives both the namespace and the name of the generated file from the name of the schema file.

Declaration

def write_schema(directory: str | PathLike[str], *models: SchemaType, allow_local_types: bool = False) -> Path

Parameters

Type	Name	Description
str | PathLike[str]	directory	The directory of the schema file.
SchemaType	*models	The models and union aliases to define.
bool	allow_local_types	True to allow types with no type name as local types, as in export_schema.

Returns

Type	Description
Path	The path of the schema file.

Exceptions

Type	Condition
ValueError	If the models belong to more than one namespace.

Variables

ABSTRACT_KEY

Annotation marking a type as abstract.

Declaration

ABSTRACT_KEY = 'x-abstract'

CAMEL_CASE_CONFIG

Model configuration writing camelCase keys and reading either camelCase or Python names.

Declaration

CAMEL_CASE_CONFIG = ConfigDict(alias_generator=_camel_case, validate_by_name=True, serialize_by_alias=True)

ENUM_NAMES_KEY

Annotation specifying the names of the values in an enumeration type.

Declaration

ENUM_NAMES_KEY = 'x-enumNames'

NAMESPACE_ATTRIBUTE

Module attribute declaring the generated namespace of the schema types in the module.

Declaration

NAMESPACE_ATTRIBUTE = 'SGEN_NAMESPACE'

TYPENAME_KEY

Annotation binding a schema definition to the fully qualified name of a type.

Declaration

TYPENAME_KEY = 'x-sgen-typename'

SchemaType

A model, union or union alias from which a schema can be exported.

Declaration

SchemaType: TypeAlias = type[BaseModel] | typing_extensions.TypeAliasType | typing.TypeAliasType