trove/trovedb/trove.py

from typing import Protocol, runtime_checkable, Optional, Dict, List, Self, NamedTuple, Iterable, TypedDict
from uuid import UUID
from pathlib import PurePosixPath


type ObjectId = int | str | UUID

class TroveError(Exception):
    """Base class for all Trove errors."""

class BadNoteType(TypeError):
    """Raised when an invalid note type is encountered."""

class TreeExists(RuntimeError):
    """Raised when a label already exists."""

class NoteNotFound(KeyError):
    """Raised when a note is not found."""

class OpenArguments(TypedDict):
    create: bool

@runtime_checkable
class Note(Protocol):
    """
    Protocol for a Note item.
    Represents access to an individual note's content and metadata.
    """
    @property
    def object_id(self) -> ObjectId:
        """The unique identifier for this note."""
        ...

    def get_raw_metadata(self, key: str) -> Optional[bytes]:
        """Retrieve metadata value for the given key."""
        ...

    def set_raw_metadata(self, key: str, value: bytes) -> None:
        """Set metadata value for the given key."""
        ...

@runtime_checkable
class Blob(Protocol):
    def read(self) -> bytes:
        """Read the raw content of the note."""
        ...

    def write(self, data: bytes) -> None:
        """Write new content to the note."""
        ...


class TreeEntry(NamedTuple):
    name: str
    object_id: ObjectId

@runtime_checkable
class Tree(Protocol):
    def link(self, name: str, note: Note):
        """Link name to a given note."""
        ...

    def unlink(self, name: str):
        """Remove name from the tree."""
        ...

    def mkdir(self, name: str) -> Self:
        """Create a new Tree with the given name."""
        ...

    def rmdir(self, name: str) -> None:
        """Remove a directory from the tree."""
        ...

    def child(self, name: str) -> Note:
        """Retrieve a child note by name."""
        ...

    def entries(self) -> Iterable[TreeEntry]:
        """Return all entries in the directory"""
        ...

    def list(self) -> dict[str, int]:
        """Return all entries as {name: object_id}."""
        ...

class BlobNote(Note, Blob):
    """Blob Note"""

class TreeNote(Note, Tree):
    """Tree Note"""


@runtime_checkable
class Trove(Protocol):
    """
    Protocol for the Trove database API.
    Provides high-level access to notes and trees.
    """

    def get_raw_note(self, note: ObjectId) -> Note:
        """Retrieve a note by a object id"""
        ...

    def create_blob(self, data: bytes | None = None) -> BlobNote:
        """Create a new blob node at the given path with content"""
        ...

    def get_root(self) -> TreeNote:
        """Get Tree Node at the given path"""
        ...