Guide

Reference material about the API itself, as opposed to the task-oriented Tutorials: what the pg.Object flags mean, how to write subclasses that satisfy both runtime validation and static type-checkers, and how the implementation performs.

Pages

• Semantics — the pg.Object semantic spectrum. One class statement spans a flat, dataclass-equivalent object through a fully tree-aware value object, along the class-level topo axis (refined by validate / eq / mutability). Read this to decide where on the spectrum your class belongs.
• Styles — conventions for writing pg.Object subclasses: the three forms of field declaration, positional __init__, ClassVar for configuration, container storage, and the field-default override pitfalls. The patterns come out of repeated friction with PEP 681's dataclass_transform model, so they are not arbitrary.
• Perf — measured pg.Object cost against @dataclass and pydantic v2 across ~50 operations, in both cores. Read ratios rather than absolutes; the numbers are machine-specific.

If you are new to PyGX, start with Learning PyGX for the concepts, or the bird's-eye view for a runnable tour.