Contributing to pytd

Development Setup

This project uses uv for fast and reliable Python package management.

Installing uv

# On macOS and Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip:
pip install uv

Setting Up Development Environment

# Clone the repository
git clone https://github.com/treasure-data/pytd.git
cd pytd

# Sync dependencies (installs everything from uv.lock)
uv sync

# Run commands in the uv-managed environment
uv run python --version
uv run pytest

Code Formatting and Testing

We use ruff for linting and formatting, and pyright for type checking.

We use nox to run tests and checks. Nox is configured to use uv as the backend for fast virtual environment creation and package installation.

You can run formatter, linter, and tests by using nox:

# Run all sessions
uvx nox

# Run specific sessions
uvx nox --session lint
uvx nox --session typecheck
uvx nox --session tests

Pre-commit Hooks

We highly recommend you to introduce pre-commit to ensure your commit follows required format.

You can install and set up pre-commit as follows:

uvx pre-commit install

Now, ruff and other checks will run each time you commit changes. You can skip these checks with git commit --no-verify.

Documenting

pip install .[doc]

Edit contents in doc/:

cd doc

Build HTML files to render Sphinx documentation:

make html

The doc/ folder is monitored and automatically published by Read the Docs.

Releasing

Update version in pyproject.toml. Set it to 1.0.0, for example:

[project]
name = "pytd"
version = "1.0.0"

Commit and push the latest code, and tag the version:

git tag 1.0.0
git push --tags

GitHub Actions Workflow then automatically releases the tagged version on PyPI. A tag and version number must be identical and following the semantic versioning convention.