Skip to content

Base classes

Params dataclass 

Params(*, preset: str | None = None)

Bases: CLI

Base class for script-style single models with parameters.

Declare parameters as class attributes in the same form as dataclass fields with any of:

When run directly as a script, CLI arguments are parsed automatically at class definition time, and resolved parameter values are accessible as class attributes. A handler is registered to retrieve the rendered model using [show][bdbox.geometry.geometry.show] when the script completes, if not manually called.

A presets class attribute may declare a selection of Preset objects.

Note

Subclasses are created as dataclasses automatically. Do not decorate subclasses with @dataclass.

Example 
class P(Params):
    width = Float(40.0, min=10, max=100)
    thickness = Float(3.0, min=1, max=10)

    presets = (Preset("small", width=15.0, thickness=2.0),)

result = Box(P.width, P.width, P.thickness)

with_preset classmethod 

with_preset(preset: str | None, **overrides: Any) -> Self

Create a new instance with values from a preset applied.

Parameters:

  • preset (str | None) –

    Name of the preset to apply.

  • **overrides (Any, default: {} ) –

    Additional field values to apply after the preset.

Source code in bdbox/model/parameters.py 
 97
 98
 99
100
101
102
103
104
105
@classmethod
def with_preset(cls, preset: str | None, **overrides: Any) -> Self:
    """Create a new instance with values from a preset applied.

    Args:
        preset: Name of the preset to apply.
        **overrides: Additional field values to apply after the preset.
    """
    return cls(preset=preset, **overrides)

Model dataclass 

Model(*, preset: str | None = None)

Bases: Params

Base class for reusable models with parameters.

Declare parameters as class attributes in the same form as dataclass fields with any of:

CLI arguments are parsed within run. A handler is registered to invoke run if not called manually and only one Model subclass is defined.

A presets class attribute may declare a selection of Preset objects.

Implement build to construct and return model geometry. Access parameter values as instance attributes.

Note

Subclasses are created as dataclasses automatically. Do not decorate subclasses with @dataclass.

Example 
class MyModel(Model):
    width = Float(40.0, min=10, max=100)
    thickness = Float(3.0, min=1, max=10)

    presets = (Preset("small", width=15.0, thickness=2.0),)

    def build(self):
        return Box(self.width, self.width, self.thickness)

build 

build() -> Model.Build

Build and return model geometry.

Info

Override this method in your subclass with your model code.

Tip

Access resolved parameter values via instance attributes (e.g. self.width would be the resolved value for a parameter called width).

Source code in bdbox/model/model.py 
70
71
72
73
74
75
76
77
78
79
80
81
def build(self) -> Model.Build:
    """Build and return model geometry.

    Info:
        Override this method in your subclass with your model code.

    Tip:
        Access resolved parameter values via instance attributes (e.g.
        ``self.width`` would be the resolved value for a parameter called
        ``width``).
    """
    raise NotImplementedError

run classmethod 

run() -> None

Parse CLI arguments, build the model, and retrieve geometry.

Calls build with the resolved parameter values and passes the result to [show][bdbox.geometry.geometry.show].

Info

Call this to build and use your model geometry.

Note

If run is not called explicitly, and a single Model subclass is defined in __main__, run will be called automatically when Python finishes.

Source code in bdbox/model/model.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
@classmethod
def run(cls) -> None:
    """Parse CLI arguments, build the model, and retrieve geometry.

    Calls [``build``][bdbox.model.model.Model.build] with the resolved
    parameter values and passes the result to
    [``show``][bdbox.geometry.geometry.show].

    Info:
        Call this to build and use your model geometry.

    Note:
        If ``run`` is not called explicitly, and a single
        [``Model``][bdbox.model.model.Model] subclass is defined in
        [``__main__``][__main__], ``run`` will be called automatically when
        Python finishes.
    """
    atexit.unregister(Model._atexit_handler)
    run_state.model_state.ensure_module_filename(cls)
    try:
        cli_result = cls.cli_config().instance_from_cli(prog=cls.__name__)
        run_state.model_state.model_cli = cli_result.params
    finally:
        run_state.model_state.module_dict = sys.modules[
            "__main__"
        ].__dict__
    if Action.mode != Action.Mode.HARNESS:
        run_state.action_state.action = cli_result.action
    if not run_state.model_state.model.class_name:
        run_state.model_state.model.class_name = cls.__name__
    with run_state.action_state.on_model_render():
        run_state.model_state.apply_overrides(cli_result.params)
        run_state.model_state.params.values = {
            f.name: getattr(cli_result.params, f.name)
            for f in fields(cli_result.params)
            if f.name != "preset"
        }
        show(cli_result.params.build())
        run_state.action_state.act_once()

with_preset classmethod 

with_preset(preset: str | None, **overrides: Any) -> Self

Create a new instance with values from a preset applied.

Parameters:

  • preset (str | None) –

    Name of the preset to apply.

  • **overrides (Any, default: {} ) –

    Additional field values to apply after the preset.

Source code in bdbox/model/parameters.py 
 97
 98
 99
100
101
102
103
104
105
@classmethod
def with_preset(cls, preset: str | None, **overrides: Any) -> Self:
    """Create a new instance with values from a preset applied.

    Args:
        preset: Name of the preset to apply.
        **overrides: Additional field values to apply after the preset.
    """
    return cls(preset=preset, **overrides)