httk.core.loading

Dispatch file readers and optional domain adapters.

load retains the neutral reader result when no domain adapter owns its format, while installed capability modules can register adapters to provide a one-call domain-loading experience. Callers that need the neutral payload can use raw=True.

Functions

reader_uses_extension(name)	Return whether name is claimed by an extension rather than a basename.
adapt_result(result, raw)	Apply a registered format adapter unless raw is requested.
load_source(source, name, *[, raw])	Load source using the reader selected by name.
load(filename, *[, raw])	Load filename and adapt its neutral payload to a domain object.
load_many(sources, *[, processes, errors])	Load multiple sources lazily, preserving input order.

Module Contents

httk.core.loading.reader_uses_extension(name)

Return whether name is claimed by an extension rather than a basename.

Parameters:

name (str) – Filename or URL path whose reader registration is checked.

Returns:

Whether an extension registration claims the name.

Return type:

bool

httk.core.loading.adapt_result(result, raw)

Apply a registered format adapter unless raw is requested.

Parameters:

• result (Any) – Neutral reader result to inspect for a format tag.

• raw (bool) – Whether to return the neutral result without adaptation.

Returns:

The adapted domain value or the unchanged reader result.

Return type:

Any

httk.core.loading.load_source(source, name, *, raw=False, **kwargs)

Load source using the reader selected by name.

Parameters:

• source (Any) – Source passed to the selected reader.

• name (str) – Name used for extension or exact-basename dispatch.

• raw (bool) – Whether to return the neutral reader result without adaptation.

• **kwargs (Any) – Additional options passed to the selected reader.

Returns:

The reader result, optionally adapted to a domain value.

Raises:

ValueError – If no reader matches the name; the error lists known extensions and basenames.

Return type:

Any

httk.core.loading.load(filename, *, raw=False, **kwargs)

Load filename and adapt its neutral payload to a domain object.

Dispatch strips at most one recognized compression suffix (.gz, .bz2, …) to obtain an inner name, then selects a reader by that inner name’s extension (.cif, .poscar, …) or, failing that, by its exact basename (POSCAR, CONTCAR; case-insensitive). The selected reader always receives the original filename; readers open it through the datastream layer, which transparently decompresses. By default, a mapping with a string "format" tag is passed to the registered domain adapter for that format. raw=True is the neutral-payload escape hatch. Payloads with unknown formats, and non-mapping reader results, pass through unchanged.

Parameters:

• filename (str) – Local filename to read.

• raw (bool) – Whether to return the neutral reader result without adaptation.

• **kwargs (Any) – Additional options passed to the selected reader.

Returns:

The loaded and optionally adapted value.

Raises:

ValueError – If filename is a URL or no reader matches it.

Return type:

Any

httk.core.loading.load_many(sources, *, processes=None, errors='raise', **kwargs)

Load multiple sources lazily, preserving input order.

processes=None uses the process-pool default. processes=0 or processes=1 loads in the current process, which is also the guaranteed path for readers registered at runtime. Parallel workers rediscover installed registration packages, but runtime registrations are not guaranteed to be present in a fresh worker. Parallel work uses bounded ordered futures rather than map() so worker failures and result-pickling failures can be returned per source.

Parameters:

• sources (collections.abc.Iterable[Any]) – Sources accepted by load().

• processes (int | None) – Number of worker processes, or None for the default.

• errors (Literal['raise', 'return']) – Whether to raise failures or yield them as exception values.

• **kwargs (Any) – Options forwarded to every load() call.

Returns:

A lazy iterator of (source, result) pairs in input order.

Raises:

• ValueError – If errors is not "raise" or "return", or if processes is negative.

• TypeError – If processes is not an integer or None.

Return type:

collections.abc.Generator[tuple[Any, Any], None, None]