OVault

A python library for accessing and editing your Obsidian vault.

Check out the examples!

Code Example

import ovault

# Open a vault at a given path
vault = ovault.Vault("test-vaults/simple_vault")

print("Vault Path  :", vault.path)
print("Notes       :", len(vault.notes()))
print("Attachments :", len(vault.attachments()))
print("Tags        :", sorted(vault.tags()))
print()

# Get the note named 'first_note'
note = vault.note("first_note")

print("Note Name   :", note.name)
print("Note Path   :", note.path)
print("Note Tokens :", note.tokens())

Output:

Vault Path  : /home/balder/projects/ovault/test-vaults/simple_vault
Notes       : 11
Attachments : 3
Tags        : ['callout4youtag', 'frontmatter-tag1', 'frontmatter-tag2', 'linksaregood']

Note Name   : first_note
Note Path   : first_note.md
Note Tokens : [Header(# FIRST NOTE!), Text(Wuhuuuuuuuuuuu!Thi...), InternalLink(second note), Text(.Takes a look at t...), InternalLink(sub/todo), Text()]

Included Utilities

OVault includes runnable modules for common tasks. Get an overview by running the ovault module:

python -m ovault

Output:

OVault provies a few utilties out of the box.

You can run them like so: `python3 -m ovault.<module>`

Available modules:
    ovault.visualize_graph        : Visualize your Obsidian vault graph using pyvis.
    ovault.check_links            : Check all external links to websites in an Obsidian vault and report any broken links.
    ovault.to_html                : Convert an obsidian vault to a simple static HTML site.
    ovault.mv                     : Rename a file within an Obsidian vault, updating all links accordingly.
    ovault.info                   : Show information about an Obsidian vault.
    ovault.name_pasted_images     : Rename pasted images in the vault based on the note they are pasted into.
    ovault.help                   : Show a list of all utility modules included in `ovault`.
    ovault.filename_compatibility : Check filenames for compatibility across different operating systems.

Install

pip install ovault

or locally

git pull https://github.com/BalderHolst/ovault
cd ovault
pip install .

Features

Vault Management

Indexing

• Indexing: Automatically indexes all notes and attachments within the vault upon initialization.
• Ignored Files: Respects and parses .vault-ignore files to exclude specified paths during indexing.
• Dangling Links: Identify and list links within your notes that point to non-existent files.

Note Handling

Access & Properties

• Access Notes & Attachments: Retrieve all notes or attachments in the vault as Python objects.
• Frontmatter Extraction: Manipulate YAML frontmatter from notes.

Modification

• Dynamic Note Modification: Programmatically insert or replace parts of a note

Tag Management

Querying Tags

• List All Tags: Get a complete list of tags present in your vault.
• Filter by Tag: Retrieve all notes associated with a specific tag.

Markdown Parsing & Tokenization

Token Representation

• Rich Token Representation: Notes are parsed into a detailed stream of Token objects, representing various markdown elements.

See Token in lexer/tokens.rs for all token definitions.

Contributing

I would be more than happy if anyone finds this useful enough to add to, or modify this code.

Development

Install ovault and development dependencies with

pip install -e ".[dev]"

or use the nix flake

nix develop

Build for Testing

maturin develop --release --features python

Test

./scripts/test.sh

Generate coverage report with

cargo tarpaulin --engine llvm --release --out Html

Build Documentation

./scripts/build-docs.py

Release

1. Bump version in Cargo.toml
2. Commit change and push
3. Merge dev into main and push
4. Create a git tag with the same version: git tag <version>
5. Push new tag: git push --tags