DataSet class conversion/creation functions¶

Update and restore datasets¶

guidata.dataset.update_dataset(dest: DataSet, source: Any | dict[str, Any], visible_only: bool = False) → None¶

Update dest dataset items from source dataset.

Parameters:

dest (DataSet) – The destination dataset object to update.
source (Union[Any, Dict[str, Any]]) – The source object or dictionary containing matching attribute names.
visible_only (bool) – If True, update only visible items. Defaults to False.

For each DataSet item, the function will try to get the attribute of the same name from the source.

If the attribute exists in the source object or the key exists in the dictionary, it will be set as the corresponding attribute in the destination dataset.

Computed items are automatically skipped as they are read-only and their values are calculated automatically based on other dataset items.

Returns:: None

guidata.dataset.restore_dataset(source: DataSet, dest: Any | dict[str, Any]) → None¶

Restore dest dataset items from source dataset.

Parameters:

source (DataSet) – The source dataset object to restore from.
dest (Union[Any, Dict[str, Any]]) – The destination object or dictionary.

This function is almost the same as update_dataset but requires the source to be a DataSet instead of the destination.

Symmetrically from update_dataset, dest may also be a dictionary.

Computed items are automatically skipped when restoring to another dataset object (since computed values should be recalculated), but are included when restoring to a dictionary (since dictionaries store all current values).

Returns:: None

Create dataset classes¶

guidata.dataset.create_dataset_from_func(func) → DataSet¶

Creates a DataSet class from a function signature.

Parameters:: func – The function to create the DataSet from.
Returns:: The DataSet class.

Note: Supported data types are: int, float, bool, str, dict, np.ndarray.

guidata.dataset.create_dataset_from_dict(dictionary: dict[str, Any], klassname: str | None = None) → DataSet¶

Creates a DataSet class from a dictionary.

Parameters:

dictionary – The dictionary to create the DataSet class from.
klassname – The name of the DataSet class. If None, the name is ‘DictDataSet’.

Returns:

The DataSet class.

Note: Supported data types are: int, float, bool, str, dict, np.ndarray.

Serialize datasets as JSON¶

Items whose data.transient property is True are omitted from the serialized output and left untouched when loading: they carry presentation context supplied by the host application, not dataset state.

guidata.dataset.dataset_to_json(param: DataSet) → str¶

Serialize dataset to JSON string.

Parameters:: param – dataset (gdt.DataSet)
Returns:: JSON string representation of the dataset

guidata.dataset.json_to_dataset(json_str: str, *, strict: bool = False, expected_class: type[DataSet] | None = None, expected_version: int | None = None, migrate: Callable[[dict[str, Any], int | None], dict[str, Any]] | None = None, allowed_missing: Iterable[str] = ()) → DataSet¶

Deserialize a DataSet from a JSON string.

Without keyword options, this function preserves the historical permissive behavior: unknown fields are ignored and missing fields use current defaults. With strict=True, class metadata, application schema version, persisted fields, and values are validated before the DataSet is constructed. A migration callback receives a deep copy of the decoded payload and its source version; its result is validated again before construction.

Parameters:

json_str – JSON string representation.
strict – If True, validate the payload before constructing the DataSet.
expected_class – Exact DataSet class expected in strict mode. Providing this constraint prevents importing a different class named by the payload.
expected_version – Maximum supported application-owned schema_version. A missing or older version is accepted; a newer version is rejected before migration and construction.
migrate – Callback transforming a copy of the decoded payload before loading. It receives (payload, source_version) and must return a dictionary.
allowed_missing – Dotted field paths explicitly allowed to use current defaults, for example {"fit.tolerance"}.

Returns:

Deserialized DataSet object.

Raises:

DataSetJSONValidationError – If strict metadata, version, schema, value, or migration-result validation fails.
ValueError – If strict-only options are provided without strict=True or an unknown path is passed in allowed_missing.
TypeError – If expected_class is not a DataSet subclass.

Note

schema_version is owned by the application. dataset_to_json() does not add it automatically. Exceptions raised by migrate are propagated unchanged.

exception guidata.dataset.DataSetJSONValidationError(message: str, *, missing_fields: set[str] | None = None, unknown_fields: set[str] | None = None, invalid_fields: Mapping[str, str] | None = None, expected_class: type[DataSet] | None = None, actual_class: str | None = None, payload_version: int | None = None, expected_version: int | None = None)¶

Error raised when strict DataSet JSON validation fails.

Parameters:

message – Summary of the validation failure.
missing_fields – Required field paths absent from the payload.
unknown_fields – Field paths not declared by the DataSet class.
invalid_fields – Mapping of invalid field paths to error messages.
expected_class – DataSet class required by the caller.
actual_class – Fully qualified class identity stored in the payload.
payload_version – Application schema version stored in the payload.
expected_version – Maximum application schema version supported.

missing_fields¶: Frozen set of required field paths absent from the payload.

unknown_fields¶: Frozen set of field paths not declared by the DataSet.

invalid_fields¶: Mapping of invalid field paths to actionable messages.

expected_class¶: DataSet class required by the caller, if any.

actual_class¶: Fully qualified class identity stored in the payload, if known.

payload_version¶: Application schema version stored in the payload, if any.

expected_version¶: Maximum application schema version supported, if any.

Strict JSON deserialization¶

The default guidata.dataset.json_to_dataset() behavior is intentionally permissive for backward compatibility. Unknown persisted fields are ignored, while fields absent from the payload receive their current defaults. This remains suitable for ordinary settings where accepting additions and removals is desirable.

Scientific parameters, long-lived persisted data, and data received across a trust boundary may instead require schema drift to be reported. Pass strict=True and, when the expected type is known, expected_class. Validation then happens before the class is constructed:

import guidata.dataset as gds

class FitParam(gds.DataSet):
        amplitude = gds.FloatItem("Amplitude", default=1.0, min=0.0)

restored = gds.json_to_dataset(
        json_text,
        strict=True,
        expected_class=FitParam,
)

Using expected_class also prevents a payload from causing an unexpected import. Strict validation reports missing, unknown, and invalid fields together through guidata.dataset.DataSetJSONValidationError:

try:
        restored = gds.json_to_dataset(
                json_text,
                strict=True,
                expected_class=FitParam,
        )
except gds.DataSetJSONValidationError as error:
        print("Missing:", sorted(error.missing_fields))
        print("Unknown:", sorted(error.unknown_fields))
        print("Invalid:", error.invalid_fields)

Every serializable input field is required in strict mode, even when the current class defines a default. This catches renamed fields instead of silently substituting that default. Applications may opt individual additions into defaulting through allowed_missing; nested fields use dotted paths:

restored = gds.json_to_dataset(
        json_text,
        strict=True,
        expected_class=FitParam,
        allowed_missing={"tolerance", "bounds.minimum"},
)

An unknown allowed_missing path is rejected, so a typo cannot accidentally weaken validation. allow_none controls whether a present value may be None; it does not make a field optional. Structural group markers and button items are not persisted. Computed items found in historical output are recognized but ignored on input, while ordinary display-only readonly items remain persisted inputs.

Application-owned versions and migrations¶

Data schema versions belong to the application. guidata.dataset.dataset_to_json() does not write a mandatory version, so existing JSON remains unchanged. An application may add the reserved schema_version key to the decoded object before storing it:

import json

payload = json.loads(gds.dataset_to_json(FitParam(amplitude=2.5)))
payload["schema_version"] = 2
json_text = json.dumps(payload)

expected_version is the maximum version understood by the caller. An absent or older version is accepted, but a future version fails before migration and before the DataSet constructor runs. A migration receives a deep copy of the complete payload and the source version. It may mutate that copy, but must return a JSON object:

def migrate_fit(payload, source_version):
        if source_version in (None, 1):
                payload["amplitude"] = float(payload.pop("a"))
                payload["schema_version"] = 2
        return payload

restored = gds.json_to_dataset(
        historical_json,
        strict=True,
        expected_class=FitParam,
        expected_version=2,
        migrate=migrate_fit,
)

The migrated mapping is revalidated strictly. A migration that leaves a behind, omits amplitude, changes the class identity, or produces an invalid value therefore fails before construction. Exceptions raised by the migration itself are propagated to the caller.

The x-guidata-version value produced by guidata.dataset.dataset_to_schema() is unrelated: it versions guidata’s frontend-oriented JSON Schema document, not application data. Dynamic choices that depend on a DataSet instance can only receive representation-level checks before construction; applications should perform domain-specific migration checks when those choices change between versions.

DataSet class conversion/creation functions¶

Update and restore datasets¶

Create dataset classes¶

Serialize datasets as JSON¶

Strict JSON deserialization¶

Application-owned versions and migrations¶

Table of Contents

Previous topic

Next topic

This Page