Skip to content

qmd_py.vpath

marq://collection/path virtual-path parsing and construction.

vpath

marq://collection/path virtual path parsing - port of the TS reference qmd's isVirtualPath/parseVirtualPath/buildVirtualPath (src/store.ts), minus the ?index= query param handling, which was for the per-project SQLite --index <name> concept the plan drops entirely (it doesn't apply to a shared Postgres backend).

is_virtual_path 

is_virtual_path(path: str) -> bool

Whether path looks like a virtual path rather than a plain one.

Accepts the bare //collection/path form as well as marq://..., since shells and editors routinely strip the scheme.

Returns:

  • bool –

    True for anything starting marq: or //. A syntactic check

  • bool –

    only - it neither parses the rest nor checks the collection

  • bool –

    exists.

Source code in src/qmd_py/vpath.py 
13
14
15
16
17
18
19
20
21
22
23
24
def is_virtual_path(path: str) -> bool:
    """Whether `path` looks like a virtual path rather than a plain one.

    Accepts the bare `//collection/path` form as well as `marq://...`,
    since shells and editors routinely strip the scheme.

    Returns:
        True for anything starting `marq:` or `//`. A syntactic check
        only - it neither parses the rest nor checks the collection
        exists.
    """
    return path.startswith("marq:") or path.startswith("//")

parse_virtual_path 

parse_virtual_path(path: str) -> tuple[str, str] | None

Split a virtual path into its collection and document path.

Parameters:

  • path (str) –

    marq://collection/path, or the scheme-less //collection/path.

Returns:

  • tuple[str, str] | None –

    A (collection_name, path) pair, or None if it doesn't parse.

  • tuple[str, str] | None –

    The path half is "" for a bare collection reference like

  • tuple[str, str] | None –

    marq://notes/, so callers should expect an empty second element

  • tuple[str, str] | None –

    rather than None.

Source code in src/qmd_py/vpath.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def parse_virtual_path(path: str) -> tuple[str, str] | None:
    """Split a virtual path into its collection and document path.

    Args:
        path: `marq://collection/path`, or the scheme-less `//collection/path`.

    Returns:
        A `(collection_name, path)` pair, or None if it doesn't parse.
        The path half is `""` for a bare collection reference like
        `marq://notes/`, so callers should expect an empty second element
        rather than None.
    """
    normalized = path if path.startswith("marq:") else f"marq:{path}"
    match = _VPATH_RE.match(normalized)
    if not match:
        return None
    return match.group(1), match.group(2)

build_virtual_path 

build_virtual_path(collection_name: str, path: str) -> str

Join a collection and document path into a marq:// URI.

No escaping is applied - see mcp/server.py's _encode_qmd_path() for the percent-encoded form the MCP resource layer needs.

Source code in src/qmd_py/vpath.py 
46
47
48
49
50
51
52
def build_virtual_path(collection_name: str, path: str) -> str:
    """Join a collection and document path into a `marq://` URI.

    No escaping is applied - see `mcp/server.py`'s `_encode_qmd_path()`
    for the percent-encoded form the MCP resource layer needs.
    """
    return f"marq://{collection_name}/{path}"