"""Rigging conventions package for OpenRig.
Provides configurable rigging defaults (axis orientation, rotate order,
default side) that can be adjusted per project via ``conventions/config.json``
or by constructing a ``RiggingConventions`` instance directly.
Public API:
- ``get_conventions() -> RiggingConventions``: returns the singleton instance.
- ``load_conventions(path) -> RiggingConventions``: loads from a custom path.
- ``RiggingConventions``: the conventions dataclass.
- ``ConventionsError``: raised on load or validation failures.
Example:
>>> from openrig.conventions import get_conventions
>>> conv = get_conventions()
>>> conv.aim_axis
<Axis.X: 'X'>
>>> conv.default_rotate_order.as_string
'xyz'
"""
from openrig.conventions.conventions import (
ConventionsError,
RiggingConventions,
load_conventions,
)
__all__ = [
"ConventionsError",
"RiggingConventions",
"get_conventions",
"load_conventions",
]
_conventions_instance: RiggingConventions | None = None
[docs]
def get_conventions() -> RiggingConventions:
"""Returns the pre-configured singleton ``RiggingConventions`` instance.
Builds the instance on first call using the defaults defined in
``conventions/config.json``. Subsequent calls return the same instance.
Returns:
The singleton ``RiggingConventions`` instance.
"""
global _conventions_instance
if _conventions_instance is None:
_conventions_instance = load_conventions()
return _conventions_instance