hdmf.build.manager module

class hdmf.build.manager.Proxy(manager, source, location, namespace, data_type)

Bases: object

A temporary object to represent a Container. This gets used when resolving the true location of a Container’s parent. Proxy objects allow simple bookkeeping of all potential parents a Container may have. This object is used by providing all the necessary information for describing the object. This object gets passed around and candidates are accumulated. Upon calling resolve, all saved candidates are matched against the information (provided to the constructor). The candidate that has an exact match is returned.

property source

The source of the object e.g. file source

property location

The location of the object. This can be thought of as a unique path

property namespace

The namespace from which the data_type of this Proxy came from

property data_type

The data_type of Container that should match this Proxy

matches(object)
Parameters:

object (BaseBuilder or Container) – the container or builder to get a proxy for

add_candidate(container)
Parameters:

container (Container) – the Container to add as a candidate match

resolve()
class hdmf.build.manager.BuildManager(type_map)

Bases: object

A class for managing builds of AbstractContainers

property namespace_catalog
property type_map
property in_export_mode
get_proxy(object, source=None)
Parameters:

  • object (BaseBuilder or AbstractContainer) – the container or builder to get a proxy for

  • source (str) – the source of container being built i.e. file path

build(container, source=None, matched_spec=None, export=False, root=False)

Build the GroupBuilder/DatasetBuilder for the given AbstractContainer

Parameters:

  • container (AbstractContainer) – the container to convert to a Builder

  • source (str) – the source of container being built i.e. file path

  • matched_spec (BaseStorageSpec) – the position-resolved subspec for this container in its parent’s spec tree. Threaded through to ObjectMapper.build, which sets it on the resulting builder as builder.matched_spec.

  • export (bool) – whether this build is for exporting

  • root (bool) – whether the container is the root of the build process

prebuilt(container, builder)

Save the Builder for a given AbstractContainer for future use

Parameters:
queue_ref(func)

Set aside creating ReferenceBuilders

purge_outdated()
clear_cache()
get_builder(container)

Return the prebuilt builder for the given container or None if it does not exist.

Parameters:

container (AbstractContainer) – the container to get the builder for

construct(builder)

Construct the AbstractContainer represented by the given builder

Parameters:

builder (DatasetBuilder or GroupBuilder) – the builder to construct the AbstractContainer from

get_cls(builder)

Get the class object for the given Builder

Parameters:

builder (Builder) – the Builder to get the class object for

get_builder_name(container)

Get the name a Builder should be given

Parameters:

container (AbstractContainer) – the container to convert to a Builder

Returns:

The name a Builder should be given when building this container

Return type:

str

get_subspec(spec, builder)

Get the specification from this spec that corresponds to the given builder

Parameters:
get_builder_ns(builder)

Get the namespace of a builder

Parameters:

builder (DatasetBuilder or GroupBuilder or LinkBuilder) – the builder to get the sub-specification for

get_builder_dt(builder)

Get the data_type of a builder

Parameters:

builder (DatasetBuilder or GroupBuilder or LinkBuilder) – the builder to get the data_type for

is_sub_data_type(builder, parent_data_type)

Return whether or not data_type of builder is a sub-data_type of parent_data_type

Parameters:
Returns:

True if data_type of builder is a sub-data_type of parent_data_type, False otherwise

Return type:

bool

class hdmf.build.manager.TypeSource(namespace: str, data_type: str)

Bases: object

A dataclass to indicate the source of a data type in a namespace.

This placeholder/proxy class represents a lazy reference to a data type from a namespace. This approach ensures that classes are only generated when actually needed, not at namespace load time, and it avoids circular dependency issues.

  • During TypeMap.load_namespaces, when loading namespace dependencies, if a container class doesn’t exist yet for a specified type or a dependent type, a TypeSource is registered instead of the actual class.

  • During TypeMap.get_dt_container_cls, when __get_container_cls encounters a TypeSource, it resolves it by:

    • Calling get_dt_container_cls on the source namespace/type (which may auto-generate the class)

    • Replacing the TypeSource with the actual class via register_container_type

  • When searching for a type across namespaces, TypeSource entries are skipped to avoid returning the wrong namespace.

This class should be used only by TypeMap. TODO: After docval is removed, make this class an inner class of TypeMap.

namespace: str

The namespace from which the data_type originates.

data_type: str

The name of the data type.

class hdmf.build.manager.TypeMap(namespaces=None, mapper_cls=None, type_config=None)

Bases: object

A class to maintain the map between ObjectMappers and AbstractContainer classes

Parameters:
property namespace_catalog
copy_mappers(type_map)
merge(type_map: TypeMap, ns_catalog: bool = False)

Merge the given TypeMap into this one.

This is used to copy the namespaces, mappers, and generators from one TypeMap to another. This is necessary when creating a new TypeMap that includes the same namespaces and mappers as an existing TypeMap, but may have different generators or other customizations. By default, namespaces are not merged to allow for cases where only mappers and generators should be copied without merging namespaces. To also merge namespaces, set ns_catalog=True.

register_generator(generator)

Add a custom class generator.

Parameters:

generator (type) – the CustomClassGenerator class to register

load_namespaces(namespace_path, resolve=True, reader=None)

Load namespaces from a namespace file. This method will call load_namespaces on the NamespaceCatalog used to construct this TypeMap. Additionally, it will process the return value to keep track of what types were included in the loaded namespaces. Calling load_namespaces here has the advantage of being able to keep track of type dependencies across namespaces.

Parameters:

  • namespace_path (str) – the path to the file containing the namespaces(s) to load

  • resolve (bool) – whether or not to include objects from included/parent spec objects. In practice, this is False when generating documentation where it is useful to show the unresolved specs

  • reader (SpecReader or dict) – the SpecReader or dict of SpecReader classes to use for reading specifications

Returns:

the namespaces loaded from the given file

Return type:

dict

get_dt_container_cls(data_type, namespace=None, post_init_method=None, autogen=True)

Get the container class from data type specification. If no class has been associated with the data_type from namespace, a class will be dynamically created and returned.

Namespace is optional. If namespace is unknown, it will be looked up from all namespaces.

Parameters:

  • data_type (str) – the data type to create a AbstractContainer class for

  • namespace (str) – the namespace containing the data_type

  • post_init_method (Callable) – The function used as a post_init method to validate the class generation.

  • autogen (bool) – autogenerate class if one does not exist

Returns:

the class for the given namespace and data_type

Return type:

type

get_builder_dt(builder)

Get the data_type of a builder

Parameters:

builder (DatasetBuilder or GroupBuilder or LinkBuilder) – the builder to get the data_type for

get_builder_ns(builder)

Get the namespace of a builder

Parameters:

builder (DatasetBuilder or GroupBuilder or LinkBuilder) – the builder to get the sub-specification for

get_cls(builder)

Get the class object for the given Builder

Parameters:

builder (Builder) – the Builder object to get the corresponding AbstractContainer class for

get_subspec(spec, builder)

Get the specification from this spec that corresponds to the given builder

Parameters:
get_container_ns_dt(obj)
get_container_cls_dt(cls)
get_container_classes(namespace=None)
Parameters:

namespace (str) – the namespace to get the container classes for

get_map(obj)

Return the ObjectMapper object that should be used for the given container

Parameters:

obj (AbstractContainer or Builder) – the object to get the ObjectMapper for

Returns:

the ObjectMapper to use for mapping the given object

Return type:

ObjectMapper

register_container_type(namespace, data_type, container_cls)

Map a container class to a data_type

Parameters:

  • namespace (str) – the namespace containing the data_type to map the class to

  • data_type (str) – the data_type to map the class to

  • container_cls (TypeSource or type) – the class to map to the specified data_type

register_map(container_cls, mapper_cls)

Map a container class to an ObjectMapper class

Parameters:

  • container_cls (type) – the AbstractContainer class for which the given ObjectMapper class gets used for

  • mapper_cls (type) – the ObjectMapper class to use to map

build(container, manager=None, source=None, builder=None, matched_spec=None)

Build the GroupBuilder/DatasetBuilder for the given AbstractContainer

Parameters:

  • container (AbstractContainer) – the container to convert to a Builder

  • manager (BuildManager) – the BuildManager to use for managing this build

  • source (str) – the source of container being built i.e. file path

  • builder (BaseBuilder) – the Builder to build on

  • matched_spec (BaseStorageSpec) – the position-resolved subspec for this container in its parent’s spec tree. Forwarded to ObjectMapper.build, which records it on the resulting builder as builder.matched_spec.

construct(builder, build_manager=None, parent=None)

Construct the AbstractContainer represented by the given builder

Parameters:
get_builder_name(container)

Get the name a Builder should be given

Parameters:

container (AbstractContainer) – the container to convert to a Builder

Returns:

The name a Builder should be given when building this container

Return type:

str