Metadata-Version: 2.4
Name: ovault
Version: 0.0.7
Requires-Dist: maturin ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pdoc3 ; extra == 'dev'
Requires-Dist: requests ; extra == 'dev'
Provides-Extra: dev
Summary: Library for Managing your Obsidian Vault 
Keywords: Obsidian,Vault,Notes
Author-email: Balder Holst <balderwh@gmail.com>
License-Expression: MIT
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://balderholst.github.io/ovault/
Project-URL: Repository, https://github.com/BalderHolst/ovault

# OVault
A python library for accessing and editing your [Obsidian](https://obsidian.md) vault.

Check out the [examples](https://github.com/BalderHolst/ovault/tree/main/examples)!

## Install
```bash
pip install ovault
```

or locally

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

## Example
```python
import ovault

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

print()
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 : 0
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()]
```

## 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.
- **Available Tokens**:
    - **Plain Text:** This is text
    - **Headers:** (`# Heading`)
    - **Internal Links:** (`[[Note Name]]`, `![[Image.png]]`)
    - **External Links:** (`[link text](url)`, `![image alt](url)`)
    - **Tags:** (`#tag`)
    - **Code Blocks:** (fenced code, `inline code`)
    - **Quotes:** (`> Quote`)
    - **Math:** (`$inline$` and `$$display$$` LaTeX)
    - **Dividers:** (`---`)
    - **Callouts:** (`> [!type] Title`)
    - **Frontmatter:** (YAML metadata)
    - **List**: `- item 1\n- item 2`
    - **NumericList**: `1. first\n2. second`
    - **CheckList**: `- [x] done\n- [ ] not done`
    - **TemplaterCommand**: (`<% code goes here %>`)

See [`lexer/tokens.rs`](./src/lexer/tokens.rs) for 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
```bash
pip install -e ".[dev]"
```

or use the nix flake
```bash
nix develop
```

### Build for Testing
```bash
maturin develop --release --features python
```

### Test
```bash
./test.sh
```

### Build Documentation
```bash
./docs/build.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`

