holder-python 0.2.5__py3-none-any.whl

holder/models/project.py

@@ -0,0 +1,207 @@
+"""Projects and their synchronous collection queries."""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field, fields
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, Literal, Self, cast
+
+from ..collections import Collection
+from ..generated.api.default import (
+    get_projects,
+    get_projects_project_id,
+    patch_projects_project_id,
+    post_projects,
+    post_projects_project_id_repair_hierarchy,
+)
+from ..generated.models import (
+    HierarchyRepairRequest,
+    ProjectCreateRequest,
+    ProjectCreateRequestPrivacyMode,
+    ProjectPrivacyMode,
+    ProjectSync,
+    ProjectUpdateRequest,
+)
+from ..generated.types import UNSET, Unset
+from .card import CardCollection
+from .tag import TagCollection
+
+if TYPE_CHECKING:
+    from ..client import Holder
+
+
+class ProjectCollection(Collection["Project"]):
+    def create(
+        self,
+        *,
+        name: str,
+        root_path: str | os.PathLike[str] | Unset = UNSET,
+        privacy_mode: Literal["encrypted_git", "plain"] | Unset = UNSET,
+    ) -> Project:
+        """Create a project using daemon defaults for omitted settings.
+
+        Listing filters do not supply creation values. Cached listings remain
+        unchanged until refreshed. The write is never retried; if the subsequent
+        fetch fails, the project may already exist.
+        """
+        if not isinstance(name, str):
+            raise TypeError("name must be a string")
+        if not isinstance(root_path, Unset):
+            root_path = os.fspath(root_path)
+            if not isinstance(root_path, str):
+                raise TypeError("root_path must be a string or a text path")
+        mode = (
+            UNSET
+            if isinstance(privacy_mode, Unset)
+            else ProjectCreateRequestPrivacyMode(privacy_mode)
+        )
+        data = self._holder._call(
+            post_projects,
+            body=ProjectCreateRequest(
+                name=name, root_path=root_path, privacy_mode=mode
+            ),
+            write=True,
+        )
+        return self.get(data.project_id)
+
+    def _clone(self, query: dict[str, Any]) -> Self:
+        return type(self)(self._holder, query)
+
+    def filter(
+        self,
+        *,
+        name: str | Unset = UNSET,
+        updated_after: int | Unset = UNSET,
+        updated_before: int | Unset = UNSET,
+    ) -> Self:
+        values = {
+            key: value
+            for key, value in {
+                "name": name,
+                "updated_after": updated_after,
+                "updated_before": updated_before,
+            }.items()
+            if not isinstance(value, Unset)
+        }
+        if "name" in values and not isinstance(name, str):
+            raise TypeError("name must be a string")
+        for key in ("updated_after", "updated_before"):
+            if key in values and (
+                not isinstance(values[key], int) or isinstance(values[key], bool)
+            ):
+                raise TypeError(f"{key} must be an integer")
+        return self._clone({**self._query, **values})
+
+    def _fetch_page(self) -> tuple[list[Project], int | None]:
+        offset = cast(int, self._next or 0)
+        data = self._holder._call(get_projects, limit=100, offset=offset, **self._query)
+        rows = [Project._from(self._holder, item) for item in data]
+        next_offset = offset + len(data) if len(data) == 100 else None
+        return rows, next_offset
+
+    def get(self, project_id: str) -> Project:
+        project = Project._from(
+            self._holder, self._holder._call(get_projects_project_id, project_id)
+        )
+        # get(id) is a direct scoped lookup, not evaluation of a filtered listing.
+        return project
+
+
+@dataclass(frozen=True)
+class RepairedCard:
+    """A hidden branch's top card and where repair moves it (None: top level)."""
+
+    card_id: str
+    parent_card_id: str | None
+
+
+@dataclass(frozen=True)
+class HierarchyRepair:
+    """Cards hidden under missing or trashed parents, and what repair does."""
+
+    applied: bool
+    moved: list[RepairedCard]
+    changed_card_count: int
+    cycle_card_ids: list[str]
+
+
+@dataclass(frozen=True, eq=False)
+class Project:
+    project_id: str
+    name: str
+    root_path: str
+    privacy_mode: ProjectPrivacyMode
+    created_at: int
+    updated_at: int
+    sync: ProjectSync
+    git_remote_url: str | None
+    git_provider: str | None
+    project_key_id: str | None
+    card_count: int | None
+    root_card_count: int | None
+    _holder: Holder = field(repr=False, compare=False)
+
+    @property
+    def id(self) -> str:
+        return self.project_id
+
+    @cached_property
+    def cards(self) -> CardCollection:
+        return CardCollection(self)
+
+    @cached_property
+    def tags(self) -> TagCollection:
+        return TagCollection(self)
+
+    @classmethod
+    def _from(cls, holder: Holder, data: Any) -> Self:
+        values: dict[str, Any] = {}
+        for f in fields(cls):
+            if f.name != "_holder":
+                value = getattr(data, f.name, None)
+                values[f.name] = None if isinstance(value, Unset) else value
+        return cls(**values, _holder=holder)
+
+    def refresh(self) -> Self:
+        fresh = self._holder.projects.get(self.id)
+        for f in fields(self):
+            if f.name != "_holder":
+                object.__setattr__(self, f.name, getattr(fresh, f.name))
+        return self
+
+    def update(self, *, name: str) -> Self:
+        """Rename this project and refresh its server metadata."""
+        if not isinstance(name, str):
+            raise TypeError("name must be a string")
+        self._holder._call(
+            patch_projects_project_id,
+            self.id,
+            body=ProjectUpdateRequest(updated_at=int(time.time()), name=name),
+            write=True,
+        )
+        return self.refresh()
+
+    def repair_hierarchy(self, *, apply: bool = False) -> HierarchyRepair:
+        """Find, and with apply=True fix, cards hidden under missing or trashed parents.
+
+        Each hidden branch moves to its nearest live ancestor (or the top level)
+        with its descendants, in one commit. Cards in parent cycles are only
+        reported. The daemon also repairs at startup, and every pull repairs
+        what it brings in. Cached listings need an explicit refresh.
+        """
+        if not isinstance(apply, bool):
+            raise TypeError("apply must be a bool")
+        data = self._holder._call(
+            post_projects_project_id_repair_hierarchy,
+            self.id,
+            body=HierarchyRepairRequest(apply=apply),
+            write=apply,
+        )
+        return HierarchyRepair(
+            applied=data.applied,
+            moved=[RepairedCard(m.card_id, m.parent_card_id) for m in data.moved],
+            changed_card_count=data.changed_card_count,
+            cycle_card_ids=list(data.cycle_card_ids),
+        )

holder/models/search.py

@@ -0,0 +1,66 @@
+"""Project-scoped card search results and lazy pagination."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, Self, cast
+
+from ..collections import Collection
+from ..generated.api.default import get_search_cards
+
+if TYPE_CHECKING:
+    from .card import Card
+    from .project import Project
+
+
+class CardSearchCollection(Collection["CardSearchResult"]):
+    """Lazy relevance-ordered results, with the usual all/refresh/index behavior."""
+
+    def __init__(self, project: Project, query: str) -> None:
+        self._project = project
+        super().__init__(project._holder, {"q": query})
+
+    def _clone(self, query: dict[str, Any]) -> Self:
+        return type(self)(self._project, query["q"])
+
+    def _fetch_page(self) -> tuple[list[CardSearchResult], int | None]:
+        offset = cast(int, self._next or 0)
+        data = self._holder._call(
+            get_search_cards,
+            project_id=self._project.id,
+            q=self._query["q"],
+            limit=100,
+            offset=offset,
+        )
+        rows = [CardSearchResult._from(self._project, item) for item in data]
+        return rows, offset + len(rows) if len(rows) == 100 else None
+
+
+@dataclass(frozen=True, eq=False)
+class CardSearchResult:
+    """Search metadata from one query, with lazy access to the current card."""
+
+    card_id: str
+    title: str
+    created_at: int
+    updated_at: int
+    snippet: str
+    rank: float
+    _project: Project = field(repr=False, compare=False)
+
+    @cached_property
+    def card(self) -> Card:
+        return self._project.cards.get(self.card_id)
+
+    @classmethod
+    def _from(cls, project: Project, data: Any) -> Self:
+        return cls(
+            card_id=data.card_id,
+            title=data.title,
+            created_at=data.created_at,
+            updated_at=data.updated_at,
+            snippet=data.snippet,
+            rank=data.rank,
+            _project=project,
+        )

holder/models/tag.py

@@ -0,0 +1,117 @@
+"""Project-scoped tags and their synchronous collections."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+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_tags,
+    get_cards_card_id,
+    get_projects_project_id_tags,
+    post_cards_card_id_tags,
+)
+from ..generated.models import CardTagMutationRequest
+
+if TYPE_CHECKING:
+    from .card import Card, CardCollection
+    from .project import Project
+
+
+class TagCollection(Collection["Tag"]):
+    """Lazy project tags, ordered by usage count and then name."""
+
+    def __init__(self, project: Project) -> None:
+        self._project = project
+        super().__init__(project._holder)
+
+    def _clone(self, query: dict[str, Any]) -> Self:
+        return type(self)(self._project)
+
+    def _fetch_page(self) -> tuple[list[Tag], None]:
+        data = self._holder._call(get_projects_project_id_tags, self._project.id)
+        return [Tag(row.tag, self._project, row.card_count) for row in data], None
+
+    def get(self, name: str) -> Tag:
+        """Fetch a tag by its normalized name, independently of cached results."""
+        if not isinstance(name, str):
+            raise TypeError("name must be a string")
+        for tag in self.all():
+            if tag.name == name:
+                return tag
+        raise NotFoundError(404, "not_found", "Tag not found in this collection")
+
+
+class CardTagCollection(TagCollection):
+    """Tags attached to one card; mutations use the daemon's editable tag line."""
+
+    def __init__(self, card: Card) -> None:
+        self._card = card
+        super().__init__(card._project)
+
+    def _clone(self, query: dict[str, Any]) -> Self:
+        return type(self)(self._card)
+
+    def _fetch_page(self) -> tuple[list[Tag], None]:
+        data = self._holder._call(get_cards_card_id, self._card.id)
+        if data.project_id != self._project.id:
+            raise NotFoundError(404, "not_found", "Card not found in this project")
+        # The generated client retains the daemon's tag array as an additional
+        # property because CardData does not yet declare it explicitly.
+        names = data.additional_properties.get("tags")
+        if not isinstance(names, list) or any(
+            not isinstance(name, str) or not name for name in names
+        ):
+            raise ProtocolError("Card response did not include valid tags")
+        return [Tag(name, self._project) for name in names], None
+
+    def add(self, name: str) -> Self:
+        """Add a tag and refresh the card. Validation and normalization are server-side."""
+        return self._mutate(post_cards_card_id_tags, name)
+
+    def remove(self, name: str) -> Self:
+        """Remove a trailing-line tag; body mentions remain until content is edited."""
+        return self._mutate(delete_cards_card_id_tags, name)
+
+    def _mutate(self, endpoint: Any, name: str) -> Self:
+        if not isinstance(name, str):
+            raise TypeError("name must be a string")
+        self._holder._call(
+            endpoint,
+            self._card.id,
+            body=CardTagMutationRequest(project_id=self._project.id, tag=name),
+            write=True,
+        )
+        # Invalidate even if the following read fails. The write is never retried.
+        self.refresh()
+        self._card.refresh()
+        return self
+
+
+@dataclass(frozen=True, eq=False)
+class Tag:
+    """A normalized project tag.
+
+    Project listings supply card_count; tags read from a card omit it until
+    refresh() fetches their project-wide count.
+    """
+
+    name: str
+    _project: Project = field(repr=False, compare=False)
+    card_count: int | None = None
+
+    @property
+    def project_id(self) -> str:
+        return self._project.id
+
+    @cached_property
+    def cards(self) -> CardCollection:
+        return self._project.cards.filter(tag=self.name)
+
+    def refresh(self) -> Self:
+        fresh = self._project.tags.get(self.name)
+        object.__setattr__(self, "card_count", fresh.card_count)
+        return self

holder_python-0.2.5.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: holder-python
+Version: 0.2.5
+Summary: Control your knowledge using Python
+Project-URL: Repository, https://github.com/HolderTeam/holder/tree/main/python/holder
+Project-URL: Issues, https://github.com/HolderTeam/holder/issues
+License-Expression: GPL-3.0-only
+Requires-Python: >=3.11
+Requires-Dist: attrs>=22.2
+Requires-Dist: httpx<0.29,>=0.23.1
+Requires-Dist: typing-extensions>=4.5
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: openapi-python-client==0.29.1; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: ruff==0.16.10; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Holder for Python
+
+Holder is an open-source, local-first knowledge app for organising your ideas
+and digital information as index cards and the connections between them.
+
+Use Python to read and update the projects and cards in your running Holder
+installation. Changes you make in a script appear in Holder too.
+
+## Get started
+
+1. You need the Holder application on your computer.
+Get it from https://www.holder.team/
+
+2. You need Python 3.11 or newer.
+If in doubt, get the latest version (i.e. 3.15) from:
+https://www.python.org/downloads/
+
+3. Install the Holder Python library with:
+
+```sh
+python3 -m pip install holder-python
+```
+
+Save this as `list_cards.py` and run it with `python3 list_cards.py`:
+
+```python
+from holder import Holder
+
+with Holder() as holder:
+    for project in holder.projects:
+        print(project.name)
+        for card in project.cards:
+            print("  ", card.title)
+```
+
+`Holder()` finds or starts your local Holder daemon using `holderctl`. The
+`with` block closes the Python connection when the script ends; it does not
+stop Holder.
+
+## Create and edit cards
+
+This example creates a project and two cards. Run it once: each run creates
+another project named `Research`.
+
+```python
+from holder import Holder
+
+with Holder() as holder:
+    project = holder.projects.create(name="Research")
+    card = project.cards.create(title="An idea", content="My notes")
+    child = card.children.create(title="Next step")
+    child.update(content="Try it out")
+    card.tags.add("research")
+```
+
+To work with an existing project, find it by name and get a card by its ID:
+
+```python
+from holder import Holder
+
+with Holder() as holder:
+    matches = holder.projects.filter(name="Research")
+    project = matches[0]
+    for card in project.cards:
+        print(card.id, card.title)
+
+    # Replace this with an ID printed above.
+    card = project.cards.get("card-id-here")
+    card.update(title="A better title")
+```
+
+The name filter matches part of a name. If there are no matches, `[0]` raises
+`IndexError`. Card content is available as `card.content`; use `card.update(...)`
+to save edits. Card attributes cannot be assigned directly.
+
+## Find cards
+
+Search within a project and inspect the matching text:
+
+```python
+from holder import Holder
+
+with Holder() as holder:
+    project = holder.projects.filter(name="Research")[0]
+    for result in project.cards.search("research notes"):
+        print(result.title, result.snippet)
+```
+
+You can also list cards with a tag using
+`project.cards.filter(tag="research")`, or list just top-level cards with
+`project.cards.roots()`.
+
+## More help
+
+- [More scripting tasks](https://github.com/HolderTeam/holder/blob/827907ae32927e7c80fb9fe077bd1dc513f61763/python/holder/docs/scripting.md): moves, Trash, tags, collection
+  refreshes, and connecting to a specific daemon.
+- [Low-level client](https://github.com/HolderTeam/holder/blob/827907ae32927e7c80fb9fe077bd1dc513f61763/python/holder/docs/low-level-client.md): direct access to HTTP endpoints.
+- [Development](https://github.com/HolderTeam/holder/blob/827907ae32927e7c80fb9fe077bd1dc513f61763/python/holder/docs/development.md): tests, builds, and generated code.
+- [Publishing](https://github.com/HolderTeam/holder/blob/827907ae32927e7c80fb9fe077bd1dc513f61763/python/holder/docs/publishing.md): PyPI setup and release steps.
+
+For offline analysis and bulk work without a running Holder installation, see
+[Holder Kit](https://github.com/HolderTeam/holder/tree/827907ae32927e7c80fb9fe077bd1dc513f61763/python/kit).