Skip to content

README

liblaf.cherries.core.assets.bundle

Classes:

  • Bundle –

    Base class for artifact companion-file discovery.

  • BundleItem –

    Related file discovered for a logged artifact.

  • BundleLandmarks –

    Expand mesh artifacts to an optional sibling landmark file.

  • BundleRegistry –

    Registry that expands logged artifacts through matching bundles.

  • BundleSeries –

    Expand a VTK .series manifest to its required frame files.

Functions:

  • relative_or_absolute –

    Return path relative to prefix, or an absolute path if unrelated.

  • relative_or_name –

    Return path relative to prefix, or just the file name if unrelated.

Attributes:

bundles module-attribute 

bundles: BundleRegistry = BundleRegistry()

Bundle

Bases: ABC


              flowchart TD
              liblaf.cherries.core.assets.bundle.Bundle[Bundle]

              

              click liblaf.cherries.core.assets.bundle.Bundle href "" "liblaf.cherries.core.assets.bundle.Bundle"

Base class for artifact companion-file discovery.

Methods:

  • ls_files –

    Yield files that should be logged with path.

  • match –

    Return whether this bundle can expand path.

ls_files abstractmethod 

ls_files(path: Path) -> Iterable[BundleItem]

Yield files that should be logged with path.

Parameters:

  • path (Path) –

    Primary artifact path.

Returns:

  • Iterable[BundleItem] –

    Iterable of companion files and their optional/missing-file policy.

Source code in src/liblaf/cherries/core/assets/bundle/_abc.py 
40
41
42
43
44
45
46
47
48
49
50
@abc.abstractmethod
def ls_files(self, path: Path) -> Iterable[BundleItem]:
    """Yield files that should be logged with `path`.

    Args:
        path: Primary artifact path.

    Returns:
        Iterable of companion files and their optional/missing-file policy.
    """
    raise NotImplementedError

match abstractmethod 

match(path: Path) -> bool

Return whether this bundle can expand path.

Parameters:

  • path (Path) –

    Primary artifact path.

Returns:

Source code in src/liblaf/cherries/core/assets/bundle/_abc.py 
27
28
29
30
31
32
33
34
35
36
37
38
@abc.abstractmethod
def match(self, path: Path) -> bool:
    """Return whether this bundle can expand `path`.

    Args:
        path: Primary artifact path.

    Returns:
        `True` when [`ls_files`][liblaf.cherries.core.assets.bundle.Bundle.ls_files]
        can yield companion files for `path`.
    """
    raise NotImplementedError

BundleItem

Bases: NamedTuple


              flowchart TD
              liblaf.cherries.core.assets.bundle.BundleItem[BundleItem]

              

              click liblaf.cherries.core.assets.bundle.BundleItem href "" "liblaf.cherries.core.assets.bundle.BundleItem"

Related file discovered for a logged artifact.

Attributes:

Parameters:

  • path (ForwardRef, default: None ) –
  • optional (ForwardRef, default: None ) –

optional instance-attribute 

optional: bool

path instance-attribute 

path: StrPath

BundleLandmarks

Bases: Bundle


              flowchart TD
              liblaf.cherries.core.assets.bundle.BundleLandmarks[BundleLandmarks]
              liblaf.cherries.core.assets.bundle._abc.Bundle[Bundle]

                              liblaf.cherries.core.assets.bundle._abc.Bundle --> liblaf.cherries.core.assets.bundle.BundleLandmarks
                


              click liblaf.cherries.core.assets.bundle.BundleLandmarks href "" "liblaf.cherries.core.assets.bundle.BundleLandmarks"
              click liblaf.cherries.core.assets.bundle._abc.Bundle href "" "liblaf.cherries.core.assets.bundle._abc.Bundle"

Expand mesh artifacts to an optional sibling landmark file.

Cherries treats files such as mesh.vtu and mesh.stl as primary mesh artifacts. When a sibling mesh.landmarks.json exists, the file is logged with the primary artifact; when it is absent, no warning is emitted.

Parameters:

  • suffixes (set[str], default: {'.vtr', '.vtkhdf', '.obj', '.stl', '.ply', '.vtu', '.vtp', '.vti', '.vts'} ) –

Methods:

  • ls_files –

    Yield the optional .landmarks.json companion for path.

  • match –

    Return whether path has a supported mesh suffix.

Attributes:

suffixes class-attribute instance-attribute 

suffixes: set[str] = field(
    factory=lambda: {
        ".obj",
        ".ply",
        ".stl",
        ".vti",
        ".vtkhdf",
        ".vtp",
        ".vtr",
        ".vts",
        ".vtu",
    }
)

ls_files 

ls_files(path: Path) -> Generator[BundleItem]

Yield the optional .landmarks.json companion for path.

Source code in src/liblaf/cherries/core/assets/bundle/_landmarks.py 
38
39
40
41
42
@override
def ls_files(self, path: Path) -> Generator[BundleItem]:
    """Yield the optional `.landmarks.json` companion for `path`."""
    absolute: Path = path.with_suffix(".landmarks.json")
    yield BundleItem(absolute, optional=True)

match 

match(path: Path) -> bool

Return whether path has a supported mesh suffix.

Source code in src/liblaf/cherries/core/assets/bundle/_landmarks.py 
33
34
35
36
@override
def match(self, path: Path) -> bool:
    """Return whether `path` has a supported mesh suffix."""
    return path.suffix in self.suffixes

BundleRegistry

Registry that expands logged artifacts through matching bundles.

Examples:

>>> registry = BundleRegistry(registry=[])
>>> list(registry.ls_files(Path("mesh.vtu")))
[]

Parameters:

  • registry (list[Bundle], default: [BundleLandmarks(suffixes={'.vtr', '.vtkhdf', '.obj', '.stl', '.ply', '.vtu', '.vtp', '.vti', '.vts'}), BundleSeries()] ) –

Methods:

  • ls_files –

    Yield companion files from every bundle that matches path.

  • register –

    Append bundle to the registry.

Attributes:

registry class-attribute instance-attribute 

registry: list[Bundle] = field(factory=_default_registry)

ls_files 

ls_files(path: Path) -> Generator[BundleItem]

Yield companion files from every bundle that matches path.

Source code in src/liblaf/cherries/core/assets/bundle/_registry.py 
28
29
30
31
32
def ls_files(self, path: Path) -> Generator[BundleItem]:
    """Yield companion files from every bundle that matches `path`."""
    for bundle in self.registry:
        if bundle.match(path):
            yield from bundle.ls_files(path)

register 

register(bundle: Bundle) -> None

Append bundle to the registry.

Source code in src/liblaf/cherries/core/assets/bundle/_registry.py 
34
35
36
def register(self, bundle: Bundle) -> None:
    """Append `bundle` to the registry."""
    self.registry.append(bundle)

BundleSeries

Bases: Bundle


              flowchart TD
              liblaf.cherries.core.assets.bundle.BundleSeries[BundleSeries]
              liblaf.cherries.core.assets.bundle._abc.Bundle[Bundle]

                              liblaf.cherries.core.assets.bundle._abc.Bundle --> liblaf.cherries.core.assets.bundle.BundleSeries
                


              click liblaf.cherries.core.assets.bundle.BundleSeries href "" "liblaf.cherries.core.assets.bundle.BundleSeries"
              click liblaf.cherries.core.assets.bundle._abc.Bundle href "" "liblaf.cherries.core.assets.bundle._abc.Bundle"

Expand a VTK .series manifest to its required frame files.

Methods:

  • ls_files –

    Read path and yield every frame listed in the manifest.

  • match –

    Return whether path ends with .series.

ls_files 

ls_files(path: Path) -> Generator[BundleItem]

Read path and yield every frame listed in the manifest.

Source code in src/liblaf/cherries/core/assets/bundle/_series.py 
53
54
55
56
57
58
59
@override
def ls_files(self, path: Path) -> Generator[BundleItem]:
    """Read `path` and yield every frame listed in the manifest."""
    series: Series = Series.model_validate_json(path.read_bytes())
    for meta in series.files:
        absolute: Path = path.parent / meta.name
        yield BundleItem(absolute, optional=False)

match 

match(path: Path) -> bool

Return whether path ends with .series.

Source code in src/liblaf/cherries/core/assets/bundle/_series.py 
48
49
50
51
@override
def match(self, path: Path) -> bool:
    """Return whether `path` ends with `.series`."""
    return path.suffix == ".series"

relative_or_absolute 

relative_or_absolute(path: Path, prefix: Path) -> Path

Return path relative to prefix, or an absolute path if unrelated.

Examples:

>>> relative_or_absolute(
...     Path("/tmp/cherries/data/out.txt"), Path("/tmp/cherries")
... )
PosixPath('data/out.txt')
>>> relative_or_absolute(Path("/var/tmp/out.txt"), Path("/tmp/cherries"))
PosixPath('/var/tmp/out.txt')
Source code in src/liblaf/cherries/core/assets/bundle/_utils.py 
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
def relative_or_absolute(path: Path, prefix: Path) -> Path:
    """Return `path` relative to `prefix`, or an absolute path if unrelated.

    Examples:
        >>> relative_or_absolute(
        ...     Path("/tmp/cherries/data/out.txt"), Path("/tmp/cherries")
        ... )
        PosixPath('data/out.txt')
        >>> relative_or_absolute(Path("/var/tmp/out.txt"), Path("/tmp/cherries"))
        PosixPath('/var/tmp/out.txt')
    """
    try:
        return path.relative_to(prefix)
    except ValueError:
        return path.resolve()

relative_or_name 

relative_or_name(path: Path, prefix: Path) -> Path

Return path relative to prefix, or just the file name if unrelated.

Examples:

>>> relative_or_name(Path("/tmp/cherries/data/out.txt"), Path("/tmp/cherries"))
PosixPath('data/out.txt')
>>> relative_or_name(Path("/var/tmp/out.txt"), Path("/tmp/cherries"))
PosixPath('out.txt')
Source code in src/liblaf/cherries/core/assets/bundle/_utils.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
def relative_or_name(path: Path, prefix: Path) -> Path:
    """Return `path` relative to `prefix`, or just the file name if unrelated.

    Examples:
        >>> relative_or_name(Path("/tmp/cherries/data/out.txt"), Path("/tmp/cherries"))
        PosixPath('data/out.txt')
        >>> relative_or_name(Path("/var/tmp/out.txt"), Path("/tmp/cherries"))
        PosixPath('out.txt')
    """
    try:
        return path.relative_to(prefix)
    except ValueError:
        return Path(path.name)