R3XA_API — API Reference

This page is reference documentation. Use it to look up exact symbols, signatures, and return types.

This page documents the public API intended for library users.

Stability policy

  • Symbols documented on this page define the supported public SDK for the 1.x series.

  • Compatibility helpers remain available throughout the 1.x series and will not be removed before 2.0.

  • Guided helpers (add_<kind>_setting/source/data_set) are part of the public contract and are tested against the schema-derived required fields.

  • Undocumented module internals may evolve more freely.

See STABILITY.md at the repository root for the concise policy.

Core class

R3XAFile

Create and manage a full R3XA document.

Constructor

R3XAFile(version: str | None = None, **header)

  • version: optional schema version, defaults to the embedded schema.

  • header: any header fields (title, description, authors, date, repository, …).

Methods

R3XAFile.from_dict(payload: dict) -> R3XAFile
R3XAFile.load(path: str | Path) -> R3XAFile
R3XAFile.loads(text: str) -> R3XAFile

Create a builder from an existing payload, JSON file, or JSON string.

set_header(**fields) -> R3XAFile

Update header fields.

add_setting(kind: str, **fields) -> dict
add_data_source(kind: str, **fields) -> dict
add_data_set(kind: str, **fields) -> dict

Low‑level methods for any schema kind.

add_<kind>_setting(...)
add_<kind>_source(...)
add_<kind>_data_set(...)

Schema‑driven guided helpers exist for every supported kind. They expose the schema required fields as explicit parameters and accept optional schema fields through **extra.

Examples:

add_generic_setting(title, description, **extra) -> dict
add_specimen_setting(title, description, sizes, **extra) -> dict
add_testing_machine_setting(title, description, type, **extra) -> dict
add_camera_source(title, output_components, output_dimension, output_units, image_size, **extra) -> dict
add_load_cell_source(output_components, output_dimension, output_units, capacity, **extra) -> dict
add_generic_data_set(title, description, data_sources, file_type, path, **extra) -> dict
add_list_data_set(title, description, file_type, data_sources, time_reference, timestamps, data, **extra) -> dict
add_file_data_set(title, description, data_sources, time_reference, timestamps, data, **extra) -> dict

Complete guided helper inventory for the current schema:

  • Settings

    • add_generic_setting(...)

    • add_specimen_setting(...)

    • add_stereorig_setting(...)

    • add_testing_machine_setting(...)

  • Data sources

    • add_camera_source(...)

    • add_dic_measurement_source(...)

    • add_generic_source(...)

    • add_identification_source(...)

    • add_infrared_source(...)

    • add_load_cell_source(...)

    • add_mechanical_analysis_source(...)

    • add_point_temperature_source(...)

    • add_strain_computation_source(...)

    • add_strain_gauge_source(...)

    • add_tomograph_source(...)

  • Data sets

    • add_file_data_set(...)

    • add_generic_data_set(...)

    • add_list_data_set(...)

  • Legacy aliases

    • add_image_set_list(...)

    • add_image_set_file(...)

Backward-compatible aliases remain available:

add_image_set_list(...) == add_list_data_set(...)
add_image_set_file(...) == add_file_data_set(...)

to_dict() -> dict
dump(indent: int = 4) -> str
validate() -> None
save(path: str | Path, indent: int = 4, validate: bool = True) -> Path

Serialize, validate, and write to disk.

Typical edit cycle:

from r3xa_api import R3XAFile

r3xa = R3XAFile.load("experiment.json")
r3xa.set_header(title="Updated title")
r3xa.save("experiment_updated.json")

Helper functions

unit(...)

unit(title: str | None = None, value: float | None = None, unit: str | None = None, scale: float | None = 1.0, **extra) -> dict

Build a schema‑compliant unit object. Only unit is required by the schema; title, value, and scale are optional metadata.

data_set_file(...)

data_set_file(filename: str, delimiter: str | None = None, data_range: str | None = None, **extra) -> dict

Build a schema‑compliant data_set_file object.

Registry utilities

load_item(path) -> dict

Load a registry JSON item from disk.

save_item(path, item, validate=True, kind=None) -> Path

Validate and save a single registry item JSON to disk. item can be a plain dict or a RegistryItem.

These helpers remain available for advanced use cases and backward compatibility. For day-to-day usage, prefer Registry.get_item(...), RegistryItem.merge(...), and RegistryItem.save(...).

Registry

Helper class that encapsulates the registry root and provides loading, validation, discovery, merge, wrapping, and save methods.

from r3xa_api import Registry, new_item, unit

registry = Registry("registry")
camera = registry.get_item("data_sources/camera/avt_dolphin_f145b")

new_camera = new_item(
    "data_sources/camera",
    title="Example generated camera",
    description="Example registry camera generated with R3XA_API",
    output_components=1,
    output_dimension="surface",
    output_units=[unit(title="graylevel", value=1.0, unit="gl", scale=1.0)],
    manufacturer="Example manufacturer",
    model="Example model",
    image_size=[
        unit(title="width", value=2048, unit="px", scale=1.0),
        unit(title="height", value=1536, unit="px", scale=1.0),
    ],
)

registry.wrap(new_camera, tree_path="data_sources/camera/example_generated_camera").save()

Most useful instance methods:

load(tree_path: str) -> dict
load_validated(tree_path: str, kind: str | None = None) -> dict
get_item(tree_path: str, validated: bool = True, kind: str | None = None) -> RegistryItem
wrap(item: Mapping[str, Any], tree_path: str | None = None) -> RegistryItem
list(section: str | None = None, kind: str | None = None) -> list[str]
iter_items(section: str | None = None, kind: str | None = None, validated: bool = False, wrapped: bool = False) -> Iterator[tuple[str, dict | RegistryItem]]
merge(tree_path: str, **overrides) -> RegistryItem
save(tree_path: str, item: dict | RegistryItem, validate: bool = True, kind: str | None = None) -> Path

Naming rule:

  • prefer load(...) / load_validated(...) in new code because these methods read JSON files from the registry tree

  • get(...) / get_validated(...) remain available as compatibility aliases

Typical registry workflow:

from r3xa_api import Registry

registry = Registry("registry")

for tree_path in registry.list(kind="data_sources/camera"):
    print(tree_path)

camera = registry.get_item("data_sources/camera/avt_dolphin_f145b").merge(
    id="cam_exp01",
    description="Camera used in experiment 01",
)
camera.save("camera_exp01.json")

RegistryItem

Dictionary-like wrapper returned by Registry.get_item(...).

It keeps the current dict-based design, but attaches the common item-level operations directly to the item: you can still use it anywhere a plain item dict is expected (for example r3xa.data_sources.append(camera_item)).

validate(kind: str | None = None, schema: dict | None = None) -> RegistryItem
merge(**overrides) -> RegistryItem
save(path: str | Path | None = None, validate: bool = True, kind: str | None = None) -> Path
save_to(registry: Registry | str | Path, tree_path: str | None = None, validate: bool = True, kind: str | None = None) -> Path
bind(registry_root: str | Path | None = None, tree_path: str | None = None) -> RegistryItem
to_dict() -> dict

Typical workflows:

from r3xa_api import Registry

registry = Registry("registry")

# Load an existing registry item, edit it, and save a standalone JSON copy.
camera = registry.get_item("data_sources/camera/avt_dolphin_f145b")
camera = camera.merge(description="Camera used in experiment 01")
camera.save("camera_exp01.json")

# Build a new item, bind it to a registry key, and save it into the registry tree.
new_camera = registry.wrap(
    {
        "id": "ds_cam_exp02",
        "kind": "data_sources/camera",
        "title": "Experiment camera",
        "description": "Bound registry item",
        "output_components": 1,
        "output_dimension": "surface",
        "output_units": [{"kind": "unit", "unit": "gl"}],
        "manufacturer": "Example",
        "model": "Cam-01",
        "image_size": [{"kind": "unit", "unit": "px"}],
    },
    tree_path="data_sources/camera/experiment_camera",
)
new_camera.validate().save()

validate_item(item, kind=None, schema=None) -> None

Validate a single item against its schema definition (e.g. data_sources/camera).

This function is part of the advanced compatibility helper layer. It remains supported in the 1.x series, but for end-user workflows the recommended entry points are RegistryItem.validate(...) and Registry.validate(...).

Advanced

load_item_path(root, tree_path) -> dict
Internal/advanced helper to load a registry item by its tree path string, e.g. settings/specimen/openhole_sample.

save_item_path(root, tree_path, item, validate=True, kind=None) -> Path
Validate then save a registry item using a section/kind/name tree path, e.g. data_sources/camera/example_generated_camera.

load_registry(root) -> dict

Load a full registry tree into memory.

merge_item(base, **overrides) -> dict

Create a new item by overriding fields of a registry item.

This is a shallow merge helper. For end-user workflows, prefer RegistryItem.merge(...) or Registry.merge(...).

Schema utilities

load_schema(path: str | None = None) -> dict

Load the embedded schema (or a custom path).

schema_version(path: str | None = None) -> str | None

Extract the schema version.

validate(instance: dict, schema: dict | None = None) -> None

Validate a JSON instance against the schema.