jsonseek 0.1.0__py3-none-any.whl

jsonseek/__init__.py

@@ -0,0 +1,3 @@
+"""jsonseek - Query and patch JSON/JSONL files from the command line."""
+
+__version__ = "0.1.0"

jsonseek/cli.py

@@ -0,0 +1,162 @@
+import argparse
+import sys
+from typing import Any, List, Optional
+
+from . import commands
+from .detect import detect_file_kind
+from .errors import JsonseekError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="jsonseek", description="Query and patch JSON/JSONL files from the command line.")
+    parser.add_argument("--version", action="version", version="%(prog)s 0.1.0")
+
+    sub = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Common arguments helper
+    def add_common(p: argparse.ArgumentParser) -> None:
+        p.add_argument("file", help="Target JSON or JSONL file")
+        p.add_argument("--kind", choices=["json", "jsonl"], default=None, help="Force file kind (auto-detect by default)")
+        p.add_argument("--output", choices=["pretty", "json"], default="pretty", help="Output format")
+        p.add_argument("--backup", action="store_true", default=False, help="Create .bak backup before writing")
+        p.add_argument("--encoding", default=None, help="File encoding (auto-detect by default)")
+        p.add_argument("--dry-run", action="store_true", default=False, help="Preview changes without applying")
+        p.add_argument("--context", type=int, default=2, help="Lines of context around target line (JSONL only)")
+
+    # shape
+    shape_p = sub.add_parser("shape", help="Show structure/shape of the file")
+    add_common(shape_p)
+    shape_p.add_argument("--max-depth", type=int, default=None, help="Maximum depth to traverse")
+    shape_p.add_argument("--array-mode", choices=["sample", "full"], default="sample", help="Array traversal mode")
+    shape_p.add_argument("--sample-size", type=int, default=100, help="Number of records to sample for JSONL")
+
+    # fields
+    fields_p = sub.add_parser("fields", help="List fields and their types")
+    add_common(fields_p)
+    fields_p.add_argument("keyword", nargs="?", default=None, help="Filter fields by keyword")
+    fields_p.add_argument("--top", action="store_true", default=False, help="Show only top-level fields")
+
+    # ls
+    ls_p = sub.add_parser("ls", help="List children at a path")
+    add_common(ls_p)
+    ls_p.add_argument("path", nargs="?", default="", help="Path to list (default: root)")
+
+    # get
+    get_p = sub.add_parser("get", help="Get value at a path")
+    add_common(get_p)
+    get_p.add_argument("path", help="Path to retrieve")
+
+    # query
+    query_p = sub.add_parser("query", help="Search for keys or values")
+    add_common(query_p)
+    query_p.add_argument("term", help="Search term")
+    query_p.add_argument("--case-sensitive", action="store_true", default=False, help="Case-sensitive matching")
+    query_p.add_argument("--exact", action="store_true", default=False, help="Exact match only")
+    query_p.add_argument("--match-mode", choices=["key", "value", "both"], default="both", help="What to match against")
+    query_p.add_argument("--max-results", type=int, default=None, help="Limit number of results")
+    query_p.add_argument("--record-id-field", default=None, help="Field to use as record ID in JSONL output")
+    query_p.add_argument("--preview-field", default=None, help="Field to preview in JSONL output")
+
+    # add
+    add_p = sub.add_parser("add", help="Add a key/value to an object")
+    add_common(add_p)
+    add_p.add_argument("path", help="Target path")
+    add_p.add_argument("value", nargs="?", default=None, help="Value to add (JSON string or literal)")
+    add_p.add_argument("--create-missing", action="store_true", default=False, help="Create missing intermediate keys")
+    add_p.add_argument("--from-file", default=None, help="Read value from file")
+
+    # del
+    del_p = sub.add_parser("del", help="Delete a key or array element")
+    add_common(del_p)
+    del_p.add_argument("path", help="Target path to delete")
+    del_p.add_argument("-y", "--yes", action="store_true", help="Skip confirmation")
+
+    # set
+    set_p = sub.add_parser("set", help="Set a value at a path")
+    add_common(set_p)
+    set_p.add_argument("path", help="Target path")
+    set_p.add_argument("value", nargs="?", default=None, help="Value to set (JSON string or literal)")
+    set_p.add_argument("--create-missing", action="store_true", default=False, help="Create missing intermediate keys")
+    set_p.add_argument("--from-file", default=None, help="Read value from file")
+
+    # append
+    append_p = sub.add_parser("append", help="Append a value to an array or JSONL file")
+    add_common(append_p)
+    append_p.add_argument("path", help="Target array path (JSON) or value (JSONL)")
+    append_p.add_argument("value", nargs="?", default=None, help="Value to append (JSON only)")
+
+    # extract
+    extract_p = sub.add_parser("extract", help="Extract a path from multiple JSON files")
+    extract_p.add_argument("pattern", help="Glob pattern to match files (e.g. '*.json' or 'data/*.json')")
+    extract_p.add_argument("path", help="Path to extract from each file")
+    extract_p.add_argument("--output", choices=["pretty", "json"], default="pretty", help="Output format")
+    extract_p.add_argument("--kind", choices=["json", "jsonl"], default=None, help="Force file kind")
+    extract_p.add_argument("--include-missing", action="store_true", default=False, help="Include files where path is missing")
+
+    # extend
+    extend_p = sub.add_parser("extend", help="Extend an array with multiple values (JSON only)")
+    add_common(extend_p)
+    extend_p.add_argument("path", help="Target array path")
+    extend_p.add_argument("value", help="JSON array string to extend with")
+
+    # concat
+    concat_p = sub.add_parser("concat", help="Concatenate multiple JSON files into JSONL")
+    concat_p.add_argument("pattern", help="Glob pattern to match JSON files (e.g. '*.json' or 'data/*.json')")
+    concat_p.add_argument("--output-file", "-o", default=None, help="Output JSONL file (default: stdout)")
+    concat_p.add_argument("--encoding", default=None, help="File encoding (auto-detect by default)")
+    concat_p.add_argument("--no-sort", action="store_true", default=False, help="Preserve glob order instead of sorting by filename")
+
+    # cutline
+    cutline_p = sub.add_parser("cutline", help="Extract a specific line from a file")
+    cutline_p.add_argument("file", help="Target file")
+    cutline_p.add_argument("line", type=int, help="Line number to extract (1-indexed)")
+    cutline_p.add_argument("--encoding", default=None, help="File encoding")
+    cutline_p.add_argument("--save-temp", action="store_true", help="Save to temp file and return path")
+
+    # replaceline
+    replaceline_p = sub.add_parser("replaceline", help="Replace a line in a file")
+    replaceline_p.add_argument("file", help="Target file")
+    replaceline_p.add_argument("line", type=int, help="Line number (1-indexed)")
+    replaceline_p.add_argument("content", nargs='?', default=None, help="Content to insert")
+    replaceline_p.add_argument("--encoding", default=None, help="File encoding")
+    replaceline_p.add_argument("--from-file", default=None, help="Read content from file")
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return 1
+    return dispatch_command(args)
+
+
+def dispatch_command(args: argparse.Namespace) -> int:
+    command = args.command
+    handlers = {
+        "shape": commands.shape_cmd.handle_shape,
+        "fields": commands.fields_cmd.handle_fields,
+        "ls": commands.ls_cmd.handle_ls,
+        "get": commands.get_cmd.handle_get,
+        "query": commands.query_cmd.handle_query,
+        "add": commands.add_cmd.handle_add,
+        "del": commands.del_cmd.handle_del,
+        "set": commands.set_cmd.handle_set,
+        "append": commands.append_cmd.handle_append,
+        "extract": commands.extract_cmd.handle_extract,
+        "extend": commands.extend_cmd.handle_extend,
+        "concat": commands.concat_cmd.handle_concat,
+        "cutline": commands.cutline_cmd.handle_cutline,
+        "replaceline": commands.replaceline_cmd.handle_replaceline,
+    }
+    handler = handlers.get(command)
+    if handler is None:
+        print(f"Unknown command: {command}", file=sys.stderr)
+        return 1
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

jsonseek/commands/__init__.py

@@ -0,0 +1,14 @@
+from . import shape_cmd
+from . import fields_cmd
+from . import ls_cmd
+from . import get_cmd
+from . import query_cmd
+from . import add_cmd
+from . import del_cmd
+from . import set_cmd
+from . import append_cmd
+from . import extract_cmd
+from . import extend_cmd
+from . import concat_cmd
+from . import cutline_cmd
+from . import replaceline_cmd

jsonseek/commands/add_cmd.py

@@ -0,0 +1,148 @@
+from typing import Tuple, Any
+import argparse
+
+from ..detect import detect_file_kind
+from ..io.json_file import load_json_file, save_json_file
+from ..io.rewrite import rewrite_jsonl_file
+from ..io.jsonl_file import get_jsonl_record_by_index, get_line_context
+from ..path_parser import parse_path
+from ..patch.locator import resolve_parent_and_key, resolve_record_and_inner_path, resolve_value_at_path
+from ..patch.object_ops import apply_add_to_object
+from ..value_utils import coerce_input_value
+from ..formatters import format_patch_preview
+from ..errors import JsonseekError, PatchError, PathError
+from ..types import KeyToken, IndexToken
+
+
+def handle_add(args: argparse.Namespace) -> int:
+    try:
+        is_dry_run = getattr(args, "dry_run", False)
+        output = getattr(args, "output", "pretty")
+        enc = getattr(args, "encoding", None)
+        context = getattr(args, "context", 2)
+
+        # Get value from file or command line
+        if getattr(args, "from_file", None):
+            from ..io.encoding import resolve_encoding
+            file_enc = args.encoding or resolve_encoding(args.file, None)
+            with open(args.from_file, 'r', encoding=file_enc) as f:
+                raw = f.read().strip()
+            value = coerce_input_value(raw)
+        else:
+            value = coerce_input_value(args.value)
+
+        kind = detect_file_kind(args.file, kind_hint=getattr(args, "kind", None))
+
+        if kind == "jsonl":
+            record_index, inner_tokens = resolve_record_and_inner_path(args.path)
+            record = get_jsonl_record_by_index(args.file, record_index, encoding=enc)
+            target_line = record.line_number
+            before_context = get_line_context(args.file, target_line, context=context, encoding=enc)
+
+            if is_dry_run:
+                print(format_patch_preview(
+                    path=args.path,
+                    output=output,
+                    dry_run=True,
+                    jsonl_before=before_context,
+                    jsonl_target_line=target_line,
+                    operation="modified",
+                ))
+                return 0
+
+            rewrite_jsonl_file(
+                args.file,
+                transform_record=lambda rec: patch_jsonl_record_add(
+                    rec, record_index, inner_tokens, value, create_missing=getattr(args, "create_missing", False)
+                ),
+                backup=getattr(args, "backup", False),
+                encoding=enc,
+            )
+
+            after_context = get_line_context(args.file, target_line, context=context, encoding=enc)
+            print(format_patch_preview(
+                path=args.path,
+                output=output,
+                dry_run=False,
+                jsonl_before=before_context,
+                jsonl_after=after_context,
+                jsonl_target_line=target_line,
+                operation="modified",
+            ))
+        else:
+            data = load_json_file(args.file, encoding=enc)
+            try:
+                before_value = resolve_value_at_path(data, parse_path(args.path))
+            except PathError:
+                before_value = "<not found>"
+
+            if is_dry_run:
+                print(format_patch_preview(
+                    path=args.path,
+                    before=before_value,
+                    after=value,
+                    output=output,
+                    dry_run=True,
+                ))
+                return 0
+
+            patched = patch_json_add(data, args.path, value, create_missing=getattr(args, "create_missing", False))
+            save_json_file(args.file, patched, backup=getattr(args, "backup", False), encoding=enc or "utf-8")
+
+            try:
+                after_value = resolve_value_at_path(patched, parse_path(args.path))
+            except PathError:
+                after_value = "<not found>"
+
+            print(format_patch_preview(
+                path=args.path,
+                before=before_value,
+                after=after_value,
+                output=output,
+                dry_run=False,
+            ))
+        return 0
+    except (JsonseekError, PatchError) as e:
+        print(f"Error: {e}", file=__import__("sys").stderr)
+        return 1
+
+
+def patch_json_add(data: Any, target_path: str, value: Any, create_missing: bool = False) -> Any:
+    tokens = parse_path(target_path)
+    parent, last_token = resolve_parent_and_key(data, tokens)
+    if isinstance(last_token, KeyToken):
+        if not isinstance(parent, dict):
+            raise PatchError(f"Expected object parent at {target_path}, got {type(parent).__name__}")
+        apply_add_to_object(parent, last_token.key, value, create_missing=create_missing)
+    else:
+        raise PatchError(f"Cannot add to array by index; use set or append: {target_path}")
+    return data
+
+
+def patch_jsonl_record_add(
+    record: Any, target_index: int, inner_tokens: list, value: Any, create_missing: bool = False
+) -> Tuple[bool, Any]:
+    from ..types import JsonlRecord
+    if not isinstance(record, JsonlRecord):
+        raise PatchError("Expected JsonlRecord")
+    if record.record_index != target_index:
+        return True, record.data
+    data = record.data
+    if not inner_tokens:
+        raise PatchError("Cannot add to root record; specify an inner path")
+    parent, last_token = resolve_parent_and_key(data, inner_tokens)
+    if isinstance(last_token, KeyToken):
+        if not isinstance(parent, dict):
+            raise PatchError(f"Expected object parent, got {type(parent).__name__}")
+        apply_add_to_object(parent, last_token.key, value, create_missing=create_missing)
+    else:
+        raise PatchError(f"Cannot add to array by index; use set or append")
+    return True, data
+
+
+def add_value(path: str, target_path: str, value: Any, create_missing: bool = False, encoding: str = "utf-8") -> None:
+    """Add a value at a path in a JSON file. Python API version."""
+    from ..io.json_file import load_json_file, save_json_file
+    data = load_json_file(path, encoding=encoding)
+    patched = patch_json_add(data, target_path, value, create_missing=create_missing)
+    save_json_file(path, patched, backup=False, encoding=encoding)

jsonseek/commands/append_cmd.py

@@ -0,0 +1,116 @@
+from typing import Any
+import argparse
+
+from ..detect import detect_file_kind
+from ..io.json_file import load_json_file, save_json_file
+from ..io.jsonl_file import append_jsonl_record, get_line_context
+from ..io.encoding import resolve_encoding
+from ..path_parser import parse_path
+from ..patch.locator import resolve_value_at_path
+from ..patch.array_ops import apply_append_to_array
+from ..value_utils import coerce_input_value
+from ..formatters import format_patch_preview
+from ..errors import JsonseekError, PatchError, PathError
+
+
+def handle_append(args: argparse.Namespace) -> int:
+    try:
+        is_dry_run = getattr(args, "dry_run", False)
+        output = getattr(args, "output", "pretty")
+        enc = getattr(args, "encoding", None)
+        context = getattr(args, "context", 2)
+
+        kind = detect_file_kind(args.file, kind_hint=getattr(args, "kind", None))
+
+        if kind == "jsonl":
+            # JSONL append: args.path is the value when args.value is omitted
+            raw_value = args.value if args.value is not None else args.path
+            value = coerce_input_value(raw_value)
+
+            # Get file end context
+            detected = resolve_encoding(args.file, enc)
+            with open(args.file, 'r', encoding=detected) as f:
+                total_lines = sum(1 for _ in f)
+            target_line = total_lines if total_lines > 0 else 1
+            before_context = get_line_context(args.file, target_line, context=context, encoding=enc)
+
+            if is_dry_run:
+                print(format_patch_preview(
+                    path=args.file,
+                    output=output,
+                    dry_run=True,
+                    jsonl_before=before_context,
+                    jsonl_target_line=target_line,
+                    operation="appended",
+                ))
+                return 0
+
+            append_jsonl_record(args.file, value, encoding=enc or "utf-8")
+
+            after_target_line = total_lines + 1
+            after_context = get_line_context(args.file, after_target_line, context=context, encoding=enc)
+            print(format_patch_preview(
+                path=args.file,
+                output=output,
+                dry_run=False,
+                jsonl_before=before_context,
+                jsonl_after=after_context,
+                jsonl_target_line=after_target_line,
+                operation="appended",
+            ))
+        else:
+            if args.value is None:
+                raise PatchError("append for JSON requires both path and value arguments")
+            value = coerce_input_value(args.value)
+            data = load_json_file(args.file, encoding=enc)
+            try:
+                before_value = resolve_value_at_path(data, parse_path(args.path))
+            except PathError:
+                before_value = "<not found>"
+
+            if is_dry_run:
+                print(format_patch_preview(
+                    path=args.path,
+                    before=before_value,
+                    after=value,
+                    output=output,
+                    dry_run=True,
+                ))
+                return 0
+
+            patched = patch_json_append(data, args.path, value)
+            save_json_file(args.file, patched, backup=getattr(args, "backup", False), encoding=enc or "utf-8")
+
+            try:
+                after_value = resolve_value_at_path(patched, parse_path(args.path))
+            except PathError:
+                after_value = "<not found>"
+
+            print(format_patch_preview(
+                path=args.path,
+                before=before_value,
+                after=after_value,
+                output=output,
+                dry_run=False,
+            ))
+        return 0
+    except (JsonseekError, PatchError) as e:
+        print(f"Error: {e}", file=__import__("sys").stderr)
+        return 1
+
+
+def patch_json_append(data: Any, target_path: str, value: Any) -> Any:
+    tokens = parse_path(target_path)
+    arr = resolve_value_at_path(data, tokens)
+    if not isinstance(arr, list):
+        raise PatchError(f"Expected array at {target_path}, got {type(arr).__name__}")
+    apply_append_to_array(arr, value)
+    return data
+
+
+def append_value(path: str, target_path: str, value: Any, encoding: str = "utf-8") -> None:
+    """Append a value to an array in a JSON file. Python API version."""
+    from ..io.json_file import load_json_file, save_json_file
+    data = load_json_file(path, encoding=encoding)
+    patched = patch_json_append(data, target_path, value)
+    save_json_file(path, patched, backup=False, encoding=encoding)

jsonseek/commands/concat_cmd.py

@@ -0,0 +1,73 @@
+import argparse
+import glob
+import json
+import os
+import shutil
+from typing import Any, List
+
+from ..errors import JsonseekError
+from ..io.encoding import resolve_encoding
+from ..io.json_file import load_json_file
+
+
+def handle_concat(args: argparse.Namespace) -> int:
+    try:
+        pattern = args.pattern
+        output_file = getattr(args, "output_file", None)
+        no_sort = getattr(args, "no_sort", False)
+
+        # Expand glob pattern
+        files = glob.glob(pattern, recursive=True)
+        if not no_sort:
+            files = sorted(files)
+        if not files:
+            if os.path.isfile(pattern):
+                files = [pattern]
+            else:
+                print(f"No files matched pattern: {pattern}", file=__import__("sys").stderr)
+                return 1
+
+        enc = getattr(args, "encoding", None)
+        lines: List[str] = []
+
+        for path in files:
+            try:
+                data = load_json_file(path, encoding=enc)
+                line = json.dumps(data, ensure_ascii=False)
+                lines.append(line)
+            except JsonseekError as e:
+                print(f"Error processing {path}: {e}", file=__import__("sys").stderr)
+                return 1
+
+        output = "\n".join(lines)
+        if output_file:
+            _write_file(output_file, output, enc or "utf-8")
+            print(f"Wrote {len(lines)} record(s) to {output_file}")
+        else:
+            print(output)
+
+        return 0
+    except JsonseekError as e:
+        print(f"Error: {e}", file=__import__("sys").stderr)
+        return 1
+
+
+def _write_file(path: str, content: str, encoding: str) -> None:
+    """Write content to a file atomically."""
+    temp_path = path + ".tmp"
+    try:
+        with open(temp_path, "w", encoding=encoding, newline="\n") as f:
+            f.write(content)
+            f.write("\n")
+        try:
+            os.replace(temp_path, path)
+        except PermissionError:
+            if os.name == "nt" and os.path.exists(path):
+                os.remove(path)
+                os.rename(temp_path, path)
+            else:
+                raise
+    except OSError as e:
+        if os.path.exists(temp_path):
+            os.remove(temp_path)
+        raise JsonseekError(f"Failed to write {path}: {e}")

jsonseek/commands/cutline_cmd.py

@@ -0,0 +1,45 @@
+import argparse
+from typing import Optional
+
+from ..io.encoding import resolve_encoding
+from ..errors import JsonseekError
+
+
+def handle_cutline(args: argparse.Namespace) -> int:
+    try:
+        line_number = args.line
+        path = args.file
+        enc = args.encoding or resolve_encoding(path, None)
+        
+        content = cut_line(path, line_number, enc)
+        
+        if args.save_temp:
+            import tempfile
+            import os
+            suffix = '.jsonline'
+            fd, tmp_path = tempfile.mkstemp(suffix=suffix, text=True)
+            with os.fdopen(fd, 'w', encoding=enc) as f:
+                f.write(content)
+            print(tmp_path)
+        else:
+            print(content)
+        return 0
+    except JsonseekError as e:
+        print(f"Error: {e}", file=__import__("sys").stderr)
+        return 1
+
+
+def cut_line(path: str, line_number: int, encoding: Optional[str] = None) -> str:
+    """Extract a specific line from a file (1-indexed)."""
+    enc = encoding or resolve_encoding(path, None)
+    try:
+        with open(path, "r", encoding=enc) as f:
+            for i, line in enumerate(f, 1):
+                if i == line_number:
+                    return line.rstrip('\n\r')
+    except FileNotFoundError:
+        raise JsonseekError(f"File not found: {path}")
+    except OSError as e:
+        raise JsonseekError(f"Failed to read {path}: {e}")
+    
+    raise JsonseekError(f"Line {line_number} not found in {path}")