DOCSEARCHbyAlgolia
Submit Docs

py-obsidianmd

repository·main·Indexed 43 days ago

https://github.com/selimrbd/py-obsidianmd

A Python library version 0.1.7 for batch-modifying Obsidian notes. It enables manipulating metadata by adding, removing, or moving data between YAML frontmatter and inline dataview notation, as well as restructuring note content by wrapping inline metadata in Obsidian callouts.

Tokens
1.6K
Snippets
8
Records
9
Agent score
53%

What's inside py-obsidianmd

  1. Overview of py-obsidianmd capabilities

    main

    py-obsidianmd is a Python library for batch-modifying metadata within Obsidian vaults. Its primary use cases include:

    • Moving metadata between YAML frontmatter and inline (dataview notation).
    • Regrouping inline metadata inside callouts.
    • Adding or removing metadata across multiple notes.

    Warning: Always back up your Obsidian vault before running scripts with this library to prevent accidental data loss.

  2. Filter, add, and remove metadata

    main

    You can perform batch operations on specific notes by filtering them first.

    1. Filter: Use notes.filter() with the has_meta parameter. The parameter accepts a list of tuples in the format (key, value, MetadataType).
    2. Add: Use notes.metadata.add(k=key, l=value, meta_type=type).
    3. Remove: Use notes.metadata.remove(k=key, l=value, meta_type=type).
    4. Persist: Call update_content() and write() to apply and save changes.
    # Filter notes that have a specific inline tag
notes.filter(has_meta=[("tags", "type/book", MetadataType.INLINE)])

# Add new inline metadata
notes.metadata.add(k="type", l="[[book]]", meta_type=MetadataType.INLINE)

# Remove specific inline metadata
notes.metadata.remove(k="tags", l="type/book", meta_type=MetadataType.INLINE)

# Apply and save
notes.update_content(inline_inplace=False, inline_position="top", inline_tml="callout")
notes.write()

  4. Initialize the Notes object

    main

    To start using the library, import Notes and MetadataType from pyomd. Pass a pathlib.Path object pointing to your Obsidian vault folder to the Notes constructor.

    from pathlib import Path
from pyomd import Notes
from pyomd.metadata import MetadataType

path_dir = Path('/path/to/obsidian/folder')
notes = Notes(path_dir)

  6. Initialize the library with Notes or Note objects

    main

    To interact with an Obsidian vault, you can initialize a Notes object to manage multiple files in a directory, or a single Note object if you only need to modify one specific file.

    Import Notes and Note from pyomd and provide the directory path using pathlib.Path.

    from pathlib import Path
from pyomd import Notes, Note

path_dir = Path("/path/to/your/directory")
# To manage all notes in the directory
notes = Notes(path_dir)

# To manage a single specific note
# note = Note(path_dir)

  7. Move metadata between frontmatter and inline

    main

    You can migrate metadata from the YAML frontmatter to inline format using the metadata.move method. After moving, you must call update_content to apply the changes to the file structure and write() to save them to disk.

    Use MetadataType.FRONTMATTER as the source (fr) and MetadataType.INLINE as the destination (to).

    notes.metadata.move(fr=MetadataType.FRONTMATTER, to=MetadataType.INLINE)
notes.update_content(inline_inplace=False, inline_position="top", inline_tml="standard") #type: ignore
notes.write()

  8. Add and remove metadata

    main

    You can manipulate metadata for specific notes using add and remove methods.

    1. Filter: Use filter() to select a subset of notes based on existing metadata. The has_meta parameter accepts a list of tuples in the format (key, value, MetadataType).
    2. Add: Use metadata.add(k=key, l=value, meta_type=...) to insert new metadata.
    3. Remove: Use metadata.remove(k=key, l=value, meta_type=...) to delete specific metadata entries.

    Always call update_content() and write() to persist these changes to the files.

    # Filter notes that have a specific inline tag
notes.filter(has_meta=[("tags", "type/book", MetadataType.INLINE)])

# Add a new inline metadata field
notes.metadata.add(k="type", l="[[book]]", meta_type=MetadataType.INLINE)

# Remove an existing inline metadata field
notes.metadata.remove(k="tags", l="type/book", meta_type=MetadataType.INLINE)

# Apply changes and save
notes.update_content(inline_inplace=False, inline_position="top", inline_tml="callout") #type: ignore
notes.write()

  9. Regroup inline metadata inside a callout

    main

    To change how inline metadata is visually presented in Obsidian, use update_content with the inline_tml parameter set to "callout". This wraps the metadata in an Obsidian callout block.

    Note: Setting inline_inplace=False ensures the metadata is repositioned according to the inline_position (e.g., "top") rather than just being modified in its current location.

    notes.update_content(inline_inplace=False, inline_position="top", inline_tml="callout") #type: ignore
notes.write()