README

def flatten_dict(
    mapping: Mapping[str, Any], prefix: str = "", sep: str = "/"
) -> dict[str, Any]:
    """Flatten nested mappings into slash-delimited keys.

    Args:
        mapping: Mapping to flatten.
        prefix: Prefix already accumulated by a recursive call.
        sep: Separator inserted between nested key segments.

    Returns:
        A one-level dictionary whose keys preserve the nested path.

    Examples:
        >>> flatten_dict({"train": {"loss": 0.4}, "epoch": 3})
        {'train/loss': 0.4, 'epoch': 3}
    """
    result: dict[str, Any] = {}
    for key, value in mapping.items():
        key_flat: str = f"{prefix}{sep}{key}" if prefix else key
        if isinstance(value, Mapping):
            result.update(flatten_dict(value, key_flat, sep))
        else:
            result[key_flat] = value
    return result

def giturlparse(url: str) -> GitUrlParsed:
    """Parse a Git remote URL with the attributes Cherries needs.

    Examples:
        >>> info = giturlparse("https://github.com/liblaf/cherries.git")
        >>> (info.platform, info.owner, info.repo)
        ('github', 'liblaf', 'cherries')
    """
    info: GitUrlParsed = _giturlparse.parse(url)  # pyright: ignore[reportAssignmentType]
    return info

def pretty_yaml(data: dict[str, Any]) -> str:
    """Serialize `data` as YAML, converting path-like objects to strings."""
    return msgspec.yaml.encode(data, enc_hook=_enc_hook).decode()

def relative_or_absolute(path: Path, prefix: Path) -> Path:
    """Return `path` relative to `prefix`, or as an absolute path.

    Args:
        path: Path to display or serialize.
        prefix: Directory that should be stripped when `path` is inside it.

    Returns:
        `path.relative_to(prefix)` when possible; otherwise `path.resolve()`.

    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')
    """
    if path.is_relative_to(prefix):
        return path.relative_to(prefix)
    return path.resolve()

def relative_or_name(path: Path, prefix: Path) -> Path:
    """Return `path` relative to `prefix`, or just its file name.

    This keeps copied artifact names short even when a user logs a file outside
    the experiment working directory.

    Args:
        path: Path to display or copy.
        prefix: Directory that should be stripped when `path` is inside it.

    Returns:
        `path.relative_to(prefix)` when possible; otherwise `Path(path.name)`.

    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')
    """
    if path.is_relative_to(prefix):
        return path.relative_to(prefix)
    return Path(path.name)

def unflatten_dict(mapping: Mapping[str, Any], sep: str = "/") -> dict[str, Any]:
    """Expand slash-delimited keys into nested dictionaries.

    Args:
        mapping: Flat mapping to expand.
        sep: Separator used between nested key segments.

    Returns:
        A nested dictionary.

    Examples:
        >>> unflatten_dict({"train/loss": 0.4, "epoch": 3})
        {'train': {'loss': 0.4}, 'epoch': 3}
    """
    result: dict[str, Any] = {}
    _insert(result, [], mapping, sep=sep)
    return result