foamwiki

A Rust-backed, notebook-first Python library and thin CLI for Foam-style Markdown wikis (folders of notes connected by [[wikilinks]]).

The native core reads and parses notes in parallel, maintains the identity and resolution indexes, and stores the link graph. The Python layer preserves the convenient data-oriented API, PyYAML frontmatter values, templates, and filesystem mutation receipts.

Installation

The distribution is named foam-wiki; the Python package and command are both named foamwiki.

Install the stable release:

uv add foam-wiki
# or: python -m pip install foam-wiki

Until the first stable release, opt into the published prerelease:

uv add --prerelease allow foam-wiki
# or: python -m pip install --pre foam-wiki

Run the CLI without adding a project dependency:

uvx --from foam-wiki foamwiki --help

To install the current branch directly from Git:

foam-wiki @ git+https://github.com/nimashoghi/foampy.git

Git installations build the extension from source and require Rust 1.88 or newer. CI produces CPython stable-ABI wheels for manylinux2014 x86_64 and AArch64 (glibc-based Linux), macOS x86_64 and Apple silicon, and Windows x86_64. Each wheel supports Python 3.10 and newer.

Core API

import foamwiki

ws = foamwiki.load()                 # walk up to .foam/ ; parse + index once
note = ws["mean-flow"]             # lookup by shortest id or path
note.title, note.tags, note.outline
note.backlinks()                   # who links here

ws.resolve("flow-matching")        # -> the target Note (falsy Unresolved if broken)
hits = ws.search("TM-align")       # compact immutable Sequence[Hit]
hits[:20]                          # materialize only the rows being inspected
hits.materialize()                 # explicit eager Rows[Hit], when required
foamwiki.orphans(ws)                 # whole-graph census (free functions)
foamwiki.check(ws)                   # strict link diagnostics
foamwiki.rename(ws, note, "papers/meanflow.md")   # dry-run preview; pass dry_run=False to apply

Resolution validates #heading and #^block fragments. Ambiguous attachment suffixes return a falsy Unresolved(reason="ambiguous") rather than silently choosing one file. Percent-encode reserved characters in attachment paths, for example ![[fig%23draft%5D.png]] for fig#draft].png; diagnostic suggestions do this automatically.

Workspace-wide operations verify that the effective configuration, indexed file census, and every indexed note still match the loaded snapshot. Applied mutations also reject symlink-backed write sources, stage all output before changing the workspace, and roll back on write or reload failure. A dry run therefore remains safe to review even while another editor is active: replanning or applying it fails loudly instead of overwriting newer content.

Compact notebook output

Public records use compact, payload-free representations while keeping identifiers and paths intact. Potentially large text fields are bounded. Search hits center an 88-character excerpt on the match instead of dumping the complete source line and nested Note/Pos records:

<Hit alphafold-2/paper L272:550 '...colaboratory). TM-align v. 20190822 (https://zhanglab.dcmb.med.umich.edu/...'>

Rows, SearchResults, tag indexes, document outlines, and node child menus display at most 20 entries and report how many remain. Slice them to continue. Literal SearchResults also materialize public hit records only on access; call .materialize() for an eager Rows[Hit]. Automatic mutation diff previews are bounded; call ChangeSet.diff() for the complete diff. These limits affect display only: Hit.text and Match.line retain the exact source line (including indentation), while record fields, iteration, and .to_df() retain complete data. Passage remains intentionally unbounded because evaluating .body or .read() is an explicit request for content.

Template authoring

Markdown templates can declare foam_template.filepath and use Foam variables in both their content and destination. Preview first, then repeat the reviewed call with dry_run=False:

draft = foamwiki.create(
    ws,
    template="meeting-scratchpad",
    when="2026-07-15T14:30:00+01:00",
    dry_run=True,
)
draft.path, draft.frontmatter, draft.text

note = foamwiki.create(
    ws,
    template="meeting-scratchpad",
    when="2026-07-15T14:30:00+01:00",
    dry_run=False,
)

foamwiki.daily(ws, "2026-07-15", dry_run=True) uses daily-note.md and prefers its template filepath. Explicit destinations always override template metadata.

Structure-aware reading (for notebook agents)

Read a large markdown file without dumping it into context. foamwiki.read returns a priced, navigable map of the file's sections — orient cheaply, drill by stable numeric path, search to a section, then read only what you choose:

doc = foamwiki.read("design.md")     # (or note.doc for a vault note — no reparse)
doc                                # repr = a priced table-of-contents (~150 tok for a 40k-tok file)
doc["3.2"]                         # drill by numeric path (or doc["Method"] / doc[3]); prints a menu, never dumps
doc.search("KL")                   # term -> the sections that contain it (Rows[Match])
doc["3.2"].body                    # read just this section's prose (a priced Passage); .read() for the whole subtree
doc["3.2"].children                # tree nav as properties: .parent .children .siblings .next .prev

Every view quotes exact line counts + ~token estimates, so you budget before you spend. Works standalone on any .md file (no workspace needed).

See AGENTS.md for the design philosophy and the placement rule. pandas and networkx are optional extras used lazily by .to_df() and to_networkx(); request the all extra in the Git dependency when needed: foam-wiki[all] @ git+https://github.com/nimashoghi/foampy.git.

Development

uv sync
uv run pytest -q
uv run ruff check .
uv run basedpyright src scripts
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features

See PERFORMANCE.md for the real-workspace baseline and reproducible benchmark command. MIGRATION.md lists the intentional behavior and naming changes. RELEASING.md documents local and CI release validation.

MIT licensed.

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for nimashoghi from gravatar.com nimashoghi

Credits

Author: Nima Shoghi

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

all graph pandas

Tags

foam wikilink markdown knowledge-base notebook

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

foam_wiki-0.4.1.tar.gz (182.9 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

foam_wiki-0.4.1-cp310-abi3-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.10+Windows x86-64

foam_wiki-0.4.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.2 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

foam_wiki-0.4.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.1 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

foam_wiki-0.4.1-cp310-abi3-macosx_11_0_arm64.whl (1.0 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

foam_wiki-0.4.1-cp310-abi3-macosx_10_12_x86_64.whl (1.1 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file foam_wiki-0.4.1.tar.gz.

File metadata

  • Download URL: foam_wiki-0.4.1.tar.gz
  • Upload date:
  • Size: 182.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for foam_wiki-0.4.1.tar.gz
Algorithm Hash digest
SHA256 c294a775e5435980f8245b9ffb3b658cf0febfb4adcb82475c18fa3d3a71b4b6
MD5 4d5467e9a81661c30c386e45de01e7f8
BLAKE2b-256 43fd4e874dab3632c9445cf08ec3c62cfaf9e70cdd514574eb106250eec7ecfc

See more details on using hashes here.

Provenance

The following attestation bundles were made for foam_wiki-0.4.1.tar.gz:

Publisher: release.yml on nimashoghi/foampy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file foam_wiki-0.4.1-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: foam_wiki-0.4.1-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 1.1 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for foam_wiki-0.4.1-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 dca5cfa8609cdd1bb14d239c5e88327341cc44fb4fc1022f3e45fce5916988d4
MD5 64aeb67c565b01b34fc0a5f14d3b5ac3
BLAKE2b-256 13829aa9054d25cbc1b159196b558e348e9a6e436ed31098eae1f176dc9b7953

See more details on using hashes here.

Provenance

The following attestation bundles were made for foam_wiki-0.4.1-cp310-abi3-win_amd64.whl:

Publisher: release.yml on nimashoghi/foampy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file foam_wiki-0.4.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for foam_wiki-0.4.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 069f495f804b5ee4bb66640ca352408baae2ec2210fdc3cbad6d134326cf242f
MD5 b171684f22858db1b0747eaeca0a38c0
BLAKE2b-256 4706a37387ebb110b80bd916ca1f740a9e1461801e315fe5a5df2aabdb7d290d

See more details on using hashes here.

Provenance

The following attestation bundles were made for foam_wiki-0.4.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on nimashoghi/foampy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file foam_wiki-0.4.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for foam_wiki-0.4.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 cbc0b63409812c249f89603999667c59645e107915640332ad963efb271bef4f
MD5 80324094fa53cca25737212a7c0bb198
BLAKE2b-256 7d2dd4f25eb23baab3639c23190203ed8891db551389c6e650e839ebfba0c75f

See more details on using hashes here.

Provenance

The following attestation bundles were made for foam_wiki-0.4.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on nimashoghi/foampy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file foam_wiki-0.4.1-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for foam_wiki-0.4.1-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 74e83a99ec715cdbdff8c6f99a023ac4b312fc720dae3d11cf6a33af5aeca43a
MD5 e77d32b5f4163f053c42a3ee04e601c9
BLAKE2b-256 9ec09d71a86d1f7c231b2517155647f90389b57e25f7e93c0a5e6666949598d0

See more details on using hashes here.

Provenance

The following attestation bundles were made for foam_wiki-0.4.1-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on nimashoghi/foampy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file foam_wiki-0.4.1-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for foam_wiki-0.4.1-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 c7c73e80862953f0c76a9dae9aac1717bd0bf4eac3cf15c18fb30604237a38a1
MD5 6d07a4c4958e1e5539b85d69152c361f
BLAKE2b-256 a9c1f651c51bf9c21bfd1034b875ab9019d51d6b135f488449e3268d87bb4b58

See more details on using hashes here.

Provenance

The following attestation bundles were made for foam_wiki-0.4.1-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on nimashoghi/foampy

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page