org-dex-parse 0.1.0__py3-none-any.whl

org_dex_parse/__init__.py

@@ -0,0 +1,29 @@
+"""org-dex-parse: parse org-mode files into structured data."""
+
+__version__ = "0.1.0"
+
+from org_dex_parse.config import Config
+from org_dex_parse.evaluator import compile_predicate
+from org_dex_parse.parser import parse_file
+from org_dex_parse.types import (
+    ClockEntry,
+    Item,
+    Link,
+    ParseResult,
+    Range,
+    StateChange,
+    Timestamp,
+)
+
+__all__ = [
+    "compile_predicate",
+    "Config",
+    "ClockEntry",
+    "Item",
+    "Link",
+    "ParseResult",
+    "Range",
+    "StateChange",
+    "Timestamp",
+    "parse_file",
+]

org_dex_parse/__main__.py

@@ -0,0 +1,294 @@
+"""CLI for org-dex-parse: python -m org_dex_parse FILE [FILE ...]
+
+Parses org files and prints each item with its populated fields.
+Uses bare configuration by default (any heading with :ID: is an item).
+
+Usage:
+    python -m org_dex_parse file.org
+    python -m org_dex_parse --json file.org
+    python -m org_dex_parse --config myconfig.json file.org
+    python -m org_dex_parse --predicate '["property", "Type"]' file.org
+    python -m org_dex_parse --todos TODO,NEXT --dones DONE file.org
+    python -m org_dex_parse --json -vv file.org   # full output with raw_text
+"""
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import datetime
+import json
+import sys
+from pathlib import Path
+
+from .config import Config
+from .parser import parse_file
+
+
+# -- Config construction -------------------------------------------------------
+# Builds a Config from CLI flags and optional JSON config file.
+# Precedence: CLI flags > config file > Config defaults.
+
+# Valid keys in the JSON config file — must match Config fields.
+# Used to reject typos early (AC11).
+_VALID_CONFIG_KEYS = frozenset({
+    "predicate", "todos", "dones", "tags_exclude_from_inheritance",
+    "exclude_drawers", "exclude_blocks", "exclude_properties",
+    "created_property", "extra_tag_chars",
+})
+
+
+def _load_config_file(path: str) -> dict:
+    """Load and validate a JSON config file.
+
+    Returns a dict with only known keys.  Raises SystemExit on
+    unknown keys or missing file (with clear error messages).
+    """
+    try:
+        text = Path(path).read_text()
+    except FileNotFoundError:
+        print(f"error: config file not found: {path}", file=sys.stderr)
+        raise SystemExit(1)
+
+    data = json.loads(text)
+    if not isinstance(data, dict):
+        print(f"error: config file must be a JSON object, got {type(data).__name__}",
+              file=sys.stderr)
+        raise SystemExit(1)
+
+    unknown = set(data.keys()) - _VALID_CONFIG_KEYS
+    if unknown:
+        print(f"error: unknown fields in config file: {', '.join(sorted(unknown))}",
+              file=sys.stderr)
+        raise SystemExit(1)
+
+    return data
+
+
+def _build_config(args: argparse.Namespace) -> Config:
+    """Build a Config from CLI args, merging config file if present.
+
+    Precedence: CLI flags > config file > Config defaults.
+    A CLI flag is considered "set" when its value differs from None
+    (argparse default for all our optional flags).
+    """
+    # Start with config file values (if any).
+    file_cfg: dict = {}
+    if args.config is not None:
+        file_cfg = _load_config_file(args.config)
+
+    # Map CLI flag names to config dict keys.
+    # Each entry: (argparse dest, config key, transform).
+    # transform converts the CLI string to the config value type.
+    _split = lambda s: tuple(s.split(",")) if s else ()
+    _split_frozen = lambda s: frozenset(s.split(",")) if s else frozenset()
+
+    cli_mappings = [
+        ("predicate", "predicate", lambda s: json.loads(s)),
+        ("todos", "todos", _split),
+        ("dones", "dones", _split),
+        ("tags_exclude", "tags_exclude_from_inheritance", _split_frozen),
+        ("exclude_drawers", "exclude_drawers", _split_frozen),
+        ("exclude_blocks", "exclude_blocks", _split_frozen),
+        ("exclude_properties", "exclude_properties", _split_frozen),
+        ("created_property", "created_property", lambda s: s),
+        ("extra_tag_chars", "extra_tag_chars", lambda s: s),
+    ]
+
+    # Merge: CLI flags override config file.
+    merged: dict = {}
+    for arg_name, cfg_key, transform in cli_mappings:
+        cli_val = getattr(args, arg_name, None)
+        if cli_val is not None:
+            # CLI flag was explicitly set — it wins.
+            merged[cfg_key] = transform(cli_val)
+        elif cfg_key in file_cfg:
+            # Config file has this key — use it.
+            merged[cfg_key] = file_cfg[cfg_key]
+        # else: use Config default (don't set in merged).
+
+    # Convert config file types to Config constructor types.
+    # JSON arrays → tuples/frozensets as needed.
+    if "todos" in merged and isinstance(merged["todos"], list):
+        merged["todos"] = tuple(merged["todos"])
+    if "dones" in merged and isinstance(merged["dones"], list):
+        merged["dones"] = tuple(merged["dones"])
+    for set_key in ("tags_exclude_from_inheritance", "exclude_drawers",
+                     "exclude_blocks", "exclude_properties"):
+        if set_key in merged and isinstance(merged[set_key], list):
+            merged[set_key] = frozenset(merged[set_key])
+
+    # predicate: list or None passed directly to Config (compiled in
+    # __post_init__).  "null" on CLI becomes None via json.loads.
+    if "predicate" in merged:
+        merged["item_predicate"] = merged.pop("predicate")
+
+    return Config(**merged)
+
+
+# -- JSON serialization --------------------------------------------------------
+# Custom encoder for Item dataclasses and org-dex-parse types.
+
+class _ItemEncoder(json.JSONEncoder):
+    """JSON encoder for Item and its nested types."""
+
+    def default(self, obj):
+        # date/datetime → ISO string.
+        if isinstance(obj, datetime.datetime):
+            return obj.isoformat()
+        if isinstance(obj, datetime.date):
+            return obj.isoformat()
+        # frozenset → sorted list.
+        if isinstance(obj, frozenset):
+            return sorted(obj)
+        return super().default(obj)
+
+
+def _item_to_dict(item, verbosity: int) -> dict:
+    """Convert an Item to a JSON-friendly dict.
+
+    Verbosity controls which fields are included:
+    - 0 (default): all fields except body and raw_text
+    - 1 (-v): adds body
+    - 2 (-vv): adds body and raw_text
+
+    Properties tuple-of-tuples is converted to a dict for readability.
+    """
+    d = dataclasses.asdict(item)
+
+    # Properties: tuple-of-tuples → dict.
+    d["properties"] = dict(d["properties"])
+
+    # Verbosity filtering.
+    if verbosity < 2:
+        d.pop("raw_text", None)
+    if verbosity < 1:
+        d.pop("body", None)
+
+    return d
+
+
+# -- Text output ---------------------------------------------------------------
+
+def _print_item(item, verbosity: int) -> None:
+    """Print a single item in human-readable text format."""
+    print(f"  {item.title}")
+    print(f"    id={item.item_id}  level={item.level}  line={item.linenumber}")
+
+    if item.parent_item_id:
+        print(f"    parent={item.parent_item_id}")
+    if item.todo:
+        print(f"    todo={item.todo}", end="")
+        if item.priority:
+            print(f"  priority={item.priority}", end="")
+        print()
+    elif item.priority:
+        print(f"    priority={item.priority}")
+    if item.local_tags:
+        print(f"    local_tags={sorted(item.local_tags)}")
+    if item.inherited_tags:
+        print(f"    inherited_tags={sorted(item.inherited_tags)}")
+    if item.properties:
+        print(f"    properties={dict(item.properties)}")
+
+    # -v: show body.
+    if verbosity >= 1 and item.body:
+        lines = item.body.split("\n")
+        preview = lines[0][:80]
+        if len(lines) > 1:
+            preview += f"  ... ({len(lines)} lines)"
+        print(f"    body: {preview}")
+
+    # -vv: show raw_text.
+    if verbosity >= 2 and item.raw_text:
+        lines = item.raw_text.split("\n")
+        preview = lines[0][:80]
+        if len(lines) > 1:
+            preview += f"  ... ({len(lines)} lines)"
+        print(f"    raw_text: {preview}")
+
+
+# -- Main ----------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="python -m org_dex_parse",
+        description="Parse org files and show items (bare config by default).",
+    )
+    parser.add_argument("files", nargs="+", help="Org files to parse")
+
+    # Configuration flags — all optional, override config file values.
+    parser.add_argument(
+        "--config", type=str, default=None, metavar="FILE",
+        help="JSON config file (all fields optional)",
+    )
+    parser.add_argument(
+        "--predicate", type=str, default=None,
+        help='JSON s-expression predicate, e.g. \'["property", "Type"]\'',
+    )
+    parser.add_argument(
+        "--todos", type=str, default=None,
+        help="Comma-separated active TODO keywords",
+    )
+    parser.add_argument(
+        "--dones", type=str, default=None,
+        help="Comma-separated done TODO keywords",
+    )
+    parser.add_argument(
+        "--tags-exclude", type=str, default=None, dest="tags_exclude",
+        help="Comma-separated tags excluded from inheritance",
+    )
+    parser.add_argument(
+        "--exclude-drawers", type=str, default=None, dest="exclude_drawers",
+        help="Comma-separated drawer names to exclude from body",
+    )
+    parser.add_argument(
+        "--exclude-blocks", type=str, default=None, dest="exclude_blocks",
+        help="Comma-separated block names to exclude from body",
+    )
+    parser.add_argument(
+        "--exclude-properties", type=str, default=None, dest="exclude_properties",
+        help="Comma-separated property names to exclude",
+    )
+    parser.add_argument(
+        "--created-property", type=str, default=None, dest="created_property",
+        help="Property name for creation date (default: CREATED)",
+    )
+    parser.add_argument(
+        "--extra-tag-chars", type=str, default=None, dest="extra_tag_chars",
+        help="Additional characters allowed in tag names",
+    )
+
+    # Output flags.
+    parser.add_argument(
+        "--json", action="store_true", dest="json_output",
+        help="Output items as JSON",
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="count", default=0,
+        help="Increase verbosity: -v adds body, -vv adds raw_text",
+    )
+
+    args = parser.parse_args()
+    config = _build_config(args)
+
+    if args.json_output:
+        # JSON mode: collect all items across files, output as one array.
+        all_items = []
+        for path in args.files:
+            result = parse_file(path, config)
+            all_items.extend(
+                _item_to_dict(item, args.verbose) for item in result.items
+            )
+        print(json.dumps(all_items, cls=_ItemEncoder, indent=2,
+                         ensure_ascii=False))
+    else:
+        # Text mode: print per-file summary.
+        for path in args.files:
+            result = parse_file(path, config)
+            print(f"\n{path}: {len(result.items)} items")
+            for item in result.items:
+                _print_item(item, args.verbose)
+
+
+if __name__ == "__main__":
+    main()

org_dex_parse/config.py

@@ -0,0 +1,108 @@
+"""Parser configuration — predicate, keywords, exclusion lists."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Any
+
+
+# Default predicate: any heading with :ID: is an item.
+# The :ID: check is a structural invariant applied before the predicate,
+# so the default predicate just returns True unconditionally.
+_DEFAULT_PREDICATE: Callable[[Any], bool] = lambda h: True
+
+
+@dataclass(frozen=True)
+class Config:
+    """Configuration for org-dex-parse.
+
+    The caller constructs this with TODO keywords, tag rules, and
+    exclusion lists matching their org-mode environment.
+
+    :arg item_predicate: Determines which headings (that already have
+        ``:ID:``) are items.  Accepts three forms:
+        - ``Callable[[Any], bool]`` — a Python function (backward compat)
+        - ``list`` — a JSON-like s-expression compiled via the evaluator
+          (e.g. ``["property", "Type"]``)
+        - ``None`` — default predicate (any heading with ``:ID:``).
+        After ``__post_init__``, always stored as a callable.
+    :arg todos: Active (unfinished) TODO keywords.
+    :arg dones: Terminal (finished) TODO keywords.
+    :arg tags_exclude_from_inheritance: Tags that don't propagate to
+        children (corresponds to ``org-tags-exclude-from-inheritance``).
+    :arg exclude_drawers: Drawer names to exclude from body text.
+        Case-insensitive — normalized to lowercase in ``__post_init__``.
+    :arg exclude_blocks: Block names to exclude from body text.
+        Case-insensitive — normalized to lowercase in ``__post_init__``.
+    :arg exclude_properties: Property names to omit from the properties
+        tuple.  Case-insensitive — normalized to lowercase in
+        ``__post_init__``.
+    :arg created_property: Name of the org property that holds the
+        creation date (e.g. ``"CREATED"``).  The parser looks for this
+        property on each item and uses its value for the ``Item.created``
+        field.  Case-insensitive — normalized to uppercase in
+        ``__post_init__`` (org-mode convention for property names).
+        Default: ``"CREATED"``.  This property is automatically excluded
+        from ``Item.properties`` (like ``ID`` and ``ARCHIVE_TIME``).
+    :arg extra_tag_chars: Additional characters to allow in org-mode tag
+        names beyond the default ``[a-zA-Z0-9_@#%]``.  The parser uses
+        this to build a monkey-patch regex for orgparse (applied in S04).
+        Default: ``""`` (no extra characters).
+    """
+
+    item_predicate: Callable[[Any], bool] = field(
+        default=_DEFAULT_PREDICATE
+    )
+    todos: tuple[str, ...] = ()
+    dones: tuple[str, ...] = ()
+    tags_exclude_from_inheritance: frozenset[str] = frozenset()
+    exclude_drawers: frozenset[str] = frozenset()
+    exclude_blocks: frozenset[str] = frozenset()
+    exclude_properties: frozenset[str] = frozenset()
+    created_property: str = "CREATED"
+    extra_tag_chars: str = ""
+
+    def __post_init__(self) -> None:
+        """Normalize fields on frozen dataclass.
+
+        - item_predicate: list/None compiled to callable via evaluator,
+          callable passed through, anything else raises ValueError.
+        - Exclusion sets lowercased for case-insensitive matching.
+
+        Uses object.__setattr__ because the dataclass is frozen — the
+        standard Python pattern for post-init normalization on frozen
+        dataclasses.
+        """
+        # -- Predicate normalization (S08) -----------------------------------
+        pred = self.item_predicate
+        if isinstance(pred, list) or pred is None:
+            from .evaluator import compile_predicate
+            object.__setattr__(
+                self, "item_predicate", compile_predicate(pred)
+            )
+        elif not callable(pred):
+            raise ValueError(
+                f"item_predicate must be callable, list, or None,"
+                f" got {type(pred).__name__}: {pred!r}"
+            )
+
+        # -- Exclusion normalization -----------------------------------------
+        object.__setattr__(
+            self,
+            "exclude_drawers",
+            frozenset(d.lower() for d in self.exclude_drawers),
+        )
+        object.__setattr__(
+            self,
+            "exclude_blocks",
+            frozenset(b.lower() for b in self.exclude_blocks),
+        )
+        object.__setattr__(
+            self,
+            "exclude_properties",
+            frozenset(p.lower() for p in self.exclude_properties),
+        )
+        object.__setattr__(
+            self,
+            "created_property",
+            self.created_property.upper(),
+        )

org_dex_parse/evaluator.py

@@ -0,0 +1,116 @@
+"""S-expression predicate compiler for item predicates.
+
+Compiles a JSON-like s-expression (Python list) into a callable predicate
+``(node) -> bool``.  The expression format mirrors org-ql, serialized as
+JSON arrays for cross-process transport (Elisp -> JSON-RPC -> Python).
+
+Example::
+
+    >>> pred = compile_predicate(["and", ["property", "Type"],
+    ...                                  ["not", ["property", "ARCHIVE_TIME"]]])
+    >>> pred(some_orgparse_node)
+    True
+
+Supported operators (extensible via ``_OPERATORS`` dispatch table):
+
+- ``["property", "Name"]`` — ``node.get_property("Name") is not None``
+- ``["not", expr]``        — negation
+- ``["and", expr, ...]``   — conjunction (n-ary, short-circuits)
+- ``["or", expr, ...]``    — disjunction (n-ary, short-circuits)
+- ``None``                 — default predicate (always True)
+"""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+def compile_predicate(
+    expr: list | None,
+) -> Callable[[Any], bool]:
+    """Compile a JSON-like s-expression into a predicate callable.
+
+    :arg expr: A list (s-expression) or None.  None returns the default
+        predicate (always True).
+    :returns: A callable ``(node) -> bool``.
+    :raises ValueError: On unknown operators, wrong arity, or invalid types.
+    """
+    if expr is None:
+        return _DEFAULT_PREDICATE
+
+    if not isinstance(expr, list):
+        raise ValueError(
+            f"expected list or None, got {type(expr).__name__}: {expr!r}"
+        )
+
+    if len(expr) == 0:
+        raise ValueError("empty expression — expected [operator, ...args]")
+
+    operator = expr[0]
+    args = expr[1:]
+
+    if operator not in _OPERATORS:
+        raise ValueError(
+            f"unknown operator {operator!r}"
+            f" — supported: {', '.join(sorted(_OPERATORS))}"
+        )
+
+    return _OPERATORS[operator](operator, args)
+
+
+# -- Default predicate -------------------------------------------------------
+
+_DEFAULT_PREDICATE: Callable[[Any], bool] = lambda _node: True
+
+
+# -- Operator handlers -------------------------------------------------------
+# Each handler takes (operator_name, args) and returns a callable.
+# operator_name is passed for error messages.
+
+
+def _compile_property(op: str, args: list) -> Callable[[Any], bool]:
+    """["property", "Name"] → node.get_property("Name") is not None."""
+    if len(args) != 1:
+        raise ValueError(
+            f"{op!r} expects exactly 1 argument (property name),"
+            f" got {len(args)}: {args!r}"
+        )
+    prop_name = args[0]
+    return lambda node: node.get_property(prop_name) is not None
+
+
+def _compile_not(op: str, args: list) -> Callable[[Any], bool]:
+    """["not", expr] → negation of sub-expression."""
+    if len(args) != 1:
+        raise ValueError(
+            f"{op!r} expects exactly 1 argument (sub-expression),"
+            f" got {len(args)}: {args!r}"
+        )
+    inner = compile_predicate(args[0])
+    return lambda node: not inner(node)
+
+
+def _compile_and(op: str, args: list) -> Callable[[Any], bool]:
+    """["and", expr, ...] → conjunction with short-circuit."""
+    if len(args) == 0:
+        raise ValueError(f"{op!r} expects at least 1 operand, got 0")
+    compiled = [compile_predicate(a) for a in args]
+    return lambda node: all(p(node) for p in compiled)
+
+
+def _compile_or(op: str, args: list) -> Callable[[Any], bool]:
+    """["or", expr, ...] → disjunction with short-circuit."""
+    if len(args) == 0:
+        raise ValueError(f"{op!r} expects at least 1 operand, got 0")
+    compiled = [compile_predicate(a) for a in args]
+    return lambda node: any(p(node) for p in compiled)
+
+
+# -- Dispatch table -----------------------------------------------------------
+# Adding a new operator: one entry here + one handler above.
+
+_OPERATORS: dict[str, Callable[[str, list], Callable[[Any], bool]]] = {
+    "property": _compile_property,
+    "not": _compile_not,
+    "and": _compile_and,
+    "or": _compile_or,
+}