labapi 1.0.3__py3-none-any.whl

labapi/util/extract.py

@@ -0,0 +1,124 @@
+"""XML Extraction Utilities Module.
+
+This module provides utility functions for extracting data from `lxml.etree.Element`
+objects, including flattening dictionaries for easier processing, converting
+strings to booleans, and a general-purpose XML extraction function.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any
+
+from labapi.exceptions import ExtractionError
+
+if TYPE_CHECKING:
+    from lxml.etree import Element
+
+type EtreeExtractorDict = Mapping[str, "EtreeExtractorDict | Callable[[Any], Any]"]
+"""
+Type alias for a dictionary used to define the structure and extraction
+logic for `lxml.etree.Element` objects.
+
+It can be nested, where keys represent XML element tags and values are either
+another `EtreeExtractorDict` for nested structures or a `Callable` to process
+the text content of the element.
+"""
+
+
+def _flatten_dict(
+    val: EtreeExtractorDict, prefix: str = ""
+) -> dict[str, Callable[[Any], Any]]:
+    """Recursively flattens a nested dictionary of `EtreeExtractorDict` into a single-level dictionary.
+
+    The keys in the flattened dictionary represent the full path to the callable
+    extractor, separated by '/'.
+
+    :param val: The nested dictionary to flatten.
+    :param prefix: The current prefix for keys during recursion. Defaults to an empty string.
+    :returns: A flattened dictionary where keys are paths and values are callable extractors.
+    :raises ValueError: If an empty string is used as a key in the input dictionary.
+    """
+    items: dict[str, Callable[[Any], Any]] = {}
+
+    for _key, value in val.items():
+        if len(_key) == 0:
+            raise ValueError("Key cannot be empty string")
+
+        key = f"{prefix}/{_key}"
+
+        if callable(value):
+            items[key] = value
+        else:
+            items.update(_flatten_dict(value, key))
+
+    return items
+
+
+def to_bool(s: str) -> bool:
+    """Convert a string representation to a boolean value.
+
+    Recognizes "true" (case-insensitive) as True and "false" (case-insensitive) as False.
+
+    :param s: The string to convert.
+    :returns: The boolean representation of the string.
+    :raises ValueError: If the string cannot be converted to a boolean.
+    """
+    match s.lower():
+        case "true":
+            return True
+        case "false":
+            return False
+        case _:
+            raise ValueError(f"Cannot convert '{s}' to bool")
+
+
+def extract_etree(_etree: Element, schema: EtreeExtractorDict) -> dict[str, Any]:
+    """Extract data from an ``lxml.etree.Element`` using a format dictionary.
+
+    This function navigates the XML tree using paths defined in the `schema` dictionary
+    and applies callable extractors to the text content of the found elements.
+
+    :param _etree: The `lxml.etree.Element` from which to extract data.
+    :param schema: A dictionary defining the structure and extraction logic.
+                   Keys are XML element tags (or paths), and values are either
+                   nested `EtreeExtractorDict` or callable functions to process the text.
+    :returns: A dictionary containing the extracted and processed data.
+    :raises ExtractionError: If an element specified in the format is not found in the etree,
+                             or if a callable extractor fails to process a value.
+    """
+    flat = _flatten_dict(schema)
+
+    items: dict[str, Any] = {}
+    etree_path = _etree.getroottree().getpath(_etree)
+
+    for key, mapper in flat.items():
+        message_path = f"./{key}"
+        value = _etree.findtext(f"./{key}")
+
+        if (
+            value is None
+        ):  # XXX should we collate errors and return at end with the dict or?
+            raise ExtractionError(
+                f"Could not find value for './{key}' while parsing element at {etree_path}"
+            )
+
+        leaf = key.split("/")[-1]
+
+        if leaf in items:
+            warnings.warn(
+                f"Duplicate extractor leaf '{leaf}' encountered at './{key}'; "
+                "overwriting previous value",
+                stacklevel=2,
+            )
+
+        try:
+            items[leaf] = mapper(value)
+        except ValueError as err:
+            raise ExtractionError(
+                f"Could not map value {value!r} with {mapper.__name__} for "
+                f"{message_path!r} while parsing element at {etree_path}"
+            ) from err
+
+    return items

labapi/util/path.py

@@ -0,0 +1,367 @@
+"""Path utilities for navigating and creating LabArchives tree nodes."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from typing import TYPE_CHECKING, overload, override
+
+from labapi.exceptions import PathError
+
+if TYPE_CHECKING:
+    from labapi.tree.mixins import AbstractBaseTreeNode
+
+
+class NotebookPath(Sequence[str]):
+    """A structured path referencing a location in the notebook tree.
+
+    Behaves like a sequence of path segments (strings) and supports Unix-style
+    path semantics including absolute/relative paths and ``..`` parent navigation.
+
+    Paths can be constructed from a tree node, another ``NotebookPath``, or raw
+    slash-separated strings. Segments are normalised on construction: empty
+    segments and ``.`` are discarded, and ``..`` collapses the preceding segment
+    (or is kept literally when at the root of a relative path).
+
+    Examples::
+
+        # From a tree node (always absolute)
+        path = NotebookPath(folder)             # e.g. /Experiments/2024
+
+        # From a string
+        path = NotebookPath("/Experiments/2024")  # absolute
+        path = NotebookPath("2024/Results")        # relative
+
+        # Combine with /
+        path = NotebookPath(notebook) / "Experiments" / "2024"
+    """
+
+    def __init__(
+        self,
+        part: NotebookPath | AbstractBaseTreeNode | str,
+        *parts: str,
+        parent: NotebookPath | AbstractBaseTreeNode | None = None,
+    ):
+        """Construct a ``NotebookPath``.
+
+        The first argument ``part`` sets the base of the path; any additional
+        positional ``parts`` are appended as extra segments.
+
+        :param part: The base of the path. Pass a tree node to create an
+            absolute path rooted at that node's location, a ``NotebookPath``
+            to extend it, or a slash-separated string (absolute strings start
+            with ``/``; others are relative).
+        :param parts: Additional slash-separated path segments appended after
+            ``part``. Segments are split on ``/`` and normalised.
+        :param parent: An absolute path (or node) that anchors a relative
+            string path for later resolution. Must be absolute.
+        :raises PathError: If ``parent`` is not absolute.
+        """
+        if parent is not None:
+            self._parent = NotebookPath(parent)
+            if not self._parent.is_absolute():
+                raise PathError(
+                    "Parent path must be absolute",
+                    path=str(part),
+                    parent=str(self._parent),
+                )
+        else:
+            self._parent = None
+
+        if isinstance(part, NotebookPath):
+            self._parts: Sequence[str] = NotebookPath._combine(
+                part._parts, parts, part._absolute
+            )
+            self._absolute: bool = part._absolute
+            self._parent = part._parent
+        elif isinstance(part, str):
+            is_abs = NotebookPath._is_absolute_seq(part) and self._parent is None
+            self._parts: Sequence[str] = NotebookPath._combine((part,), parts, is_abs)
+            self._absolute = is_abs
+        else:
+            self._parts: Sequence[str] = NotebookPath._combine(
+                NotebookPath._of_node(part), parts, True
+            )
+            self._absolute = True
+
+    def __truediv__(self, other: str | NotebookPath) -> NotebookPath:
+        """Append a segment or another path using the ``/`` operator.
+
+        When ``other`` is a string it is appended as a new segment. When
+        ``other`` is a relative ``NotebookPath`` it is resolved against
+        ``self``; when it is absolute it is returned as-is.
+
+        :param other: A path segment string or another ``NotebookPath``.
+        :returns: A new ``NotebookPath`` with ``other`` appended or resolved.
+        """
+        if isinstance(other, str):
+            return NotebookPath(self, other)
+        return other.resolve(self)
+
+    def to_string(self) -> str:
+        """Return the path as a slash-separated string.
+
+        Absolute paths are prefixed with ``/``; relative paths are not.
+
+        :returns: The string representation of this path (e.g.
+            ``"/Experiments/2024"`` or ``"2024/Results"``).
+        """
+        if self._absolute:
+            return f"/{'/'.join(self._parts)}"
+
+        return "/".join(self._parts)
+
+    def is_absolute(self) -> bool:
+        """Return whether this path is absolute.
+
+        An absolute path is rooted at the notebook level and begins with
+        ``/`` in its string form.
+
+        :returns: ``True`` if the path is absolute, ``False`` if relative.
+        """
+        return self._absolute
+
+    def resolve(
+        self, parent: NotebookPath | None = None, recurse: bool = False
+    ) -> NotebookPath:
+        """Return an absolute version of this path.
+
+        If the path is already absolute it is returned unchanged. Otherwise
+        the path is resolved against ``parent`` (if given) or against the
+        ``parent`` anchor stored at construction time.
+
+        :param parent: An absolute path to resolve against. Ignored when the
+            path is already absolute or has a stored parent anchor.
+        :param recurse: If ``True``, ``parent`` itself is resolved before use.
+        :returns: A new absolute ``NotebookPath``.
+        :raises PathError: If the path is relative and no parent is available
+            to resolve against.
+        """
+        if self.is_absolute():
+            return self
+        if self._parent is None:
+            if parent is not None:
+                return NotebookPath(
+                    parent.resolve() if recurse else parent, *self._parts
+                )
+
+            raise PathError(
+                "Cannot resolve relative path without an absolute parent",
+                path=str(self),
+            )
+
+        return NotebookPath(self._parent, *self._parts)
+
+    def startswith(self, other: NotebookPath) -> bool:
+        """Return whether this path starts with another path's segments.
+
+        Compares raw segments without resolving either path.
+
+        :param other: The prefix path to test against.
+        :returns: ``True`` if the leading segments of this path equal all
+            segments of ``other``.
+        """
+        if len(self) < len(other):
+            return False
+        return self[: len(other)] == other[: len(other)]
+
+    def is_relative_to(self, other: NotebookPath | AbstractBaseTreeNode) -> bool:
+        """Return whether this path is located inside ``other``.
+
+        Unanchored relative paths are considered to be relative to any
+        absolute path.
+
+        :param other: The candidate ancestor path or tree node.
+        :returns: ``True`` if this path is equal to or below ``other``.
+        """
+        if not isinstance(other, NotebookPath):
+            other = NotebookPath(other)
+
+        if not other._absolute and other._parent is None:
+            if not self._absolute and self._parent is None:
+                return self.startswith(other)
+            return False
+
+        if not self._absolute and self._parent is None:
+            return True
+
+        return self.resolve().startswith(other.resolve())
+
+    def relative_to(self, other: NotebookPath | AbstractBaseTreeNode) -> NotebookPath:
+        """Return this path made relative to ``other``.
+
+        The result is a new relative ``NotebookPath`` whose ``parent`` anchor
+        is set to the resolved form of ``other``, so it can be resolved back
+        to an absolute path later.
+
+        :param other: The ancestor path or tree node to relativise against.
+        :returns: A relative ``NotebookPath`` from ``other`` to this path.
+        :raises PathError: If this path is not located inside ``other``.
+        """
+        if not isinstance(other, NotebookPath):
+            other = NotebookPath(other)
+
+        if not self.is_relative_to(other):
+            raise PathError(
+                f'Cannot compute relative path: "{self}" is outside of "{other}"',
+                path=str(self),
+                parent=str(other),
+            )
+
+        if not other._absolute and other._parent is None:
+            return NotebookPath(*self[len(other) :])
+
+        p_origin = other.resolve()
+        p_endpoint = self.resolve(other)
+
+        remaining = list(p_endpoint[len(p_origin) :])
+        return (
+            NotebookPath(*remaining, parent=p_origin)
+            if remaining
+            else NotebookPath("", parent=p_origin)
+        )
+
+    @property
+    def name(self) -> str:
+        """The final segment of the path.
+
+        Equivalent to the node's display name when the path was built from a
+        tree node. Returns ``"."`` for an empty path.
+
+        :returns: The last path segment, or ``"."`` if the path is empty.
+        """
+        if len(self._parts):
+            return self._parts[-1]
+        return "."
+
+    @property
+    def parts(self) -> Sequence[str]:
+        """All path segments except the last one.
+
+        Analogous to the parent directory in a file path.
+
+        :returns: A sequence of segment strings, empty if the path has only
+            one segment.
+        """
+        return self._parts[:-1]
+
+    @property
+    def parent(self) -> NotebookPath:
+        """The parent path (all segments except the last).
+
+        Resolves the path first, then appends ``..`` to obtain the parent.
+
+        :returns: An absolute ``NotebookPath`` pointing to the parent location.
+        """
+        return self.resolve() / ".."
+
+    @override
+    def __iter__(self) -> Iterator[str]:
+        """Iterate over the path segments in order."""
+        return iter(self._parts)
+
+    @override
+    def __len__(self) -> int:
+        """Return the number of segments in the path."""
+        return len(self._parts)
+
+    @overload
+    def __getitem__(self, idx: int) -> str: ...
+
+    @overload
+    def __getitem__(self, idx: slice) -> Sequence[str]: ...
+
+    @override
+    def __getitem__(self, idx: int | slice) -> str | Sequence[str]:
+        """Return the segment at ``idx``, or a sub-sequence for a slice."""
+        return self._parts[idx]
+
+    @override
+    def __hash__(self) -> int:
+        """Hash based on absoluteness, segments, and parent anchor."""
+        return hash((self._absolute, tuple(self._parts)))
+
+    @override
+    def __eq__(self, other: object) -> bool:
+        """Return ``True`` if ``other`` has the same path semantics.
+
+        Equality compares absoluteness, normalized segments, and any stored
+        parent anchor.
+        """
+        if self is other:
+            return True
+        if not isinstance(other, NotebookPath):
+            return False
+        return (
+            self._absolute == other._absolute
+            and self._parts == other._parts
+            and self._parent == other._parent
+        )
+
+    @override
+    def __repr__(self) -> str:
+        """Return a developer-readable representation, e.g. ``NotebookPath('/a/b')``."""
+        return f"{type(self).__name__}({self.to_string()!r})"
+
+    @override
+    def __str__(self) -> str:
+        """Return the slash-separated string form of the path."""
+        return self.to_string()
+
+    @staticmethod
+    def _is_absolute_seq(a: Sequence[str]) -> bool:
+        """Return ``True`` if the first element of ``a`` starts with ``/``."""
+        return len(a) > 0 and a[0].startswith("/")
+
+    @staticmethod
+    def _combine(a: Sequence[str], b: Sequence[str], from_root: bool) -> Sequence[str]:
+        """Merge two sequences of raw path segments into a normalised list.
+
+        Splits each element on ``/``, strips whitespace, drops empty segments
+        and ``.``, and resolves ``..`` (popping the previous segment, or
+        keeping ``..`` literally at the start of a relative path).
+
+        :param a: First sequence of raw segments (e.g. from an existing path).
+        :param b: Second sequence of raw segments to append.
+        :param from_root: Whether the combined path is rooted (absolute). When
+            ``True``, a leading ``..`` is silently dropped instead of kept.
+        :returns: A flat list of normalised, non-empty segment strings.
+        """
+        canonical: list[str] = []
+
+        # NOTE no support for escapes
+        for segment in [k.strip() for part in [*a, *b] for k in part.split("/")]:
+            match segment:
+                case "." | "":
+                    continue
+                case "..":
+                    if len(canonical) == 0:
+                        if not from_root:
+                            canonical.append("..")
+                    elif canonical[-1] == "..":
+                        canonical.append("..")
+                    else:
+                        canonical.pop()
+                case _:
+                    canonical.append(segment)
+        return canonical
+
+    @staticmethod
+    def _of_node(a: AbstractBaseTreeNode) -> Sequence[str]:
+        """Return the ordered list of ancestor names from the notebook root to ``a``.
+
+        Walks ``a.parent`` until the root is reached, building the segment list
+        from the bottom up.
+
+        :param a: The tree node to derive a path for.
+        :returns: A sequence of name strings representing the path from root to
+            ``a``, not including the root notebook itself.
+        """
+        stack: list[str] = []
+
+        curr = a
+
+        while curr is not curr.root:
+            stack.append(curr.name)
+            curr = curr.parent
+
+        return stack[::-1]

labapi/util/types.py

@@ -0,0 +1,76 @@
+"""Types Module.
+
+This module defines enumeration classes and data types used throughout
+the LabArchives API client.
+"""
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal
+
+
+class InsertBehavior(Enum):
+    """Enumeration of behaviors when inserting a node that already exists."""
+
+    Replace = 0
+    """Delete the existing node(s) and create a new one."""
+    Ignore = 1
+    """Just create a new node anyways."""
+    Retain = 2
+    """Keep the existing node and return it."""
+    Raise = 3
+    """Raise :class:`~labapi.exceptions.NodeExistsError` if the node already exists."""
+
+
+class Index(Enum):
+    """Represents the available indexing methods for accessing items in a collection."""
+
+    Id = "id"
+    """Index by the unique identifier of an item."""
+    Name = "name"
+    """Index by the human-readable name of an item."""
+
+
+type IdIndex = "slice[Literal[Index.Id], str, None]"
+"""
+Type alias for indexing by item ID.
+
+Example: ``Index.Id:"some_id"``
+"""
+type NameIndex = "slice[Literal[Index.Name], str, None]"
+"""
+Type alias for indexing by item name.
+
+Example: ``Index.Name:"some_name"``
+"""
+
+type IdOrNameIndex = str | IdIndex | NameIndex
+"""
+Type alias representing a flexible index that can be either an item's ID (string),
+or a slice using :attr:`Index.Id` or :attr:`Index.Name`.
+"""
+
+
+@dataclass
+class NotebookInit:
+    """Represents the initial data required to set up a LabArchives notebook object.
+
+    This dataclass holds essential information such as the notebook's ID, and name.
+    """
+
+    id: str
+    """The unique identifier of the notebook."""
+    name: str
+    """The name of the notebook."""
+    is_default: bool
+    """A value indicating if this notebook is the user's default."""
+
+
+type JsonData = (
+    Sequence["JsonData"] | Mapping[str, "JsonData"] | str | bool | int | float | None
+)
+"""
+A recursive type alias representing any data structure that can be
+serialized to or deserialized from JSON.
+"""