Base Utilities

Base utilities and decorators for the scene edition API.

This module provides foundational components used across all editor classes, including logging decorators, value limit checking, and referential validation.

Type Aliases

mimic_scene_edition.editors.base.Referential

Literal type for coordinate frame specification: "local" or "world".

mimic_scene_edition.editors.base.Axis

Literal type for axis specification: "x", "y", or "z".

Decorators

mimic_scene_edition.editors.base.log_method(func)

Decorator that logs method calls to the editions list.

This decorator automatically records method invocations to the _editions list on the object, enabling tracking of all modifications made to scene elements.

The decorator only logs if:

• The method returns self (fluent interface pattern), or

• The method name is in _MUTATING_NON_FLUENT.

Parameters:

func (Callable) – The method to wrap.

Returns:

The wrapped method with logging behavior.

Return type:

Callable

Notes

The object must have a _editions attribute that is a list of EditionDict objects.

Examples

>>> class MyEditor:
...     def __init__(self):
...         self._editions = []
...
...     @log_method
...     def shift(self, forward: float = 0.0) -> "MyEditor":
...         # ... implementation ...
...         return self

mimic_scene_edition.editors.base.check_value_limits(func)

Decorator that validates parameter values against defined limits.

When limited_mode is enabled on the object, this decorator checks that numeric parameters fall within the bounds specified in value_limits.

Parameters:

func (Callable) – The method to wrap.

Returns:

The wrapped method with value limit checking.

Return type:

Callable

Raises:

ValueError – If a parameter value is outside its defined limits.

Notes

The object must have:

• limited_mode: bool attribute enabling/disabling checks

• value_limits: dict mapping parameter names to (min, max) tuples

Examples

>>> class MyEditor:
...     def __init__(self):
...         self.limited_mode = True
...         self.value_limits = {"forward": (-10.0, 10.0)}
...
...     @check_value_limits
...     def shift(self, forward: float = 0.0) -> "MyEditor":
...         # ... implementation ...
...         return self
...
>>> editor = MyEditor()
>>> editor.shift(forward=15.0)  # Raises ValueError

mimic_scene_edition.editors.base.validate_referential(param='referential')

Decorator factory that validates a referential parameter.

Creates a decorator that ensures the specified parameter has a valid referential value ("local" or "world").

Parameters:

param (str, optional) – Name of the parameter to validate. Default is "referential".

Returns:

A decorator that validates the referential parameter.

Return type:

Callable

Raises:

ValueError – If the referential value is not in VALID_REFERENTIALS.

Examples

>>> @validate_referential("referential")
... def transform(self, *, referential: str = "local") -> "MyEditor":
...     # ... implementation ...
...     return self

Type Definitions

class mimic_scene_edition.editors.base.EditionDict

Bases: TypedDict

Dictionary structure for recording edit operations.

Variables:

• method (str) – The name of the method that was called.

• params (dict[str, Any]) – The parameters passed to the method.

• description (str) – A human-readable description of the edit operation.

Examples

>>> edition = EditionDict(
...     method="shift",
...     params={"forward": 5.0, "left": 2.0},
...     description="Shift: forward=5.0, left=2.0"
... )

method: str

params: dict[str, Any]

description: str