Build 1 — CLI Tool (Typer + tests + package + publish)

# Build 1 — CLI Tool ## The brief Build a CLI tool that does something useful. Package it; publish to PyPI Test. The full project lifecycle. ## What to build Choose one (or your own): - **csv-grep**: like grep but for CSV files; filter by column. - **json-pretty**: pretty-print and query JSON files (like jq, but simpler). - **port-scanner**: scan a given port range on a host. - **dir-stats**: compute size and file counts per subdirectory. - **password-gen**: generate strong passwords with constraints. ## Step 1: Project setup (15 min) ```bash mkdir my-cli cd my-cli uv init uv add typer rich # Typer for CLI; rich for pretty output uv add --dev pytest pytest-cov pyright ``` pyproject.toml: ```toml [project] name = "my-cli" version = "0.1.0" description = "..." requires-python = ">=3.11" dependencies = ["typer>=0.9", "rich>=13"] [project.scripts] my-cli = "my_cli.main:app" [build-system] requires = ["hatchling"] build-backend = "hatchling.build" ``` src layout: ``` my-cli/ ├── pyproject.toml ├── src/ │ └── my_cli/ │ ├── __init__.py │ └── main.py └── tests/ └── test_main.py ``` ## Step 2: Write the CLI (30 min) Typer example: ```python # src/my_cli/main.py import typer from typing import Annotated from rich import print app = typer.Typer(help="A useful CLI tool") @app.command() def search( pattern: Annotated[str, typer.Argument(help="Pattern to search for")], file: Annotated[str, typer.Argument(help="File to search in")], case_insensitive: Annotated[bool, typer.Option("-i", "--insensitive")] = False, ): """Search for PATTERN in FILE.""" flags = re.IGNORECASE if case_insensitive else 0 with open(file) as f: for line in f: if re.search(pattern, line, flags): print(line.rstrip()) @app.command() def version(): """Show version.""" print("0.1.0") if __name__ == "__main__": app() ``` Typer gives you: - Auto-generated `--help`. - Type hints become validation. - Subcommands. - Rich integration for pretty output. ## Step 3: Write tests (20 min) ```python # tests/test_main.py from typer.testing import CliRunner from my_cli.main import app runner = CliRunner() def test_version(): result = runner.invoke(app, ["version"]) assert result.exit_code == 0 assert "0.1.0" in result.stdout def test_search_finds_match(tmp_path): # Create test file test_file = tmp_path / "data.txt" test_file.write_text("apple\nbanana\napricot\n") result = runner.invoke(app, ["search", "ap", str(test_file)]) assert result.exit_code == 0 assert "apple" in result.stdout assert "apricot" in result.stdout assert "banana" not in result.stdout def test_case_insensitive(tmp_path): test_file = tmp_path / "data.txt" test_file.write_text("APPLE\nbanana\n") result = runner.invoke(app, ["search", "-i", "apple", str(test_file)]) assert result.exit_code == 0 assert "APPLE" in result.stdout ``` Run: ```bash uv run pytest -v uv run pytest --cov=src --cov-report=html ``` Aim for 80%+ coverage on the main logic. ## Step 4: Type check (5 min) ```bash uv run pyright src tests ``` Fix any type errors. Add type hints where missing. ## Step 5: Build and install locally (5 min) ```bash # Build uv build # Output in dist/: my_cli-0.1.0-py3-none-any.whl + .tar.gz # Install editable for testing uv pip install -e . # Run my-cli search "pattern" /path/to/file ``` ## Step 6: Publish to PyPI Test (15 min) ```bash # Create account at https://test.pypi.org/ # Get API token from account settings # Publish uv publish --publish-url https://test.pypi.org/legacy/ \ --token pypi-AgEIcHl... ``` Or with twine: ```bash pip install twine twine upload --repository testpypi dist/* ``` Verify: ```bash pip install --index-url https://test.pypi.org/simple/ my-cli my-cli --help ``` ## Deliverables - GitHub repo with pyproject.toml, src/, tests/, README. - ≥ 80% test coverage on main logic. - Pyright strict mode passing. - Published to PyPI Test. - README with installation + usage examples. ## What you'll learn - Modern Python project structure. - CLI design with Typer. - pytest with CLI testing (CliRunner). - Building and publishing to PyPI. - Type-checked production-style code. ## Stretch - Add a config file (TOML) the CLI reads. - Add multiple subcommands. - Add a `--verbose` flag using logging. - Set up GitHub Actions CI to run tests + publish on tag.