holder-python 0.2.5__tar.gz

holder_python-0.2.5/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/

holder_python-0.2.5/PKG-INFO

@@ -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).

holder_python-0.2.5/README.md

@@ -0,0 +1,102 @@
+# 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).

holder_python-0.2.5/docs/development.md

@@ -0,0 +1,62 @@
+# Developing Holder for Python
+
+Please refer to this package as Holder for Python or the Holder Python library,
+or just Holder when the Python context is clear. Its scope is Holder
+functionality using Python, independent of the current transport.
+
+## Set up a checkout
+
+Requires Python 3.11 or newer. From `python/holder/` in the Holder repository:
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest
+python scripts/generate.py --check
+python -m build
+```
+
+The current implementation uses the daemon's HTTP API. The generated client
+comes from [openapi-python-client](https://github.com/openapi-generators/openapi-python-client),
+which is a development dependency. Installed clients need only HTTPX, attrs,
+and typing-extensions. Entity and recovery policy belongs in the daemon or
+core, not in this library.
+
+## Layout and regeneration
+
+```text
+../../api/openapi.yaml  Owning HTTP contract for generation
+openapi/                 Generator config and contract/tool provenance
+src/holder/generated/    Generated transport, endpoint modules and models
+src/holder/events.py     Handwritten incremental asyncio change-feed transport
+scripts/generate.py      Regeneration and comparison against checked-in code
+tests/                   Mock HTTP transport and contract coverage checks
+```
+
+Do not hand-edit `src/holder/generated`. It is isolated so it can be replaced
+if a different implementation is needed. Handwritten transport and higher-level
+APIs live beside it; the incremental change-feed transport is in
+`src/holder/events.py`.
+
+Fix contract errors in the canonical [`api/openapi.yaml`](../../../api/openapi.yaml)
+and test them with the daemon before regenerating the client. The generator
+finds that contract from its own location, regardless of the caller's working
+directory.
+
+```sh
+# Regenerate from the owning contract.
+python scripts/generate.py
+
+# Compare the owning contract, provenance and generated output without changing files.
+python scripts/generate.py --check
+```
+
+The generator and Ruff versions are pinned in `pyproject.toml`. Generation runs
+in a temporary directory and fails on warnings before replacing the package.
+The provenance file records the contract's SHA-256 and tool versions. No schema
+transformations or custom templates are used. The config treats YAML download
+responses as plain text so their bodies are retained. CI checks the owning
+contract against the generated client, runs tests and builds on Python 3.11
+and 3.14. Installed packages contain the generated code and do not need the
+repository contract.

holder_python-0.2.5/docs/low-level-client.md

@@ -0,0 +1,35 @@
+# Low-level Holder client
+
+The regular `Holder` API covers common scripting tasks. For direct access to
+the daemon's HTTP endpoints, use `holder.generated`. Supply both the daemon URL
+and bearer token explicitly; this client does not discover local connection
+details or read credentials from your machine.
+
+```python
+import os
+
+from holder.generated import AuthenticatedClient
+from holder.generated.api.default import get_health
+from holder.generated.models import HealthResponse
+
+with AuthenticatedClient(
+    base_url="http://127.0.0.1:11499",
+    token=os.environ["HOLDER_TOKEN"],
+    raise_on_unexpected_status=True,
+) as client:
+    response = get_health.sync_detailed(client=client)
+    if isinstance(response.parsed, HealthResponse):
+        print(response.parsed.data.server_version)
+    else:
+        print(response.status_code, response.parsed)
+```
+
+`Client` supports public endpoints such as `get_ping`. Endpoint modules expose
+`sync`, `sync_detailed`, `asyncio` and `asyncio_detailed`; use `async with` for
+asynchronous clients. Detailed responses retain status, headers, raw bytes and
+the parsed response. Documented HTTP errors return an `ErrorResponse` when the
+contract specifies one; `raise_on_unexpected_status` applies to undocumented
+statuses. Transport errors propagate from HTTPX.
+
+This code is generated from the daemon's [OpenAPI contract](../../../api/openapi.yaml).
+For regeneration and contribution instructions, see [development](development.md).

holder_python-0.2.5/docs/publishing.md

@@ -0,0 +1,79 @@
+# Publishing Holder for Python
+
+The distribution is `holder-python`; users import `holder`. It is a pure Python
+package, so one `py3-none-any` wheel and one source archive cover all supported
+platforms. The version follows the repository's root `VERSION`.
+
+[`Release / Holder Python to PyPI`](../../../.github/workflows/release-holder-python-pypi.yml)
+builds both files, checks their metadata, installs each in a fresh virtual
+environment, and saves them as the `holder-python-distributions` artifact. A
+pull request or a manual run with `destination=none` only builds. Publishing
+uses Trusted Publishing. PyPI requires a manual run from the
+`holder-v<version>` tag with a matching `python/holder/pyproject.toml` version.
+The initial package-only `0.2.5` release also accepts
+`holder-python-v0.2.5-r2`; this tag does not start a Holder-wide release.
+
+## One-time setup for each package index
+
+PyPI and TestPyPI are separate services. Sign in to each one where you want to
+publish and configure a **GitHub Actions Trusted Publisher** for the project
+`holder-python`. If that project has not yet been created, use your account's
+**Publishing** page to add a *pending publisher*. If it already belongs to you,
+open the project's **Manage → Publishing** page and add a publisher there.
+Use these values on both sites:
+
+| Field | Value |
+| --- | --- |
+| PyPI project name (pending publisher only) | `holder-python` |
+| GitHub owner | `HolderTeam` |
+| GitHub repository | `holder` |
+| Workflow filename | `release-holder-python-pypi.yml` |
+| Environment name | `pypi` on PyPI; `testpypi` on TestPyPI |
+
+The repository's GitHub environments must have those exact names. If they use
+deployment branch or tag rules, allow `main`, `holder-v*`, and, for the
+backfill, `holder-python-v0.2.5-r2`; add required reviewers if desired. The Kit
+release workflow already uses these environment names, but **each PyPI project
+needs its own Trusted Publisher entry**. No PyPI API token or GitHub secret is
+needed. A pending publisher does not reserve the
+project name until the first successful upload.
+
+## TestPyPI previews
+
+TestPyPI already has `holder-python 0.2.5` from the original README. Uploaded
+files cannot be replaced, even after deleting the project. Keep that project
+and use a new preview number for each revised build:
+
+1. Merge the changes to `main`. In GitHub Actions, run **Release / Holder
+   Python to PyPI** on `main` with `destination=testpypi` and
+   `preview_number=1`. The build temporarily changes the package version to
+   `0.2.5.post1`; the committed `pyproject.toml` and root `VERSION` stay at
+   `0.2.5`.
+2. Wait for the TestPyPI upload and published-wheel install check to pass.
+   Review the `0.2.5.post1` page on TestPyPI.
+3. If the description needs another edit, merge that edit and repeat from
+   `main` with `preview_number=2`, then `3`, and so on. Each number creates
+   new wheel and source filenames. A preview number can only publish to
+   TestPyPI from `main`.
+
+## First `0.2.5` PyPI release
+
+After accepting a preview, create `holder-python-v0.2.5-r2` on its reviewed
+`main` commit. The original `holder-python-v0.2.5` tag points to the old README
+and must not be moved. Run **Release / Holder Python to PyPI** from the new tag
+with `destination=pypi` and `preview_number=0`. This publishes version `0.2.5`
+with the corrected README to real PyPI, which has not received that version.
+Confirm the project page and install it in a fresh environment with
+`python -m pip install holder-python==0.2.5`.
+
+## Later releases
+
+Update the unified version with `release/scripts/version.py <new-version>`, then
+publish `holder-python` from the matching `holder-v<version>` tag as part of
+the normal Holder release. The package-specific tag is accepted only for
+`0.2.5`.
+
+The workflow resolves README links to URLs at the build commit, so the project
+description links back to that exact source. A failed upload does not make an
+existing file replaceable: inspect the index before retrying, and choose a new
+preview number if its files were already published.

holder_python-0.2.5/docs/scripting.md

@@ -0,0 +1,139 @@
+# More Holder scripting tasks
+
+Start with the [README](../README.md) for installation and a first script.
+The examples below assume you have a `project` or `card` inside a
+`with Holder() as holder:` block.
+
+## Create projects with options
+
+```python
+from pathlib import Path
+
+project = holder.projects.create(
+    name="Research",
+    root_path=Path("/path/to/my/project"),
+    privacy_mode="encrypted_git",
+)
+```
+
+The daemon chooses IDs, timestamps and card placement. You can omit
+`root_path` and `privacy_mode`; the daemon then uses its defaults, including
+encrypted Git for privacy. You can also choose `privacy_mode="plain"`.
+Creation returns a fully loaded object. Filters on a collection do not supply
+values when you create an object through it; `card.children.create(...)` does
+supply the parent.
+
+## Work with tags
+
+Tags belong to a project. Add and remove them on a card, or list cards sharing
+a tag:
+
+```python
+card.tags.add("research")
+card.tags.remove("draft")
+tag = project.tags.get("research")
+for related_card in tag.cards:
+    print(related_card.title)
+```
+
+The daemon validates and normalizes tag names. `project.tags.get(name)` uses
+the normalized name. Removing a tag edits its trailing tag line; a mention in
+the body stays until you edit the content. Project tags include `card_count`
+and are ordered by descending count, then name.
+
+## Move, trash and restore cards
+
+Supply exactly one target when moving a card:
+
+```python
+card.move(parent=another_card)  # append as a child
+card.move(parent=None)          # append at the project's top level
+card.move(before=sibling)
+card.move(after=sibling)
+```
+
+Moving before or after another card adopts that card's parent. The daemon
+checks project and hierarchy rules.
+
+```python
+card.trash()                          # its live children move up a level
+card.trash(children="trash_subtree")  # its live descendants go to Trash too
+card.restore()                        # restore this card alone
+```
+
+When you restore a card, children that were moved up stay where they are.
+
+## Find and repair hidden cards
+
+Older clients, manual file removal, or sync can leave cards under a missing or
+trashed parent. Preview a repair before applying it:
+
+```python
+repair = project.repair_hierarchy()
+print(repair.moved)
+repair = project.repair_hierarchy(apply=True)
+```
+
+The daemon also repairs at startup and after every pull.
+
+## Search and filter
+
+```python
+for result in project.cards.search("research notes"):
+    print(result.title, result.snippet)
+    print(result.card.content)
+```
+
+Search results are ordered by relevance and loaded as you iterate. The
+`result.card` property fetches and caches the current card on first access;
+the snippet reflects the search result. Search collections support indexing,
+`.all()` and `.refresh()`. Search uses the daemon's full-text syntax and cannot
+be combined with tag or hierarchy filters, so search through `project.cards`.
+For listing, use `project.cards.filter(tag="research")`,
+`project.cards.roots()`, or `card.children`. Tag filters can be combined with
+hierarchy queries. Card listings exclude trashed cards and are always scoped
+to a project.
+
+Project filters are `name` (substring), `updated_after`, and `updated_before`.
+`get(id)` fetches an object directly. Collection indexes must be nonnegative.
+
+## Refresh data after changes
+
+Collections load as you iterate and cache results they have visited. To see
+changes made after a listing was loaded, call `.refresh()` on that collection:
+
+```python
+cards = project.cards
+for card in cards:
+    print(card.title)
+
+project.cards.create(title="Another idea")
+cards.refresh()
+for card in cards:
+    print(card.title)
+```
+
+`.all()` makes a fresh, independent query. Objects also have `.refresh()`.
+Card bodies load when you read `card.content`. Explicit `.update(...)` writes
+changes; card attributes cannot be assigned directly. Moves and tag changes
+refresh the affected card, but other previously loaded listings still need `.refresh()`.
+A move may also change nearby siblings' sort keys. Iteration observes live
+data rather than a frozen snapshot.
+
+## Connect to a specific daemon
+
+For a daemon you already know how to reach, supply both its URL and bearer
+token:
+
+```python
+import os
+
+from holder import Holder
+
+with Holder(url="http://127.0.0.1:11499", token=os.environ["HOLDER_TOKEN"]) as holder:
+    for project in holder.projects:
+        print(project.name)
+```
+
+Connection and API failures raise exceptions from `holder.exceptions`.
+For direct endpoint access, see the [low-level client](low-level-client.md).

holder_python-0.2.5/openapi/generator.yaml

@@ -0,0 +1,4 @@
+package_name_override: generated
+project_name_override: holder-python
+content_type_overrides:
+  application/yaml: text/plain

holder_python-0.2.5/openapi/provenance.json

@@ -0,0 +1,8 @@
+{
+  "source": "api/openapi.yaml",
+  "sha256": "aee5268031b6aaa4b7a3d7a43340af312a6e6f145c75c32575debe4b36de260b",
+  "generator": {
+    "openapi-python-client": "0.29.1",
+    "ruff": "0.16.10"
+  }
+}

holder_python-0.2.5/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "holder-python"
+version = "0.2.5"
+description = "Control your knowledge using Python"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "GPL-3.0-only"
+dependencies = ["httpx>=0.23.1,<0.29", "attrs>=22.2", "typing-extensions>=4.5"]
+
+[project.urls]
+Repository = "https://github.com/HolderTeam/holder/tree/main/python/holder"
+Issues = "https://github.com/HolderTeam/holder/issues"
+
+[project.optional-dependencies]
+dev = [
+    "openapi-python-client==0.29.1",
+    "ruff==0.16.10",
+    "pytest>=8,<10",
+    "build>=1.2,<2",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/holder"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"