ovault 0.0.4

Library for Managing your Obsidian Vault

OVault

A python library for accessing and editing your Obsidian vault.

Check out the examples!

Install

pip install ovault

Example

import ovault

v = ovault.Vault("path/to/vault")

print()
print("path        :", v.path)
print("notes       :", len(v.notes()))
print("attachments :", len(v.attachments()))
print("tags        :", v.tags())

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.
• Note Properties: Access key information for each note, including its full path, relative path, name, character length, associated tags, internal links, and backlinks.
• Content Access: Read the raw content of any note.
• Frontmatter Extraction: Easily retrieve YAML frontmatter from notes.

Modification

• Dynamic Note Modification: Programmatically insert text into notes at specific character positions, or intelligently before/after recognized markdown tokens.

Tag Management

Querying Tags

• List All Tags: Get a complete list of all unique tags present across your entire vault.
• Filter by Tag: Efficiently 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.
• Available Tokens:
  • Headers: (# Heading)
  • Tags: (#tag)
  • Code Blocks: (fenced code, inline code)
  • Quotes: (> Quote)
  • Math: ($inline$ and $$display$$ LaTeX)
  • Dividers: (---)
  • Callouts: (> [!type] Title)
  • Plain Text:
  • Frontmatter: (YAML metadata)
  • Internal Links: ([[Note Name]], ![[Image.png]])
  • External Links: ([link text](url), ![image alt](url))
  • TemplaterCommand: (<% code goes here %>)

Development

Install ovault and development dependencies with

pip install -e ".[dev]"

Build for Testing

maturin develop --release --features python

Test

./test.sh

Build Documentation

./docs/build.py

Release

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