cal-pystats 1.0.0

A simple CLI tool to analyse Python file statistics in a directory

cal-pystats

A simple CLI tool that scans directories for Python files and displays statistics.

Features

• Recursively scans directories for .py files
• Reports:
  • Number of Python files
  • Total size (KB/MB)
  • Total lines
  • Code lines (excluding blank lines, docstrings, and decorative comments)
• Beautiful ASCII box output with ANSI colours (when running in a terminal)
• Plain text and JSON output formats available

Installation

# Using uv
uv pip install cal-pystats

# Using pip
pip install cal-pystats

Usage

# Scan current directory
cal-pystats

# Scan a specific directory
cal-pystats /path/to/project

# Plain text output (no box)
cal-pystats --plain

# JSON output
cal-pystats --json

Example Output

╭────────────────────────────────╮
│     Python Stats: my-project   │
│────────────────────────────────│
│  Files       :            42   │
│  Total Size  :       128.5 KB  │
│  Total Lines :         3,847   │
│  Code Lines  :         2,691   │
╰────────────────────────────────╯

Development

# Set up development environment
make dev

# Run linting and type checks
make check

# Format code
make format

# Build wheel and docs
make build

Publishing

Publishing requires cal-publish-python configuration. See the cal-publish-python documentation for setup.

# Build first
make build

# Publish wheel to PyPI and docs to GitLab Pages
make publish

Licence

MIT License — Copyright (c) 2026 Cyber Assessment Labs