parq-cli 0.0.1__tar.gz

parq_cli-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'  # 当推送 v 开头的 tag 时触发（如 v0.1.0, v1.0.0）
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: 📥 Checkout code
+        uses: actions/checkout@v4
+      
+      - name: 🐍 Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: 📦 Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+      
+      - name: 🔨 Build package
+        run: python -m build
+      
+      - name: 🔍 Check package
+        run: twine check dist/*
+      
+      - name: 🚀 Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*
+      
+      - name: 📝 Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: dist/*
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

parq_cli-0.0.1/.github/workflows/test.yml

@@ -0,0 +1,48 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+    
+    steps:
+      - name: 📥 Checkout code
+        uses: actions/checkout@v4
+      
+      - name: 🐍 Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      
+      - name: 📦 Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install pandas  # Ensure pandas is installed for tests
+      
+      - name: 🧪 Run tests
+        run: pytest --cov=parq --cov-report=xml
+      
+      - name: 📊 Upload coverage
+        uses: codecov/codecov-action@v4
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+      
+      - name: 🔍 Code quality check
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+        run: |
+          pip install black ruff
+          black --check parq tests
+          ruff check parq tests
+

parq_cli-0.0.1/.gitignore

@@ -0,0 +1,210 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+project_document/
+.history/

parq_cli-0.0.1/.python-version

@@ -0,0 +1 @@
+3.11

parq_cli-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jinfeng Sun
+
+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.

parq_cli-0.0.1/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: parq-cli
+Version: 0.0.1
+Summary: A powerful command-line tool for inspecting and analyzing Apache Parquet files
+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
+Project-URL: Documentation, https://github.com/Tendo33/parq-cli#readme
+Author-email: SimonSun <sjf19981112@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: analytics,apache-parquet,cli,data,data-tools,parquet
+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-Dist: pandas>=2.0.0
+Requires-Dist: pyarrow>=18.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0.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'
+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/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+一个强大的 Apache Parquet 文件命令行工具 🚀
+
+## ✨ 特性
+
+- 📊 **元数据查看**: 快速查看 Parquet 文件的元数据信息
+- 📋 **Schema 展示**: 美观地展示文件的列结构和数据类型
+- 👀 **数据预览**: 支持查看文件的前 N 行或后 N 行
+- 🔢 **行数统计**: 快速获取文件的总行数
+- 🎨 **美观输出**: 使用 Rich 库提供彩色、格式化的终端输出
+
+## 📦 安装
+
+### 从源码安装
+
+```bash
+git clone https://github.com/yourusername/parq-cli.git
+cd parq-cli
+pip install -e .
+```
+
+### 使用 pip 安装（即将支持）
+
+```bash
+pip install parq-cli
+```
+
+## 🚀 快速开始
+
+### 基本用法
+
+```bash
+# 查看文件元数据
+parq data.parquet
+
+# 显示 schema 信息
+parq data.parquet --schema
+
+# 显示前 10 行
+parq data.parquet --head 10
+
+# 显示后 5 行
+parq data.parquet --tail 5
+
+# 显示总行数
+parq data.parquet --count
+```
+
+### 组合使用
+
+```bash
+# 同时显示 schema 和行数
+parq data.parquet --schema --count
+
+# 显示前 5 行和 schema
+parq data.parquet --head 5 --schema
+```
+
+## 📖 命令参考
+
+### 主命令
+
+```
+parq [OPTIONS] FILE
+```
+
+**参数:**
+- `FILE`: Parquet 文件路径（必需）
+
+**选项:**
+- `--schema, -s`: 显示 schema 信息
+- `--head N`: 显示前 N 行
+- `--tail N`: 显示后 N 行
+- `--count, -c`: 显示总行数
+- `--help`: 显示帮助信息
+
+### 版本信息
+
+```bash
+parq version
+```
+
+## 🎨 输出示例
+
+### 元数据展示
+
+```
+╭─────────────────────── 📊 Parquet File Metadata ───────────────────────╮
+│ file_path: /path/to/data.parquet                                       │
+│ num_rows: 1000                                                         │
+│ num_columns: 5                                                         │
+│ num_row_groups: 1                                                      │
+│ format_version: 2.6                                                    │
+│ serialized_size: 2048                                                  │
+│ created_by: parquet-cpp-arrow version 18.0.0                          │
+╰────────────────────────────────────────────────────────────────────────╯
+```
+
+### Schema 展示
+
+```
+                    📋 Schema Information
+┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
+┃ Column Name ┃ Data Type     ┃ Nullable ┃
+┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
+│ id          │ int64         │ ✗        │
+│ name        │ string        │ ✓        │
+│ age         │ int64         │ ✓        │
+│ city        │ string        │ ✓        │
+│ salary      │ double        │ ✓        │
+└─────────────┴───────────────┴──────────┘
+```
+
+## 🛠️ 技术栈
+
+- **[PyArrow](https://arrow.apache.org/docs/python/)**: 高性能的 Parquet 读取引擎
+- **[Typer](https://typer.tiangolo.com/)**: 现代化的 CLI 框架
+- **[Rich](https://rich.readthedocs.io/)**: 美观的终端输出
+
+## 🧪 开发
+
+### 安装开发依赖
+
+```bash
+pip install -e ".[dev]"
+```
+
+### 运行测试
+
+```bash
+pytest
+```
+
+### 运行测试（带覆盖率）
+
+```bash
+pytest --cov=parq --cov-report=html
+```
+
+### 代码格式化
+
+```bash
+# 使用 Black
+black parq tests
+
+# 使用 Ruff 检查
+ruff check parq tests
+```
+
+## 🗺️ 路线图
+
+- [x] 基础元数据查看
+- [x] Schema 展示
+- [x] 数据预览（head/tail）
+- [x] 行数统计
+- [ ] SQL 查询支持
+- [ ] 数据统计分析
+- [ ] 格式转换（CSV, JSON, Excel）
+- [ ] 文件对比
+- [ ] 云存储支持（S3, GCS, Azure）
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request
+
+## 📄 许可证
+
+本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
+
+## 🙏 致谢
+
+- 灵感来源于 [parquet-cli](https://github.com/chhantyal/parquet-cli)
+- 感谢 Apache Arrow 团队提供强大的 Parquet 支持
+- 感谢 Rich 库为终端输出增添色彩
+
+## 📮 联系方式
+
+- 作者: Jinfeng Sun
+- 项目地址: https://github.com/Tendo33/parq-cli
+
+---
+
+**⭐ 如果这个项目对你有帮助，请给个 Star！**

parq_cli-0.0.1/QUICKSTART.md

@@ -0,0 +1,165 @@
+# 快速开始指南
+
+## 📦 安装
+
+### 1. 克隆项目
+
+```bash
+git clone <your-repo-url>
+cd parq-cli
+```
+
+### 2. 安装依赖
+
+#### 使用 pip（推荐开发环境）
+
+```bash
+# 安装开发模式（可编辑安装）
+pip install -e .
+
+# 或安装开发依赖
+pip install -e ".[dev]"
+```
+
+#### 使用 uv（更快）
+
+```bash
+uv pip install -e .
+```
+
+### 3. 验证安装
+
+```bash
+parq --help
+parq version
+```
+
+## 🚀 快速使用
+
+### 生成测试数据
+
+首先，生成一些示例 Parquet 文件用于测试：
+
+```bash
+python examples/create_sample_data.py
+```
+
+### 基础命令
+
+#### 1. 查看文件元数据（默认行为）
+
+```bash
+parq examples/simple.parquet
+```
+
+#### 2. 显示 Schema
+
+```bash
+parq examples/simple.parquet --schema
+# 或使用短选项
+parq examples/simple.parquet -s
+```
+
+#### 3. 预览数据
+
+```bash
+# 显示前 10 行
+parq examples/simple.parquet --head 10
+
+# 显示后 5 行
+parq examples/simple.parquet --tail 5
+```
+
+#### 4. 统计行数
+
+```bash
+parq examples/simple.parquet --count
+# 或使用短选项
+parq examples/simple.parquet -c
+```
+
+#### 5. 组合使用
+
+```bash
+# 同时显示多个信息
+parq examples/simple.parquet --schema --count --head 5
+```
+
+## 🧪 运行测试
+
+### 运行所有测试
+
+```bash
+pytest
+```
+
+### 运行特定测试
+
+```bash
+# 测试 CLI
+pytest tests/test_cli.py
+
+# 测试 Reader
+pytest tests/test_reader.py
+```
+
+### 查看测试覆盖率
+
+```bash
+pytest --cov=parq --cov-report=html
+# 然后打开 htmlcov/index.html 查看详细报告
+```
+
+## 🛠️ 开发
+
+### 代码格式化
+
+```bash
+# 使用 Black 格式化代码
+black parq tests
+
+# 使用 Ruff 检查
+ruff check parq tests
+
+# 自动修复
+ruff check --fix parq tests
+```
+
+### 类型检查（可选）
+
+```bash
+pip install mypy
+mypy parq
+```
+
+## 📋 常见问题
+
+### Q: 如何处理大文件？
+
+A: parq-cli 会自动处理大文件，使用流式读取避免内存溢出。
+
+### Q: 支持哪些 Parquet 版本？
+
+A: 支持所有 PyArrow 支持的 Parquet 版本（1.0 和 2.x）。
+
+### Q: 如何贡献代码？
+
+A: 
+1. Fork 本仓库
+2. 创建特性分支
+3. 提交更改
+4. 运行测试确保通过
+5. 提交 Pull Request
+
+## 🎯 下一步
+
+- 查看完整文档：[README.md](README.md)
+- 查看示例：[examples/README.md](examples/README.md)
+- 查看架构设计：[project_document/parq-cli-architecture-design.md](project_document/parq-cli-architecture-design.md)
+
+## 💡 提示
+
+- 使用 `parq --help` 查看所有可用选项
+- 大文件建议先用 `--count` 查看行数，再用 `--head` 预览数据
+- 结合使用多个选项可以快速了解文件内容
+