pqx 0.1.0__tar.gz

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

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+    tags: ["v*"]   # a release tag runs the full matrix alongside publish.yml
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools-scm needs the tags and history
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check pqx tests
+      - name: Test
+        run: pytest -v
+
+  package:
+    name: build and install the package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools-scm needs the tags and history
+      - uses: astral-sh/setup-uv@v6
+      - name: Build sdist and wheel
+        env:
+          UV_PYTHON: "3.12"
+        run: uv build
+      - name: Install the wheel in a clean environment and run it
+        run: |
+          uv venv /tmp/pqx-wheel --python 3.12
+          uv pip install --python /tmp/pqx-wheel dist/*.whl
+          /tmp/pqx-wheel/bin/pqx --version
+          /tmp/pqx-wheel/bin/python -c "import pqx, importlib.resources as r; assert pqx.__version__ != '0.0.0.dev0'; assert (r.files('pqx') / 'app.tcss').is_file()"

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

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+# Publishing a GitHub Release (which creates its vX.Y.Z tag) builds pqx and
+# uploads it to PyPI; setuptools-scm takes the version from that tag. The same
+# tag also runs the full test matrix (ci.yml).
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write   # OIDC for PyPI trusted publishing: no API token stored
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools-scm needs full history
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build package
+        env:
+          UV_PYTHON: "3.12"
+        run: uv build
+
+      - name: Check the version matches the release tag
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          ls dist
+          test -f "dist/pqx-${tag}-py3-none-any.whl" || { echo "built version != tag ${GITHUB_REF_NAME}"; exit 1; }
+
+      - name: Publish to PyPI (trusted publishing)
+        run: uv publish --trusted-publishing always

pqx-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+.venv/
+__pycache__/
+*.egg-info/
+*.parquet
+!tests/data/*.parquet
+.pytest_cache/
+# setuptools-scm generated version file
+pqx/_version.py
+# build output (uv build / pip wheel)
+build/
+dist/
+# Textual debug input log (TEXTUAL_DEBUG=1 writes it to the current directory)
+keys.log
+# coverage
+.coverage
+.coverage.*
+htmlcov/
+# OS and editor files
+.DS_Store
+*.swp
+*~
+.idea/
+.vscode/

pqx-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: pqx
+Version: 0.1.0
+Summary: A fast, friendly terminal explorer for Parquet files (Textual + DuckDB)
+Author: Mario Juric
+License: BSD-3-Clause
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: textual>=1.0
+Requires-Dist: duckdb>=1.1
+Requires-Dist: pyarrow>=14
+Requires-Dist: numpy>=1.23
+Requires-Dist: pytz
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# pqx — a terminal explorer for Parquet files
+
+`pqx` is an interactive, keyboard-driven terminal UI for looking inside
+Parquet files: browse rows, filter with SQL, profile columns, draw sky maps and
+density plots, and export subsets. It is built for large LSST catalogs
+(SSSource, SSObject, DiaSource, …) but works with any single Parquet file.
+
+Nothing is loaded in full. The grid pulls small windows of rows, and every
+aggregate (counts, statistics, histograms, sky maps) runs inside
+[DuckDB](https://duckdb.org). A multi-GB file opens instantly, and jumping to
+row 3,000,000,000 costs one row-group read.
+
+```
+pip install -e .          # or: pip install -e ".[dev]" for tests
+pqx catalog.parquet
+pqx sssource.parquet --where "ssObjectId = 9000123"
+python -m pqx.demo demo.parquet --rows 1000000   # a synthetic LSST-like file to play with
+```
+
+## What you get
+
+| Tab | |
+|---|---|
+| **Data** | A fast, scrollable grid over the entire file. Headers show type and unit, and values use astronomy-aware formatting. **d** opens a detail panel with every column of the current row at full precision, plus derived readings: MJD → UTC date, RA/Dec → sexagesimal, errors in mas, flux → AB mag. |
+| **Schema** | Every column with its type, unit, description (from Parquet field metadata, including Felis-style `"[unit] description"`), null count, min/max from row-group statistics, compressed size, compression ratio and encodings. |
+| **Stats** | Pick a column to see count, nulls, NaNs, distinct values, min/max, mean/std and quantiles, with a histogram for numeric and time columns or a top-values bar chart for categorical ones. |
+| **Plot** | **Sky (Mollweide)** maps of any lon/lat pair, with RA/Dec auto-detected, and **density scatter** plots of any two numeric columns, both drawn in text with sub-character resolution and log-density colour. |
+| **Metadata** | File overview, row-group table and key-value metadata, with JSON shown pretty-printed. |
+
+The **filter bar** (press `/`) takes either
+
+* a SQL `WHERE` expression: `mag < 21 and band = 'r'`, `ssObjectId is not null`,
+  `ra between 10 and 20`; or
+* a full query over the table `t`: `select band, count(*), avg(mag) from t group by 1`.
+
+The filter applies everywhere: grid, stats, plots and export. Column names
+auto-complete (→ accepts), ↑/↓ recall history, and errors appear inline
+without losing the current view.
+
+## Keys
+
+| key | action |
+|---|---|
+| `/` · `x` / `Ctrl+X` | edit filter · clear filter (`Ctrl+X` also works while typing in the filter box) |
+| arrows, PgUp/PgDn, Ctrl+Home/End | move; the row window slides seamlessly |
+| `g` | go to row: `1234`, `1.5M`, `50%`, `-1` |
+| `s` | sort by the cursor column (asc → desc → off); clicking a header does the same |
+| `=` | narrow the filter to rows equal to the cursor cell |
+| `d` / Enter | row detail panel |
+| `c` · `-` · `p` | choose columns · hide column · pin columns |
+| Home / End | first / last column; `‹` `›` beside the header mark hidden columns (click to page) |
+| `f` · `y` · `i` | raw/smart formatting · copy cell · stats for column |
+| `1`–`5` · `Ctrl+←` `Ctrl+→` | go to a tab · previous / next tab. The strip in the panel border reads `1 Data ─ 2 Schema ─ … ^← ^→`; names underline under the mouse and switch on click |
+| `e` | export the current view (filter + sort + visible columns) to Parquet/CSV/JSON |
+| `m` | toggle sampling for stats and plots |
+| `l` `L` `[` `]` | Stats: log counts, log values, fewer/more bins |
+| click · `enter` | Plot: open a settings field's drop-down (type to narrow the column list) |
+| `tab` · `← →` | Plot: move between settings fields · step the field's value |
+| `r` | Plot: rotate the sky-map centre between RA 0° and 180° |
+| Esc | cancel running queries / leave the filter bar |
+| `?` · `q` | help · quit |
+
+## Look
+
+pqx draws with your terminal's own background and 16-colour palette, so it
+matches whatever scheme you use, and it looks the same with or without 24-bit
+colour. Panels are thin boxes, the focused one in the accent colour. Colour is
+kept for things that mean something: the file name and other object names are
+cyan, and status lines use ✓ (green) for done, ! (yellow) for warnings such as
+sampling, ✗ (red) for errors, and ⠸ while running. The style follows acid's CLI
+design language.
+
+| option | env | |
+|---|---|---|
+| `--accent blue\|cyan\|magenta\|green\|yellow` | `PQX_ACCENT` | focus colour (default blue) |
+| `--dim faint\|bright-black` | `PQX_DIM` | secondary text: the faint attribute (default), or ANSI bright black for terminals that ignore faint |
+| `--border NAME` | `PQX_BORDER` | unfocused panel border, an ANSI colour name (default `bright_black`) |
+| `--theme NAME` | | use a Textual theme instead of the terminal's colours |
+
+Sky maps and density plots default to **magma**; the colormaps (magma,
+viridis, inferno, plasma, gray) are emitted as exact xterm-256 colours, and
+`terminal` draws density with your palette alone (faint, accent, bold).
+
+## Large files
+
+* **Seeking.** When no filter or sort is active, a window is fetched with DuckDB's
+  `file_row_number` pushdown. Only the row group(s) holding the window are read,
+  so paging is O(1) in file size (about 20 ms per window on a 30M-row / 850 MB file).
+* **Filtered and sorted views** use `LIMIT/OFFSET` over the query. The total
+  row count is computed in the background, and the grid is usable before it
+  arrives.
+* **Cancellation.** A new filter, stats request or plot interrupts the
+  now-stale DuckDB query instead of letting it run to completion. Esc cancels
+  everything that's running.
+* **Sampling** (`m`, `--sample`) makes stats and plots read about 2M rows from
+  up to 16 evenly spaced row groups and skip the rest. It turns on
+  automatically for files over 200M rows or 8 GiB, and is worth enabling
+  whenever the storage is slow (network file systems, cold caches). Sampled
+  results are marked as such.
+* `--threads N` caps DuckDB's parallelism on shared machines.
+
+## Sky maps
+
+The Mollweide renderer is a port of the one in
+[acid](https://github.com/mjuric/acid) (`acid/io/skymap_art.py`), adapted to
+work from an equirectangular count grid, which DuckDB bins in a single
+`GROUP BY`, instead of a HEALPix map:
+
+* each character cell is inverse-projected, so rendering cost doesn't depend on row count;
+* **area** is carried by glyph shape: 2×2 quadrant sub-cells light up when at
+  least half of a sub-cell is covered, so partial coverage draws as partially
+  filled glyphs;
+* **density** is carried by colour: log surface density in deg⁻² through a
+  selectable colormap (magma by default; viridis, inferno, plasma, gray, or
+  `terminal`), with a colorbar legend;
+* the limb and graticule are a braille outline, and RA increases to the left.
+
+## Versions
+
+The version comes from git tags via [setuptools-scm](https://setuptools-scm.readthedocs.io/), as in
+acid: a tagged commit `vX.Y.Z` is version `X.Y.Z`, and anything after it is a dev version such as
+`0.2.dev3+g1a2b3c4`. `pqx --version` prints it.
+
+To release, publish a GitHub Release; creating it also creates the tag:
+
+```
+gh release create v0.2.0 --generate-notes
+```
+
+That runs `.github/workflows/publish.yml`, which builds the package with `uv build` and uploads it to
+PyPI with trusted publishing (OIDC, no stored token). The same tag runs the full test matrix in CI.
+One-time setup on PyPI: add a trusted publisher for project `pqx`: owner `mjuric`, repository `pqx`,
+workflow `publish.yml`, environment `pypi`.
+
+## Development
+
+```
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest          # data layer, formatting/plots, and headless UI tests (Textual pilot)
+```
+
+Layout: `pqx/data.py` (DuckDB/PyArrow access layer), `pqx/fmt.py`
+(astronomy-aware formatting), `pqx/plots.py` (text plots), `pqx/app.py` +
+`pqx/screens.py` + `pqx/app.tcss` (the Textual UI), `pqx/demo.py` (synthetic data).

pqx-0.1.0/README.md

@@ -0,0 +1,144 @@
+# pqx — a terminal explorer for Parquet files
+
+`pqx` is an interactive, keyboard-driven terminal UI for looking inside
+Parquet files: browse rows, filter with SQL, profile columns, draw sky maps and
+density plots, and export subsets. It is built for large LSST catalogs
+(SSSource, SSObject, DiaSource, …) but works with any single Parquet file.
+
+Nothing is loaded in full. The grid pulls small windows of rows, and every
+aggregate (counts, statistics, histograms, sky maps) runs inside
+[DuckDB](https://duckdb.org). A multi-GB file opens instantly, and jumping to
+row 3,000,000,000 costs one row-group read.
+
+```
+pip install -e .          # or: pip install -e ".[dev]" for tests
+pqx catalog.parquet
+pqx sssource.parquet --where "ssObjectId = 9000123"
+python -m pqx.demo demo.parquet --rows 1000000   # a synthetic LSST-like file to play with
+```
+
+## What you get
+
+| Tab | |
+|---|---|
+| **Data** | A fast, scrollable grid over the entire file. Headers show type and unit, and values use astronomy-aware formatting. **d** opens a detail panel with every column of the current row at full precision, plus derived readings: MJD → UTC date, RA/Dec → sexagesimal, errors in mas, flux → AB mag. |
+| **Schema** | Every column with its type, unit, description (from Parquet field metadata, including Felis-style `"[unit] description"`), null count, min/max from row-group statistics, compressed size, compression ratio and encodings. |
+| **Stats** | Pick a column to see count, nulls, NaNs, distinct values, min/max, mean/std and quantiles, with a histogram for numeric and time columns or a top-values bar chart for categorical ones. |
+| **Plot** | **Sky (Mollweide)** maps of any lon/lat pair, with RA/Dec auto-detected, and **density scatter** plots of any two numeric columns, both drawn in text with sub-character resolution and log-density colour. |
+| **Metadata** | File overview, row-group table and key-value metadata, with JSON shown pretty-printed. |
+
+The **filter bar** (press `/`) takes either
+
+* a SQL `WHERE` expression: `mag < 21 and band = 'r'`, `ssObjectId is not null`,
+  `ra between 10 and 20`; or
+* a full query over the table `t`: `select band, count(*), avg(mag) from t group by 1`.
+
+The filter applies everywhere: grid, stats, plots and export. Column names
+auto-complete (→ accepts), ↑/↓ recall history, and errors appear inline
+without losing the current view.
+
+## Keys
+
+| key | action |
+|---|---|
+| `/` · `x` / `Ctrl+X` | edit filter · clear filter (`Ctrl+X` also works while typing in the filter box) |
+| arrows, PgUp/PgDn, Ctrl+Home/End | move; the row window slides seamlessly |
+| `g` | go to row: `1234`, `1.5M`, `50%`, `-1` |
+| `s` | sort by the cursor column (asc → desc → off); clicking a header does the same |
+| `=` | narrow the filter to rows equal to the cursor cell |
+| `d` / Enter | row detail panel |
+| `c` · `-` · `p` | choose columns · hide column · pin columns |
+| Home / End | first / last column; `‹` `›` beside the header mark hidden columns (click to page) |
+| `f` · `y` · `i` | raw/smart formatting · copy cell · stats for column |
+| `1`–`5` · `Ctrl+←` `Ctrl+→` | go to a tab · previous / next tab. The strip in the panel border reads `1 Data ─ 2 Schema ─ … ^← ^→`; names underline under the mouse and switch on click |
+| `e` | export the current view (filter + sort + visible columns) to Parquet/CSV/JSON |
+| `m` | toggle sampling for stats and plots |
+| `l` `L` `[` `]` | Stats: log counts, log values, fewer/more bins |
+| click · `enter` | Plot: open a settings field's drop-down (type to narrow the column list) |
+| `tab` · `← →` | Plot: move between settings fields · step the field's value |
+| `r` | Plot: rotate the sky-map centre between RA 0° and 180° |
+| Esc | cancel running queries / leave the filter bar |
+| `?` · `q` | help · quit |
+
+## Look
+
+pqx draws with your terminal's own background and 16-colour palette, so it
+matches whatever scheme you use, and it looks the same with or without 24-bit
+colour. Panels are thin boxes, the focused one in the accent colour. Colour is
+kept for things that mean something: the file name and other object names are
+cyan, and status lines use ✓ (green) for done, ! (yellow) for warnings such as
+sampling, ✗ (red) for errors, and ⠸ while running. The style follows acid's CLI
+design language.
+
+| option | env | |
+|---|---|---|
+| `--accent blue\|cyan\|magenta\|green\|yellow` | `PQX_ACCENT` | focus colour (default blue) |
+| `--dim faint\|bright-black` | `PQX_DIM` | secondary text: the faint attribute (default), or ANSI bright black for terminals that ignore faint |
+| `--border NAME` | `PQX_BORDER` | unfocused panel border, an ANSI colour name (default `bright_black`) |
+| `--theme NAME` | | use a Textual theme instead of the terminal's colours |
+
+Sky maps and density plots default to **magma**; the colormaps (magma,
+viridis, inferno, plasma, gray) are emitted as exact xterm-256 colours, and
+`terminal` draws density with your palette alone (faint, accent, bold).
+
+## Large files
+
+* **Seeking.** When no filter or sort is active, a window is fetched with DuckDB's
+  `file_row_number` pushdown. Only the row group(s) holding the window are read,
+  so paging is O(1) in file size (about 20 ms per window on a 30M-row / 850 MB file).
+* **Filtered and sorted views** use `LIMIT/OFFSET` over the query. The total
+  row count is computed in the background, and the grid is usable before it
+  arrives.
+* **Cancellation.** A new filter, stats request or plot interrupts the
+  now-stale DuckDB query instead of letting it run to completion. Esc cancels
+  everything that's running.
+* **Sampling** (`m`, `--sample`) makes stats and plots read about 2M rows from
+  up to 16 evenly spaced row groups and skip the rest. It turns on
+  automatically for files over 200M rows or 8 GiB, and is worth enabling
+  whenever the storage is slow (network file systems, cold caches). Sampled
+  results are marked as such.
+* `--threads N` caps DuckDB's parallelism on shared machines.
+
+## Sky maps
+
+The Mollweide renderer is a port of the one in
+[acid](https://github.com/mjuric/acid) (`acid/io/skymap_art.py`), adapted to
+work from an equirectangular count grid, which DuckDB bins in a single
+`GROUP BY`, instead of a HEALPix map:
+
+* each character cell is inverse-projected, so rendering cost doesn't depend on row count;
+* **area** is carried by glyph shape: 2×2 quadrant sub-cells light up when at
+  least half of a sub-cell is covered, so partial coverage draws as partially
+  filled glyphs;
+* **density** is carried by colour: log surface density in deg⁻² through a
+  selectable colormap (magma by default; viridis, inferno, plasma, gray, or
+  `terminal`), with a colorbar legend;
+* the limb and graticule are a braille outline, and RA increases to the left.
+
+## Versions
+
+The version comes from git tags via [setuptools-scm](https://setuptools-scm.readthedocs.io/), as in
+acid: a tagged commit `vX.Y.Z` is version `X.Y.Z`, and anything after it is a dev version such as
+`0.2.dev3+g1a2b3c4`. `pqx --version` prints it.
+
+To release, publish a GitHub Release; creating it also creates the tag:
+
+```
+gh release create v0.2.0 --generate-notes
+```
+
+That runs `.github/workflows/publish.yml`, which builds the package with `uv build` and uploads it to
+PyPI with trusted publishing (OIDC, no stored token). The same tag runs the full test matrix in CI.
+One-time setup on PyPI: add a trusted publisher for project `pqx`: owner `mjuric`, repository `pqx`,
+workflow `publish.yml`, environment `pypi`.
+
+## Development
+
+```
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest          # data layer, formatting/plots, and headless UI tests (Textual pilot)
+```
+
+Layout: `pqx/data.py` (DuckDB/PyArrow access layer), `pqx/fmt.py`
+(astronomy-aware formatting), `pqx/plots.py` (text plots), `pqx/app.py` +
+`pqx/screens.py` + `pqx/app.tcss` (the Textual UI), `pqx/demo.py` (synthetic data).

pqx-0.1.0/pqx/__init__.py

@@ -0,0 +1,6 @@
+"""pqx — a fast, friendly terminal explorer for Parquet files."""
+
+try:  # written by setuptools-scm from the git tags at build/install time
+    from pqx._version import version as __version__
+except ImportError:  # a source checkout that was never built or installed
+    __version__ = "0.0.0.dev0"

pqx-0.1.0/pqx/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

pqx-0.1.0/pqx/_terminal.py

@@ -0,0 +1,122 @@
+"""Work-arounds for terminals and multiplexers that speak older mouse protocols.
+
+pqx asks for SGR mouse reporting (mode 1006), like every Textual app. Some
+multiplexers (GNU screen 4.x in particular) don't support SGR and hand the app
+X10-encoded events instead -- ``ESC [ M`` followed by three raw bytes -- or
+urxvt-encoded ones (``ESC [ b;x;y M``). Textual (as of 8.x) has two problems
+with that:
+
+* it only parses SGR mouse events, so X10/urxvt clicks are silently dropped;
+* it decodes terminal input as strict UTF-8, and an X10 coordinate above 95
+  is a byte > 127 that is not valid UTF-8: the input thread dies with
+  ``UnicodeDecodeError`` while the app keeps drawing -- it looks frozen.
+
+:func:`install` makes input decoding lenient (an invalid byte becomes the
+character with that code, which is exactly what an X10 coordinate means) and
+translates X10/urxvt mouse events into SGR before Textual parses them.
+
+It also keeps mouse coordinates in character cells. When a terminal says it
+supports in-band resize reports (mode 2048), Textual switches the mouse to
+pixel coordinates (mode 1016) and relies on those reports to convert back to
+cells. iTerm2 accepts 1016 but doesn't send the reports, so every click lands
+at a pixel position far off-screen and does nothing. Textual guards against
+this only when ``TERM_PROGRAM``/``LC_TERMINAL`` name iTerm, which they don't
+over ssh. pqx never needs sub-cell mouse precision, so pixel mode stays off.
+
+Finally, quitting always leaves a clean terminal. Textual draws on the
+alternate screen (mode 1049) and switches back on exit, which restores the
+shell's previous contents. Where the alternate screen is unavailable (some
+ssh/container setups, or a terminal or tmux with it turned off), pqx would
+have drawn over the normal screen and left its last frame behind, with the
+prompt in the middle of it. pqx clears the screen just before switching
+back: invisible when the alternate screen works, a clean screen when not.
+"""
+from __future__ import annotations
+
+import codecs
+import functools
+import re
+
+_ERRORS = "pqx-bytes"
+_X10 = re.compile(r"\x1b\[M(.)(.)(.)\Z", re.S)
+_URXVT = re.compile(r"\x1b\[(\d+);(\d+);(\d+)M\Z")
+_installed = False
+
+
+def _bytes_as_chars(err: UnicodeDecodeError):
+    return "".join(chr(b) for b in err.object[err.start:err.end]), err.end
+
+
+def x10_to_sgr(code: str, last_button: int = 0) -> tuple[str, int] | None:
+    """Translate an X10 or urxvt mouse sequence to SGR. Returns (sgr, last_button)."""
+    m = _X10.match(code)
+    if m:
+        b, x, y = (ord(c) - 32 for c in m.groups())
+    else:
+        m = _URXVT.match(code)
+        if not m:
+            return None
+        b, x, y = int(m.group(1)) - 32, int(m.group(2)), int(m.group(3))
+    if x < 1 or y < 1:
+        return None
+    if b & 64 or b & 32:  # wheel, or motion (with or without a button held)
+        return f"\x1b[<{b};{x};{y}M", last_button
+    if b & 3 == 3:  # X10 release doesn't say which button: use the one pressed last
+        return f"\x1b[<{last_button | (b & ~3)};{x};{y}m", last_button
+    return f"\x1b[<{b};{x};{y}M", b & 3
+
+
+def install() -> None:
+    """Patch Textual's input path (idempotent)."""
+    global _installed
+    if _installed:
+        return
+    _installed = True
+    try:
+        codecs.lookup_error(_ERRORS)
+    except LookupError:
+        codecs.register_error(_ERRORS, _bytes_as_chars)
+
+    try:
+        from textual.drivers import linux_driver
+
+        real = codecs.getincrementaldecoder
+
+        def lenient(encoding: str):
+            return functools.partial(real(encoding), errors=_ERRORS)
+
+        linux_driver.getincrementaldecoder = lenient
+    except Exception:  # pragma: no cover - other platforms / Textual versions
+        pass
+
+    try:
+        from textual.drivers.linux_driver import LinuxDriver
+
+        LinuxDriver._enable_mouse_pixels = lambda self: None  # cells, always (see above)
+
+        stop = LinuxDriver.stop_application_mode
+
+        @functools.wraps(stop)
+        def stop_application_mode(self):
+            self.write("\x1b[0m\x1b[H\x1b[2J")  # reset attributes, home, clear: before leaving 1049
+            stop(self)
+
+        LinuxDriver.stop_application_mode = stop_application_mode
+    except Exception:  # pragma: no cover
+        pass
+
+    try:
+        from textual._xterm_parser import XTermParser
+
+        original = XTermParser.parse_mouse_code
+
+        @functools.wraps(original)
+        def parse_mouse_code(self, code: str):
+            translated = x10_to_sgr(code, getattr(self, "_pqx_last_button", 0))
+            if translated is not None:
+                code, self._pqx_last_button = translated
+            return original(self, code)
+
+        XTermParser.parse_mouse_code = parse_mouse_code
+    except Exception:  # pragma: no cover
+        pass

pqx-0.1.0/pqx/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = 'g006519c4f'