holder-python 0.2.5__py3-none-any.whl

holder/generated/models/trash_item.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, TypeVar, cast
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+from typing_extensions import Self
+
+from ..types import UNSET, Unset
+
+T = TypeVar("T", bound="TrashItem")
+
+
+@_attrs_define
+class TrashItem:
+    """
+    Attributes:
+        type_ (str):
+        card_id (None | str | Unset):
+        message_id (None | str | Unset):
+        thread_id (None | str | Unset):
+        project_id (str | Unset):
+        title (None | str | Unset):
+        role (None | str | Unset):
+        deleted_at (int | Unset):
+        created_at (int | Unset):
+        rel_path (None | str | Unset):
+    """
+
+    type_: str
+    card_id: None | str | Unset = UNSET
+    message_id: None | str | Unset = UNSET
+    thread_id: None | str | Unset = UNSET
+    project_id: str | Unset = UNSET
+    title: None | str | Unset = UNSET
+    role: None | str | Unset = UNSET
+    deleted_at: int | Unset = UNSET
+    created_at: int | Unset = UNSET
+    rel_path: None | str | Unset = UNSET
+    additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        type_ = self.type_
+
+        card_id: None | str | Unset
+        if isinstance(self.card_id, Unset):
+            card_id = UNSET
+        else:
+            card_id = self.card_id
+
+        message_id: None | str | Unset
+        if isinstance(self.message_id, Unset):
+            message_id = UNSET
+        else:
+            message_id = self.message_id
+
+        thread_id: None | str | Unset
+        if isinstance(self.thread_id, Unset):
+            thread_id = UNSET
+        else:
+            thread_id = self.thread_id
+
+        project_id = self.project_id
+
+        title: None | str | Unset
+        if isinstance(self.title, Unset):
+            title = UNSET
+        else:
+            title = self.title
+
+        role: None | str | Unset
+        if isinstance(self.role, Unset):
+            role = UNSET
+        else:
+            role = self.role
+
+        deleted_at = self.deleted_at
+
+        created_at = self.created_at
+
+        rel_path: None | str | Unset
+        if isinstance(self.rel_path, Unset):
+            rel_path = UNSET
+        else:
+            rel_path = self.rel_path
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(self.additional_properties)
+        field_dict.update(
+            {
+                "type": type_,
+            }
+        )
+        if card_id is not UNSET:
+            field_dict["card_id"] = card_id
+        if message_id is not UNSET:
+            field_dict["message_id"] = message_id
+        if thread_id is not UNSET:
+            field_dict["thread_id"] = thread_id
+        if project_id is not UNSET:
+            field_dict["project_id"] = project_id
+        if title is not UNSET:
+            field_dict["title"] = title
+        if role is not UNSET:
+            field_dict["role"] = role
+        if deleted_at is not UNSET:
+            field_dict["deleted_at"] = deleted_at
+        if created_at is not UNSET:
+            field_dict["created_at"] = created_at
+        if rel_path is not UNSET:
+            field_dict["rel_path"] = rel_path
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any]) -> Self:
+        d = dict(src_dict)
+        type_ = d.pop("type")
+
+        def _parse_card_id(data: object) -> None | str | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(None | str | Unset, data)
+
+        card_id = _parse_card_id(d.pop("card_id", UNSET))
+
+        def _parse_message_id(data: object) -> None | str | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(None | str | Unset, data)
+
+        message_id = _parse_message_id(d.pop("message_id", UNSET))
+
+        def _parse_thread_id(data: object) -> None | str | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(None | str | Unset, data)
+
+        thread_id = _parse_thread_id(d.pop("thread_id", UNSET))
+
+        project_id = d.pop("project_id", UNSET)
+
+        def _parse_title(data: object) -> None | str | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(None | str | Unset, data)
+
+        title = _parse_title(d.pop("title", UNSET))
+
+        def _parse_role(data: object) -> None | str | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(None | str | Unset, data)
+
+        role = _parse_role(d.pop("role", UNSET))
+
+        deleted_at = d.pop("deleted_at", UNSET)
+
+        created_at = d.pop("created_at", UNSET)
+
+        def _parse_rel_path(data: object) -> None | str | Unset:
+            if data is None:
+                return data
+            if isinstance(data, Unset):
+                return data
+            return cast(None | str | Unset, data)
+
+        rel_path = _parse_rel_path(d.pop("rel_path", UNSET))
+
+        trash_item = cls(
+            type_=type_,
+            card_id=card_id,
+            message_id=message_id,
+            thread_id=thread_id,
+            project_id=project_id,
+            title=title,
+            role=role,
+            deleted_at=deleted_at,
+            created_at=created_at,
+            rel_path=rel_path,
+        )
+
+        trash_item.additional_properties = d
+        return trash_item
+
+    @property
+    def additional_keys(self) -> list[str]:
+        return list(self.additional_properties.keys())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.additional_properties[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.additional_properties[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.additional_properties[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.additional_properties

holder/generated/models/trash_list_response.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+from typing_extensions import Self
+
+if TYPE_CHECKING:
+    from ..models.trash_item import TrashItem
+
+
+T = TypeVar("T", bound="TrashListResponse")
+
+
+@_attrs_define
+class TrashListResponse:
+    """
+    Attributes:
+        ok (bool):
+        data (list[TrashItem]):
+    """
+
+    ok: bool
+    data: list[TrashItem]
+    additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        ok = self.ok
+
+        data = []
+        for data_item_data in self.data:
+            data_item = data_item_data.to_dict()
+            data.append(data_item)
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(self.additional_properties)
+        field_dict.update(
+            {
+                "ok": ok,
+                "data": data,
+            }
+        )
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls, src_dict: Mapping[str, Any]) -> Self:
+        from ..models.trash_item import TrashItem
+
+        d = dict(src_dict)
+        ok = d.pop("ok")
+
+        data = []
+        _data = d.pop("data")
+        for data_item_data in _data:
+            data_item = TrashItem.from_dict(data_item_data)
+
+            data.append(data_item)
+
+        trash_list_response = cls(
+            ok=ok,
+            data=data,
+        )
+
+        trash_list_response.additional_properties = d
+        return trash_list_response
+
+    @property
+    def additional_keys(self) -> list[str]:
+        return list(self.additional_properties.keys())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.additional_properties[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.additional_properties[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.additional_properties[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.additional_properties

holder/generated/types.py

@@ -0,0 +1,54 @@
+"""Contains some shared types for properties"""
+
+from collections.abc import Mapping, MutableMapping
+from http import HTTPStatus
+from typing import IO, BinaryIO, Generic, Literal, TypeVar
+
+from attrs import define
+
+
+class Unset:
+    def __bool__(self) -> Literal[False]:
+        return False
+
+
+UNSET: Unset = Unset()
+
+# The types that `httpx.Client(files=)` can accept, copied from that library.
+FileContent = IO[bytes] | bytes | str
+FileTypes = (
+    # (filename, file (or bytes), content_type)
+    tuple[str | None, FileContent, str | None]
+    # (filename, file (or bytes), content_type, headers)
+    | tuple[str | None, FileContent, str | None, Mapping[str, str]]
+)
+RequestFiles = list[tuple[str, FileTypes]]
+
+
+@define
+class File:
+    """Contains information for file uploads"""
+
+    payload: BinaryIO
+    file_name: str | None = None
+    mime_type: str | None = None
+
+    def to_tuple(self) -> FileTypes:
+        """Return a tuple representation that httpx will accept for multipart/form-data"""
+        return self.file_name, self.payload, self.mime_type
+
+
+T = TypeVar("T")
+
+
+@define
+class Response(Generic[T]):
+    """A response from an endpoint"""
+
+    status_code: HTTPStatus
+    content: bytes
+    headers: MutableMapping[str, str]
+    parsed: T | None
+
+
+__all__ = ["UNSET", "File", "FileTypes", "RequestFiles", "Response", "Unset"]

holder/library.py

@@ -0,0 +1,15 @@
+"""Compatibility imports for the original synchronous library module."""
+
+from .client import Holder
+from .collections import Collection
+from .models.card import Card, CardCollection
+from .models.project import Project, ProjectCollection
+
+__all__ = [
+    "Card",
+    "CardCollection",
+    "Collection",
+    "Holder",
+    "Project",
+    "ProjectCollection",
+]

holder/models/__init__.py

@@ -0,0 +1,15 @@
+"""Project, card, tag and search result models for the Holder client."""
+
+from .card import Card
+from .project import HierarchyRepair, Project, RepairedCard
+from .search import CardSearchResult
+from .tag import Tag
+
+__all__ = [
+    "Card",
+    "CardSearchResult",
+    "HierarchyRepair",
+    "Project",
+    "RepairedCard",
+    "Tag",
+]

holder/models/card.py

@@ -0,0 +1,272 @@
+"""Cards and their project-scoped synchronous collection queries."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field, fields
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, Self
+
+from ..collections import Collection
+from ..exceptions import NotFoundError, ProtocolError
+from ..generated.api.default import (
+    delete_cards_card_id,
+    get_cards_card_id,
+    get_projects_project_id_cards,
+    patch_cards_card_id,
+    post_cards,
+    post_cards_card_id_move,
+    post_cards_card_id_restore,
+)
+from ..generated.models import (
+    CardCreateRequest,
+    CardMoveIntent,
+    CardMoveRequest,
+    CardUpdateRequest,
+    DeleteCardsCardIdChildren,
+)
+from ..generated.models.get_projects_project_id_cards_parent_type_0 import (
+    GetProjectsProjectIdCardsParentType0 as CardParent,
+)
+from ..generated.types import UNSET, Unset
+from .search import CardSearchCollection
+from .tag import CardTagCollection
+
+if TYPE_CHECKING:
+    from .project import Project
+
+
+class CardCollection(Collection["Card"]):
+    def __init__(self, project: Project, query: dict[str, Any] | None = None) -> None:
+        self._project = project
+        super().__init__(project._holder, query)
+
+    def create(self, *, title: str, content: str = "") -> Card:
+        """Create a root card, or a child when called on a children collection.
+
+        Tag filters do not add tags to the content. Cached listings remain
+        unchanged until refreshed. The write is never retried; if the subsequent
+        fetch fails, the card may already exist.
+        """
+        if not isinstance(title, str):
+            raise TypeError("title must be a string")
+        if not isinstance(content, str):
+            raise TypeError("content must be a string")
+        parent = self._query.get("parent", UNSET)
+        if parent == CardParent.ROOTS:
+            parent = UNSET
+        data = self._holder._call(
+            post_cards,
+            body=CardCreateRequest(
+                project_id=self._project.id,
+                title=title,
+                content=content,
+                parent_card_id=parent,
+            ),
+            write=True,
+        )
+        return self.get(data.card_id)
+
+    def _clone(self, query: dict[str, Any]) -> Self:
+        return type(self)(self._project, query)
+
+    def filter(self, *, tag: str) -> Self:
+        if not isinstance(tag, str) or not tag.strip():
+            raise ValueError("tag must be a nonempty string")
+        return self._clone({**self._query, "tag": tag})
+
+    def roots(self) -> Self:
+        return self._clone({**self._query, "parent": CardParent.ROOTS})
+
+    def search(self, query: str) -> CardSearchCollection:
+        """Search this project's cards using the daemon's full-text query syntax.
+
+        Tag and hierarchy filters cannot be combined with the search endpoint.
+        """
+        if not isinstance(query, str):
+            raise TypeError("query must be a string")
+        if not query.strip():
+            raise ValueError("query must be nonempty")
+        if self._query:
+            raise ValueError("Search does not support tag or hierarchy filters")
+        return CardSearchCollection(self._project, query)
+
+    def _fetch_page(self) -> tuple[list[Card], str | None]:
+        data = self._holder._call(
+            get_projects_project_id_cards,
+            self._project.id,
+            limit=200,
+            cursor=self._next or UNSET,
+            **self._query,
+        )
+        rows = [Card._from(self._project, item) for item in data.items]
+        if any(card.project_id != self._project.id for card in rows):
+            raise ProtocolError("Card listing returned an object from another project")
+        cursor = data.next_cursor
+        if cursor is not None and (
+            not isinstance(cursor, str)
+            or not cursor
+            or not rows
+            or cursor == self._next
+        ):
+            raise ProtocolError("Card pagination did not advance")
+        return rows, cursor
+
+    def get(self, card_id: str) -> Card:
+        data = self._holder._call(get_cards_card_id, card_id)
+        if data.project_id != self._project.id:
+            raise NotFoundError(404, "not_found", "Card not found in this project")
+        return Card._from(self._project, data)
+
+
+@dataclass(frozen=True, eq=False)
+class Card:
+    card_id: str
+    project_id: str
+    title: str
+    rel_path: str
+    sort_key: float
+    created_at: int
+    updated_at: int
+    parent_card_id: str | None
+    deleted_at: int | None
+    child_count: int | None
+    _project: Project = field(repr=False, compare=False)
+    _content: str | None = field(default=None, repr=False, compare=False)
+
+    @property
+    def id(self) -> str:
+        return self.card_id
+
+    @property
+    def content(self) -> str:
+        self._project._holder._active()
+        if self._content is None:
+            self.refresh()
+        if self._content is None:
+            raise ProtocolError("Card response did not include content")
+        return self._content
+
+    @cached_property
+    def children(self) -> CardCollection:
+        return CardCollection(self._project, {"parent": self.id})
+
+    @cached_property
+    def tags(self) -> CardTagCollection:
+        return CardTagCollection(self)
+
+    @classmethod
+    def _from(cls, project: Project, data: Any) -> Self:
+        values: dict[str, Any] = {
+            f.name: getattr(data, f.name, None)
+            for f in fields(cls)
+            if not f.name.startswith("_")
+        }
+        values = {k: None if isinstance(v, Unset) else v for k, v in values.items()}
+        # Collection pages carry content only when asked; an absent field means "not loaded".
+        content = getattr(data, "content", None)
+        if isinstance(content, Unset):
+            content = None
+        return cls(**values, _project=project, _content=content)
+
+    def refresh(self) -> Self:
+        fresh = self._project.cards.get(self.id)
+        for f in fields(self):
+            if f.name != "_project":
+                object.__setattr__(self, f.name, getattr(fresh, f.name))
+        if "tags" in self.__dict__:
+            self.tags.refresh()
+        return self
+
+    def update(
+        self, *, title: str | None | Unset = UNSET, content: str | Unset = UNSET
+    ) -> Self:
+        if isinstance(title, Unset) and isinstance(content, Unset):
+            raise TypeError("Supply title or content")
+        if not isinstance(title, (str, Unset)) and title is not None:
+            raise TypeError("title must be a string or None")
+        if not isinstance(content, (str, Unset)):
+            raise TypeError("content must be a string")
+        # Verify membership and obtain fresh content before any write.
+        current = self._project.cards.get(self.id)
+        if isinstance(content, Unset):
+            content = current.content
+        body = CardUpdateRequest(
+            updated_at=int(time.time()), title=title, content=content
+        )
+        self._project._holder._call(patch_cards_card_id, self.id, body=body, write=True)
+        return self.refresh()
+
+    def move(
+        self,
+        *,
+        parent: Card | None | Unset = UNSET,
+        before: Card | Unset = UNSET,
+        after: Card | Unset = UNSET,
+    ) -> Self:
+        """Move into a parent or immediately before/after a target card.
+
+        Supply exactly one Card, or parent=None to append the card to the
+        project's top level. Relative moves adopt the target's parent.
+        The daemon enforces project membership and prevents hierarchy cycles.
+        The moved card is refreshed; evaluated listings need explicit refresh.
+        Writes are never retried, even if the subsequent refresh fails.
+        """
+        supplied = [
+            (intent, target)
+            for intent, target in (
+                (CardMoveIntent.INTO, parent),
+                (CardMoveIntent.BEFORE, before),
+                (CardMoveIntent.AFTER, after),
+            )
+            if not isinstance(target, Unset)
+        ]
+        if len(supplied) != 1:
+            raise TypeError("Supply exactly one of parent, before or after")
+        intent, target = supplied[0]
+        if intent is CardMoveIntent.INTO and target is None:
+            # An explicit null parent is the project's top level.
+            body = CardMoveRequest(
+                project_id=self._project.id,
+                intent=CardMoveIntent.TO_END,
+                parent_card_id=None,
+            )
+        elif isinstance(target, Card):
+            body = CardMoveRequest(
+                project_id=self._project.id,
+                intent=intent,
+                target_card_id=target.id,
+            )
+        else:
+            raise TypeError("The move target must be a Card")
+        self._project._holder._call(
+            post_cards_card_id_move, self.id, body=body, write=True
+        )
+        return self.refresh()
+
+    def trash(self, *, children: str = "promote") -> None:
+        """Move this card to Trash.
+
+        With children="promote" (the default), its live children take its place
+        among its siblings, keeping their own descendants. With
+        children="trash_subtree", every live descendant goes to Trash with it.
+        A trashed card cannot be read again until restored, so this object is
+        not refreshed. The write is never retried.
+        """
+        try:
+            policy = DeleteCardsCardIdChildren(children)
+        except ValueError:
+            raise ValueError('children must be "promote" or "trash_subtree"') from None
+        self._project._holder._call(
+            delete_cards_card_id, self.id, children=policy, write=True
+        )
+
+    def restore(self) -> Self:
+        """Restore this card from Trash, and refresh it.
+
+        Restoring is single-card: it returns to its saved parent when that
+        parent is live, otherwise to its nearest live ancestor or the top level.
+        Children promoted when it was trashed stay where they are.
+        """
+        self._project._holder._call(post_cards_card_id_restore, self.id, write=True)
+        return self.refresh()