Contributing - MiguelElGallo/iparq GitHub Wiki

Contributing

This page covers development setup, testing, CI/CD, and contribution guidelines for iparq.

Development Setup

git clone https://github.com/MiguelElGallo/iparq.git
cd iparq
uv sync --all-extras  # Installs all deps including test and checks groups

Python >= 3.9 is required. This project uses UV for package management.

Running the Tool Locally

uv run iparq inspect dummy.parquet

Testing

uv run pytest -vv
uv run pytest -vv --cov=src/iparq --cov-report=term-missing  # With coverage

There are 22 tests in tests/test_cli.py covering:

  • Basic inspection, metadata-only flag, and column filtering
  • JSON output format, multiple files, and glob patterns
  • Single file output (no header) and error handling with multiple files
  • --sizes flag output (rich and JSON) and format_size function (B, KB, MB, GB, TB)
  • Pydantic model validation (ColumnInfo with all fields and defaults)
  • output_json function, column filter no match, and nonexistent file handling
  • Default command behavior

Test fixture: tests/dummy.parquet with 3 columns (one, two, three), SNAPPY compression, and bloom filters.

Linting and Type Checking

uv run ruff check .                           # Linting
uvx black . --check --verbose                 # Formatting check
cd src/iparq && uv run mypy . --config-file=../../pyproject.toml  # Type checking

CI/CD Pipelines

The project has several GitHub Actions workflows:

python-package.yml (Main CI)

  • Triggers on push and pull request to main
  • Matrix: Ubuntu + Windows × Python 3.9-3.13
  • Steps: Install deps → Ruff lint → mypy type check → Black format check → pytest with coverage → Codecov upload

test.yml

  • Triggers on push and pull request to main, plus manual dispatch
  • Matrix: Ubuntu × Python 3.9-3.13
  • Steps: Install deps → pytest

merge.yml

  • Triggers on push and pull request to main
  • Ignores .md, .azdo, .devcontainer, and .github
  • Same matrix as main CI but without coverage upload

python-publish.yml (PyPI Release)

  • Manual trigger via workflow_dispatch
  • Three jobs: test-and-validate → release-build → pypi-publish
  • Uses trusted publishing (OIDC)
  • Tests linting, type checking, pytest, build, and install verification

copilot-setup-steps.yml

  • Sets up the environment for the GitHub Copilot coding agent
  • Installs UV

Dependency Management

  • Runtime dependencies: pyarrow, typer, pydantic, rich
  • Test group: pytest, pytest-cov
  • Checks group: mypy, ruff
  • Dependabot is configured for weekly UV ecosystem updates

Contribution Workflow

  1. Fork the repository
  2. Clone your fork
  3. Create a branch: git checkout -b feature-name
  4. Make changes
  5. Run tests and lints locally
  6. Commit with clear messages: type(scope): message
  7. Push and create a pull request

Code Style

  • Formatted with Black
  • Linted with Ruff
  • Type-checked with mypy
  • PEP 561 compliant (py.typed marker)

Link back to Home.