`ssb_timeseries.io.json_metadata`¶

Provides a file-based I/O handler for storing metadata in JSON format.

This handler registers dataset metadata in a central “catalog” directory. The structure is /<repository_catalog_path>/<dataset_name>-metadata.json.

This approach duplicates metadata that might also be stored in data files (like Parquet headers), but provides a fast and searchable central index.

class JsonMetaIO(repository, path='', **options)¶

Bases: object

Provides file-based metadata storage for time series Datasets.

This class handles reading and writing metadata to a central catalog, where each dataset’s metadata is stored in a separate JSON file.

Parameters:

repository (FileBasedRepository)
path (str)
options (Any)

__init__(repository, path='', **options)¶

Initialize the handler for a given repository.

The handler holds configuration only. The dataset an operation concerns is named in that operation, so one instance can serve any number of datasets.

Parameters:

repository (Repository) – The repository configuration dictionary.
path (str) – Root path of the catalog, passed in from the repository binding’s options by the dispatcher.
**options (typing.Any) – Handler specific options. Unknown keys are accepted and retained so that handlers can be extended without changing the dispatcher.

Return type:

None

property dir: str¶: Return the configured catalog directory path for the repository.

exists(name)¶

Check if the metadata file for a given dataset exists.

Return type:: bool
Parameters:: name (str)

fullpath(name)¶

Return the full path to a dataset’s metadata file.

Return type:: str
Parameters:: name (str)

read(name)¶

Read and return the metadata for a given dataset.

Parameters:: name (str) – The name of the dataset to read.
Return type:: dict

search(**kwargs)¶

Search the catalog for datasets and series matching given criteria.

Parameters:: **kwargs – Search criteria including ‘equals’, ‘contains’, ‘pattern’, ‘tags’, ‘datasets’ (bool), and ‘series’ (bool).
Return type:: list[dict]
Returns:: A list of dictionaries, where each dictionary represents a matching dataset or series.

write(name, tags)¶

Write metadata tags to a dataset’s JSON file.

Parameters:

name (str) – The name of the dataset.
tags (dict) – The dictionary of metadata to write.

Return type:

None

__getattr__(name)¶

Warn on access to names that have been deprecated (PEP 562).

Module-level __getattr__ only fires for names absent from the module namespace, so deprecated names are defined privately and surfaced here.

Return type:: typing.Any
Parameters:: name (str)

find_metadata_files(path, pattern='', contains='', equals='', **kwargs)¶

Find metadata JSON files in the catalog directory.

Parameters:

path (str | PathLike[str]) – The directory path to search in.
pattern (str) – A glob pattern to match against dataset names.
contains (str) – A substring to match within dataset names.
equals (str) – An exact dataset name to match.
**kwargs – Additional arguments passed to the underlying search function.

Return type:

list[str]

Returns:

A list of full paths to the matching metadata files.

tags_from_json(dict_with_json_string, byte_encoded=True)¶

Deserialize a tag dictionary from the Parquet metadata format.

This is the reverse of tags_to_json, extracting the JSON string from the container dictionary and parsing it.

Return type:

dict

Parameters:

dict_with_json_string (dict)
byte_encoded (bool)

tags_from_json_file(file_or_files)¶

Read and parse one or more metadata JSON files.

Return type:: dict | list[dict]
Parameters:: file_or_files (str | PathLike[str] | list[str | PathLike[str]])

tags_to_json(x)¶

Serialize a tag dictionary into a format suitable for Parquet metadata.

This function encodes the entire tag dictionary as a single JSON string within a new dictionary, which is required for compatibility with the PyArrow schema metadata.

ssb_timeseries.io.json_metadata¶

`ssb_timeseries.io.json_metadata`¶