annals.tools#

The operations, as plain functions: JSON-able arguments in, JSON-able dicts out.

This module is the single source of truth for what a annals can do. The CLI (annals.__main__, via cw), the MCP server (py2mcp over string refs to these names) and the shipped skill all describe the same functions, so there is nothing to keep in parity. Nothing here prints or exits; the surfaces do that.

Functions

`configure`(*[, target, base_url])	Write the publisher config (where to publish, what link to print) and show it.
`group`(title, doc_ids, *[, target, base_url])	Make a group (one URL for a set of documents) from existing document ids.
`groups`(*[, target, base_url])	List groups, newest first.
`ls`([q, trash, limit, target, base_url])	List documents (newest first), optionally filtered by words or showing the bin.
`page_shell`(*[, api, base, title])	The page's html shell, for a host that serves the API under its own prefix.
`publish`(paths, *[, title, tags, group, ...])	Publish one document and print its link; several paths become several documents.
`restore`(doc_ids, *[, target])	Bring documents back from the recycle bin.
`serve`(*[, host, port, data_dir, base_path])	Serve the annals page and API (needs `pip install 'annals[server]'`).
`show`(doc_id, *[, target, base_url])	A document's metadata and link.
`trash`(doc_ids, *[, target])	Move documents to the recycle bin (restorable).

annals.tools.configure(*, target=None, base_url=None)[source]#

Write the publisher config (where to publish, what link to print) and show it.

Return type:: dict

Example

annals configure --target tw:/root/.local/share/annals --base-url https://apps.example.com/annals. With no arguments, shows the resolved settings without writing.

annals.tools.group(title, doc_ids, *, target=None, base_url=None)[source]#

Make a group (one URL for a set of documents) from existing document ids.

Return type:: dict

annals.tools.groups(*, target=None, base_url=None)[source]#

List groups, newest first.

Return type:: dict

annals.tools.ls(q='', *, trash=False, limit=50, target=None, base_url=None)[source]#

List documents (newest first), optionally filtered by words or showing the bin.

Return type:: dict

annals.tools.page_shell(*, api='/api/annals', base='/annals', title='annals')[source]#

The page’s html shell, for a host that serves the API under its own prefix.

An enlace app writes it once as its frontend: annals page-shell --api /api/annals --base /annals > frontend/index.html. The shell only names the two paths; the page’s code loads from the API, so it upgrades with the package.

Return type:: str

annals.tools.publish(paths, *, title=None, tags='', group=None, add_to=None, session=None, all_files=False, target=None, base_url=None)[source]#

Publish one document and print its link; several paths become several documents.

paths: files of any kind (markdown, html, images, video, audio, pdf, text), a directory (one document: an index.html or single page with its assets, else a gallery of everything in it), or - for stdin (markdown). tags is comma separated. group names a group to create from the published documents; the reply then carries group_url too. add_to appends them to an existing group instead (its id, as printed in a group link), so a second batch lands under the link the owner already has. session records who published (the source shown on the page). A directory skips hidden files and caches (.*, __pycache__, *.pyc) unless all_files.

Return type:: dict

annals.tools.restore(doc_ids, *, target=None)[source]#

Bring documents back from the recycle bin.

Return type:: dict

annals.tools.serve(*, host='127.0.0.1', port=8765, data_dir=None, base_path='/annals')[source]#

Serve the annals page and API (needs pip install 'annals[server]').

Auth comes from the environment: ANNALS_WHOAMI_URL + ANNALS_ALLOWED_USERS to sit behind an existing login, ANNALS_BASIC_USER + ANNALS_BASIC_PASSWORD for HTTP Basic, nothing for an open server on localhost.

Return type:: None

annals.tools.show(doc_id, *, target=None, base_url=None)[source]#

A document’s metadata and link.

Return type:: dict

annals.tools.trash(doc_ids, *, target=None)[source]#

Move documents to the recycle bin (restorable).

Return type:: dict