koji_habitude.loader

koji_habitude.loader

YAML file loading, path discovery, and pretty-printing.

author:

Christopher O’Brien <obriencj@gmail.com>

license:

GNU General Public License v3

ai-assistant:

Claude 3.5 Sonnet via Cursor

class koji_habitude.loader.MultiLoader(loader_types: List[Type[LoaderProtocol]])

Bases: object

While a YAMLLoader can load one file, a MultiLoader can be used to load a wide range of files and yield the resulting documents in a predictable order

add_loader_type(loader_type: Type[LoaderProtocol]) → None

Add a loader type to the multi-loader.

Parameters:

loader_type – The loader type class to add

load(paths: List[str | Path], recursive: bool = False) → Iterator[Dict[str, Any]]

Load YAML documents from the given paths.

Parameters:

  • paths – List of paths to load from

  • recursive – Whether to recursively search directories

Returns:

Iterator of YAML documents

loader(filename: str | Path) → LoaderProtocol

Lookup the loader type for the given filename and create an instance of it.

Parameters:

filename – The filename to lookup the loader type for

Returns:

An instance of the loader type for the given filename

Raises:

ValueError – If no loader type is found for the given filename

lookup_loader_type(filename: str | Path) → Type[LoaderProtocol] | None

Lookup the loader type for the given filename.

Parameters:

filename – The filename to lookup the loader type for

Returns:

The loader type for the given filename, or None if not found

class koji_habitude.loader.YAMLLoader(filename: str | Path)

Bases: LoaderProtocol

Wraps the invocation of yaml.load_all using a customized MagicSafeLoader, enabling the injection of a '__file__' and '__line__' key into each doc on load, representing the file path it was loaded from, and the line number in that file that the document started on.

Can be added to a MultiLoader to enable handling of files with .yml and .yaml extensions

extensions: Sequence[str] = ('.yml', '.yaml')
load()

Load YAML documents from the file.

Returns:

Iterator of YAML documents with __file__ and __line__ keys

Raises:

YAMLError – If YAML parsing fails

koji_habitude.loader.combine_find_files(pathlist: Iterable[str | Path], extensions: Iterable[str] = ('.yml', '.yaml'), recursive: bool = False, strict: bool = True) → List[Path]

Find files in multiple paths using find_files().

Parameters:

  • pathlist – List of paths to search

  • extensions – File extensions to search for

  • recursive – Whether to recursively search subdirectories

  • strict – Whether to raise an error if paths don’t exist

Returns:

List of matching file paths

koji_habitude.loader.find_files(pathname: str | Path, extensions: Iterable[str] = ('.yml', '.yaml'), recursive: bool = False, strict: bool = True) → List[Path]

Find files with the specified extensions in the given path.

Parameters:

  • pathname – The path to search

  • extensions – File extensions to search for

  • recursive – Whether to recursively search subdirectories

  • strict – Whether to raise an error if the path doesn’t exist

Returns:

List of matching file paths

Raises:
koji_habitude.loader.load_all(fd: TextIO) → Iterator[Dict[str, Any]]

Load all YAML documents from the given file descriptor.

Parameters:

fd – The file descriptor to load from

Returns:

Iterator of YAML documents

koji_habitude.loader.load_yaml_files(paths: List[str | Path], recursive: bool = False) → List[Dict[str, Any]]

Load YAML file content from the given paths, in order, and return the resulting documents as a list.

A shortcut for creating a MultiLoader with the YAMLLoader class and using it to load the given paths.

Parameters:

  • paths – List of file paths to load

  • recursive – Whether to recursively search directories

Returns:

List of YAML documents

koji_habitude.loader.pretty_yaml(doc: ~typing.Dict[str, ~typing.Any], out=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, comments=True, **opts) → None

Pretty-print a single YAML object to the given output stream.

Handles special features of the koji-habitude YAML format, in particular the __file__, __line__, and __trace__ keys. These are removed from the main document body and represented as comments preceeding the document.

Parameters:

  • doc – The YAML document to pretty-print

  • out – The output stream to write to

  • comments – Whether to include comments

  • opts – Additional options to pass to the yaml.dump function

koji_habitude.loader.pretty_yaml_all(sequence: ~typing.Iterable[~typing.Dict[str, ~typing.Any]], out=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, comments=True, **opts) → None

Pretty-print a sequence of YAML documents to the given output stream, with document separators.

Uses pretty_yaml() to pretty-print each document, and so handles the special features of the koji-habitude YAML format, in particular the __file__, __line__, and __trace__ keys.

Parameters:

  • sequence – The sequence of YAML documents to pretty-print

  • out – The output stream to write to

  • comments – Whether to include comments

  • opts – Additional options to pass to the yaml.dump function