Skip to content

Index

subsurfaceio.pydantic_utils

Shared pydantic building blocks for application models.

Optional numeric form fields, bundled JSON datasets, and columnar dumps of model lists. Canonical imports come from this package, not the private modules:

from subsurfaceio.pydantic_utils import Model, NullableFloat, models_to_dict_of_lists

class Point(Model):
    x: NullableFloat = None
    y: NullableFloat = None

columns = models_to_dict_of_lists([Point(x=0, y=0), Point(x=1, y=1)])

Model is the base for top-level app models and loads JSON from datasets/<ClassName>/. RangeParameters builds an inclusive sample grid. NullableInt and NullableFloat coerce '' and NaN to None.

Classes:

Name Description
Model

Top-level application model with optional bundled JSON datasets.
RangeParameters

Inclusive numeric range used to generate a 1D sample grid.

Functions:

Name Description
models_to_dict_of_lists

Columnar dump of a homogeneous list of models.

Attributes:

Name Type Description
NullableFloat TypeAlias

Optional float that treats '' and NaN as None.
NullableInt TypeAlias

Optional int that treats '' and NaN as None.

NullableFloat module-attribute 

NullableFloat: TypeAlias = Annotated[
    float | None, BeforeValidator(_empty_numeric_to_none)
]

Optional float that treats '' and NaN as None.

NullableInt module-attribute 

NullableInt: TypeAlias = Annotated[
    int | None, BeforeValidator(_empty_numeric_to_none)
]

Optional int that treats '' and NaN as None.

Model pydantic-model

Bases: BaseModel

Top-level application model with optional bundled JSON datasets.

Bundled files live under subsurfaceio/datasets/<ClassName>/ as *.json. Subclasses that do not ship datasets still inherit these classmethods; available_datasets returns [] when that directory is missing. Override both methods when the dataset source is not that folder.

available_datasets classmethod 

available_datasets() -> list[str]

List bundled dataset ids for this class.

Returns:

Type Description
list[str]

Sorted JSON stems under datasets/<ClassName>, or [] if that directory does not exist.

load_dataset classmethod 

load_dataset(dataset_id: str) -> Self

Validate and return the bundled JSON dataset named dataset_id.

Parameters:

Name Type Description Default
dataset_id str

Stem of a .json file under datasets/<ClassName>.

 required

Returns:

Type Description
Self

A validated instance of this class.

Raises:

Type Description
FileNotFoundError

When dataset_id is not among available_datasets.

RangeParameters pydantic-model

Bases: BaseModel

Inclusive numeric range used to generate a 1D sample grid.

Attributes:

Name Type Description
start float

First sample.
end float

Last sample when it is a near-multiple of step; otherwise the last sample is the nearest grid point that does not pass end.
step float

Positive spacing between samples.

Config:

  • extra: forbid

Fields:

Validators:

  • _end_at_least_start

end pydantic-field 

end: float

model_config class-attribute instance-attribute 

model_config = ConfigDict(extra='forbid')

start pydantic-field 

start: float

step pydantic-field 

step: float

values property 

values: ndarray

Sample grid from start through end, without overshooting.

Returns:

Type Description
ndarray

1D array of n = round((end - start) / step) + 1 points.

models_to_dict_of_lists 

models_to_dict_of_lists(
    models: Sequence[BaseModel],
) -> dict[str, list[Any]]

Columnar dump of a homogeneous list of models.

Keys come from the first model's model_dump. Later rows must share those keys.

Parameters:

Name Type Description Default
models Sequence[BaseModel]

Homogeneous row models.

 required

Returns:

Type Description
dict[str, list[Any]]

Mapping of field name to per-row values, or {} when models is empty.