Metadata-Version: 2.4
Name: cuj
Version: 0.3.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Office/Business :: News/Diary
Classifier: Topic :: Text Processing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
Summary: cuj, the plain-text PKM, from Python — your notes as data: tags, hierarchical categories, typed edges, todos with real due dates, imported Evernote and Obsidian included; queryable via cuj's Quarb surface
Keywords: pkm,notes,quarb,query,jot
Home-Page: https://cuj.net
Author: Bojan Đuričković
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://cuj.net/
Project-URL: Repository, https://gitlab.com/cujot/cuj-rs

# cuj · Python bindings

[cuj](https://cuj.net) — *n. Clever Use of Jots* — is a
plain-text PKM engine: one-line captures, inline
[Jot Syntax](https://jotsyntax.org) annotations (tags,
hierarchical categories, labeled references, todos with due
dates), a content-addressed fact store underneath, and
importers for Evernote (`.enex`) and Obsidian vaults. Your
notes stay plain text; the engine makes them answer questions.

This package binds cuj into Python. The first release exposes
the vault's query surface — the library twin of the `cuj q`
command, running [Quarb](https://quarb.org) over the vault
in-process:

```python
import cuj

# The open todo list, due dates as data.
cuj.q("//*<todo && open> | rec(::description, ::due)")
# [{'description': 'buy primus spares', 'due': None},
#  {'description': 'renew NZ transit visas',
#   'due': datetime.datetime(2026, 6, 15, ...)}, ...]

# Who cites note 3 - and who contradicts it.
cuj.q("/default/3<-cites::summary")
cuj.q("/default/3<-contradicts::summary")

# Notes sharing a tag with note 14 but not linked to it.
cuj.q("/default/14 . <-tagged->tagged"
      "[::::id != (1)::::id][!--*[::::id = (1)::::id]]::summary")
```

Node results return as cuj's own display strings
(`--default--12`, `///wiki/note.md`, `..tag`); value results as
typed Python values — `int`, `float`, tz-aware `datetime`,
`timedelta`, dicts for records, quantities as their written
face (`"204.808 kB"`).

Keyword arguments mirror the CLI's flags:

```python
cuj.q(expr,
      config="~/vaults/field/config.toml",  # else CUJ_CONFIG / ~/.cuj
      profile="all",                        # widen across profiles
      at="~8",                              # a historical state
      now="2026-07-31T12:00:00Z")           # pin now() - reproducible
```

Errors raise `ValueError` with cuj's or the engine's message.

The vault itself is made with the
[`cuj` CLI](https://crates.io/crates/cuj) (`cargo install cuj`)
— capture, import, label, promote; reading is the engine's job,
actions are the tool's. The data model and protocol are
documented from [cuj.net](https://cuj.net); the query language
in the [Quarb spec](https://quarb.org/spec/latest).

License: MIT OR Apache-2.0.

