parq-cli 0.2.0__tar.gz → 0.2.2__tar.gz

parq_cli-0.2.2/.claude/settings.json

@@ -0,0 +1,6 @@
+{
+  "env": {
+    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1"
+  },
+  "enabledPlugins": {}
+}

{parq_cli-0.2.0 → parq_cli-0.2.2}/.github/workflows/publish.yml

@@ -35,8 +35,6 @@ jobs:
   build-and-publish:
     needs: pre-publish-tests
     runs-on: ubuntu-latest
-    permissions:
-      id-token: write
 
     steps:
       - name: 📥 Checkout code
@@ -68,10 +66,17 @@ jobs:
           path: dist/*
 
       - name: 🚀 Publish to PyPI
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
-        run: twine upload dist/*
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: ⛔ Refuse publish outside a version tag
+        if: ${{ !startsWith(github.ref, 'refs/tags/v') }}
+        run: |
+          echo "Refusing to publish: PyPI uploads only run from a v* tag."
+          exit 1
 
   create-github-release:
     needs: build-and-publish
@@ -87,7 +92,7 @@ jobs:
           path: dist
 
       - name: 📝 Create GitHub Release
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v2
         with:
           files: dist/*
           generate_release_notes: true

{parq_cli-0.2.0 → parq_cli-0.2.2}/.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.10', '3.11', '3.12', '3.13']
     
     steps:
       - name: 📥 Checkout code

{parq_cli-0.2.0 → parq_cli-0.2.2}/.gitignore

@@ -210,3 +210,6 @@ project_document/
 .history/
 .worktrees/
 worktrees/
+
+# macOS
+.DS_Store

parq_cli-0.2.2/AGENTS.md

@@ -0,0 +1,15 @@
+# Project Agent Entrypoint
+
+This file is the cross-tool entrypoint for parq-cli.
+
+## Working Rules
+
+- parq-cli is a pure Python CLI package, not a full-stack or frontend project.
+- Keep Python on `>=3.10`.
+- Preserve Typer command contracts, rich/plain/json output modes, and streaming behavior for large CSV/XLSX workflows.
+
+## Execution Style
+
+- Read `parq/cli.py`, `parq/reader.py`, relevant `parq/formats/*`, output formatters, and tests before editing.
+- Keep changes small and covered by CLI/reader/output tests.
+- Run focused tests first, then the repository verification gate: `pytest -m "not performance"` and `ruff check parq tests`.

parq_cli-0.2.2/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.2.2
+
+- `merge --force` and `convert` now refuse an output path that is one of the inputs. Previously `--force` deleted that input before reading it.
+- XLSX workbook XML is parsed with `defusedxml` (added to the `xlsx` extra).
+- Table output escapes cell markup and summarizes binary values (#4).
+- Errors include the file path (#5).
+- Dependency security updates: certifi, urllib3, idna, pygments, cryptography, pyarrow.
+
+## 0.2.1
+
+- `diff` and `merge` honor the global `--delimiter` and `--sheet` options.
+- `.tsv` is a supported output format for `convert`, `split`, and `merge`.
+- XLSX `schema` still samples the first 1000 rows. Full reads widen a column when a later row does not fit that sample.
+- String cardinality and top values stay exact past 10,000 distinct values. Nulls are not counted as empty strings.
+- `diff` spills inputs larger than 100,000 rows per side into temporary files.
+- `split --record-count` progress stays indeterminate while the total is still unknown.
+- PyPI uploads run from a `v*` tag and use the repository `PYPI_API_TOKEN`.
+- XLSX reads use `python-calamine`. A full read parses the workbook once and reuses those rows.
+- CSV `convert` no longer counts every row before writing when a progress bar is shown.
+- `--output`, `--delimiter`, and `--sheet` work before a subcommand and on the subcommand. The value on the subcommand wins when both are set.
+
+## 0.2.0
+
+- Inspect, split, convert, diff, and merge Parquet, CSV, TSV, and XLSX files.

parq_cli-0.2.2/CLAUDE.md

@@ -0,0 +1,24 @@
+# Claude Project Entrypoint
+
+
+## Guardrails
+
+- parq-cli is a Python command-line tool for Parquet, CSV, TSV, and XLSX files.
+- There is no frontend layer.
+- Package baseline is Python `>=3.10`.
+- Default tests exclude performance scenarios; run performance tests only when relevant.
+- Keep `parq` CLI output stable for automation, especially `plain` and `json` output modes.
+
+## Commands
+
+```bash
+pytest -m "not performance"
+ruff check parq tests
+pytest tests/test_performance.py -m performance -q -s
+```
+
+## Gotchas
+
+- `parq schema` on XLSX samples the first 1000 rows. Full reads parse the sheet once with python-calamine and widen a column when a later value does not fit. Writing XLSX still uses openpyxl.
+- `diff` and `merge` use the global `--delimiter` and `--sheet`. `diff` keeps at most 100,000 rows per side in memory, then spills to temporary files.
+- `.tsv` is valid for both input and output. Output uses a tab delimiter.

{parq_cli-0.2.0 → parq_cli-0.2.2}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: parq-cli
-Version: 0.2.0
-Summary: A powerful command-line tool for inspecting tabular files like Parquet, CSV, and XLSX
+Version: 0.2.2
+Summary: A command-line tool for inspecting tabular files: Parquet, CSV, TSV, and XLSX
 Project-URL: Homepage, https://github.com/Tendo33/parq-cli
 Project-URL: Repository, https://github.com/Tendo33/parq-cli
 Project-URL: Issues, https://github.com/Tendo33/parq-cli/issues
@@ -14,12 +14,11 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: pyarrow>=18.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.15.0
@@ -27,16 +26,18 @@ Provides-Extra: dev
 Requires-Dist: build>=1.2.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: ruff>=0.7.0; extra == 'dev'
+Requires-Dist: ruff==0.14.0; extra == 'dev'
 Requires-Dist: twine>=5.1.0; extra == 'dev'
 Requires-Dist: vulture>=2.14; extra == 'dev'
 Provides-Extra: xlsx
+Requires-Dist: defusedxml>=0.7.1; extra == 'xlsx'
 Requires-Dist: openpyxl>=3.1.0; extra == 'xlsx'
+Requires-Dist: python-calamine>=0.8.0; extra == 'xlsx'
 Description-Content-Type: text/markdown
 
 # parq-cli
 
-[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 A command-line tool for inspecting, transforming, and comparing tabular files.
@@ -133,7 +134,7 @@ parq merge chunks/*.parquet merged.parquet --force         # overwrite if exists
 | `diff` | yes | yes | yes | no, convert first |
 | `merge` | yes | yes | yes | yes |
 
-`XLSX` support requires `openpyxl`. TSV files are auto-detected by the `.tsv` extension; a custom delimiter can be supplied with `--delimiter`.
+`XLSX` reads use `python-calamine` and writes use `openpyxl`; both install with `parq-cli[xlsx]`. Formula cells are read from Excel's cached value, so a formula Excel has not calculated comes back empty. TSV files are auto-detected by the `.tsv` extension; a custom delimiter can be supplied with `--delimiter`.
 
 ## Command Reference
 
@@ -200,8 +201,8 @@ Rules:
 - specify exactly one of `--file-count` or `--record-count`
 - output format is inferred from `--name-format`
 - by default, existing target files raise an error; use `--force` / `-F` to overwrite
-- in `--record-count` mode, CSV/XLSX now stream in a single pass instead of pre-counting the entire file
-- a live progress bar is shown during the split
+- in `--record-count` mode, CSV streams in one pass and the progress bar stays indeterminate
+- XLSX is parsed once before writing; the record-count progress bar stays indeterminate
 
 ### `stats`
 
@@ -218,6 +219,8 @@ Computes simple per-column statistics.
 - string, boolean, and date columns additionally include `cardinality` and `top_values` (top N most frequent values with their occurrence counts)
 - default `--top-n` is `5`; set to `0` to suppress top-values output entirely
 - default `--limit` is `50` to avoid flooding the terminal on very wide tables
+- cardinality and top values are exact, including columns with more than 10,000 distinct values
+- nulls stay in `null_count` and are not treated as empty strings
 
 ### `convert`
 
@@ -233,7 +236,7 @@ Notes:
 
 - current targets are `.parquet`, `.csv`, `.tsv`, and `.xlsx`
 - conversion is streaming-based where possible
-- a live progress bar is shown during the conversion
+- a live progress bar is shown during the conversion; CSV stays indeterminate because the row count is not known ahead of time
 - by default, existing output files raise an error; use `--force` / `-F` to overwrite
 
 ### `diff`
@@ -255,9 +258,11 @@ Compares two datasets by key and reports:
 Notes:
 
 - `--key` is required
-- `diff` currently supports Parquet and CSV inputs
+- `diff` currently supports Parquet, CSV, and TSV inputs
+- the global `--delimiter` applies to both CSV inputs
 - XLSX files should be converted first
 - duplicate keys on either side are treated as an error
+- inputs larger than 100,000 rows on a side spill into temporary files instead of holding every key in memory
 - `--summary-only` keeps the counts and omits sample payloads
 
 ### `merge`
@@ -274,19 +279,22 @@ Notes:
 
 - schemas must be identical or safely unifiable by Arrow
 - by default, existing output files raise an error; use `--force` / `-F` to overwrite
-- output format is inferred from the output suffix
+- output format is inferred from the output suffix, including `.tsv`
+- the global `--delimiter` and `--sheet` apply to every input
 - a live progress bar is shown during the merge
 
 ## Output Modes
 
 Global options:
 
-- `--version`, `-v`: show version information
+- `--version`, `-v`: show version information. Place this before the subcommand: `parq --version`
 - `--output`, `-o`: select output format (`rich` | `plain` | `json`)
 - `--delimiter`, `-d`: field delimiter for CSV/TSV input (default: `,`); `.tsv` files default to `\t` automatically
-- `--sheet`: XLSX sheet name or 0-based index to read (default: active sheet)
+- `--sheet`: XLSX sheet name or 0-based index to read (default: active sheet). A value made only of digits is an index, including a sheet whose name is `1` or `2`
 - `--help`: show command help
 
+`--output`, `--delimiter`, and `--sheet` work before the subcommand and on the subcommand. If you pass the same option in both places, the value on the subcommand wins. On `convert`, `--output` / `-o` still selects the display format; the destination file is the positional `OUTPUT` argument.
+
 Available output modes:
 
 - `rich`: human-friendly terminal rendering
@@ -309,9 +317,11 @@ On Windows terminals that cannot safely render emoji or extended characters, Ric
 
 - Parquet metadata, row counts, and previews use Arrow metadata and row-group shortcuts where available.
 - CSV `tail` uses a fixed-size column window instead of materializing every row as Python dicts.
-- CSV/XLSX `split --record-count` streams in one pass.
+- CSV `split --record-count` and CSV `convert` stream in one pass. Their progress bars stay indeterminate because the row count is not known ahead of time.
 - `meta --fast` is the best option when you need quick metadata from large CSV/XLSX inputs.
-- XLSX schema inference samples the first 1000 rows instead of scanning the entire sheet up front.
+- `parq schema` and a short `head` sample the first 1000 XLSX rows. `count`, `tail`, `stats`, `convert`, `split`, and `merge` parse the selected sheet once, widen a column when a later value does not fit that sample, and keep those rows in memory.
+- `split --record-count` keeps the progress bar indeterminate while it writes.
+- `diff` indexes at most 100,000 rows per side in memory, then hash-partitions larger inputs into temporary Parquet files.
 
 For repeated heavy workflows, converting large CSV/XLSX files to Parquet is still the best path for throughput.
 

{parq_cli-0.2.0 → parq_cli-0.2.2}/README.md

@@ -1,6 +1,6 @@
 # parq-cli
 
-[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 A command-line tool for inspecting, transforming, and comparing tabular files.
@@ -97,7 +97,7 @@ parq merge chunks/*.parquet merged.parquet --force         # overwrite if exists
 | `diff` | yes | yes | yes | no, convert first |
 | `merge` | yes | yes | yes | yes |
 
-`XLSX` support requires `openpyxl`. TSV files are auto-detected by the `.tsv` extension; a custom delimiter can be supplied with `--delimiter`.
+`XLSX` reads use `python-calamine` and writes use `openpyxl`; both install with `parq-cli[xlsx]`. Formula cells are read from Excel's cached value, so a formula Excel has not calculated comes back empty. TSV files are auto-detected by the `.tsv` extension; a custom delimiter can be supplied with `--delimiter`.
 
 ## Command Reference
 
@@ -164,8 +164,8 @@ Rules:
 - specify exactly one of `--file-count` or `--record-count`
 - output format is inferred from `--name-format`
 - by default, existing target files raise an error; use `--force` / `-F` to overwrite
-- in `--record-count` mode, CSV/XLSX now stream in a single pass instead of pre-counting the entire file
-- a live progress bar is shown during the split
+- in `--record-count` mode, CSV streams in one pass and the progress bar stays indeterminate
+- XLSX is parsed once before writing; the record-count progress bar stays indeterminate
 
 ### `stats`
 
@@ -182,6 +182,8 @@ Computes simple per-column statistics.
 - string, boolean, and date columns additionally include `cardinality` and `top_values` (top N most frequent values with their occurrence counts)
 - default `--top-n` is `5`; set to `0` to suppress top-values output entirely
 - default `--limit` is `50` to avoid flooding the terminal on very wide tables
+- cardinality and top values are exact, including columns with more than 10,000 distinct values
+- nulls stay in `null_count` and are not treated as empty strings
 
 ### `convert`
 
@@ -197,7 +199,7 @@ Notes:
 
 - current targets are `.parquet`, `.csv`, `.tsv`, and `.xlsx`
 - conversion is streaming-based where possible
-- a live progress bar is shown during the conversion
+- a live progress bar is shown during the conversion; CSV stays indeterminate because the row count is not known ahead of time
 - by default, existing output files raise an error; use `--force` / `-F` to overwrite
 
 ### `diff`
@@ -219,9 +221,11 @@ Compares two datasets by key and reports:
 Notes:
 
 - `--key` is required
-- `diff` currently supports Parquet and CSV inputs
+- `diff` currently supports Parquet, CSV, and TSV inputs
+- the global `--delimiter` applies to both CSV inputs
 - XLSX files should be converted first
 - duplicate keys on either side are treated as an error
+- inputs larger than 100,000 rows on a side spill into temporary files instead of holding every key in memory
 - `--summary-only` keeps the counts and omits sample payloads
 
 ### `merge`
@@ -238,19 +242,22 @@ Notes:
 
 - schemas must be identical or safely unifiable by Arrow
 - by default, existing output files raise an error; use `--force` / `-F` to overwrite
-- output format is inferred from the output suffix
+- output format is inferred from the output suffix, including `.tsv`
+- the global `--delimiter` and `--sheet` apply to every input
 - a live progress bar is shown during the merge
 
 ## Output Modes
 
 Global options:
 
-- `--version`, `-v`: show version information
+- `--version`, `-v`: show version information. Place this before the subcommand: `parq --version`
 - `--output`, `-o`: select output format (`rich` | `plain` | `json`)
 - `--delimiter`, `-d`: field delimiter for CSV/TSV input (default: `,`); `.tsv` files default to `\t` automatically
-- `--sheet`: XLSX sheet name or 0-based index to read (default: active sheet)
+- `--sheet`: XLSX sheet name or 0-based index to read (default: active sheet). A value made only of digits is an index, including a sheet whose name is `1` or `2`
 - `--help`: show command help
 
+`--output`, `--delimiter`, and `--sheet` work before the subcommand and on the subcommand. If you pass the same option in both places, the value on the subcommand wins. On `convert`, `--output` / `-o` still selects the display format; the destination file is the positional `OUTPUT` argument.
+
 Available output modes:
 
 - `rich`: human-friendly terminal rendering
@@ -273,9 +280,11 @@ On Windows terminals that cannot safely render emoji or extended characters, Ric
 
 - Parquet metadata, row counts, and previews use Arrow metadata and row-group shortcuts where available.
 - CSV `tail` uses a fixed-size column window instead of materializing every row as Python dicts.
-- CSV/XLSX `split --record-count` streams in one pass.
+- CSV `split --record-count` and CSV `convert` stream in one pass. Their progress bars stay indeterminate because the row count is not known ahead of time.
 - `meta --fast` is the best option when you need quick metadata from large CSV/XLSX inputs.
-- XLSX schema inference samples the first 1000 rows instead of scanning the entire sheet up front.
+- `parq schema` and a short `head` sample the first 1000 XLSX rows. `count`, `tail`, `stats`, `convert`, `split`, and `merge` parse the selected sheet once, widen a column when a later value does not fit that sample, and keep those rows in memory.
+- `split --record-count` keeps the progress bar indeterminate while it writes.
+- `diff` indexes at most 100,000 rows per side in memory, then hash-partitions larger inputs into temporary Parquet files.
 
 For repeated heavy workflows, converting large CSV/XLSX files to Parquet is still the best path for throughput.
 

{parq_cli-0.2.0 → parq_cli-0.2.2}/README_CN.md

@@ -1,6 +1,6 @@
 # parq-cli
 
-[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 一个用于查看、转换、对比和处理表格文件的命令行工具。
@@ -9,7 +9,7 @@
 
 ## 简介
 
-`parq` 面向日常最常见的表格文件操作，支持 `.parquet`、`.csv`、`.xlsx`：
+`parq` 面向日常最常见的表格文件操作，支持 `.parquet`、`.csv`、`.tsv`、`.xlsx`：
 
 - 查看元数据和 schema
 - 预览前几行或后几行
@@ -73,19 +73,19 @@ parq merge part-001.parquet part-002.parquet merged.parquet
 
 ## 支持的格式
 
-| 命令 | Parquet | CSV | XLSX |
-| --- | --- | --- | --- |
-| `meta` | 支持 | 支持 | 支持 |
-| `schema` | 支持 | 支持 | 支持 |
-| `head` / `tail` | 支持 | 支持 | 支持 |
-| `count` | 支持 | 支持 | 支持 |
-| `split` | 支持 | 支持 | 支持 |
-| `stats` | 支持 | 支持 | 支持 |
-| `convert` | 支持 | 支持 | 支持 |
-| `diff` | 支持 | 支持 | 先转换再对比 |
-| `merge` | 支持 | 支持 | 支持 |
+| 命令 | Parquet | CSV | TSV | XLSX |
+| --- | --- | --- | --- | --- |
+| `meta` | 支持 | 支持 | 支持 | 支持 |
+| `schema` | 支持 | 支持 | 支持 | 支持 |
+| `head` / `tail` | 支持 | 支持 | 支持 | 支持 |
+| `count` | 支持 | 支持 | 支持 | 支持 |
+| `split` | 支持 | 支持 | 支持 | 支持 |
+| `stats` | 支持 | 支持 | 支持 | 支持 |
+| `convert` | 支持 | 支持 | 支持 | 支持 |
+| `diff` | 支持 | 支持 | 支持 | 先转换再对比 |
+| `merge` | 支持 | 支持 | 支持 | 支持 |
 
-`XLSX` 依赖 `openpyxl`。
+`XLSX` 的读取使用 `python-calamine`，写出仍使用 `openpyxl`，两者都随 `parq-cli[xlsx]` 安装。公式单元格读取的是 Excel 已经算出的缓存值，没有缓存的公式会是空值。`.tsv` 按扩展名自动使用制表符；其它分隔符用 `--delimiter`。`--sheet` 选择 XLSX 工作表，对 `merge` 同样生效。
 
 ## 命令说明
 
@@ -149,9 +149,9 @@ parq split FILE --record-count 100000 -n "chunks/part-%03d.parquet"
 规则：
 
 - `--file-count` 与 `--record-count` 二选一
-- 输出格式由 `--name-format` 的后缀决定
-- 不会覆盖已存在的目标文件
-- 在 `--record-count` 模式下，CSV/XLSX 现在走单遍流式拆分，不再先整表计数
+- 输出格式由 `--name-format` 的后缀决定，包括 `.tsv`
+- 默认遇到已存在的目标文件会报错；`--force` / `-F` 会覆盖
+- 在 `--record-count` 模式下，CSV 单遍流式写出，进度条保持不确定状态。XLSX 会先把工作表解析进内存，写出时进度条同样保持不确定状态
 
 ### `stats`
 
@@ -164,7 +164,9 @@ parq stats FILE --limit 20
 计算按列汇总的轻量统计：
 
 - 数值列输出 `count`、`null_count`、`min`、`max`、`mean`
-- 非数值列输出 `count` 和 `null_count`
+- 字符串、布尔和时间列另外输出 `cardinality` 和 `top_values`
+- 默认 `--top-n` 是 `5`；设为 `0` 则不输出 top values
+- 不同值超过 1 万个时，基数和 top values 仍然是精确结果；空值只计入 `null_count`
 - 默认 `--limit 50`，避免宽表直接刷满终端
 
 ### `convert`
@@ -178,9 +180,9 @@ parq convert SOURCE OUTPUT --columns id,name,status
 
 说明：
 
-- 当前目标格式为 `.parquet`、`.csv`、`.xlsx`
+- 当前目标格式为 `.parquet`、`.csv`、`.tsv`、`.xlsx`
 - 能流式处理的路径会尽量流式处理
-- 若输出文件已存在，会直接报错，不会覆盖
+- 默认遇到已存在的输出文件会报错；`--force` / `-F` 会覆盖
 
 ### `diff`
 
@@ -201,9 +203,11 @@ parq diff LEFT RIGHT --key id --summary-only
 说明：
 
 - `--key` 必填
-- `diff` 当前仅支持 Parquet 和 CSV
+- `diff` 当前支持 Parquet、CSV 和 TSV
+- 全局 `--delimiter` 会同时用于左右两个 CSV 输入
 - XLSX 需要先转换
 - 任一侧若出现重复 key，会直接报错
+- 单侧超过 10 万行时，会把数据按主键散列到临时文件，而不是把全部 key 放进内存
 - `--summary-only` 只保留计数，不输出样本内容
 
 ### `merge`
@@ -218,17 +222,22 @@ parq merge chunks/*.parquet merged.parquet
 说明：
 
 - schema 必须一致，或能被 Arrow 安全统一
-- 不会覆盖已存在的输出文件
-- 输出格式由输出文件后缀决定
+- 默认遇到已存在的输出文件会报错；`--force` / `-F` 会覆盖
+- 输出格式由输出文件后缀决定，包括 `.tsv`
+- 全局 `--delimiter` 和 `--sheet` 会作用于每一个输入
 
 ## 输出模式
 
 全局选项：
 
-- `--version`, `-v`：显示版本号
-- `--output`, `-o`：选择输出格式
+- `--version`, `-v`：显示版本号。放在子命令前面：`parq --version`
+- `--output`, `-o`：选择输出格式（`rich` | `plain` | `json`）
+- `--delimiter`, `-d`：CSV/TSV 输入分隔符，默认 `,`；`.tsv` 会自动使用制表符
+- `--sheet`：XLSX 工作表名称或从 0 开始的序号，默认活动工作表。纯数字会按序号处理，名叫 `1` 或 `2` 的工作表也一样
 - `--help`：显示帮助
 
+`--output`、`--delimiter`、`--sheet` 可以写在子命令前面，也可以写在子命令上面。同一个选项两处都写时，子命令上的值生效。`convert` 的 `--output` / `-o` 仍然是显示格式，目标文件是位置参数 `OUTPUT`。
+
 可选输出模式：
 
 - `rich`：适合人在终端中阅读
@@ -249,9 +258,9 @@ parq diff left.parquet right.parquet --key id --summary-only --output json
 
 - Parquet 的元数据、行数和预览会优先利用 Arrow metadata 与 row group 能力。
 - CSV `tail` 使用固定大小列窗口，而不是把整份数据都转成 Python dict。
-- CSV/XLSX 的 `split --record-count` 走单遍流式处理。
+- CSV 的 `split --record-count` 和 `convert` 单遍流式处理，进度条保持不确定状态，因为行数要等这一遍结束才知道。
 - 对大 CSV/XLSX，`meta --fast` 是最快的元数据探查入口。
-- XLSX 的 schema 推断只采样前 1000 行，不再默认整表扫描。
+- `parq schema` 和较短的 `head` 对 XLSX 只采样前 1000 行。`count`、`tail`、`stats`、`convert`、`split`、`merge` 把选中的工作表解析一次，后续值放不进样本类型时放宽该列，并把这些行留在内存里复用。
 
 如果你会反复处理大文件，把 CSV/XLSX 先转成 Parquet 依然是吞吐量最好的路径。
 

{parq_cli-0.2.0 → parq_cli-0.2.2}/docs/QUICKSTART.md

@@ -5,7 +5,7 @@
 ### 1. 克隆项目
 
 ```bash
-git clone <your-repo-url>
+git clone https://github.com/Tendo33/parq-cli.git
 cd parq-cli
 ```
 
@@ -118,18 +118,15 @@ ruff check parq tests
 ruff check --fix parq tests
 ```
 
-### 类型检查（可选）
+### 检查门
 
-```bash
-pip install mypy
-mypy parq
-```
+仓库的检查门是 Ruff 和 pytest。当前没有配置 mypy，CI 也不运行它。
 
 ## 📋 常见问题
 
 ### Q: 如何处理大文件？
 
-A: Parquet 文件会尽量利用元数据和 row group 做更高效的读取；CSV 会按批次流式处理，XLSX 会按行增量处理，因此预览、计数和分割都不再需要先整表载入内存。对于超大数据集，Parquet 仍然会有更好的整体吞吐。
+A: Parquet 用文件元数据和 row group，不必先读完全部数据。CSV 按批次流式处理。XLSX 的 `schema` 和较短的 `head` 只采样前 1000 行；`count`、`tail`、`stats`、`convert`、`split`、`merge` 会把选中的工作表解析一次并放在内存里复用。反复处理大文件时，先转成 Parquet 吞吐更好。
 
 ### Q: 空文件会怎么处理？
 

{parq_cli-0.2.0 → parq_cli-0.2.2}/docs/RELEASE.md

@@ -83,7 +83,7 @@ python scripts/bump_version.py --version 0.1.1 --yes
 
 **检查步骤:**
 1. 查看 Actions 日志: https://github.com/Tendo33/parq-cli/actions
-2. 确认 PyPI token 配置正确 (Repository Settings → Secrets)
+2. 确认仓库 Secret `PYPI_API_TOKEN` 仍然有效
 3. 运行本地检查: `python scripts/check_version.py`
 
 ## 🎯 手动发布 (不推荐)
@@ -114,6 +114,10 @@ git push origin v0.1.2
 - **PyPI 页面:** https://pypi.org/project/parq-cli/
 - **GitHub Releases:** https://github.com/Tendo33/parq-cli/releases
 
+## PyPI 上传
+
+发布 job 在 `v*` tag 上使用仓库 Secret `PYPI_API_TOKEN` 上传。从普通分支手动运行会在上传前失败。GitHub 上已经有一个名为 `pypi` 的 environment，当前 workflow 不依赖它。
+
 ## 💡 最佳实践
 
 1. **发布前测试:** 始终运行 `./.venv/bin/pytest -m "not performance"` 确保测试通过
@@ -124,5 +128,5 @@ git push origin v0.1.2
 
 ---
 
-**上次更新:** 2025-11-17
+**上次更新:** 2026-10-10
 **维护者:** SimonSun (@Tendo33)

{parq_cli-0.2.0 → parq_cli-0.2.2}/parq/__init__.py

@@ -1,5 +1,5 @@
 """
-parq-cli: A powerful command-line tool for inspecting and analyzing Apache Parquet files.
+parq-cli: A command-line tool for inspecting Parquet, CSV, TSV, and XLSX files.
 """
 
 __author__ = "SimonSun"