tq-query 0.1.0__tar.gz

tq_query-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --locked --extra cli
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q

tq_query-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - run: uv sync --locked --extra cli
+      - name: Check tag matches package version
+        run: |
+          uv run python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          expected = f"v{version}"
+          actual = os.environ["GITHUB_REF_NAME"]
+          if actual != expected:
+              raise SystemExit(f"tag {actual!r} does not match package version {expected!r}")
+          PY
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tq-query
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

tq_query-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/

tq_query-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: tq-query
+Version: 0.1.0
+Summary: Query arrays of structured data
+License: Apache-2.0
+Keywords: arrays,json,query
+Requires-Python: >=3.11
+Provides-Extra: cli
+Requires-Dist: rich<15,>=13.7; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# tq
+
+`tq` is a small Python package and CLI for querying JSON records.
+
+It reads JSON Lines, JSON arrays, multiline objects, and consecutive JSON objects from a file or stdin, and writes matching records as JSON.
+
+## Get started
+
+Install the Python library only:
+
+```sh
+pip install tq-query
+```
+
+Install the CLI and its optional dependencies:
+
+```sh
+pip install "tq-query[cli]"
+# or: uv tool install "tq-query[cli]"
+```
+
+The `tq` command requires the `cli` extra; without it, the command prints an install hint.
+
+To try `tq` with OpenRouter model data from models.dev, download the catalog and convert it to `models.jsonl`:
+
+```sh
+curl -fsSL https://models.dev/catalog.json \
+  | jq '.providers.openrouter.models[] | {id, modalities, limit, reasoning, tool_call}' -c \
+  > models.jsonl
+```
+
+Each line is one model record. Query by identity or fields:
+
+```sh
+tq 'openai/*[reasoning;tool_call]' models.jsonl
+tq '[limit.context>=200000]' models.jsonl
+tq '[modalities.input has image]' models.jsonl
+tq '[modalities.input has all (text,image)]' models.jsonl
+```
+
+## CLI
+
+```text
+usage: tq [OPTIONS] QUERY [FILE]
+
+Arguments:
+  query                 match expression
+  file                  JSON input file; defaults to stdin
+
+Options:
+  -h, --help            show this help message and exit
+  -k KEY                identity field (default: ref, then id)
+  -r, --reorder         order matches by query branch, then input position
+  -C, --color           force colored output
+  -M, --no-color        force uncolored output
+  -c, --compact         compact JSON output, one record per line
+```
+
+Color is enabled for terminals and disabled for pipes. `-c` controls formatting independently.
+
+## Query syntax
+
+A query is a comma-separated list of branches. Each branch may combine an identity pattern with predicates:
+
+```text
+IDENTITY[PREDICATE;PREDICATE],IDENTITY[PREDICATE]
+```
+
+Omit the identity to match any record. Branches are OR-ed; predicates within a branch are AND-ed and may be separated by commas or semicolons.
+
+| Syntax | Meaning |
+| --- | --- |
+| `foo*` / `foo?` | Identity glob: `*` matches any sequence; `?` matches one character |
+| `"foo*"` | Exact identity; wildcards are literal |
+| `f` / `!f` | `f = true` / `f = false` |
+| `f = v` / `f != v` | Equal / not equal |
+| `f < v`, `f <= v`, `f > v`, `f >= v` | Ordered comparison |
+| `f has v` / `f has no v` | Array contains / does not contain `v` |
+| `f has any (a,b)` | Array contains at least one candidate |
+| `f has all (a,b)` | Array contains every candidate |
+| `f has none (a,b)` | Array contains no candidate |
+| `v in f` / `v not in f` | Aliases for `f has v` / `f has no v` |
+| `a.b.c` | Access a nested field |
+
+`has any`, `has all`, and `has none` require at least two candidates.
+
+Quote values when needed; for example, `"true"` is the text value `true`. Missing fields never match a predicate, including negative predicates. Explicit `null` is distinct from a missing field.
+
+## Python API
+
+```python
+from tq import Query
+
+schema = {"key": "id", "filter": ["reasoning", "tool_call"]}
+query = Query.parse("openai/*[reasoning;tool_call]").validate(schema)
+
+record = {
+    "id": "openai/gpt-5",
+    "reasoning": True,
+    "tool_call": True,
+}
+
+branch = query.match(record)
+```
+
+## Publishing
+
+See [PUBLISHING.md](PUBLISHING.md) for PyPI Trusted Publishing setup and release instructions.

tq_query-0.1.0/PUBLISHING.md

@@ -0,0 +1,27 @@
+# Publishing
+
+The `publish.yml` workflow publishes `tq-query` to PyPI when a `v*` version tag is pushed. It verifies that the tag matches the version in `pyproject.toml`, runs checks and tests, builds the wheel and source distribution, then publishes them using PyPI Trusted Publishing (OIDC). No PyPI token is stored in GitHub.
+
+## One-time PyPI setup
+
+Configure a Trusted Publisher for `tq-query` with:
+
+- Owner: `briceyan`
+- Repository: `tq`
+- Workflow: `publish.yml`
+- Environment: `pypi`
+
+If the project has not been published before, configure it as a pending publisher when creating the PyPI project.
+
+## Release a version
+
+1. Update `project.version` in `pyproject.toml` and refresh `uv.lock` with `uv lock`.
+2. Run the CI checks and commit the changes to `main`.
+3. Create and push a matching version tag, for example:
+
+   ```sh
+   git tag v0.1.1
+   git push origin v0.1.1
+   ```
+
+The tag push starts the publish workflow. A GitHub Release is not required.

tq_query-0.1.0/README.md

@@ -0,0 +1,108 @@
+# tq
+
+`tq` is a small Python package and CLI for querying JSON records.
+
+It reads JSON Lines, JSON arrays, multiline objects, and consecutive JSON objects from a file or stdin, and writes matching records as JSON.
+
+## Get started
+
+Install the Python library only:
+
+```sh
+pip install tq-query
+```
+
+Install the CLI and its optional dependencies:
+
+```sh
+pip install "tq-query[cli]"
+# or: uv tool install "tq-query[cli]"
+```
+
+The `tq` command requires the `cli` extra; without it, the command prints an install hint.
+
+To try `tq` with OpenRouter model data from models.dev, download the catalog and convert it to `models.jsonl`:
+
+```sh
+curl -fsSL https://models.dev/catalog.json \
+  | jq '.providers.openrouter.models[] | {id, modalities, limit, reasoning, tool_call}' -c \
+  > models.jsonl
+```
+
+Each line is one model record. Query by identity or fields:
+
+```sh
+tq 'openai/*[reasoning;tool_call]' models.jsonl
+tq '[limit.context>=200000]' models.jsonl
+tq '[modalities.input has image]' models.jsonl
+tq '[modalities.input has all (text,image)]' models.jsonl
+```
+
+## CLI
+
+```text
+usage: tq [OPTIONS] QUERY [FILE]
+
+Arguments:
+  query                 match expression
+  file                  JSON input file; defaults to stdin
+
+Options:
+  -h, --help            show this help message and exit
+  -k KEY                identity field (default: ref, then id)
+  -r, --reorder         order matches by query branch, then input position
+  -C, --color           force colored output
+  -M, --no-color        force uncolored output
+  -c, --compact         compact JSON output, one record per line
+```
+
+Color is enabled for terminals and disabled for pipes. `-c` controls formatting independently.
+
+## Query syntax
+
+A query is a comma-separated list of branches. Each branch may combine an identity pattern with predicates:
+
+```text
+IDENTITY[PREDICATE;PREDICATE],IDENTITY[PREDICATE]
+```
+
+Omit the identity to match any record. Branches are OR-ed; predicates within a branch are AND-ed and may be separated by commas or semicolons.
+
+| Syntax | Meaning |
+| --- | --- |
+| `foo*` / `foo?` | Identity glob: `*` matches any sequence; `?` matches one character |
+| `"foo*"` | Exact identity; wildcards are literal |
+| `f` / `!f` | `f = true` / `f = false` |
+| `f = v` / `f != v` | Equal / not equal |
+| `f < v`, `f <= v`, `f > v`, `f >= v` | Ordered comparison |
+| `f has v` / `f has no v` | Array contains / does not contain `v` |
+| `f has any (a,b)` | Array contains at least one candidate |
+| `f has all (a,b)` | Array contains every candidate |
+| `f has none (a,b)` | Array contains no candidate |
+| `v in f` / `v not in f` | Aliases for `f has v` / `f has no v` |
+| `a.b.c` | Access a nested field |
+
+`has any`, `has all`, and `has none` require at least two candidates.
+
+Quote values when needed; for example, `"true"` is the text value `true`. Missing fields never match a predicate, including negative predicates. Explicit `null` is distinct from a missing field.
+
+## Python API
+
+```python
+from tq import Query
+
+schema = {"key": "id", "filter": ["reasoning", "tool_call"]}
+query = Query.parse("openai/*[reasoning;tool_call]").validate(schema)
+
+record = {
+    "id": "openai/gpt-5",
+    "reasoning": True,
+    "tool_call": True,
+}
+
+branch = query.match(record)
+```
+
+## Publishing
+
+See [PUBLISHING.md](PUBLISHING.md) for PyPI Trusted Publishing setup and release instructions.

tq_query-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tq-query"
+version = "0.1.0"
+description = "Query arrays of structured data"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+keywords = ["query", "json", "arrays"]
+dependencies = []
+
+[project.optional-dependencies]
+cli = ["rich>=13.7,<15"]
+
+[project.scripts]
+tq = "tq.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tq"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.16.9",
+]

tq_query-0.1.0/src/tq/__init__.py

@@ -0,0 +1,5 @@
+"""Public API for parsing, validating, and matching tq queries."""
+
+from .query import Field, Match, Predicate, Query, QueryError
+
+__all__ = ["Field", "Match", "Predicate", "Query", "QueryError"]

tq_query-0.1.0/src/tq/__main__.py

@@ -0,0 +1,5 @@
+"""Run tq as ``python -m tq``."""
+
+from .cli import main
+
+raise SystemExit(main())

tq_query-0.1.0/src/tq/cli.py

@@ -0,0 +1,135 @@
+"""CLI for matching JSON records and rendering results."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from .query import Query, QueryError
+
+
+def _read_records(source: str) -> list[Mapping[str, Any]]:
+    decoder = json.JSONDecoder()
+    records: list[Mapping[str, Any]] = []
+    position = 0
+    while position < len(source):
+        while position < len(source) and source[position].isspace():
+            position += 1
+        if position == len(source):
+            break
+        try:
+            value, position = decoder.raw_decode(source, position)
+        except json.JSONDecodeError as error:
+            line = source.count("\n", 0, error.pos) + 1
+            raise QueryError(f"invalid JSON near line {line}: {error.msg}") from error
+        for record in value if isinstance(value, list) else (value,):
+            if not isinstance(record, Mapping):
+                raise QueryError("input records must be JSON objects")
+            records.append(record)
+    return records
+
+
+def _infer_key(records: Sequence[Mapping[str, Any]], explicit: str | None) -> str:
+    if explicit:
+        return explicit
+    for candidate in ("ref", "id"):
+        if any(candidate in record for record in records):
+            return candidate
+    raise QueryError("cannot infer key field; provide -k KEY")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Filter JSON records with tq match union syntax",
+        usage="tq [-h] [-k KEY] [-r] [-C | -M] [-c] query [file]",
+    )
+    parser.add_argument("query", metavar="query", help="match union expression")
+    parser.add_argument(
+        "file", nargs="?", metavar="file", help="JSON input file; defaults to stdin"
+    )
+    parser.add_argument(
+        "-k",
+        "--key",
+        metavar="KEY",
+        dest="key",
+        help="record key field (default: ref, then id)",
+    )
+    parser.add_argument(
+        "-r",
+        "--reorder",
+        action="store_true",
+        help="order matches by query branch, then input position",
+    )
+    parser.add_argument(
+        "-c",
+        "--compact",
+        action="store_true",
+        help="compact output to one line per record",
+    )
+    colors = parser.add_mutually_exclusive_group()
+    colors.add_argument(
+        "-C",
+        "--color",
+        action="store_true",
+        help="force color even when output is piped",
+    )
+    colors.add_argument(
+        "-M", "--no-color", action="store_true", help="force plain output"
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Filter records and render each result as JSON."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        from rich.console import Console
+        from rich.json import JSON
+    except ModuleNotFoundError:
+        parser.error("the CLI requires the optional extra; install `tq-query[cli]`")
+    try:
+        source = (
+            Path(args.file).read_text(encoding="utf-8")
+            if args.file
+            else sys.stdin.read()
+        )
+        records = _read_records(source)
+        query = Query.parse(args.query)
+        key = _infer_key(records, args.key)
+        matched = [
+            (index, branch)
+            for index, item in enumerate(records)
+            if (branch := query.match(item, key=key)) is not None
+        ]
+        if args.reorder:
+            matched.sort(key=lambda result: (result[1], result[0]))
+
+        is_terminal = bool(getattr(sys.stdout, "isatty", lambda: False)())
+        color_enabled = args.color or (
+            is_terminal and not args.no_color and "NO_COLOR" not in os.environ
+        )
+        console = Console(
+            file=sys.stdout,
+            force_terminal=color_enabled,
+            no_color=not color_enabled,
+            color_system="standard" if color_enabled else None,
+            width=100_000,
+        )
+        for item_index, _branch in matched:
+            record = records[item_index]
+            if args.compact:
+                compact = json.dumps(record, ensure_ascii=False, separators=(",", ":"))
+                console.print(
+                    JSON(compact, indent=None, ensure_ascii=False), soft_wrap=True
+                )
+            else:
+                console.print(JSON.from_data(record, indent=2, ensure_ascii=False))
+    except (OSError, QueryError, TypeError, ValueError) as error:
+        parser.error(str(error))
+    return 0