pyiron_snippets.resources module

Classes to find data files and executables in global paths.

class pyiron_snippets.resources.AbstractResolver

Bases: ABC

Interface for resolvers.

Implementations must define _search(), taking a tuple of names to search for and yielding instances of any type. Implementations should pick a single type to yield, e.g. ResourceResolver always yields absolute paths, while ExecutableResolver always yields 2-tuples of a version tag and absolute paths.

chain(*resolvers: AbstractResolver) → Self | ResolverChain

Return a new resolver that searches this and all given resolvers sequentially.

You will likely want to ensure that all given resolvers yield the same types and e.g. not mix ExecutableResolver and ResourceResolver, but this is not checked.

The advantage of using chain() rather than adding more paths to one resolver is when different paths have different internal sub structure, such as when combining resources from pyiron resources and conda data packages. When searching for lammps potential files, e.g. we have some folders that are set up as

<resources>/lammps/potentials/…

but iprpy conda package that ships the NIST potentials doesn’t have the lammps/potentials

<iprpy>/…

With chaining we can do very easily

>>> ResourceResolver([<resources>], "lammps", "potentials").chain(
...     ResourceResolver([<iprpy>]))

without we’d need to modify the resource paths ourselves explicitly

>>> ResourceResolver([r + '/lammps/potentials' for r in <resources>] + [<iprpy>])

which is a bit more awkward.

Parameters:

resolvers (AbstractResolver) – any number of sub resolvers

Returns:

if resolvers is empty ResolverChain: otherwise

Return type:

self

first(name: Iterable[str] | str = '*') → Any

Return first match.

Parameters:

name (str, iterable of str) – file name to search for; can be an exact file name, a glob or list of those

Returns:

the first match returned by search().

Return type:

object

Raises:

ResourceNotFound – if no matches are found.

list(name: Iterable[str] | str = '*') → list[Any]

Return all matches.

Parameters:

name (str, iterable of str) – file name to search for; can be an exact file name, a glob or list of those

Returns:

all matches returned by search().

Return type:

list

search(name: Iterable[str] | str = '*') → Iterator[Any]

Yield all matches.

When name is given as an iterable, returned results match at least one of the name globs.

Parameters:

name (str, iterable of str) – file name to search for; can be an exact file name, a glob or list of those

Yields:

object – resources matching name

class pyiron_snippets.resources.ExecutableResolver(resource_paths, code, module=None, suffix='sh')

Bases: AbstractResolver

A resolver for executable scripts.

Executables are expected to conform to the following format:

<resource_path>/<module>/bin/run_<code>_<version_string>.<suffix>

and have the executable bit set. search() yields tuples of version strings and full paths to the executable instead of plain strings.

Except on windows results are filtered to make sure all returned scripts have the executable bit set. When the bit is not set, a warning is printed.

>>> exe = ExecutableResolver(..., "lammps")
>>> exe.list()
[
    ('v1', '/my/resources/lammps/bin/run_lammps_v1.sh),
    ('v1_mpi', '/my/resources/lammps/bin/run_lammps_v1_mpi.sh),
    ('v2_default', '/my/resources/lammps/bin/run_lammps_v2_default.sh),
]
>>> exe.default_version
"v2_default"
>>> exe.dict("v1*")
{
    'v1': '/my/resources/lammps/bin/run_lammps_v1.sh),
    'v1_mpi': '/my/resources/lammps/bin/run_lammps_v1_mpi.sh)
}

property available_versions

all found versions

Type:

list of str

property default_version

the first version found in resources

If a version matching *default* exists, the first matching is returned.

Raises:

.ResourceNotFound – if no executables are found at all

Type:

str

dict(name='*') → dict[str, str]

Construct dict from search() results.

Parameters:

name (str or list of str) – glob(s) to filter the version strings

Returns:

mapping version strings to full paths

Return type:

dict

class pyiron_snippets.resources.ResolverChain(*resolvers)

Bases: AbstractResolver

A chain of resolvers. Matches are returned sequentially.

exception pyiron_snippets.resources.ResolverWarning

Bases: RuntimeWarning

exception pyiron_snippets.resources.ResourceNotFound

Bases: RuntimeError

class pyiron_snippets.resources.ResourceResolver(resource_paths, module, *subdirs)

Bases: AbstractResolver

Generic resolver for files and directories.

Resources are expected to conform to the following format:

<resource_path>/<module>/<subdir0>/<subdir1>/…

All entries within in this final subdir are yielded by search(), whether they are files or directories. Search results can be restricted by passing a (list of) globs. If a list is given, entries matching at least one of them are returned.

>>> res = ResourceResolver(..., "lammps")
>>> res.list()
[
    "bin",
    "potentials",
    "potentials.csv"
]