Parsing a note (vaultkg.parse)

vaultkg.parse

parse.py -- read one Obsidian note into its structural parts.

Everything here is syntax, not interpretation: frontmatter is YAML, a heading is an ATX # line, a link is [[...]] or [...](x.md), a typed link is a Dataview inline field (key:: [[X]]) or a frontmatter key whose value holds wikilinks. Nothing is inferred from prose, so the same file always yields the same parts.

Code is not markup: wikilinks, tags and fields inside fenced blocks, inline code spans and %% comments are masked out before any of them are matched. Masking replaces characters with spaces, so match positions still line up with the original text.

Heading(level, text, line, end_line) dataclass

One ATX heading and the section it opens.

Parameters:

Name	Type	Description	Default
level	int	1-6.	required
text	str	Heading text with trailing # stripped.	required
line	int	1-based line of the heading.	required
end_line	int	Last line of its section (before the next heading of the same or a higher level, or the end of the file).	required

Link(target, anchor, alias, line, embed=False, relation='', markdown=False) dataclass

One link occurrence in a note.

Parameters:

Name	Type	Description	Default
target	str	Page part of the target, as written (no #anchor).	required
anchor	str	Heading or ^block after #; empty when absent.	required
alias	str	Display text after |; empty when absent.	required
line	int	1-based line the link sits on (0 for frontmatter links).	required
embed	bool	True for ![[...]] and .	False
relation	str	Typed-link key (supports) or empty for a plain link.	''
markdown	bool	True for a [...](path) link rather than a wikilink.	False

ParsedNote(frontmatter, frontmatter_error, body_start, lines, headings=list(), links=list(), tags=list()) dataclass

Structural parts of one note.

Parameters:

Name	Type	Description	Default
frontmatter	dict[str, Any]	Parsed YAML mapping; empty when absent or invalid.	required
frontmatter_error	str	YAML error message, or empty.	required
body_start	int	1-based line where the body begins (after frontmatter).	required
lines	list[str]	All lines of the file, without newlines.	required
headings	list[Heading]	Headings in file order.	list()
links	list[Link]	Links in file order; frontmatter links first.	list()
tags	list[str]	Distinct tags, frontmatter first, without #.	list()

body property

The note text after the frontmatter.

parse_note(text)

Parse one note's text.

Parameters:

Name	Type	Description	Default
text	str	Full file contents.	required

Returns:

Type	Description
ParsedNote	The note's frontmatter, headings, links and tags.

Source code in src/vaultkg/parse.py

def parse_note(text: str) -> ParsedNote:
    """Parse one note's text.

    :param text: Full file contents.
    :return: The note's frontmatter, headings, links and tags.
    """
    lines = text.splitlines()
    frontmatter, fm_error, body_start = _read_frontmatter(lines)
    masked = _mask(lines, body_start)
    note = ParsedNote(frontmatter, fm_error, body_start, lines)
    note.headings = _headings(masked, body_start)
    note.links.extend(_frontmatter_links(frontmatter))

    tags = _frontmatter_tags(frontmatter)
    for idx, line in enumerate(masked, start=1):
        if not line.strip():
            continue
        fields = _field_spans(line)

        def _rel(pos: int, fields: list[tuple[int, int, str]] = fields) -> str:
            for start, end, rel in fields:
                if start <= pos < end:
                    return rel
            return ""

        link_spans: list[tuple[int, int]] = []
        for m in WIKILINK.finditer(line):
            link_spans.append(m.span())
            page, anchor, alias = split_target(m.group(2))
            if not page and not anchor:
                continue
            note.links.append(Link(page, anchor, alias, idx, bool(m.group(1)), _rel(m.start())))
        for m in MDLINK.finditer(line):
            link_spans.append(m.span())
            target = m.group(3).strip("<>")
            if re.match(r"^[a-zA-Z][a-zA-Z0-9+.-]*:", target):
                continue  # http:, mailto:, obsidian: ...
            page, _, anchor = target.partition("#")
            if not page and not anchor:
                continue
            note.links.append(
                Link(page, anchor, m.group(2).strip(), idx, bool(m.group(1)), _rel(m.start()), True)
            )

        # Tags: never inside a link (``[[#Heading]]``, ``(#anchor)``) and never
        # the heading marker itself (``# Title`` has a space, so TAG skips it).
        scan = list(line)
        for a, b in link_spans:
            scan[a:b] = " " * (b - a)
        for m in TAG.finditer("".join(scan)):
            tags.append(m.group(1).rstrip("/"))

    seen: set[str] = set()
    for t in tags:
        key = t.lower()
        if key not in seen:
            seen.add(key)
            note.tags.append(t)
    return note

relation_name(key)

Normalise a typed-link key to an edge relation: part-of -> PART_OF.

Parameters:

Name	Type	Description	Default
key	str	Frontmatter key or inline-field key.	required

Returns:

Type	Description
str	Upper-case relation name.

Source code in src/vaultkg/parse.py

def relation_name(key: str) -> str:
    """Normalise a typed-link key to an edge relation: ``part-of`` -> ``PART_OF``.

    :param key: Frontmatter key or inline-field key.
    :return: Upper-case relation name.
    """
    return re.sub(r"[^A-Za-z0-9]+", "_", key.strip()).strip("_").upper()

split_target(raw)

Split a wikilink body into (target, anchor, alias).

Parameters:

Name	Type	Description	Default
raw	str	Text between [[ and ]].	required

Returns:

Type	Description
tuple[str, str, str]	Page target, anchor after # and alias after |, each stripped.

Source code in src/vaultkg/parse.py

def split_target(raw: str) -> tuple[str, str, str]:
    """Split a wikilink body into ``(target, anchor, alias)``.

    :param raw: Text between ``[[`` and ``]]``.
    :return: Page target, anchor after ``#`` and alias after ``|``, each stripped.
    """
    raw = raw.replace("\\|", "|")
    target, _, alias = raw.partition("|")
    page, _, anchor = target.partition("#")
    return page.strip(), anchor.strip(), alias.strip()