labapi 1.0.3__py3-none-any.whl

labapi/entry/__init__.py

@@ -0,0 +1,28 @@
+"""LabArchives Entry Package.
+
+This package defines the core components for handling various types of entries
+within LabArchives pages, including base entry classes, specific entry types
+(text, widget, attachment), and collections of entries.
+"""
+
+from .attachment import Attachment
+from .collection import Entries
+from .comment import Comment
+from .entries.attachment import AttachmentEntry
+from .entries.base import Entry
+from .entries.text import HeaderEntry, PlainTextEntry, TextEntry
+from .entries.unknown import UnknownEntry
+from .entries.widget import WidgetEntry
+
+__all__ = [
+    "Attachment",
+    "AttachmentEntry",
+    "Comment",
+    "Entries",
+    "Entry",
+    "HeaderEntry",
+    "PlainTextEntry",
+    "TextEntry",
+    "UnknownEntry",
+    "WidgetEntry",
+]

labapi/entry/attachment.py

@@ -0,0 +1,191 @@
+"""Attachment data structure."""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+from collections.abc import Buffer
+from contextlib import ExitStack
+from mimetypes import guess_type
+from pathlib import Path
+from typing import IO, Any, BinaryIO, Protocol, cast
+
+# NOTE: from Pylance
+# Unfortunately PEP 688 does not allow us to distinguish read-only
+# from writable buffers. We use these aliases for readability for now.
+# Perhaps a future extension of the buffer protocol will allow us to
+# distinguish these cases in the type system.
+# Same as WriteableBuffer, but also includes read-only buffer types (like bytes).
+type ReadableBuffer = Buffer  # stable
+
+
+class NamedBinaryIO(Protocol):
+    """Binary file-like object with a ``name`` attribute."""
+
+    @property
+    def name(self) -> str:
+        """Return the local filename for this stream."""
+        ...
+
+    def read(self, size: int = -1, /) -> bytes:
+        """Read bytes from the stream."""
+        ...
+
+    def write(self, data: ReadableBuffer, /) -> int:
+        """Write bytes to the stream."""
+        ...
+
+    def seek(self, offset: int, whence: int = 0, /) -> int:
+        """Move the stream cursor."""
+        ...
+
+    def tell(self) -> int:
+        """Return the current stream cursor position."""
+        ...
+
+    def close(self) -> None:
+        """Close the stream."""
+        ...
+
+    def seekable(self) -> bool:
+        """Return whether the stream supports random access."""
+        ...
+
+
+class Attachment:
+    """Represents an attachment file with associated metadata.
+
+    This class wraps a file-like object (such as BytesIO or TemporaryFile) along
+    with metadata like MIME type, filename, and caption. It provides a convenient
+    interface for working with file attachments in LabArchives.
+
+    .. note::
+       Write operations to the backing buffer need explicit syncing with the server.
+    """
+
+    @staticmethod
+    def from_file(file: NamedBinaryIO) -> Attachment:
+        """Create an attachment by cloning a seekable file object.
+
+        The content of the provided file is copied into a temporary buffer,
+        making the Attachment independent of the original file's state.
+        The MIME type is automatically guessed from the local file name.
+        If the MIME type cannot be determined, it defaults to
+        "application/octet-stream".
+
+        :param file: The file object to create an attachment from. Must have a `name` attribute.
+        :returns: A new Attachment object wrapping a clone of the file.
+        """
+        if not file.seekable():
+            raise ValueError("Attachment.from_file requires a seekable file object")
+
+        remote_filename = Path(file.name).name
+        mime_type = guess_type(file.name)[0] or "application/octet-stream"
+        original_position = file.tell()
+
+        # Create a spooled temporary file as the new backing buffer.
+        # It stays in memory until it reaches 4MB, then rolls over to disk.
+        with ExitStack() as stack:
+            backing = cast(
+                BinaryIO,
+                stack.enter_context(
+                    tempfile.SpooledTemporaryFile(max_size=4 * 1024 * 1024, mode="w+b")
+                ),
+            )
+            try:
+                file.seek(0)
+                shutil.copyfileobj(file, backing)
+            finally:
+                file.seek(original_position)
+            backing.seek(0)
+            stack.pop_all()
+
+        return Attachment(
+            backing,
+            mime_type,
+            remote_filename,
+            caption=f"API-uploaded {mime_type} file.",
+        )
+
+    def __init__(
+        self,
+        backing: IO[bytes],
+        mime_type: str,
+        filename: str,
+        caption: str,
+    ):
+        """Initialize an attachment wrapper.
+
+        :param backing: The file-like object that contains the attachment data.
+                        Can be a BufferedRandom, BufferedReader, BytesIO, or TemporaryFile.
+        :param mime_type: The MIME type of the attachment (e.g., "image/png", "application/pdf").
+        :param filename: The filename of the attachment.
+        :param caption: A descriptive caption for the attachment.
+        """
+        self._backing = backing
+        if self._backing.seekable():
+            self._backing.seek(0)
+
+        self._mime_type = mime_type
+        self._filename = filename
+        self._caption = caption
+
+    def __getattr__(self, attr: str) -> Any:
+        """Delegate unknown attributes to the backing file object.
+
+        This allows the Attachment to behave like the underlying file object
+        for operations like read(), write(), etc.
+
+        :param attr: The attribute name to access on the backing object.
+        :returns: The attribute value from the backing object.
+        :raises AttributeError: If the attribute does not exist on the backing object.
+        """
+        return getattr(self._backing, attr)
+
+    def read(self, size: int = -1, /) -> bytes:
+        """Read bytes from the backing attachment stream."""
+        return self._backing.read(size)
+
+    def write(self, data: ReadableBuffer, /) -> int:
+        """Write bytes to the backing attachment stream."""
+        return self._backing.write(data)
+
+    def seek(self, offset: int, whence: int = 0, /) -> int:
+        """Move the backing stream cursor."""
+        return self._backing.seek(offset, whence)
+
+    def tell(self) -> int:
+        """Return the current backing stream cursor position."""
+        return self._backing.tell()
+
+    def close(self) -> None:
+        """Close the backing attachment stream."""
+        self._backing.close()
+
+    def seekable(self) -> bool:
+        """Return whether the backing stream supports random access."""
+        return self._backing.seekable()
+
+    @property
+    def filename(self) -> str:
+        """Return the attachment filename.
+
+        :returns: The filename.
+        """
+        return self._filename
+
+    @property
+    def mime_type(self) -> str:
+        """Return the attachment MIME type.
+
+        :returns: The MIME type (e.g., "image/png", "application/pdf").
+        """
+        return self._mime_type
+
+    @property
+    def caption(self) -> str:
+        """Return the attachment caption.
+
+        :returns: The caption text.
+        """
+        return self._caption

labapi/entry/collection.py

@@ -0,0 +1,209 @@
+"""Entries collection class."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from datetime import datetime
+from html import escape
+from io import BytesIO
+from json import dumps
+from typing import TYPE_CHECKING, Any, SupportsIndex, TypeVar, overload, override
+
+from labapi.util import extract_etree
+
+from .attachment import Attachment
+from .entries import AttachmentEntry, Entry, TextEntry
+
+E = TypeVar("E", bound="Entry[Any]")
+
+if TYPE_CHECKING:
+    from labapi.tree import NotebookPage
+    from labapi.user import User
+    from labapi.util import JsonData
+
+
+class Entries(Sequence["Entry[Any]"]):
+    """A collection of entries on a LabArchives page.
+
+    This class provides a sequence-like interface for managing entries within
+    a page, including a generic method for creating new entries by class.
+    """
+
+    def __init__(self, entries: Sequence[Entry[Any]], user: User, page: NotebookPage):
+        """Initialize an entries collection.
+
+        :param entries: A sequence of :class:`~labapi.entry.Entry` objects.
+        :param user: The authenticated user.
+        :param page: The page that this collection belongs to.
+        """
+        super().__init__()
+        self._user = user
+        self._page = page
+        self._entries: list[Entry[Any]] = list(entries)
+
+    @overload
+    def __getitem__(self, index: SupportsIndex) -> Entry[Any]:
+        pass
+
+    @overload
+    def __getitem__(self, index: str) -> Entry[Any]:
+        pass
+
+    @overload
+    def __getitem__(self, index: slice) -> Sequence[Entry[Any]]:
+        pass
+
+    @override
+    def __getitem__(
+        self, index: SupportsIndex | str | slice[Any, Any, Any]
+    ) -> Entry[Any] | Sequence[Entry[Any]]:
+        """Look up entries by index, slice, or entry identifier."""
+        if isinstance(index, str):
+            for entry in self._entries:
+                if entry.id == index:
+                    return entry
+            raise KeyError(f"Entry with id '{index}' not found")
+        return self._entries[index]
+
+    @override
+    def __iter__(self) -> Iterator[Entry[Any]]:
+        """Iterate over a snapshot of this page's entries."""
+        return iter(tuple(self._entries))
+
+    @override
+    def __reversed__(self) -> Iterator[Entry[Any]]:
+        """Iterate over a snapshot of this page's entries in reverse order."""
+        return reversed(tuple(self._entries))
+
+    @override
+    def __len__(self):
+        """Return the number of entries in this collection."""
+        return len(self._entries)
+
+    # TODO delete entries
+
+    def create_json_entry(
+        self,
+        data: JsonData,
+        *,
+        filename: str | None = None,
+        caption: str | None = None,
+    ) -> tuple[AttachmentEntry, TextEntry]:
+        """Create a JSON attachment plus a companion reference text entry.
+
+        This method uploads JSON data as an attachment file and creates a
+        companion text entry that references the attachment and displays
+        a formatted preview of the JSON data.
+
+        :param data: The JSON-serializable data to upload.
+        :param filename: Optional stable filename for the uploaded JSON attachment.
+        :param caption: Optional label/caption for the generated attachment and reference entry.
+        :returns: A tuple containing the attachment entry and the text entry.
+        """
+        # TODO treat this as one entry in the code
+
+        name = filename or f"uploaded_data_{datetime.now().timestamp():.0f}.json"
+        display_caption = caption or name
+        preview_json = escape(dumps(data, indent=4))
+
+        file_entry = self.create(
+            AttachmentEntry,
+            Attachment(
+                BytesIO(dumps(data).encode()),
+                "application/json",
+                name,
+                display_caption,
+            ),
+        )
+
+        text_entry = self.create(
+            TextEntry,
+            f"""
+<p>Reference Attachment: {escape(display_caption)}</p>
+<p>Entry ID: {escape(file_entry.id)}</p>
+<pre>
+{preview_json}
+</pre>
+""",
+        )
+        return file_entry, text_entry
+
+    @overload
+    def create(
+        self,
+        cls: type[AttachmentEntry],
+        data: Attachment,
+        *,
+        client_ip: str | None = None,
+    ) -> AttachmentEntry: ...
+
+    @overload
+    def create(self, cls: type[E], data: str, *, client_ip: str | None = None) -> E: ...
+
+    def create(
+        self, cls: type[E], data: str | Attachment, *, client_ip: str | None = None
+    ) -> E:
+        """Create a new entry on the page.
+
+        This method supports creating any entry type by passing the entry class directly,
+        similar to :meth:`~labapi.tree.mixins.AbstractTreeContainer.create`. The created
+        entry is automatically added to the collection.
+
+        :param cls: The entry class to create (e.g., :class:`~labapi.entry.entries.TextEntry`,
+                   :class:`~labapi.entry.entries.HeaderEntry`,
+                   :class:`~labapi.entry.entries.AttachmentEntry`).
+        :param data: The content of the entry. For text-based entries, this should be a string.
+                    For :class:`~labapi.entry.entries.AttachmentEntry`, this should be an
+                    :class:`~labapi.entry.Attachment` object.
+        :param client_ip: Optional end-user IP to pass through on attachment uploads.
+        :returns: The newly created entry object of the specified type.
+        :raises RuntimeError: If the API call to create the entry fails.
+        """
+        if issubclass(cls, AttachmentEntry):
+            if not isinstance(data, Attachment):
+                raise TypeError(
+                    f"{cls.__name__} requires Attachment data, got "
+                    f"{type(data).__name__}"
+                )
+
+            if data._backing.seekable():  # pyright: ignore[reportPrivateUsage]
+                data._backing.seek(0)  # pyright: ignore[reportPrivateUsage]
+
+            upload_kwargs = {
+                "filename": data.filename,
+                "caption": data.caption,
+                "nbid": self._page.root.id,
+                "pid": self._page.id,
+                "change_description": "File uploaded via API",
+            }
+
+            if client_ip is not None:
+                upload_kwargs["client_ip"] = client_ip
+
+            entry_tree = self._user.api_post(
+                "entries/add_attachment",
+                data._backing,  # pyright: ignore[reportPrivateUsage, reportArgumentType]
+                **upload_kwargs,
+            )
+
+            eid = extract_etree(entry_tree, {"entry": {"eid": str}})["eid"]
+            entry = cls(eid, data.caption, self._user)
+
+        else:
+            if not isinstance(data, str):
+                raise TypeError(
+                    f"{cls.__name__} requires str data, got {type(data).__name__}"
+                )
+            entry_tree = self._user.api_post(
+                "entries/add_entry",
+                {"entry_data": data},
+                part_type=cls._part_type,  # pyright: ignore[reportPrivateUsage]
+                pid=self._page.id,
+                nbid=self._page.root.id,
+            )
+
+            eid = extract_etree(entry_tree, {"entry": {"eid": str}})["eid"]
+            entry = cls(eid, data, self._user)
+
+        self._entries.append(entry)
+        return entry

labapi/entry/comment.py

@@ -0,0 +1,15 @@
+"""Comment Module.
+
+This module defines the :class:`~labapi.entry.comment.Comment` class,
+representing a comment associated with an entity (e.g., an entry) within LabArchives.
+"""
+
+from __future__ import annotations
+
+
+class Comment:
+    """Represents a comment associated with an entity in LabArchives.
+
+    Currently, this class is a placeholder and does not contain specific
+    attributes or methods for comment management.
+    """

labapi/entry/entries/__init__.py

@@ -0,0 +1,22 @@
+"""LabArchives Entry Types Package.
+
+This package defines various types of entries that can exist on a LabArchives page,
+including a base entry class and specific implementations for text, widget,
+and attachment entries.
+"""
+
+from .attachment import AttachmentEntry
+from .base import Entry
+from .text import HeaderEntry, PlainTextEntry, TextEntry
+from .unknown import UnknownEntry
+from .widget import WidgetEntry
+
+__all__ = [
+    "AttachmentEntry",
+    "Entry",
+    "HeaderEntry",
+    "PlainTextEntry",
+    "TextEntry",
+    "UnknownEntry",
+    "WidgetEntry",
+]

labapi/entry/entries/attachment.py

@@ -0,0 +1,148 @@
+"""Attachment Entry Module.
+
+This module defines the :class:`~labapi.entry.entries.attachment.AttachmentEntry` class,
+which represents an attachment entry within a LabArchives page.
+"""
+
+from __future__ import annotations
+
+from email.message import Message
+from io import BytesIO
+from tempfile import TemporaryFile
+from typing import IO, TYPE_CHECKING, override
+
+from labapi.entry.attachment import Attachment
+from labapi.exceptions import ApiError
+
+from .base import Entry
+
+if TYPE_CHECKING:
+    from labapi.user import User
+
+
+def _make_backing_io(use_tempfile: bool) -> IO[bytes]:
+    return TemporaryFile() if use_tempfile else BytesIO()
+
+
+class AttachmentEntry(Entry[Attachment], part_type="Attachment"):
+    """Represents an attachment entry on a LabArchives page.
+
+    This class handles the retrieval and updating of file attachments,
+    providing access to the attachment's content, filename, and caption.
+    """
+
+    def __init__(self, eid: str, caption: str, user: User):
+        """Initialize an attachment entry.
+
+        :param eid: The unique ID of the entry.
+        :param caption: The caption associated with the attachment.
+        :param user: The authenticated user.
+        """
+        super().__init__(eid, caption, user)
+        self._filedata: Attachment | None = None
+        self._filename: str | None = None
+        self._mime_type: str | None = None
+
+    def _ensure_attachment(self, use_tempfile: bool) -> None:
+        if self._filedata is None or self._filedata.closed:
+            output = _make_backing_io(use_tempfile)
+
+            with self._user.client.stream_api_get(
+                "entries/entry_attachment", uid=self._user.id, eid=self.id
+            ) as attachment_stream:
+                for chunk in attachment_stream:
+                    output.write(chunk)
+
+            headers = attachment_stream.headers
+
+            msg = Message()
+            msg["Content-Type"] = (
+                headers.get("Content-Type") or "application/octet-stream"
+            )
+            msg["Content-Disposition"] = headers.get("Content-Disposition")
+            filename = msg.get_filename()
+            mime_type = msg.get_content_type()
+
+            if filename is None:
+                raise ApiError("Could not determine filename from API response headers")
+
+            self._filedata = Attachment(output, mime_type, filename, self._data)
+
+    def get_attachment(self, use_tempfile: bool = False) -> Attachment:
+        """Return the attachment payload as an independent stream copy.
+
+        The attachment data is fetched from the LabArchives API and cached.
+        Subsequent calls will return the cached data.
+
+        :param use_tempfile: If True, the attachment data will be stored in a
+                             temporary file; otherwise, in an in-memory BytesIO object.
+                             Defaults to False.
+        :returns: An :class:`~labapi.entry.attachment.Attachment` object containing the file data and metadata.
+        """
+        self._ensure_attachment(use_tempfile)
+
+        assert self._filedata is not None
+        output = _make_backing_io(use_tempfile)
+
+        # Return an independent copy so each caller gets isolated read/seek/close state
+        # while still sharing a single downloaded backing attachment in the cache.
+        self._filedata.seek(0)
+        output.write(self._filedata.read())
+        output.seek(0)
+
+        return Attachment(
+            output,
+            self._filedata.mime_type,
+            self._filedata.filename,
+            self._filedata.caption,
+        )
+
+    @property
+    @override
+    def content(self) -> Attachment:
+        """Return the attachment content.
+
+        This property retrieves the attachment data, caching it for subsequent access.
+
+        :returns: The attachment object.
+        """
+        return self.get_attachment()
+
+    @content.setter
+    @override
+    def content(self, value: Attachment):
+        """Set the attachment content.
+
+        This operation updates the attachment in LabArchives via an API call
+        and invalidates any previously cached attachment data.
+
+        :param value: The new attachment object to upload.
+        """
+        # NOTE: this implicitly invalidates all previous Attachments
+        # NOTE: if every time content is called we give a new copy anyways that's fine
+        #       (see get_attachment())
+        if value._backing.seekable():  # pyright: ignore[reportPrivateUsage]
+            value._backing.seek(0)  # pyright: ignore[reportPrivateUsage]
+
+        self._user.api_post(
+            "entries/update_attachment",
+            value._backing,  # pyright: ignore[reportPrivateUsage, reportArgumentType]
+            filename=value.filename,
+            caption=value.caption,
+            eid=self.id,
+            change_description="File updated via API",
+        )
+
+        self._data = value.caption
+
+        if self._filedata:
+            self._filedata.close()
+        self._filedata = None
+
+    @property
+    def caption(self) -> str:
+        """Return the attachment caption.
+
+        :returns: The caption string.
+        """
+        return self._data