TimeAtlas Client

Acts as the interface between in-memory RDE model objects and the serialization layer expected by the Time Atlas ingestion pipeline. Entities are grouped by their concrete class and written to individual JSON files, each wrapped in the standard RDE envelope format used throughout the project:

{
    "name": "<filename stem>",
    "type_in_file": ["<rde_type string>"],
    "creation_time": "<ISO-8601 timestamp>",
    "rde_objects": [ ... ]
}

rdes: Flat list of all RDE instances held in this collection.

__init__(rdes)[source]

Create an RDECollection.

Parameters:: rdes (list[RDE]) – List of RDE instances to include in this collection.

add(rdes)[source]

Append one or more RDE instances to the collection.

Parameters:: rdes (list[RDE] | RDE) – A single RDE instance or a list of RDE instances to add.
Return type:: None

save_rde_to_files(output_dir, overwrite=False, rde_types=None)[source]

Serialize the collection’s RDE entities to individual JSON files grouped by type.

For each RDE class present in the collection, one .json file is written to output_dir. The file name matches the keys in _FILE_MAP (e.g. historical_records.json, observations.json).

Serialization relies on each entity’s own to_dict() method. Shapely geometry objects that appear in the resulting dicts (e.g. from Observation or PointOfInterest) are automatically converted to GeoJSON-compatible dicts during the JSON encoding step, so no manual geometry handling is required before calling this method.

If a file already exists and overwrite is False, the serialized rde_objects list is compared with the file’s current content; the file is only rewritten when the content has actually changed. This avoids spurious modification timestamps that would trigger unnecessary downstream reprocessing.

Parameters:

output_dir (str) – Path to the directory where output files are written. The directory (and any missing parents) is created automatically if it does not yet exist.
overwrite (bool) – When True, rewrite every output file unconditionally, even if the content is unchanged. Defaults to False.
rde_types (list[type] | None) – Optional list of RDE classes to serialize (e.g. [HistoricalRecord, Observation]). When None (the default), all types present in the collection are written.

Raises:

OSError – If output_dir cannot be created or a file cannot be written.

Return type:

None

classmethod read_rde_from_files(input_dir)[source]

Deserialize RDE entities from JSON files produced by save_rde_to_files().

Scans input_dir for .json files, reads each envelope, and reconstructs the appropriate RDE class instances using the rde_type label stored in the type_in_file envelope field. The class is resolved once per file via RDE_TYPE_TO_STATIC_CLASS_DEF, then each object in rde_objects is passed to the matching class’s constructor_from_json_obj classmethod.

Files whose type_in_file value is absent or unrecognised are silently skipped, so partially-populated directories are handled gracefully.

Parameters:

input_dir (str) – Path to the directory containing the serialized .json files.

Returns:

A new RDECollection populated with all successfully deserialized RDE instances.

Raises:

FileNotFoundError – If input_dir does not exist.
json.JSONDecodeError – If a file contains malformed JSON.

Return type:

RDECollection

consolidate_data()[source]

Produce the PoIS and update observations references to them.

Return type:: None

validate_data()[source]

Validate the internal consistency of all RDE entities in the collection.

Performs three categories of checks:

Global UUID uniqueness — every entity in the collection must have a distinct UUID.
Array-field UUID uniqueness — within each entity, array fields that hold references to other RDEs must not contain duplicate UUIDs. The affected fields are:
No stale references — whenever an entity references another entity by UUID, that target entity must also be present in the collection. The following reference fields are checked:
- HistoricalRecord.dataset → Dataset
- HistoricalRecord.has_observations → Observation
- Observation.historical_record → HistoricalRecord
- Observation.part_of_point_of_interest → PointOfInterest
- Observation.has_geometries → Geometry
- Layer.map → Map
- Map.layers → Layer
The following fields are intentionally exempt from stale-reference checking because they routinely point to entities outside the collection:
- Geometry.part_of_layer
- Dataset.has_areas
- Map.areas

Sets _valid_data to True when all checks pass. Any failure raises a ValueError listing every detected problem.

Returns:: True when the collection passes all checks.
Raises:: ValueError – If one or more validation checks fail. The exception message lists every individual problem found.
Return type:: bool

Usage Examples

Basic Usage

from timeatlas import TimeAtlas

# Initialize the client
client = TimeAtlas(api_url='https://your-timeatlas-instance.com/v1')

# Fetch a single RDE object
entity = client.get_single_rde_object('historical-records', 'uuid-here')

# Save entity cache to file
client.save_entity_cache_to_file('my_cache.pkl')

Working with Cached Entities

The TimeAtlas client maintains an internal cache of fetched entities for improved performance. The cache is automatically saved to disk and loaded on subsequent client initializations.

# Cache is automatically loaded from default file on initialization
client = TimeAtlas(api_url='https://api.example.com/v1')

# Save cache to custom location
client.save_entity_cache_to_file('custom_cache.pkl')

Serializing and Validating RDE Collections

RDECollection groups entities for validation and file-based interchange.

from timeatlas import RDECollection

collection = RDECollection([dataset, historical_record, observation])
collection.validate_data()
collection.save_rde_to_files("export", overwrite=True)

restored = RDECollection.read_rde_from_files("export")