labapi 1.0.3__py3-none-any.whl

labapi/entry/entries/base.py

@@ -0,0 +1,139 @@
+"""Base entry classes."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from inspect import isabstract
+from typing import TYPE_CHECKING, Any, TypeVar
+
+if TYPE_CHECKING:
+    from labapi.user import User
+
+
+T = TypeVar("T")
+
+_entries_registry: dict[str, type[Entry[Any]]] = {}
+
+
+class Entry[T](ABC):
+    """Abstract base class for all entry types on a LabArchives page.
+
+    This class provides a common interface for different entry types such as
+    text entries, headers, attachments, and widgets. It uses a generic type
+    parameter `T` to represent the content type of the entry.
+
+    LabArchives does not currently expose an API endpoint for deleting
+    individual entries, so this class intentionally does not provide a
+    ``delete()`` method.
+
+    :param T: The type of content stored in the entry (e.g., str for text, Attachment for files).
+    """
+
+    _part_type: str
+
+    @staticmethod
+    def is_registered(part_type: str) -> bool:
+        """Return whether an entry class is registered for ``part_type``.
+
+        :param part_type: The LabArchives part type identifier to check.
+        :returns: True if a class is registered for this part type, False otherwise.
+        """
+        return part_type in _entries_registry
+
+    @staticmethod
+    def class_of(part_type: str) -> type[Entry[Any]]:
+        """Return the registered entry class for ``part_type``.
+
+        :param part_type: The LabArchives part type identifier.
+        :returns: The :class:`Entry` subclass registered for this part type.
+        :raises KeyError: If no class is registered for the specified part type.
+        """
+        return _entries_registry[part_type]
+
+    @staticmethod
+    def from_part_type(part_type: str, eid: str, data: str, user: User) -> Entry[Any]:
+        """Create an entry instance for a LabArchives part type.
+
+        This method takes a part type string and returns the corresponding
+        entry class instance. The part type is normalized before matching.
+
+        :param part_type: The type of entry to create (e.g., "heading", "text entry",
+                         "plain text entry", "attachment", "widget entry").
+        :param eid: The unique ID of the entry.
+        :param data: The entry data. For text-based entries, this is the text content.
+                    For attachment entries, this is the caption.
+        :param user: The authenticated user associated with this entry.
+        :returns: An entry instance of the appropriate type.
+        :raises NotImplementedError: If the part type is not recognized or implemented.
+        """
+        try:
+            klass = _entries_registry[part_type]
+            return klass(eid, data, user)
+        except KeyError as err:
+            raise NotImplementedError(f"{part_type}") from err
+
+    # TODO perms
+    def __init__(
+        self,
+        eid: str,
+        data: str,
+        user: User,
+    ):
+        """Initialize an entry.
+
+        :param eid: The unique ID of the entry.
+        :param user: The authenticated user associated with this entry.
+        """
+        super().__init__()
+        self._id = eid
+        self._data = data
+        self._user = user
+
+    def __init_subclass__(cls, part_type: str = "", **kwargs: Any) -> None:
+        """Register concrete entry subclasses by their LabArchives part type."""
+        if not isabstract(cls) and part_type == "":
+            raise TypeError(f"{cls.__name__} must define a part_type")
+
+        cls._part_type = part_type
+
+        _entries_registry[part_type] = cls
+        super().__init_subclass__(**kwargs)
+
+    @property
+    def id(self):
+        """Return the unique identifier of the entry.
+
+        :returns: The entry's ID as a string.
+        """
+        return self._id
+
+    @property
+    def content_type(self) -> str:
+        """Return the LabArchives content type identifier for this entry.
+
+        :returns: A string representing the entry's type (e.g., "text entry", "Attachment").
+        """
+        return self._part_type
+
+    @property
+    @abstractmethod
+    def content(self) -> T:
+        """Return the entry content.
+
+        The specific type of the content depends on the entry type
+        (e.g., string for text entries, :class:`~labapi.entry.attachment.Attachment` for attachments).
+
+        :returns: The content of the entry.
+        """
+        raise NotImplementedError
+
+    @content.setter
+    @abstractmethod
+    def content(self, value: T) -> None:
+        """Set the entry content.
+
+        This operation typically updates the entry in LabArchives via an API call.
+
+        :param value: The new content for the entry.
+        """
+        raise NotImplementedError

labapi/entry/entries/text.py

@@ -0,0 +1,69 @@
+"""Text-based Entry Classes Module.
+
+This module defines various classes for text-based entries within LabArchives,
+including a base class for common text entry functionalities and specific
+implementations for plain text, rich text, and header entries.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, override
+
+from .base import Entry
+
+if TYPE_CHECKING:
+    from labapi.user import User
+
+
+class PlainTextEntry(Entry[str], part_type="plain text entry"):
+    """Represents a plain text entry on a LabArchives page.
+
+    This class is used for entries containing unformatted, raw text.
+    Additionally, it provides common functionalities for entries whose content is
+    represented as a string, including methods for getting and setting the content.
+    """
+
+    def __init__(self, eid: str, data: str, user: User):
+        """Initialize a plain-text entry.
+
+        :param eid: The unique ID of the entry.
+        :param data: The text content of the entry.
+        :param user: The authenticated user.
+        """
+        super().__init__(eid, data, user)
+
+    @property
+    @override
+    def content(self) -> str:
+        """Return the entry text.
+
+        :returns: The content of the entry as a string.
+        """
+        return self._data
+
+    @content.setter
+    @override
+    def content(self, value: str) -> None:
+        """Set the entry text.
+
+        This operation updates the entry's content in LabArchives via an API call.
+
+        :param value: The new text content for the entry.
+        """
+        self._user.api_post("entries/update_entry", {"entry_data": value}, eid=self.id)
+
+        self._data = value
+
+
+class TextEntry(PlainTextEntry, part_type="text entry"):
+    """Represents a rich text entry on a LabArchives page.
+
+    This class is used for entries containing formatted text, typically HTML.
+    """
+
+
+class HeaderEntry(PlainTextEntry, part_type="heading"):
+    """Represents a header entry on a LabArchives page.
+
+    This class is used for entries that function as headings or titles within a page.
+    """

labapi/entry/entries/unknown.py

@@ -0,0 +1,41 @@
+"""Unknown entry fallback type."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, override
+
+from .base import Entry
+
+if TYPE_CHECKING:
+    from labapi.user import User
+
+_UNKNOWN_ENTRY_REGISTRY_SENTINEL = "__labapi_internal_unknown_entry__"
+
+
+class UnknownEntry(Entry[str], part_type=_UNKNOWN_ENTRY_REGISTRY_SENTINEL):
+    """Fallback entry wrapper for unimplemented or unknown upstream part types."""
+
+    def __init__(self, eid: str, data: str, user: User, *, part_type: str):
+        """Initialize an unknown entry wrapper."""
+        super().__init__(eid, data, user)
+        self._source_part_type = part_type
+
+    @property
+    @override
+    def content_type(self) -> str:
+        """Return the original upstream part type."""
+        return self._source_part_type
+
+    @property
+    @override
+    def content(self) -> str:
+        """Return the raw entry payload."""
+        return self._data
+
+    @content.setter
+    @override
+    def content(self, value: str) -> None:
+        """Reject updates for unsupported entry types."""
+        raise NotImplementedError(
+            f"Cannot update unsupported entry type '{self._source_part_type}'"
+        )

labapi/entry/entries/widget.py

@@ -0,0 +1,29 @@
+"""Widget Entry Module.
+
+This module defines the :class:`~labapi.entry.entries.widget.WidgetEntry` class,
+which represents a widget entry within a LabArchives page.
+"""
+
+from __future__ import annotations
+
+from typing import override
+
+from .text import PlainTextEntry
+
+
+class WidgetEntry(PlainTextEntry, part_type="widget entry"):
+    """Represents a widget entry on a LabArchives page.
+
+    Widget entries typically embed interactive content or external applications.
+    At this time, LabArchives returns the value of the widget as a JSON string
+    and not the content making up the widget.
+    """
+
+    @PlainTextEntry.content.setter
+    @override
+    def content(self, value: str) -> None:
+        """Widget entries are read-only for the API.
+
+        :raises AttributeError: Always, as updating widget content is not supported.
+        """
+        raise AttributeError("Widget entries are read-only.")

labapi/exceptions.py

@@ -0,0 +1,80 @@
+"""Custom exception types raised by ``labapi``."""
+
+
+class LabArchivesError(Exception):
+    """Base for all ``labapi`` exceptions."""
+
+
+class AuthenticationError(LabArchivesError):
+    """Missing credentials or failed authentication flow.
+
+    ``error_code`` is set when the error originates from the LabArchives API
+    (e.g. 4506 invalid akid, 4514 bad login, 4520 bad signature, 4533 session
+    timeout).  It is ``None`` for locally-detected credential errors.
+    """
+
+    def __init__(self, message: str, error_code: int | None = None) -> None:
+        """Initialize an authentication error."""
+        super().__init__(message)
+        self.error_code = error_code
+
+
+class ApiError(LabArchivesError):
+    """LabArchives API returned an error or unexpected response.
+
+    ``error_code`` is the numeric code from the API ``<error-code>`` element,
+    or ``None`` if the error was detected before parsing the response body.
+    """
+
+    def __init__(self, message: str, error_code: int | None = None) -> None:
+        """Initialize an API error."""
+        super().__init__(message)
+        self.error_code = error_code
+
+
+class NodeExistsError(LabArchivesError):
+    """A tree node with the given name already exists (raised by InsertBehavior.Raise)."""
+
+
+class PathError(LabArchivesError):
+    """Path construction or resolution failed."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        path: str | None = None,
+        parent: str | None = None,
+    ) -> None:
+        """Initialize a path error with optional path context."""
+        super().__init__(message)
+        self.path = path
+        self.parent = parent
+
+
+class TraversalError(LabArchivesError):
+    """Tree traversal failed."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        path: str | None = None,
+        segment: str | None = None,
+        parent: str | None = None,
+        available_children: list[str] | None = None,
+    ) -> None:
+        """Initialize a traversal error with optional path context."""
+        super().__init__(message)
+        self.path = path
+        self.segment = segment
+        self.parent = parent
+        self.available_children = available_children
+
+
+class ExtractionError(LabArchivesError, ValueError):
+    """Structured parse/extraction failure while reading XML data."""
+
+
+class TreeChildParseError(ExtractionError):
+    """A tree child node could not be parsed from a tree-level response."""

labapi/py.typed

@@ -0,0 +1 @@
+

labapi/tree/__init__.py

@@ -0,0 +1,21 @@
+"""LabArchives Tree Structure Package.
+
+This package defines the hierarchical structure of LabArchives notebooks,
+including abstract base classes for tree nodes and containers, and concrete
+implementations for notebooks, directories, and pages.
+"""
+
+from .collection import Notebooks
+from .directory import NotebookDirectory
+from .mixins import AbstractTreeContainer, AbstractTreeNode
+from .notebook import Notebook
+from .page import NotebookPage
+
+__all__ = [
+    "AbstractTreeContainer",
+    "AbstractTreeNode",
+    "Notebook",
+    "NotebookDirectory",
+    "NotebookPage",
+    "Notebooks",
+]

labapi/tree/collection.py

@@ -0,0 +1,163 @@
+"""Notebook Collection Module.
+
+This module defines the :class:`~labapi.tree.collection.Notebooks` class,
+which acts as a collection manager for a user's LabArchives notebooks.
+It provides methods for accessing, iterating over, and creating notebooks.
+"""
+
+from __future__ import annotations
+
+from collections.abc import ItemsView, Iterator, KeysView, Mapping, Sequence, ValuesView
+from typing import TYPE_CHECKING, Literal, overload, override
+
+from labapi.exceptions import ApiError
+from labapi.util import IdOrNameIndex, Index, NotebookInit, extract_etree
+
+from .notebook import Notebook
+
+if TYPE_CHECKING:
+    from labapi.user import User
+
+
+class Notebooks(Mapping[IdOrNameIndex, Notebook | Sequence[Notebook]]):
+    """A collection of LabArchives notebooks accessible to a user.
+
+    This class provides dictionary-like access to notebooks by their ID or name,
+    and supports creating new notebooks. It manages a list of :class:`~labapi.tree.notebook.Notebook`
+    objects.
+    """
+
+    def __init__(self, notebooks: Sequence[NotebookInit], user: User):
+        """Initialize the notebook collection.
+
+        :param notebooks: A sequence of :class:`~labapi.util.types.NotebookInit` objects
+                          containing initial data for the notebooks.
+        :param user: The authenticated :class:`~labapi.user.User` associated with these notebooks.
+        """
+        super().__init__()
+        self._user = user
+        self._notebooks = [Notebook(n, user, self) for n in notebooks]
+        self._notebooks_by_id = {n.id: n for n in self._notebooks}
+
+    @overload
+    def __getitem__(self, key: str) -> Notebook: ...
+
+    @overload
+    def __getitem__(self, key: slice[Literal[Index.Id], str, None]) -> Notebook: ...
+
+    @overload
+    def __getitem__(
+        self, key: slice[Literal[Index.Name], str, None]
+    ) -> list[Notebook]: ...
+
+    @override
+    def __getitem__(self, key: IdOrNameIndex) -> Notebook | list[Notebook]:
+        """Look up notebooks by name or indexed selector.
+
+        - If `key` is a string, it attempts to find a single notebook with that name.
+        - If `key` is a slice with start of :attr:`~labapi.util.Index.Id`
+          (e.g., ``Index.Id:"some_id"``),
+          it returns the notebook with the matching ID.
+        - If `key` is a slice with start of :attr:`~labapi.util.Index.Name`
+          (e.g., ``Index.Name:"some_name"``),
+          it returns a list of all notebooks with the matching name (as names are not unique).
+
+        :param key: The index to use for accessing notebooks. Can be a string (for name lookup),
+                    or a slice with :attr:`~labapi.util.Index.Id` or
+                    :attr:`~labapi.util.Index.Name`.
+        :returns: A single :class:`~labapi.tree.notebook.Notebook` object or a list of them.
+        :raises KeyError: If a single notebook is requested by ID or unique name and not found.
+        """
+        match key:
+            case slice(start=Index.Id, stop=val):
+                return self._notebooks_by_id[val]
+            case slice(start=Index.Name, stop=val):
+                return [node for node in self._notebooks if node.name == val]
+            case str():
+                for node in self._notebooks:
+                    if node.name == key:
+                        return node
+                raise KeyError(f'Notebook with name "{key}" not found')
+            case _:
+                raise TypeError(
+                    "Invalid key type. Use `str`, `Index.Id:<id>`, or `Index.Name:<name>`."
+                )
+
+    @override
+    def __iter__(self) -> Iterator[str]:
+        """Iterate over notebook names in collection order."""
+        return iter([c.name for c in self._notebooks])
+
+    def __reversed__(self) -> Iterator[str]:
+        """Iterate over notebook names in reverse collection order."""
+        return reversed([c.name for c in self._notebooks])
+
+    @override
+    def __len__(self) -> int:
+        """Return the number of notebooks in this collection."""
+        return len(self._notebooks)
+
+    @override
+    def keys(self) -> KeysView[str]:
+        """Return a mapping-compatible view of notebook names.
+
+        :returns: A keys view of notebook names.
+        """
+        return KeysView({n.name: n for n in self._notebooks})
+
+    @override
+    def items(self) -> ItemsView[str, Notebook]:
+        """Return a mapping-compatible view of ``(name, notebook)`` pairs.
+
+        :returns: An items view of ``(name, notebook)`` pairs.
+        """
+        return ItemsView({n.name: n for n in self._notebooks})
+
+    @override
+    def values(self) -> ValuesView[Notebook]:
+        """Return a mapping-compatible view of notebook objects.
+
+        :returns: A values view of notebook objects.
+        """
+        return ValuesView({n.name: n for n in self._notebooks})
+
+    def all_keys(self) -> Sequence[str]:
+        """Return notebook names in collection order, preserving duplicates."""
+        return [n.name for n in self._notebooks]
+
+    def all_items(self) -> Sequence[tuple[str, Notebook]]:
+        """Return ``(name, notebook)`` pairs in collection order, preserving duplicates."""
+        return [(n.name, n) for n in self._notebooks]
+
+    def all_values(self) -> Sequence[Notebook]:
+        """Return notebook objects in collection order, preserving duplicates."""
+        return list(self._notebooks)
+
+    def create_notebook(self, name: str) -> Notebook:
+        """Create a new notebook in LabArchives.
+
+        :param name: The name of the new notebook.
+        :returns: The newly created :class:`~labapi.tree.notebook.Notebook` object.
+        :raises RuntimeError: If the underlying client session has been closed.
+        :raises AuthenticationError: If LabArchives rejects the request due to
+                                     invalid or expired credentials.
+        :raises ApiError: If LabArchives returns a non-success response, or if
+                          the API returns a notebook ID that already exists in
+                          the local collection.
+        """
+        nbid = extract_etree(
+            self._user.api_get(
+                "notebooks/create_notebook", name=name, initial_folders="Empty"
+            ),
+            {"nbid": str},
+        )["nbid"]
+
+        if nbid in self._notebooks_by_id:
+            raise ApiError(f"API returned an existing notebook ID: {nbid}")
+
+        new_notebook = Notebook(NotebookInit(nbid, name, False), self._user, self)
+
+        self._notebooks.append(new_notebook)
+        self._notebooks_by_id[nbid] = new_notebook
+
+        return new_notebook

labapi/tree/directory.py

@@ -0,0 +1,57 @@
+"""Notebook Directory Module.
+
+This module defines the :class:`~labapi.tree.directory.NotebookDirectory` class,
+representing a directory (folder) within a LabArchives notebook. It extends
+both :class:`~labapi.tree.mixins.AbstractTreeContainer` and
+:class:`~labapi.tree.mixins.AbstractTreeNode` to allow it to contain other
+nodes and be managed as a node itself.
+"""
+
+from __future__ import annotations
+
+from typing import override
+
+from labapi.util import InsertBehavior
+
+from .mixins import AbstractTreeContainer, AbstractTreeNode
+
+
+class NotebookDirectory(AbstractTreeContainer, AbstractTreeNode):
+    """Represents a directory (folder) within a LabArchives notebook.
+
+    A `NotebookDirectory` can contain other directories and pages, forming
+    a hierarchical structure. It inherits functionalities for both being a
+    container and being a movable/modifiable node within the tree.
+    """
+
+    @override
+    def copy_to(self, destination: AbstractTreeContainer) -> NotebookDirectory:
+        """Copy this directory and its contents into ``destination``.
+
+        This operation recursively copies all child directories and pages.
+
+        :param destination: The target container to copy the directory to.
+        :returns: A new instance of the copied directory in the destination.
+        """
+        if self.is_parent_of(destination) or self is destination:
+            raise ValueError(
+                "Cannot copy a directory into itself or one of its descendants"
+            )
+
+        new_dir = destination.create(
+            NotebookDirectory, self.name, if_exists=InsertBehavior.Ignore
+        )
+
+        for child in self.children:
+            child.copy_to(new_dir)
+
+        return new_dir
+
+    @property
+    @override
+    def id(self) -> str:
+        """Return the directory identifier.
+
+        :returns: The directory's ID.
+        """
+        return super().id