vibeview.importers

Third-party importer discovery for vibe-view.

Importer packages register one object in the vibeview.importers entry point group. The object may be an ImporterSpec or a zero-argument factory returning one. Keeping the contract in this small, renderer-free module lets chemistry codes add file support without depending on vibe-view’s web or desktop stack.

Functions

available_importers()	Return successfully loaded importers in deterministic order.
clear_importer_cache()	Clear discovery state after installing a plugin in this process.
convert_with_importer(spec, path)	Run one plugin and validate its QVF output before returning it.
detect_importer(path)	Return the first installed plugin accepting path.
discover_importers()	Load installed importer plugins, isolating failures per plugin.
get_importer(format_name)	Return the installed importer named format_name.

Classes

ImporterSpec(format_name, description, ...)	Versioned contract implemented by a third-party file importer.
ImporterStatus(entry_point, distribution, spec)	One discovered entry point, including isolated load failures.

Exceptions

ImporterError

An importer could not be loaded or did not produce a valid QVF.

exception vibeview.importers.ImporterError

Bases: ValueError

An importer could not be loaded or did not produce a valid QVF.

class vibeview.importers.ImporterSpec(format_name, description, extensions, convert, stems=(), probe=None, data_kinds=('structure',), api_version=1)

Bases: object

Versioned contract implemented by a third-party file importer.

format_name is the stable CLI name used by --from. Extensions include their leading dot and are matched case-insensitively. Exact stems cover extensionless formats such as POSCAR. A custom probe may inspect a path when suffix matching is insufficient.

convert must return a complete QVF archive as bytes or a readable binary file object positioned anywhere; vibe-view rewinds and validates the archive before it reaches the caller.

Parameters:

• format_name (str)

• description (str)

• extensions (tuple[str, ...])

• convert (Callable[[Path], bytes | bytearray | BinaryIO])

• stems (tuple[str, ...])

• probe (Callable[[Path], bool] | None)

• data_kinds (tuple[str, ...])

• api_version (int)

format_name: str

description: str

extensions: tuple[str, ...]

convert: Callable[[Path], bytes | bytearray | BinaryIO]

stems: tuple[str, ...] = ()

probe: Callable[[Path], bool] | None = None

data_kinds: tuple[str, ...] = ('structure',)

api_version: int = 1

matches(path)

Return whether this importer accepts path.

Parameters:

path (Path)

Return type:

bool

class vibeview.importers.ImporterStatus(entry_point, distribution, spec, error=None)

Bases: object

One discovered entry point, including isolated load failures.

Parameters:

• entry_point (str)

• distribution (str | None)

• spec (ImporterSpec | None)

• error (str | None)

entry_point: str

distribution: str | None

spec: ImporterSpec | None

error: str | None = None

property available: bool

vibeview.importers.discover_importers()

Load installed importer plugins, isolating failures per plugin.

Return type:

tuple[ImporterStatus, …]

vibeview.importers.clear_importer_cache()

Clear discovery state after installing a plugin in this process.

Return type:

None

vibeview.importers.available_importers()

Return successfully loaded importers in deterministic order.

Return type:

tuple[ImporterSpec, …]

vibeview.importers.get_importer(format_name)

Return the installed importer named format_name.

Parameters:

format_name (str)

Return type:

ImporterSpec | None

vibeview.importers.detect_importer(path)

Return the first installed plugin accepting path.

Parameters:

path (str | Path)

Return type:

ImporterSpec | None

vibeview.importers.convert_with_importer(spec, path)

Run one plugin and validate its QVF output before returning it.

Parameters:

• spec (ImporterSpec)

• path (str | Path)

Return type:

BytesIO