Skip to content

omnipy.data.param

Parameter model helpers for configurable Omnipy model and dataset classes.

This module defines the read-only parameter class pattern used by Omnipy models and datasets, plus helpers that clone classes with adjusted parameter defaults.

CLASS DESCRIPTION
ParamsBase

Read-only class-level parameter container for adjusted model variants.
FUNCTION DESCRIPTION
bind_adjust_dataset_func

Bind a dataset-cloning helper to model and parameter classes.
bind_adjust_model_func

Bind a model-cloning helper to a parameter class.
params_dataclass

Decorate a params declaration as a keyword-only dataclass.

ParamsBase

Bases: pyd.BaseModel


              flowchart BT
              omnipy.data.param.ParamsBase[ParamsBase]

                              omnipy.util.pydantic.BaseModel --> omnipy.data.param.ParamsBase
                


              click omnipy.data.param.ParamsBase href "" "omnipy.data.param.ParamsBase"

Read-only class-level parameter container for adjusted model variants.

ParamsBase subclasses declare validated default values as pydantic fields, but they are used as class objects rather than instantiated data objects. Omnipy reads parameter values directly from the class and can clone the parameter class with selected defaults overridden.

Returned by:
CLASS DESCRIPTION
Config

Pydantic model configuration: allows arbitrary types and enables smart union matching.
METHOD DESCRIPTION
copy_and_adjust

Clone the parameter class with updated default field values.
Source code in src/omnipy/data/param.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
class ParamsBase(pyd.BaseModel, metaclass=_ParamsMeta):
    """Read-only class-level parameter container for adjusted model variants.

    ``ParamsBase`` subclasses declare validated default values as pydantic
    fields, but they are used as class objects rather than instantiated data
    objects. Omnipy reads parameter values directly from the class and can clone
    the parameter class with selected defaults overridden.
    """
    class Config:
        """Pydantic model configuration: allows arbitrary types and enables smart union matching."""
        arbitrary_types_allowed = True
        smart_union = True

    def __new__(cls, *args: object, **kwargs: object) -> None:  # type: ignore[misc]
        """Disallow instantiation of parameter classes.

        Args:
            *args: Ignored positional arguments.
            **kwargs: Ignored keyword arguments.

        Raises:
            RuntimeError: Always, because parameter classes are used only via
                class attributes.
        """
        raise RuntimeError(f'{cls.__name__} cannot be instantiated')

    @classmethod
    def copy_and_adjust(cls, model_name: str, **kwargs: object) -> type['ParamsBase']:
        """Clone the parameter class with updated default field values.

        Args:
            model_name: Name to assign to the cloned parameter class.
            **kwargs: Field defaults to override in the clone.

        Returns:
            A new :class:`ParamsBase` subclass with validated adjusted defaults.
        """
        all_field_infos = {
            field_name: deepcopy(field.field_info) for field_name, field in cls.__fields__.items()
        }

        for key, value in kwargs.items():
            all_field_infos[key].default = value

        field_definitions: dict[str, Any] = {
            field_name: (cls.__fields__[field_name].outer_type_, field_info)
            for field_name, field_info in all_field_infos.items()
        }
        return pyd.create_model(  # type: ignore[call-overload]
            model_name, __base__=ParamsBase, **field_definitions)

Config

Pydantic model configuration: allows arbitrary types and enables smart union matching.

ATTRIBUTE DESCRIPTION
arbitrary_types_allowed

smart_union

Source code in src/omnipy/data/param.py 
144
145
146
147
class Config:
    """Pydantic model configuration: allows arbitrary types and enables smart union matching."""
    arbitrary_types_allowed = True
    smart_union = True

arbitrary_types_allowed class-attribute instance-attribute 

arbitrary_types_allowed = True

smart_union class-attribute instance-attribute 

smart_union = True

copy_and_adjust classmethod 

copy_and_adjust(model_name: str, **kwargs: object) -> type[ParamsBase]

Clone the parameter class with updated default field values.

PARAMETER DESCRIPTION
model_name

Name to assign to the cloned parameter class.

TYPE: str

**kwargs

Field defaults to override in the clone.

TYPE: object DEFAULT: {}

RETURNS DESCRIPTION
type[ParamsBase]

A new :class:ParamsBase subclass with validated adjusted defaults.
Source code in src/omnipy/data/param.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
@classmethod
def copy_and_adjust(cls, model_name: str, **kwargs: object) -> type['ParamsBase']:
    """Clone the parameter class with updated default field values.

    Args:
        model_name: Name to assign to the cloned parameter class.
        **kwargs: Field defaults to override in the clone.

    Returns:
        A new :class:`ParamsBase` subclass with validated adjusted defaults.
    """
    all_field_infos = {
        field_name: deepcopy(field.field_info) for field_name, field in cls.__fields__.items()
    }

    for key, value in kwargs.items():
        all_field_infos[key].default = value

    field_definitions: dict[str, Any] = {
        field_name: (cls.__fields__[field_name].outer_type_, field_info)
        for field_name, field_info in all_field_infos.items()
    }
    return pyd.create_model(  # type: ignore[call-overload]
        model_name, __base__=ParamsBase, **field_definitions)

bind_adjust_dataset_func 

bind_adjust_dataset_func(
    clone_dataset_func: Callable[..., type[_DatasetT]],
    model_cls: type[_ModelT],
    params_cls: Callable[_ParamsP, Any],
) -> Callable[Concatenate[str, str, _ParamsP], type[_DatasetT]]

Bind a dataset-cloning helper to model and parameter classes.

The returned function first creates an adjusted model class, then clones a dataset class bound to that model, while also attaching a cloned Params class with the same adjusted defaults.

PARAMETER DESCRIPTION
clone_dataset_func

Function that clones the dataset class.

TYPE: Callable[..., type[_DatasetT]]

model_cls

Base model class to adjust before cloning the dataset.

TYPE: type[_ModelT]

params_cls

Parameter class whose defaults should be adjusted.

TYPE: Callable[_ParamsP, Any]

RETURNS DESCRIPTION
Callable[Concatenate[str, str, _ParamsP], type[_DatasetT]]

A helper that accepts dataset and model names plus keyword-only parameter overrides, then returns the adjusted dataset class.
Used by:
Source code in src/omnipy/data/param.py 
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
def bind_adjust_dataset_func(
    clone_dataset_func: Callable[..., type[_DatasetT]],
    model_cls: type[_ModelT],
    params_cls: Callable[_ParamsP, Any],
) -> Callable[Concatenate[str, str, _ParamsP], type[_DatasetT]]:
    """Bind a dataset-cloning helper to model and parameter classes.

    The returned function first creates an adjusted model class, then clones a
    dataset class bound to that model, while also attaching a cloned ``Params``
    class with the same adjusted defaults.

    Args:
        clone_dataset_func: Function that clones the dataset class.
        model_cls: Base model class to adjust before cloning the dataset.
        params_cls: Parameter class whose defaults should be adjusted.

    Returns:
        A helper that accepts dataset and model names plus keyword-only
        parameter overrides, then returns the adjusted dataset class.
    """
    def _func(dataset_name: str, model_name: str, *args: _ParamsP.args,
              **kwargs: _ParamsP.kwargs) -> type[_DatasetT]:
        """Create an adjusted clone of the dataset class.

        Args:
            dataset_name: Name for the cloned dataset class.
            model_name: Name for the intermediate adjusted model class.
            *args: Positional arguments, which are not supported.
            **kwargs: Parameter overrides applied to model and params classes.

        Returns:
            A cloned dataset class bound to the adjusted model class.

        Raises:
            AttributeError: If any positional argument is supplied.

        Example:
            >>> adjust_dataset = bind_adjust_dataset_func(clone_dataset_func, model_cls, params_cls)
            >>> NewDataset = adjust_dataset('NewDataset', 'NewModel', retries=2)
        """
        if len(args) > 0:
            raise AttributeError(f'Positional arguments are not supported for '
                                 f'{params_cls.__module__}.{params_cls.__name__}')
        new_model_cls: type[_ModelT] = cast(
            type[_ModelT],
            model_cls.adjust(model_name, **kwargs),  # type: ignore[attr-defined]
        )

        new_dataset_cls = clone_dataset_func(dataset_name, new_model_cls)
        new_model_cls.Params = params_cls.copy_and_adjust(  # type: ignore[attr-defined]
            'Params',
            **kwargs,
        )
        return new_dataset_cls

    return _func

bind_adjust_model_func 

bind_adjust_model_func(
    clone_model_func: Callable[..., type[_ModelT]], params_cls: Callable[_ParamsP, Any]
) -> Callable[Concatenate[str, _ParamsP], type[_ModelT]]

Bind a model-cloning helper to a parameter class.

The returned function creates a cloned model class, then replaces its Params class with a copy of params_cls whose defaults are adjusted from the supplied keyword arguments.

PARAMETER DESCRIPTION
clone_model_func

Function that clones the target model class.

TYPE: Callable[..., type[_ModelT]]

params_cls

Parameter class whose defaults should be adjusted.

TYPE: Callable[_ParamsP, Any]

RETURNS DESCRIPTION
Callable[Concatenate[str, _ParamsP], type[_ModelT]]

A helper that accepts a new model name and keyword-only parameter overrides, then returns the adjusted model class.
Used by:
Source code in src/omnipy/data/param.py 
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
def bind_adjust_model_func(
    clone_model_func: Callable[..., type[_ModelT]],
    params_cls: Callable[_ParamsP, Any],
) -> Callable[Concatenate[str, _ParamsP], type[_ModelT]]:
    """Bind a model-cloning helper to a parameter class.

    The returned function creates a cloned model class, then replaces its
    ``Params`` class with a copy of ``params_cls`` whose defaults are adjusted
    from the supplied keyword arguments.

    Args:
        clone_model_func: Function that clones the target model class.
        params_cls: Parameter class whose defaults should be adjusted.

    Returns:
        A helper that accepts a new model name and keyword-only parameter
        overrides, then returns the adjusted model class.
    """
    def _func(model_name: str, *args: _ParamsP.args, **kwargs: _ParamsP.kwargs) -> type[_ModelT]:
        """Create an adjusted clone of the model class.

        Args:
            model_name: Name for the cloned model class.
            *args: Positional arguments, which are not supported.
            **kwargs: Parameter overrides applied to the cloned ``Params`` class.

        Returns:
            A cloned model class with adjusted parameter defaults.

        Raises:
            AttributeError: If any positional argument is supplied.

        Example:
            >>> adjust_model = bind_adjust_model_func(clone_model_func, params_cls)
            >>> NewModel = adjust_model('NewModel', retries=2)
        """
        if len(args) > 0:
            raise AttributeError(f'Positional arguments are not supported for '
                                 f'{params_cls.__module__}.{params_cls.__name__}')
        new_model_cls = clone_model_func(model_name)
        new_model_cls.Params = params_cls.copy_and_adjust(  # type: ignore[attr-defined]
            'Params',
            **kwargs,
        )
        return new_model_cls

    return _func

params_dataclass 

params_dataclass(cls: type[_ParamsT]) -> type[_ParamsT]

Decorate a params declaration as a keyword-only dataclass.

RETURNS DESCRIPTION
type[_ParamsT]

The same class wrapped by :func:dataclasses.dataclass with kw_only=True.
Source code in src/omnipy/data/param.py 
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
@dataclass_transform(kw_only_default=True)
def params_dataclass(cls: type[_ParamsT]) -> type[_ParamsT]:
    """Decorate a params declaration as a keyword-only dataclass.

    Returns:
        The same class wrapped by :func:`dataclasses.dataclass` with
        ``kw_only=True``.
    """
    def wrap(cls):
        """Wrap a class using ``dataclass(..., kw_only=True)``.

        Returns:
            The dataclass-decorated class.

        Example:
            >>> @params_dataclass
            ... class P:
            ...     x: int = 1
            >>> P(x=2)
            P(x=2)
        """
        return dataclass(cls, kw_only=True)

    return wrap(cls)