notekey 0.1.0__tar.gz

notekey-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: notekey
+Version: 0.1.0
+Summary: CLI utilities for Obsidian vault notes: initialize note bases, search markdown files, and read note content.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: python-frontmatter>=1.1.0
+Requires-Dist: readtime>=3.0.0
+
+# notekey
+
+CLI utilities for working with Markdown notes in an Obsidian vault.
+
+`notekey` can:
+
+- initialize a folder with an Obsidian `.base` file and a matching Markdown note
+- search vault notes by tag, filename, or content
+- read a single note by filename or path match
+
+## Requirements
+
+- Python 3.11+
+- An Obsidian vault directory containing a `.obsidian/` folder
+
+## Installation
+
+After the package is published to PyPI:
+
+```bash
+pip install notekey
+```
+
+## Usage
+
+```bash
+notekey init [path]
+notekey search [path] [--tags TAGS] [--filename NAME] [--content TEXT]
+notekey read FILENAME
+```
+
+If `path` is omitted, `notekey` uses the `OBSIDIAN_VAULT` environment variable. If that variable is not set, it uses the current directory.
+
+```bash
+export OBSIDIAN_VAULT="/path/to/your/vault"
+```
+
+### Initialize a note folder
+
+```bash
+notekey init /path/to/vault/Projects/MyProject
+```
+
+This creates:
+
+- `MyProject.base`
+- `MyProject.md`
+
+Add extra base filters with comma-separated tags:
+
+```bash
+notekey init /path/to/vault/Projects/MyProject --tags python,docs
+```
+
+Overwrite existing generated files with:
+
+```bash
+notekey init /path/to/vault/Projects/MyProject --force
+```
+
+### Search notes
+
+Search by tag:
+
+```bash
+notekey search --tags python
+```
+
+Search by multiple tags. Files must match all tags:
+
+```bash
+notekey search --tags python,web
+```
+
+Search by filename:
+
+```bash
+notekey search --filename flask
+```
+
+Search by content:
+
+```bash
+notekey search --content pandas
+```
+
+Use `=` for exact matches:
+
+```bash
+notekey search --tags "=python"
+notekey search --filename "=deep/hidden-note"
+```
+
+### Read a note
+
+```bash
+notekey read flask-app
+```
+
+For an exact filename match:
+
+```bash
+notekey read "=flask-app"
+```
+
+## Development
+
+Run tests with:
+
+```bash
+pytest
+```
+
+Build distribution files with:
+
+```bash
+python -m build
+```
+
+Upload is intentionally manual. Use TestPyPI or PyPI with your API token when ready.

notekey-0.1.0/README.md

@@ -0,0 +1,120 @@
+# notekey
+
+CLI utilities for working with Markdown notes in an Obsidian vault.
+
+`notekey` can:
+
+- initialize a folder with an Obsidian `.base` file and a matching Markdown note
+- search vault notes by tag, filename, or content
+- read a single note by filename or path match
+
+## Requirements
+
+- Python 3.11+
+- An Obsidian vault directory containing a `.obsidian/` folder
+
+## Installation
+
+After the package is published to PyPI:
+
+```bash
+pip install notekey
+```
+
+## Usage
+
+```bash
+notekey init [path]
+notekey search [path] [--tags TAGS] [--filename NAME] [--content TEXT]
+notekey read FILENAME
+```
+
+If `path` is omitted, `notekey` uses the `OBSIDIAN_VAULT` environment variable. If that variable is not set, it uses the current directory.
+
+```bash
+export OBSIDIAN_VAULT="/path/to/your/vault"
+```
+
+### Initialize a note folder
+
+```bash
+notekey init /path/to/vault/Projects/MyProject
+```
+
+This creates:
+
+- `MyProject.base`
+- `MyProject.md`
+
+Add extra base filters with comma-separated tags:
+
+```bash
+notekey init /path/to/vault/Projects/MyProject --tags python,docs
+```
+
+Overwrite existing generated files with:
+
+```bash
+notekey init /path/to/vault/Projects/MyProject --force
+```
+
+### Search notes
+
+Search by tag:
+
+```bash
+notekey search --tags python
+```
+
+Search by multiple tags. Files must match all tags:
+
+```bash
+notekey search --tags python,web
+```
+
+Search by filename:
+
+```bash
+notekey search --filename flask
+```
+
+Search by content:
+
+```bash
+notekey search --content pandas
+```
+
+Use `=` for exact matches:
+
+```bash
+notekey search --tags "=python"
+notekey search --filename "=deep/hidden-note"
+```
+
+### Read a note
+
+```bash
+notekey read flask-app
+```
+
+For an exact filename match:
+
+```bash
+notekey read "=flask-app"
+```
+
+## Development
+
+Run tests with:
+
+```bash
+pytest
+```
+
+Build distribution files with:
+
+```bash
+python -m build
+```
+
+Upload is intentionally manual. Use TestPyPI or PyPI with your API token when ready.

notekey-0.1.0/notekey/main.py

@@ -0,0 +1,329 @@
+import argparse
+import os
+from pathlib import Path
+
+from notekey.markdown import Markdown
+from notekey.template import BASE_FILTER_TEMPLATE, MOC_TEMPLATE
+
+
+def _resolve_path(path: str | None = None) -> str:
+    """Return the effective path: CLI arg > ``$OBSIDIAN_VAULT`` > ``.``."""
+    if path is not None:
+        return path
+    env = os.environ.get("OBSIDIAN_VAULT")
+    if env:
+        return env
+    return "."
+
+
+def _get_folder(path: str | None = None) -> Path:
+    target = Path(path).expanduser().resolve() if path else Path.cwd()
+
+    if not target.exists():
+        raise FileNotFoundError(f"Path does not exist: {target}")
+    if not target.is_dir():
+        raise NotADirectoryError(f"Path is not a directory: {target}")
+
+    return target
+
+
+def _find_vault_root(target: Path) -> Path:
+    for candidate in [target, *target.parents]:
+        if (candidate / ".obsidian").is_dir():
+            return candidate
+    raise FileNotFoundError(f"No Obsidian vault (.obsidian) found above: {target}")
+
+
+def _build_filters(name: str, tags: str | None = None) -> str:
+    parsed_tags = [tag.strip() for tag in tags.split(",")] if tags else []
+
+    filters: list[str] = []
+    for tag in [name, *parsed_tags]:
+        if tag and tag not in filters:
+            filters.append(tag)
+
+    return ", ".join(f'"{tag}"' for tag in filters)
+
+
+def _create_base(target: Path, name: str, tags: str | None = None, force: bool = False) -> Path:
+    vault_root = _find_vault_root(target)
+    folder = target.relative_to(vault_root).as_posix()
+    filters = _build_filters(name, tags)
+    base_path = target / f"{name}.base"
+    content = BASE_FILTER_TEMPLATE.format(folder=folder, name=name, filters=filters).lstrip()
+
+    if base_path.exists() and not force:
+        raise FileExistsError(f"Base file already exists: {base_path}")
+
+    base_path.write_text(content, encoding="utf-8")
+    return base_path
+
+
+def _create_markdown(target: Path, name: str, force: bool = False) -> Path:
+    markdown_path = target / f"{name}.md"
+    content = MOC_TEMPLATE.format(name=name).lstrip()
+
+    if markdown_path.exists() and not force:
+        raise FileExistsError(f"Markdown file already exists: {markdown_path}")
+
+    markdown_path.write_text(content, encoding="utf-8")
+    return markdown_path
+
+
+# ---------------------------------------------------------------------------
+#  Search
+# ---------------------------------------------------------------------------
+
+
+def _parse_filter(value: str) -> tuple[bool, str]:
+    """Parse a filter value into (exact_match, clean_value).
+
+    ``"=python"`` → ``(True, "python")``  — exact match
+    ``"python"``   → ``(False, "python")`` — substring / containment match
+    ``"= hello"``  → ``(True, " hello")``  — spaces after ``=`` are preserved
+    """
+    if value.startswith("="):
+        return True, value[1:]
+    return False, value
+
+
+def _filename_candidates(md_path: Path, vault_root: Path) -> tuple[str, str, str]:
+    """Return filename candidates: stem, vault-relative path, vault-relative stem."""
+    stem = md_path.stem
+    try:
+        rel = md_path.relative_to(vault_root)
+        return stem, rel.as_posix(), rel.with_suffix("").as_posix()
+    except ValueError:
+        return stem, md_path.name, stem
+
+
+def _search_files(
+    vault_root: Path,
+    tags: list[str] | None = None,
+    filename: str | None = None,
+    content: str | None = None,
+) -> list[Markdown]:
+    """Walk *vault_root* for ``.md`` files and return those matching.
+
+    Filter values prefixed with ``=`` require an **exact** match;
+    unprefixed values use substring / containment matching.
+
+    Examples::
+
+        --tags py          # tag contains "py" (matches "python")
+        --tags "=python"   # tag equals "python"
+        --filename test    # filename contains "test"
+        --filename "=test" # filename equals "test"
+
+    Filters are applied cheapest-first:
+      1. Filename (no parsing needed)
+      2. Content  (raw text scan)
+      3. Tags     (requires full ``Markdown`` object)
+    """
+    # Parse exact/substring flags upfront.
+    filename_exact, filename_val = (
+        _parse_filter(filename) if filename else (False, None)
+    )
+    content_exact, content_val = (
+        _parse_filter(content) if content else (False, None)
+    )
+    parsed_tags: list[tuple[bool, str]] = (
+        [_parse_filter(t) for t in tags] if tags else []
+    )
+
+    results: list[Markdown] = []
+
+    for md_path in sorted(vault_root.rglob("*.md")):
+        # --- filename filter (cheapest) ---
+        if filename_val is not None:
+            candidates = _filename_candidates(md_path, vault_root)
+
+            if filename_exact:
+                if filename_val not in candidates:
+                    continue
+            else:
+                val_lower = filename_val.lower()
+                if not any(val_lower in candidate.lower() for candidate in candidates):
+                    continue
+
+        # --- content filter (raw text scan, no full parse yet) ---
+        if content_val is not None:
+            try:
+                raw = md_path.read_text(encoding="utf-8", errors="replace")
+            except Exception:
+                continue
+            if content_exact:
+                if content_val != raw:
+                    continue
+            else:
+                if content_val.lower() not in raw.lower():
+                    continue
+
+        # --- tags filter (requires full parse — most expensive) ---
+        try:
+            md = Markdown(md_path)
+        except Exception:
+            continue
+
+        if parsed_tags:
+            md_tag_lower = [t.lower() for t in md.tags]
+            matched = True
+            for exact, user_tag in parsed_tags:
+                if exact:
+                    if not any(user_tag.lower() == ft.lower() for ft in md.tags):
+                        matched = False
+                        break
+                else:
+                    if not any(user_tag.lower() in ft for ft in md_tag_lower):
+                        matched = False
+                        break
+            if not matched:
+                continue
+
+        results.append(md)
+
+    return results
+
+
+def _display_search_results(results: list[Markdown], vault_root: Path) -> None:
+    """Print search results with paths relative to the vault root."""
+    if not results:
+        print("No matching files found.")
+        return
+
+    print(f"\nFound {len(results)} file{'s' if len(results) != 1 else ''}:\n")
+
+    # Column widths
+    name_width = max(len(_relative_to_vault(r, vault_root)) for r in results)
+    name_width = max(name_width, 8) + 2  ##### ≥ "Filename"
+
+    for md in results:
+        rel = _relative_to_vault(md, vault_root)
+        tags_str = (
+            ", ".join(md.tags[:5])
+            + ("..." if len(md.tags) > 5 else "")
+            or "—"
+        )
+        print(
+            f"  {rel:<{name_width}}  "
+            f"tags: [{tags_str}]  "
+            f"{md.reading_time}  "
+            f"{md._normalize_size()}"
+        )
+    print()
+
+
+def _relative_to_vault(md: Markdown, vault_root: Path) -> str:
+    """Return the file path relative to the vault root."""
+    try:
+        return md._path.relative_to(vault_root).as_posix()
+    except ValueError:
+        return md._path.name
+
+
+def _display_file(md: Markdown, vault_root: Path) -> None:
+    """Print the full raw content of a ``Markdown`` file."""
+    print(md.content, end="")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="notekey")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # -- init ---------------------------------------------------------------
+    init_parser = subparsers.add_parser("init", help="Initialize notekey in a folder")
+    init_parser.add_argument(
+        "path",
+        nargs="?",
+        default=None,
+        help="Target folder (defaults to $OBSIDIAN_VAULT or current directory)",
+    )
+    init_parser.add_argument(
+        "-t",
+        "--tags",
+        help="Comma-separated tags to append to the default {name} filter in {name}.base",
+    )
+    init_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing {name}.base and {name}.md files",
+    )
+
+    # -- search -------------------------------------------------------------
+    search_parser = subparsers.add_parser("search", help="Search markdown files in the vault")
+    search_parser.add_argument(
+        "path",
+        nargs="?",
+        default=None,
+        help="Directory to search in (defaults to $OBSIDIAN_VAULT or current directory)",
+    )
+    search_parser.add_argument(
+        "-t",
+        "--tags",
+        help="Comma-separated list of tags — file must have ALL of them",
+    )
+    search_parser.add_argument(
+        "-f",
+        "--filename",
+        help="Substring to match in the filename (case-insensitive)",
+    )
+    search_parser.add_argument(
+        "-c",
+        "--content",
+        help="Substring to match in the file content (case-insensitive)",
+    )
+
+    # -- read ---------------------------------------------------------------
+    read_parser = subparsers.add_parser("read", help="Read a single markdown file by name or path")
+    read_parser.add_argument(
+        "filename",
+        help="Filename or path to match — first match wins (prefix = for exact)",
+    )
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command == "init":
+        target = _get_folder(_resolve_path(args.path))
+        current_location = str(target)
+        folder_name = target.name
+        base_path = _create_base(target, folder_name, tags=args.tags, force=args.force)
+        markdown_path = _create_markdown(target, folder_name, force=args.force)
+
+        print(f"Full path: {current_location}")
+        print(f"Folder name: {folder_name}")
+        print(f"Created base: {base_path}")
+        print(f"Created markdown: {markdown_path}")
+
+    elif args.command == "search":
+        target = _get_folder(_resolve_path(args.path))
+        vault_root = _find_vault_root(target)
+        tags = [t.strip() for t in args.tags.split(",")] if args.tags else None
+        results = _search_files(
+            vault_root,
+            tags=tags,
+            filename=args.filename,
+            content=args.content,
+        )
+        _display_search_results(results, vault_root)
+
+    elif args.command == "read":
+        target = _get_folder(_resolve_path())
+        vault_root = _find_vault_root(target)
+        results = _search_files(vault_root, filename=args.filename)
+
+        if not results:
+            print(f"No file found matching: {args.filename}")
+        elif len(results) > 1:
+            print(f"Multiple matches — showing first of {len(results)}:")
+            _display_file(results[0], vault_root)
+        else:
+            _display_file(results[0], vault_root)
+
+
+if __name__ == "__main__":
+    main()

notekey-0.1.0/notekey/markdown.py

@@ -0,0 +1,88 @@
+import datetime
+from pathlib import Path
+from typing import Any
+
+import frontmatter
+import readtime
+
+from notekey.utils import extract_inline_tags, extract_markdown_links, extract_wiki_links, normalize_size
+
+
+class Markdown:
+    """Represents a parsed Markdown file from an Obsidian vault.
+
+    Uses ``python-frontmatter`` for frontmatter parsing and ``readtime``
+    for reading-time estimation.
+    """
+
+    created_at: datetime.datetime
+    updated_at: datetime.datetime
+    name: str
+    size: float
+    metadata: dict
+    content: str
+    tags: list[str]
+    links: list[str]
+    reading_time: str
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path).expanduser().resolve()
+
+        if not self._path.exists():
+            raise FileNotFoundError(f"File not found: {self._path}")
+        if not self._path.is_file():
+            raise IsADirectoryError(f"Path is not a file: {self._path}")
+
+        stat = self._path.stat()
+        self.name = self._path.stem
+        self._size_bytes: float = float(stat.st_size)
+        self.size = self._size_bytes
+        self.created_at = datetime.datetime.fromtimestamp(stat.st_birthtime)
+        self.updated_at = datetime.datetime.fromtimestamp(stat.st_mtime)
+
+        # Full raw content (frontmatter + body) — needed for link extraction.
+        self.content = self._path.read_text(encoding="utf-8")
+
+        # Parse frontmatter via python-frontmatter.
+        post: Any = frontmatter.loads(self.content)
+        self.metadata = dict(post.metadata)
+        self._body: str = post.content  # body *without* frontmatter
+
+        # Reading time estimated from the body content.
+        self._reading_time_result = readtime.of_markdown(self._body)
+        self.reading_time = str(self._reading_time_result)
+
+        self.tags = self._get_tags()
+        self.links = self._get_links()
+
+    def _get_tags(self) -> list[str]:
+        """Extract tags from frontmatter *and* inline ``#tag`` references."""
+        tags: set[str] = set()
+
+        # Tags from frontmatter
+        fm_tags = self.metadata.get("tags", [])
+        if isinstance(fm_tags, list):
+            tags.update(str(t).strip() for t in fm_tags if t)
+        elif isinstance(fm_tags, str):
+            tags.add(fm_tags.strip())
+
+        # Tags from body content (#tag syntax)
+        tags.update(extract_inline_tags(self._body))
+
+        return sorted(tags)
+
+    def _get_links(self) -> list[str]:
+        """Extract wiki links and markdown links from the file content."""
+        links: set[str] = set()
+        links.update(extract_wiki_links(self.content))
+        links.update(extract_markdown_links(self.content))
+        return sorted(links)
+
+    def _normalize_size(self) -> str:
+        """Return the file size as a human-readable string."""
+        return normalize_size(self._size_bytes)
+
+    def __repr__(self) -> str:
+        return (
+            f"<Markdown filename='{self.name}' size='{self._normalize_size()}'>"
+        )

notekey-0.1.0/notekey/template.py

@@ -0,0 +1,28 @@
+BASE_FILTER_TEMPLATE="""
+views:
+  - type: table
+    name: Notes
+    filters:
+      or:
+        - and:
+            - '!file.inFolder("{folder}")'
+            - file.tags.containsAny({filters})
+            - '!file.inFolder("{folder}/openspec")'
+        - and:
+            - file.inFolder("{folder}")
+            - '!file.name.endsWith(".base")'
+            - file.name != "{name}"
+            - '!file.inFolder("{folder}/openspec")'
+    order:
+      - date
+      - file.name
+      - about
+    sort:
+      - property: date
+        direction: ASC
+"""
+
+MOC_TEMPLATE="""
+### Notes
+![[{name}.base]]
+"""