tab-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{tab_cli-0.1.0 → tab_cli-0.1.2}/.gitignore

@@ -60,3 +60,9 @@ htmlcov/
 # Misc
 *.log
 .DS_Store
+
+# Generated assets
+docs/assets/
+
+# Claude
+.claude/

tab_cli-0.1.2/CHANGELOG.md

@@ -0,0 +1,5 @@
+ - 0.1.2:
+   - Bugfix on reading directories.
+ - 0.1.1:
+   - Better credential handling for Azure Blob Storage and Google Cloud Storage.
+ - 0.1.0: Initial release

tab_cli-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tongfei Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tab_cli-0.1.2/Makefile

@@ -0,0 +1,58 @@
+SHELL := /bin/bash
+
+.PHONY: install dev clean lint format test build mkdocs-build mkdocs-serve docs publish publish-test gh-deploy-docs
+
+install:
+	uv tool install . --force
+
+dev:
+	uv sync --dev
+
+clean:
+	rm -rf dist/ build/ *.egg-info .pytest_cache .mypy_cache .ruff_cache
+	find . -type d -name __pycache__ -exec rm -rf {} +
+
+lint:
+	uv run ruff check tab_cli/
+
+format:
+	uv run ruff format tab_cli/
+
+typecheck:
+	uv run ty check tab_cli/
+
+test:
+	uv run pytest
+
+build: clean
+	uv build
+
+mkdocs-build:
+	sh ./docs/gen_assets.sh
+	mkdocs build --strict
+
+mkdocs-serve:
+	mkdocs serve --dev-addr=127.0.0.1:8000
+
+docs: mkdocs-build
+
+publish: build
+	uv publish
+
+publish-test: build
+	uv publish --publish-url https://test.pypi.org/legacy/
+
+gh-deploy-docs: docs
+	set -ex ; \
+	WORK="$$( mktemp -d )" ; \
+	VER="$$( git describe --always --tags --dirty )" ; \
+	git worktree add --force "$$WORK" gh-pages ; \
+	rm -rf "$$WORK"/* ; \
+	rsync -av site/ "$$WORK"/ ; \
+	if [ -f CNAME ] ; then cp CNAME "$$WORK"/ ; fi ; \
+	pushd "$$WORK" ; \
+	git add -A ; \
+	git commit -m "Updated gh-pages $$VER" ; \
+	popd ; \
+	git worktree remove "$$WORK" ; \
+	git push origin gh-pages

tab_cli-0.1.2/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: tab-cli
+Version: 0.1.2
+Summary: A CLI tool for tabular data
+Author-email: Tongfei Chen <tongfei@pm.me>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: blobfile>=3.0
+Requires-Dist: fsspec>=2025.1.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: polars-fastavro>=0.5.1
+Requires-Dist: polars>=1.0
+Requires-Dist: pyarrow>=15.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.21.1
+Provides-Extra: azure
+Requires-Dist: adlfs>=2025.1.0; extra == 'azure'
+Requires-Dist: azure-identity>=1.10.0; extra == 'azure'
+Provides-Extra: gcs
+Requires-Dist: gcsfs>=2025.1.0; extra == 'gcs'
+Requires-Dist: google-auth>=2.27.0; extra == 'gcs'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.28.0; extra == 's3'
+Requires-Dist: s3fs>=2025.1.0; extra == 's3'
+Description-Content-Type: text/markdown
+
+# tab
+
+A CLI tool for viewing, querying, and converting tabular data files. Supports AWS / Azure / Google Cloud Storage URLs.

tab_cli-0.1.2/README.md

@@ -0,0 +1,3 @@
+# tab
+
+A CLI tool for viewing, querying, and converting tabular data files. Supports AWS / Azure / Google Cloud Storage URLs.

tab_cli-0.1.2/docs/cli-ref.md

@@ -0,0 +1,105 @@
+# CLI Reference
+
+## `tab view`
+
+View tabular data from a data file, or a directory of partitions of data files.
+
+```bash
+tab view $path [OPTIONS]
+```
+
+Options:
+
+| Option                  | Description                                                                                               |
+|-------------------------|-----------------------------------------------------------------------------------------------------------|
+| `-i` / `--input-format` | Input format (`parquet`, `csv`, `tsv`, `jsonl`, `avro`). Auto-detected from extension if omitted.         |
+| `-o` / `--output-format` | Output format (`parquet`, `csv`, `tsv`, `jsonl`, `avro`). If not specified, print Rich table in terminal. |
+| `--limit`               | Maximum number of rows to display.                                                                        |
+| `--skip`                | Number of rows to skip from the beginning.                                                                |
+
+## `tab schema`
+
+Display the schema of a tabular data file.
+
+```bash
+tab schema $path [OPTIONS]
+```
+
+Options:
+
+| Option                  | Description                                                                                               |
+|-------------------------|-----------------------------------------------------------------------------------------------------------|
+| `-i` / `--input-format` | Input format (`parquet`, `csv`, `tsv`, `jsonl`, `avro`). Auto-detected from extension if omitted.         |
+
+
+## `tab summary`
+
+Display summary information about a tabular data file.
+
+```bash
+tab summary $path [OPTIONS]
+```
+
+Options:
+
+| Option                  | Description                                                                                               |
+|-------------------------|-----------------------------------------------------------------------------------------------------------|
+| `-i` / `--input-format` | Input format (`parquet`, `csv`, `tsv`, `jsonl`, `avro`). Auto-detected from extension if omitted.         |
+
+
+## `tab sql`
+
+Run a SQL query on tabular data. The table is available as `t`.
+
+```bash
+tab sql $query $path [OPTIONS]
+```
+
+Options:
+
+| Option                  | Description                                                                                               |
+|-------------------------|-----------------------------------------------------------------------------------------------------------|
+| `-i` / `--input-format` | Input format (`parquet`, `csv`, `tsv`, `jsonl`, `avro`). Auto-detected from extension if omitted.         |
+| `-o` / `--output-format` | Output format (`parquet`, `csv`, `tsv`, `jsonl`, `avro`). If not specified, print Rich table in terminal. |
+| `--limit`               | Maximum number of rows to display.                                                                        |
+| `--skip`                | Number of rows to skip from the beginning.                                                                |
+
+## `tab convert`
+
+Convert tabular data from one format to another.
+
+```bash
+tab convert $src $dst [OPTIONS]
+```
+
+Options:
+
+| Option                  | Description                                                                                             |
+|-------------------------|---------------------------------------------------------------------------------------------------------|
+| `-i` / `--input-format` | Input format (`parquet`, `csv`, `tsv`, `jsonl`, `avro`). Auto-detected from extension if omitted.       |
+| `-o` / `--output-format` | Output format (`parquet`, `csv`, `tsv`, `jsonl`, `avro`). If not specified, inherits from input format. |
+| `-n` / `--num-partitions` | Number of output partitions. Creates a directory with partition files.                                  |
+
+
+## `tab cat`
+
+Concatenate tabular data from multiple files.
+
+```bash
+tab cat $paths [OPTIONS]
+```
+
+Options:
+
+| Option                  | Description                                                                                               |
+|-------------------------|-----------------------------------------------------------------------------------------------------------|
+| `-i` / `--input-format` | Input format (`parquet`, `csv`, `tsv`, `jsonl`, `avro`). Auto-detected from extension if omitted.         |
+| `-o` / `--output-format` | Output format (`parquet`, `csv`, `tsv`, `jsonl`, `avro`). If not specified, print Rich table in terminal. |
+
+
+## Global options
+
+| Option                  | Description                                                                                                                  |
+|-------------------------|------------------------------------------------------------------------------------------------------------------------------|
+| `--az-url-authority-is-account` | Interpret az:// URL authority as storage account name instead of container name. See [azure.md](Azure) for more information. |
+| `--log-level`               | Log level from `{DEBUG, INFO, WARNING, ERROR, CRITICAL}`.                                                                     |

tab_cli-0.1.2/docs/cloud.md

@@ -0,0 +1,89 @@
+# Cloud support
+
+`tab` supports directly reading tabular data files or directories from cloud storage:
+
+```bash
+tab view s3://$bucket/$path
+tab view gs://$bucket/$path
+tab view az://$container/$path
+tab view abfss://$container@$account.dfs.core.windows.net/$path
+```
+
+
+## AWS S3
+
+Authentication methods (in order):
+
+1. **Environment variables**: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`
+2. **Profile**: `AWS_PROFILE` or default — handles `~/.aws/credentials`, SSO, assume role, instance metadata
+
+```bash
+# Option 1: Set credentials directly
+export AWS_ACCESS_KEY_ID=...
+export AWS_SECRET_ACCESS_KEY=...
+
+# Option 2: Use a profile
+aws configure              # static keys
+aws sso login              # SSO authentication
+export AWS_PROFILE=my-profile
+```
+
+## Azure Blob Storage
+
+Authentication methods (in order):
+
+1. **Connection string**: `AZURE_STORAGE_CONNECTION_STRING`
+2. **Account key**: `AZURE_STORAGE_KEY`
+3. **SAS token**: `AZURE_STORAGE_SAS_TOKEN`
+4. **Azure AD / RBAC**: `DefaultAzureCredential`
+5. **Azure CLI**: Key fetched via `az storage account keys list`
+
+```bash
+# Option 1: Connection string
+export AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=...;AccountKey=..."
+
+# Option 2: Account key
+export AZURE_STORAGE_ACCOUNT=myaccount
+export AZURE_STORAGE_KEY=...
+
+# Option 3: SAS token
+export AZURE_STORAGE_ACCOUNT=myaccount
+export AZURE_STORAGE_SAS_TOKEN="?sv=2022-11-02&ss=..."
+
+# Option 4: Azure AD (requires RBAC role: Storage Blob Data Reader)
+az login
+
+# Option 5: CLI fallback (requires ARM access)
+az login
+```
+
+#### Interpretation of `az://` URLs
+The interpretation of the `az://` URL authority (the part between `az://` and the first `/`) can be configured with the `--az-url-authority-is-account` flag.
+
+Two interpretations are supported:
+
+ - `az://$container/$path` - the authority is the container name (default adlfs behavior)
+ - `az://$account/$container/$path` - the authority is the storage account name
+
+The first form is consistent with `s3://` and `gs://` URLs, but requires the `AZURE_STORAGE_ACCOUNT` environment variable to be set.
+The second form requires the `--az-url-authority-is-account` flag. 
+
+## Google Cloud Storage
+
+Authentication methods (in order):
+
+1. **`GOOGLE_APPLICATION_CREDENTIALS`**: Path to service account JSON
+2. **ADC file**: `~/.config/gcloud/application_default_credentials.json`
+3. **gcloud CLI**: Token from `gcloud auth print-access-token`
+4. **`google.auth.default()`**: Default credential resolution
+
+```bash
+# Option 1: Service account
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+
+# Option 2: User credentials (ADC)
+gcloud auth application-default login
+
+# Option 3: CLI login (fallback)
+gcloud auth login
+```

tab_cli-0.1.2/docs/gen_assets.sh

@@ -0,0 +1,3 @@
+mkdir -p docs/assets
+uv run tab view docs/test.csv -o table-svg 2> docs/assets/test.svg
+uv run tab sql 'SELECT * FROM t WHERE Metric_A_Value > 80' docs/test.csv -o table-svg 2> docs/assets/test-where.svg

tab_cli-0.1.0/README.md → tab_cli-0.1.2/docs/index.md

@@ -1,12 +1,13 @@
 # tab
 
-A fast CLI tool for viewing, querying, and converting tabular data files.
+A CLI tool for viewing, querying, and converting tabular data files. Supports AWS / Azure / Google Cloud Storage URLs.
 
 ## Supported Formats
- - Parquet
+ - Jsonl
  - CSV
  - TSV
- - Jsonl
+ - Parquet
+ - Avro
 
 ## Usage
 
@@ -15,10 +16,9 @@ A fast CLI tool for viewing, querying, and converting tabular data files.
 Display rows from a tabular data file:
 
 ```bash
-tab view data.parquet
-tab view data.csv --limit 20
-tab view data.tsv --skip 100 --limit 50
+tab view data.csv
 ```
+![tab view](assets/test.svg)
 
 Output to different formats:
 
@@ -27,17 +27,13 @@ tab view data.parquet -o jsonl
 tab view data.parquet -o csv
 ```
 
-### Schema
-
-Display the schema (column names and types):
+### Show schema
 
 ```bash
 tab schema data.parquet
 ```
 
-### Summary
-
-Display summary information about a file:
+### Show summary
 
 ```bash
 tab summary data.parquet
@@ -48,9 +44,9 @@ tab summary data.parquet
 Run SQL queries on your data. The table is referenced as `t`:
 
 ```bash
-tab sql "SELECT * FROM t WHERE age > 30" data.parquet
-tab sql "SELECT name, COUNT(*) FROM t GROUP BY name" data.csv
+tab sql 'SELECT * FROM t WHERE Metric_A_Value > 80' test.csv
 ```
+![tab sql](assets/test-where.svg)
 
 ### Convert
 
@@ -67,6 +63,12 @@ Write partitioned output:
 tab convert data.csv output_dir/ -o parquet -n 4
 ```
 
+### Concatenate multiple files
+
+```bash
+tab cat data1.csv data2.csv data3.csv -o jsonl > output.jsonl
+```
+
 ## Options
 
 ### Common options

tab_cli-0.1.2/docs/test.csv

@@ -0,0 +1,9 @@
+Participant_ID,Timestamp,Treatment_Group,Metric_A_Value,Metric_B_Value,Status
+P001,2026-01-28T08:00:00Z,Control,72.4,1.05,Baseline
+P001,2026-01-28T12:00:00Z,Control,74.1,1.08,Active
+P002,2026-01-28T08:05:00Z,Experimental,68.9,0.92,Baseline
+P002,2026-01-28T12:05:00Z,Experimental,81.3,1.45,Active
+P003,2026-01-28T08:10:00Z,Placebo,70.2,1.01,Baseline
+P003,2026-01-28T12:10:00Z,Placebo,71.5,1.03,Active
+P004,2026-01-28T08:15:00Z,Experimental,65.8,0.88,Baseline
+P004,2026-01-28T12:15:00Z,Experimental,88.2,1.82,Active

tab_cli-0.1.2/mkdocs.yml

@@ -0,0 +1,38 @@
+site_name: 'tab'
+site_description: 'A CLI tool for tabular data'
+site_author: 'Tongfei Chen'
+copyright: 'Copyright © 2026 Tongfei Chen'
+
+theme:
+  name: 'material'
+  palette:
+    primary: 'light blue'
+  font:
+    text: 'Inter'
+    code: 'Roboto Mono'
+  icon:
+    logo: material/table-eye
+
+markdown_extensions:
+  - toc:
+      permalink: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.highlight
+  - pymdownx.tabbed:
+      alternate_style: true
+  - admonition
+
+repo_name: 'ctongfei/tab'
+repo_url: 'https://github.com/ctongfei/tab'
+
+nav:
+  - 'Introduction': 'index.md'
+  - 'Cloud support': 'cloud.md'
+  - 'CLI reference': 'cli-ref.md'
+
+watch:
+  - tab_cli

{tab_cli-0.1.0 → tab_cli-0.1.2}/pyproject.toml

@@ -1,28 +1,37 @@
 [project]
 name = "tab-cli"
-version = "0.1.0"
+version = "0.1.2"
 description = "A CLI tool for tabular data"
 authors = [{name = "Tongfei Chen", email = "tongfei@pm.me"}]
 readme = "README.md"
 repository = "https://github.com/tongfei/tab"
 requires-python = ">=3.10"
 dependencies = [
-    "fire>=0.5",
+    "typer>=0.21.1",
     "rich>=13.0",
     "polars>=1.0",
     "pyarrow>=15.0",
     "blobfile>=3.0",
+    "polars-fastavro>=0.5.1",
+    "fsspec>=2025.1.0",
+    "loguru>=0.7.3",
 ]
 
-[project.scripts]
-tab = "tab_cli.cli:main"
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
+[project.optional-dependencies]
+s3 = ["s3fs>=2025.1.0", "boto3>=1.28.0"]
+gcs = ["gcsfs>=2025.1.0", "google-auth>=2.27.0"]
+azure = ["adlfs>=2025.1.0", "azure-identity>=1.10.0"]
 
 [dependency-groups]
 dev = [
     "ruff>=0.14.14",
     "ty>=0.0.14",
+    "mkdocs-material>=9.0.0"
 ]
+
+[project.scripts]
+tab = "tab_cli.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"