A minimal, practical project template for small Python projects and experiments.

• Python 3.8+
• uv

1. Fork or Copy: Fork this repository or copy the files to a new directory.
2. Rename Directory: Rename the directory to your desired project name.
3. Initialize Project: Run the following command to initialize the project with uv, which will generate a pyproject.toml based on your directory name:

   uv init --lib --build-backend hatchling .

   Note: If you want to specify a project name different from the directory name, you can pass the --name argument (if supported by your uv version) or simply rename the directory first.

1. Install dependencies:

   uv sync

• Run the main script or module:

  uv run -m your_package

  Replace your_package with the actual package or script name.

• Run tests using pytest:

  uv run pytest
  # or
  just test

The project uses pytest-benchmark with custom Plotly visualization for automated performance benchmarking:

• Run fast benchmarks (excludes slow 50M+ cases):

  just benchmark

• Run large/slow benchmarks and merge with existing results:

  just benchmark-large

• View benchmark reports:

  just benchmark-view

Benchmark reports are automatically generated in reports/benchmarks/ including:

• Combined JSON statistics (benchmark.json)
• Regular/large JSON inputs (benchmark.json and benchmark-large.json)
• Historical data (organized by commit hash and timestamp)
• Interactive HTML dashboard (benchmark_dashboard.html) with all benchmark groups
• Individual SVG plots per benchmark group in reports/benchmarks/plots/

The visualization system features:

• Automatic test grouping by benchmark category
• Consistent color scheme across implementations (numpy vs pandas)
• Horizontal bar charts for better readability
• Interactive hover information with detailed statistics
• Fully configurable styling (colors, fonts, layout)

For detailed benchmark usage, see agc/20260204_01_benchmark_usage.md

Contributions are welcome. Open an issue or submit a pull request with a short description of changes.

MIT