Vault Explorer

Python library for interacting with Obsidian vaults. Provides data models and services for reading notes, parsing links, and searching vault content.

Features

• Data Models: Immutable dataclasses for Note and Link
• Link Parsing: Support for WikiLinks, markdown links, embeds, and section links
• Frontmatter: Parse and preserve YAML frontmatter
• Vault Operations: Load notes, resolve links, calculate backlinks
• Search: Content, tag, and title search

Installation

uv sync

Quick Start

from pathlib import Path
from vault_explorer import VaultService, SearchService

# Initialize vault
vault = VaultService(Path("/path/to/vault"))

# Load all notes
notes = vault.get_all_notes()

# Get specific note
note = vault.get_note_by_title("My Note")

# Access note properties
print(f"Title: {note.title}")
print(f"Links: {len(note.links)}")
print(f"Tags: {note.frontmatter.get('tags', [])}")

# Resolve links
for link in note.links:
    target_path = vault.resolve_link(link, note)
    if target_path:
        print(f"Link to: {target_path}")

# Calculate backlinks
backlinks = vault.calculate_backlinks()
my_backlinks = backlinks.get("My Note", [])

# Search
search = SearchService(vault)
results = search.search_content("python")
tagged = search.search_by_tag("project")

API Reference

Models

LinkType (Enum)

• WIKILINK: [[Note]] or [[Note|Display]]
• MARKDOWN: [text](note.md)
• EMBED: ![[Note]]
• SECTION: [[Note#Heading]]

Link (dataclass)

• link_type: LinkType - Type of link
• target: str - Target note name or path
• display_text: Optional[str] - Display text if specified
• section: Optional[str] - Section/heading reference
• line_number: int - Line number in source (1-indexed)
• raw_text: str - Original markdown text

Note (dataclass)

• path: Path - Absolute path to .md file
• title: str - Note title (filename without .md)
• content: str - Markdown content (excluding frontmatter)
• frontmatter: dict - Parsed YAML frontmatter
• links: tuple[Link, ...] - All outgoing links

VaultService

VaultService(vault_path: Path)

Methods:

• load_note(note_path: Path) -> Note - Load single note
• get_all_notes() -> list[Note] - Load all notes recursively
• get_note_by_title(title: str) -> Optional[Note] - Find by title (case-insensitive)
• resolve_link(link: Link, source_note: Note) -> Optional[Path] - Resolve link to file path
• calculate_backlinks() -> dict[str, list[Link]] - Build backlink index

SearchService

SearchService(vault: VaultService)

Methods:

• search_content(query: str, case_sensitive: bool = False) -> list[Note] - Text search
• search_by_tag(tag: str) -> list[Note] - Find notes with tag
• search_by_title(query: str) -> list[Note] - Search note titles

LinkParser

LinkParser()

Methods:

• parse_links(content: str, frontmatter_lines: int = 0) -> list[Link] - Extract all links

Development

# Install dependencies
uv sync --dev

# Run tests
uv run pytest

# Run specific test file
uv run pytest tests/test_vault.py -v

# Lint
uv run ruff check src tests

# Format
uv run ruff format src tests

Architecture

Hybrid Design: Immutable dataclasses for data + service layer for operations

• models.py: Core data structures
• parser.py: Link and frontmatter parsing
• vault.py: Note loading and link resolution
• search.py: Search functionality

Future Extensions

• Link suggestion engine (semantic similarity)
• Note editing capabilities
• Claude Code skills integration
• Performance optimization for large vaults
• Block reference support

License

MIT