labapi 1.0.3__py3-none-any.whl

labapi/tree/notebook.py

@@ -0,0 +1,69 @@
+"""Notebook Module.
+
+This module defines the :class:`~labapi.tree.notebook.Notebook` class,
+representing a LabArchives notebook. It extends :class:`~labapi.tree.mixins.AbstractTreeContainer`
+to manage its hierarchical content (directories and pages) and provides
+notebook-specific functionalities.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, override
+
+from .mixins import AbstractTreeContainer, HasNameMixin
+
+if TYPE_CHECKING:
+    from labapi.user import User
+    from labapi.util import NotebookInit
+
+    from .collection import Notebooks
+
+
+class Notebook(AbstractTreeContainer):
+    """Represents a LabArchives notebook, acting as the root of a tree structure.
+
+    A notebook is a specialized :class:`~labapi.tree.mixins.AbstractTreeContainer`
+    that holds directories and pages. It provides methods to access notebook-specific
+    information and manage its contents.
+    """
+
+    def __init__(self, init: NotebookInit, user: User, notebooks: Notebooks):
+        """Initialize a notebook.
+
+        :param init: Initial data for the notebook.
+        :param user: The authenticated user.
+        :param notebooks: The collection of notebooks this notebook belongs to.
+        """
+        super().__init__("0", init.name, self, self, user)
+        self._id = init.id
+        self._is_default = init.is_default
+        self._notebooks = notebooks
+
+    @property
+    @override
+    def id(self) -> str:
+        """Return the notebook identifier.
+
+        :returns: The notebook's ID.
+        """
+        return self._id
+
+    @HasNameMixin.name.setter
+    def name(self, value: str):
+        """Set the notebook name.
+
+        This operation updates the notebook's name in LabArchives via an API call.
+
+        :param value: The new name for the notebook.
+        """
+        self.user.api_get("notebooks/modify_notebook_info", nbid=self.id, name=value)
+
+        self._name = value
+
+    @property
+    def is_default(self) -> bool:
+        """Return whether this notebook is the user's default notebook.
+
+        :returns: True if the notebook is the default, False otherwise.
+        """
+        return self._is_default

labapi/tree/page.py

@@ -0,0 +1,218 @@
+"""Notebook Page Module.
+
+This module defines the :class:`~labapi.tree.page.NotebookPage` class,
+representing a page within a LabArchives notebook. It extends
+:class:`~labapi.tree.mixins.AbstractTreeNode` and provides access to the
+entries contained within the page.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import TYPE_CHECKING, Any, Literal, Self, cast, override
+
+from labapi.entry import Attachment, Entries, Entry, UnknownEntry
+from labapi.util import ALL_PART_TYPES, InsertBehavior, extract_etree
+
+from .mixins import AbstractTreeContainer, AbstractTreeNode
+
+if TYPE_CHECKING:
+    from labapi.user import User
+
+
+class NotebookPage(AbstractTreeNode):
+    """Represents a single page within a LabArchives notebook.
+
+    A `NotebookPage` is a leaf node in the tree structure and contains
+    a collection of :class:`~labapi.entry.Entry` objects. It provides
+    functionalities to access and manage these entries.
+    """
+
+    def __init__(
+        self,
+        tree_id: str,
+        name: str,
+        root: AbstractTreeContainer,
+        parent: AbstractTreeContainer,
+        user: User,
+    ):
+        """Initialize a notebook page.
+
+        :param tree_id: The unique ID of the page.
+        :param name: The name of the page.
+        :param root: The root node of the tree (the Notebook).
+        :param parent: The parent node of this page (a Directory or Notebook).
+        :param user: The authenticated user.
+        """
+        super().__init__(tree_id, name, root, parent, user)
+        self._entries: Entries | None = None
+
+    @property
+    @override
+    def id(self) -> str:
+        """Return the page identifier.
+
+        :returns: The page's ID.
+        """
+        return super().id
+
+    @property
+    def entries(self) -> Entries:
+        """Return this page's entries, loading them on first access.
+
+        This property lazily loads the entries from the LabArchives API if they
+        have not been loaded yet.
+
+        .. note::
+           Slicing on the returned collection provides snapshots.
+           Iterators over the collection are also snapshots and are therefore
+           insulated from later collection mutations.
+
+        :returns: An :class:`~labapi.entry.Entries` object managing the page's entries.
+        """
+        if self._entries is None:
+            entries: list[Entry[Any]] = []
+
+            entries_tree = self._user.api_get(
+                "tree_tools/get_entries_for_page",
+                page_tree_id=self.id,
+                nbid=self.root.id,
+                entry_data=True,
+            )
+
+            for entry in entries_tree.iterfind(".//entry"):
+                entry_data = extract_etree(
+                    entry,
+                    {
+                        "eid": str,
+                        "part-type": str,
+                        "attach-file-name": str,
+                        "attach-content-type": str,
+                        "entry-data": str,
+                    },
+                )
+
+                part_type = entry_data["part-type"]
+
+                if part_type in ALL_PART_TYPES:
+                    if Entry.is_registered(part_type):
+                        # Cast extracted string values to ensure type checker knows they're not None
+                        entries.append(
+                            Entry.from_part_type(
+                                part_type,
+                                cast(str, entry_data["eid"]),
+                                cast(str, entry_data["entry-data"]),
+                                self._user,
+                            )
+                        )
+                    else:
+                        warnings.warn(
+                            f"Entry type '{part_type}' (ID: {entry_data['eid']}) is recognized but not "
+                            f"implemented in labapi. Wrapping as UnknownEntry.",
+                            UserWarning,
+                            stacklevel=2,
+                        )
+                        entries.append(
+                            UnknownEntry(
+                                cast(str, entry_data["eid"]),
+                                cast(str, entry_data["entry-data"]),
+                                self._user,
+                                part_type=part_type,
+                            )
+                        )
+                else:
+                    warnings.warn(
+                        f"Unknown entry type '{part_type}' (ID: {entry_data['eid']}) encountered. "
+                        f"Wrapping as UnknownEntry.",
+                        RuntimeWarning,
+                        stacklevel=2,
+                    )
+                    entries.append(
+                        UnknownEntry(
+                            cast(str, entry_data["eid"]),
+                            cast(str, entry_data["entry-data"]),
+                            self._user,
+                            part_type=part_type,
+                        )
+                    )
+
+            self._entries = Entries(entries, self._user, self)
+
+        return self._entries
+
+    @override
+    def copy_to(self, destination: AbstractTreeContainer) -> NotebookPage:
+        """Copy this page and its entries into ``destination``.
+
+        .. warning::
+           This method has known limitations:
+
+           - LabArchives may rename attachment files during copy operations
+           - Only certain entry types are fully supported (text, plain text, headers, attachments)
+           - Some entry types may fail to copy and will cause errors
+
+        :param destination: The target container to copy the page to.
+        :returns: A new instance of the copied page in the destination.
+
+        Copy behavior for attachments is explicit:
+
+        - attachment payloads are copied by reading and re-uploading the attachment content,
+        - attachment resources opened during copy are always released,
+        - any per-entry copy failure is reported via warning and that entry is skipped.
+
+        .. note::
+           This method is best-effort and may produce partial copies if one or more
+           entries fail while others succeed.
+
+        :raises RuntimeWarning: Emitted when an individual entry fails to copy.
+        """
+        new_page = destination.create(
+            NotebookPage, self.name, if_exists=InsertBehavior.Ignore
+        )
+
+        for entry in self.entries:
+            entry_content: Any | None = None
+            try:
+                entry_content = entry.content
+                # Re-upload behavior is intentional: copy_to creates a new entry on the
+                # destination page using the source entry's runtime class and content.
+                # For attachments, Entries.create uploads the payload and returns a
+                # distinct destination attachment entry; it does not mutate the source
+                # entry or preserve source attachment IDs.
+                assert entry_content is not None
+                new_page.entries.create(cast(Any, entry.__class__), entry_content)
+            except Exception as exc:
+                warnings.warn(
+                    f"Failed to copy entry {entry.id!r} ({entry.content_type!r}) from page "
+                    f"{self.id!r} to page {new_page.id!r}: {exc}. This entry was skipped.",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+            finally:
+                if isinstance(entry_content, Attachment):
+                    entry_content.close()
+
+        return new_page
+
+    @override
+    def is_dir(self) -> Literal[False]:
+        """Return ``False`` because pages are leaf nodes.
+
+        :returns: Always False.
+        """
+        return False
+
+    @override
+    def refresh(self) -> Self:
+        """Refresh this page by clearing its cached entries.
+
+        This method clears the internal entries cache, forcing the page
+        to re-fetch its entries from the LabArchives API on the next access.
+
+        .. note::
+           Currently only clears the entries cache. Future implementation should
+           properly invalidate all entry objects before clearing.
+        """
+        # TODO: Properly invalidate all entry objects before clearing
+        self._entries = None
+        return self

labapi/user.py

@@ -0,0 +1,146 @@
+"""LabArchives User Module.
+
+This module defines the :class:`~labapi.user.User` class, which represents an
+authenticated user session with the LabArchives API. It provides methods for
+interacting with the API on behalf of the user, managing notebooks, and
+accessing user-specific information.
+"""
+
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING, Any
+
+from labapi.tree.collection import Notebooks
+from labapi.util import extract_etree
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from labapi.util import NotebookInit
+
+    from .client import Client
+
+
+class User:
+    """Represents an authenticated LabArchives user session.
+
+    This class holds user-specific information such as the user ID and provides
+    an interface to interact with the LabArchives API, particularly for
+    accessing and managing notebooks and their contents.
+    """
+
+    def __init__(
+        self,
+        uid: str,
+        email: str,
+        notebooks: Sequence[NotebookInit],
+        client: Client,
+    ):
+        """Initialize a user session.
+
+        :param uid: The unique ID of the user.
+        :param email: The email address of the user.
+        :param notebooks: A sequence of :class:`~labapi.util.types.NotebookInit` objects
+                          representing the notebooks accessible to the user.
+        :param client: The :class:`~labapi.client.Client` instance used for API communication.
+        """
+        super().__init__()
+        self._id: str = uid
+        self._email: str = email
+        self._notebooks = Notebooks(notebooks, self)
+        self._client = client
+
+    @property
+    def id(self) -> str:
+        """The unique ID of the user.
+
+        :returns: The user's ID.
+        """
+        return self._id
+
+    @property
+    def email(self) -> str:
+        """The email address of the user.
+
+        :returns: The user's email.
+        """
+        return self._email
+
+    @property
+    def client(self) -> Client:
+        """The :class:`~labapi.client.Client` instance associated with this user session.
+
+        :returns: The client instance.
+        """
+        return self._client
+
+    def api_get(self, api_method_uri: str | Sequence[str], **kwargs: Any):
+        """Send a GET request on behalf of this user.
+
+        This method automatically appends the user's ID to the API call.
+
+        :param api_method_uri: The API method URI (e.g., "get_user_settings").
+                               Can be a string or a sequence of strings representing path segments.
+        :param kwargs: Additional query parameters to pass to the API method.
+        :returns: The response from the API, typically an
+                  ``lxml.etree.Element``.
+        :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 any other non-success response.
+
+        Invalid XML propagates ``lxml.etree.XMLSyntaxError``.
+        """
+        return self._client.api_get(api_method_uri, **kwargs, uid=self._id)
+
+    def api_post(
+        self,
+        api_method_uri: str | Sequence[str],
+        body: Mapping[str, str] | IO[bytes] | IO[str],
+        **kwargs: Any,
+    ):
+        """Send a POST request on behalf of this user.
+
+        This method automatically appends the user's ID to the API call.
+
+        :param api_method_uri: The API method URI (e.g., "create_entry").
+                               Can be a string or a sequence of strings representing path segments.
+        :param body: The request body, which can be a mapping of form data or a file-like object.
+        :param kwargs: Additional query parameters to pass to the API method.
+        :returns: The response from the API, typically an
+                  ``lxml.etree.Element``.
+        :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 any other non-success response.
+
+        Invalid XML propagates ``lxml.etree.XMLSyntaxError``.
+        """
+        return self._client.api_post(api_method_uri, body, **kwargs, uid=self._id)
+
+    def get_max_upload_size(self) -> int:
+        """Return the maximum upload size for this user in bytes.
+
+        The unit of the returned value is bytes.
+
+        :returns: The maximum upload size in bytes.
+        :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 any other non-success response.
+        :raises labapi.exceptions.ExtractionError: If the response does not
+                                                   include ``max-file-size``.
+
+        Invalid XML propagates ``lxml.etree.XMLSyntaxError``.
+        """
+        return extract_etree(
+            self.api_get("users/max_file_size"), {"max-file-size": int}
+        )["max-file-size"]
+
+    @property
+    def notebooks(self) -> Notebooks:
+        """Provides access to the user's notebooks.
+
+        :returns: A :class:`~labapi.tree.collection.Notebooks` object managing the user's notebooks.
+        """
+        return self._notebooks

labapi/util/__init__.py

@@ -0,0 +1,45 @@
+"""Utility Functions and Classes for LabArchives API Client.
+
+This package provides various utility functions and classes used throughout
+the LabArchives API client, including XML extraction, type conversions,
+indexing mechanisms, and data structures for notebook initialization.
+"""
+
+from .extract import extract_etree, to_bool
+from .path import NotebookPath
+from .types import (
+    IdIndex,
+    IdOrNameIndex,
+    Index,
+    InsertBehavior,
+    JsonData,
+    NameIndex,
+    NotebookInit,
+)
+
+#: All known LabArchives entry part types.
+ALL_PART_TYPES = (
+    "Attachment",
+    "plain text entry",
+    "heading",
+    "text entry",
+    "widget entry",
+    "sketch entry",
+    "reference entry",
+    "equation entry",
+    "assignment entry",
+)
+
+__all__ = [
+    "ALL_PART_TYPES",
+    "IdIndex",
+    "IdOrNameIndex",
+    "Index",
+    "InsertBehavior",
+    "JsonData",
+    "NameIndex",
+    "NotebookInit",
+    "NotebookPath",
+    "extract_etree",
+    "to_bool",
+]

labapi/util/browser.py

@@ -0,0 +1,125 @@
+"""Browser detection helpers for interactive authentication."""
+
+from __future__ import annotations
+
+import os
+import warnings
+from typing import Literal, TypeGuard
+
+_DETECTABLE_BROWSERS = ("chrome", "firefox", "edge")
+_CHOOSEABLE_BROWSERS = ("chrome", "firefox", "edge", "terminal")
+
+
+type _DetectableBrowser = Literal["chrome", "firefox", "edge"]
+type _ChoosableBrowser = Literal["chrome", "firefox", "edge", "terminal"]
+
+
+def _is_choosable(string: str) -> TypeGuard[_ChoosableBrowser]:
+    return string in _CHOOSEABLE_BROWSERS
+
+
+def _parse_detectable(string: str | None) -> _DetectableBrowser | Literal[False]:
+    if string is None:
+        return False
+
+    lowered = string.lower().strip()
+    for d in _DETECTABLE_BROWSERS:
+        if d in lowered:
+            return d
+    return False
+
+
+def _get_env_browser() -> _ChoosableBrowser | None:
+    # TODO put the load dotenv here
+    browser = os.getenv("LA_AUTH_BROWSER", "").strip().lower()
+
+    if browser == "":
+        return None
+    if _is_choosable(browser):
+        return browser
+
+    warnings.warn(
+        f"Unrecognized LA_AUTH_BROWSER value {browser!r}; "
+        "supported values are chrome, firefox, edge, or terminal. "
+        "Falling back to automatic browser detection.",
+        stacklevel=2,
+    )
+
+    return None
+
+
+def _find_chosen_browser(browser: _ChoosableBrowser | None) -> _ChoosableBrowser | None:
+    if browser == "terminal":
+        return browser
+    if browser is None:
+        return None
+
+    try:
+        import installed_browsers  # pyright: ignore[reportMissingImports, reportMissingTypeStubs]
+    except ImportError:
+        warnings.warn(
+            "Non-terminal browsers require the optional 'builtin-auth' "
+            "dependencies. Install them with: pip install 'labapi[builtin-auth]' "
+            "or set LA_AUTH_BROWSER=terminal for manual authentication.",
+            stacklevel=2,
+        )
+        return "terminal"
+
+    if installed_browsers.do_i_have_installed(browser):
+        return browser
+
+    warnings.warn(
+        f"Configured LA_AUTH_BROWSER value {browser!r} is not installed. "
+        "Falling back to automatic browser detection.",
+        stacklevel=2,
+    )
+    return None
+
+
+def _autodetect_browser() -> _DetectableBrowser | None:
+    try:
+        import installed_browsers  # pyright: ignore[reportMissingImports, reportMissingTypeStubs]
+    except ImportError:
+        warnings.warn(
+            "Automatic browser detection requires the optional 'builtin-auth' "
+            "dependencies. Install them with: pip install 'labapi[builtin-auth]' "
+            "or set LA_AUTH_BROWSER=terminal for manual authentication.",
+            stacklevel=2,
+        )
+        return None
+
+    try:
+        raw_default_browser = installed_browsers.what_is_the_default_browser()
+        default_browser = _parse_detectable(raw_default_browser)
+
+        if default_browser:
+            return default_browser
+
+        for browser in installed_browsers.browsers():
+            name = _parse_detectable(browser.get("name"))
+            if name:
+                return name
+
+        warnings.warn(
+            "Automatic browser detection failed: No compatible browser. Falling back to terminal/manual auth.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return None
+    except Exception as exc:
+        warnings.warn(
+            f"Automatic browser detection failed: {exc}. Falling back to terminal/manual auth.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+
+
+def detect_default_browser() -> _ChoosableBrowser:
+    """Resolve the preferred browser for the current auth attempt."""
+    env_browser = _get_env_browser()
+    chosen_browser = _find_chosen_browser(env_browser)
+
+    if chosen_browser is None:
+        return _autodetect_browser() or "terminal"
+
+    return chosen_browser