Spec¶

Specify where your metadata is within a directory.

An extension of the spec module I started in the nwb-conversion-tools package, rebuilt here.

In reseracher-specific data formats, metadata is tucked away in a thousand unpredictable places. The spec module is intended to give you the means of expressing where it is.

If it’s embedded within some path name, try spec.Path,

If it’s embedded in some .mat file, try spec.Mat

Functions:

parse_nested_spec(spec, base_dir)

onice_conversion.spec.parse_nested_spec(spec, base_dir)¶

Base Spec¶

Classes:

BaseSpec(retype, *args, **kwargs)

Base class for specification objects.

Functions:

from_dict(spec_dict)

Reconstitute a spec object from a dict created by BaseSpec.to_dict()

class onice_conversion.spec.base_spec.BaseSpec(retype: Optional[Callable] = None, *args, **kwargs)¶

Bases: abc.ABC, onice_conversion.utils.IntrospectionMixin

Base class for specification objects.

Abstract, should not be instantiated on its own.

Parameters: retype (Callable (optional))

Methods:

`__init__`([retype])	Parameters retype (Callable (optional))
`parse`(base_path[, metadata])	Parse all parameters from self and child `_parse()` methods, combining into single dictionary
`_parse`([base_path, metadata])	All Specs should instantiate a _parse method that returns a dictionary of metadata variable keys and values. eg::.
`children`()	Generator for iterating over children (added)
`to_dict`()	Get a dictionary description of this spec object, of the form.
`_expand_named_fields`(named_fields)	Convert nested key specs like key[key2] into nested dicts
`_full_name`()	Returns the full module and class name of an object, eg.
`_get_init_args`()	introspect object and get all arguments passed on __init__

Attributes:

`specifies`	Which metadata variables are specified by this Spec object and its children
`parent`

__init__(retype: Optional[Callable] = None, *args, **kwargs)¶

Parameters: retype (Callable (optional))

parse(base_path: pathlib.Path, metadata: Optional[dict] = None) → dict ¶

Parse all parameters from self and child _parse() methods, combining into single dictionary

Parameters

base_path (Path) – The base path we compute the spec’d value from!
metadata (dict) – other metadata used by the parsing function, usually passed in NWBConverter.run_conversion()

abstract _parse(base_path=None, metadata: Optional[dict] = None) → dict ¶

All Specs should instantiate a _parse method that returns a dictionary of metadata variable keys and values. eg:

>>> BaseSpec().parse()
{ 'subject_id': 'jonny' }

The typical use is to be able to specify some metadata values that are contained *somewhere* relative to a directory of data, so the passed argument should typically be that directory.

property specifies¶

Which metadata variables are specified by this Spec object and its children

Returns
Return type: tuple of strings

property parent¶

children() → Iterable[onice_conversion.spec.base_spec.BaseSpec]¶: Generator for iterating over children (added)

to_dict() → dict ¶

Get a dictionary description of this spec object, of the form:

{
    'module': self.__module__,
    'class': type(self).__name__,
    'kwargs': self._init_args,
    'children': [ ... same structure as top-level without children list ...]
}

That allows a spec to be reconstituted with from_dict()

Returns
Return type: dict of initialization parameters, as described above

_expand_named_fields(named_fields)¶

Convert nested key specs like key[key2] into nested dicts

borroed from: https://github.com/r1chardj0n3s/parse/blob/0477aa58673cd957c19d377e029347ce72c08b1b/parse.py#L944

_full_name()¶

Returns the full module and class name of an object, eg. nwb_conversion_tools.spec.external_file.JSON

Returns
Return type: str

_get_init_args()¶

introspect object and get all arguments passed on __init__

depends on introspecting up frames so should only be called during the top-level __init__ of the base class :)

Returns
Return type: dict of argument names and params

onice_conversion.spec.base_spec.from_dict(spec_dict: dict) → onice_conversion.spec.base_spec.BaseSpec ¶

Reconstitute a spec object from a dict created by BaseSpec.to_dict()

Parameters: spec_dict (dict) – A dictionary created by BaseSpect.to_dict()
Returns
Return type: The reconstituted spec object!