Scaldys-template

A modern Python project template with best practices.

Features

This template provides a solid foundation for Python projects with integrated testing, documentation, and quality assurance tools.

Version 0.11.0

• Modern Python development with Python 3.13+
• Tkinter-based GUI built with ttkbootstrap — includes a Signal Analyzer, real-time JSON Editor, and a widget showcase (Windows only)
• Command-line interface (CLI) built with Typer — global flags (--log, --verbose) resolved once before any subcommand runs
• Application lifecycle entry point (__main__.py) covering freeze support, crash hooks, signal handlers, asyncio policy, and environment validation
• Reference implementations in core/ for async processing pipelines (async_processor.py) and database abstraction (database.py)
• Fast dependency management with uv
• Comprehensive testing with pytest, pytest-asyncio, pytest-mock, and coverage reporting — structured with unit / integration / slow markers
• Code quality verification with ruff (linting & formatting) and pyright (type checking)
• Documentation with reStructuredText and sphinx using ReadTheDocs theme
• Windows build infrastructure with Cython, scaldys-project, and — depending on the deployment mode — PyInstaller, Inno Setup, or wheel-only packaging
• GitHub Actions workflows for CI/CD and PyPI publishing

Relationship with scaldys-project

This template is designed to work in tandem with scaldys-project, a specialized toolset for managing Python project lifecycles, build pipelines, and distribution.

scaldys-template serves as the reference example for all scaldys-project compatible projects. It demonstrates the standard directory structure, configuration patterns (via scaldys-project.toml), and integration points—such as Cython compilation, Windows installer generation, and automated documentation builds—that the ecosystem supports.

Project Structure

src/scaldys_template/
├── __main__.py             ← lifecycle entry point (freeze_support, crash hook,
│                             signal handlers, asyncio policy, env validation)
├── cli/
│   ├── cli.py              ← Typer app; owns the single setup_logging() call
│   ├── settings.py         ← AppSettings: persisted log level (INI + Pydantic)
│   └── commands/
│       ├── arg_types.py    ← shared Annotated type definitions
│       ├── cmd_export.py
│       ├── cmd_process.py  ← demonstrates async pipeline + DB connection
│       └── cmd_settings.py
├── common/
│   ├── app_location.py     ← OS-aware path resolution (Windows/macOS/Linux,
│   │                         source vs installed vs frozen)
│   └── logging.py          ← QueueHandler-based JSON logging setup
├── core/
│   ├── export.py
│   ├── async_processor.py  ← async pipeline pattern + sync wrapper
│   └── database.py         ← connection, transaction, pool scaffold
└── tk/
    ├── app.py              ← Main Application (Tkinter)
    └── ui/                 ← GUI frames (Analyzer, Editor, UI Examples)

tests/
├── conftest.py             ← isolated_app_location keystone fixture
├── unit/
│   ├── conftest.py         ← reset_scaldys_template_logger autouse fixture
│   ├── common/             ← mirrors src/scaldys_template/common/
│   ├── cli/                ← mirrors src/scaldys_template/cli/
│   ├── core/               ← mirrors src/scaldys_template/core/
│   └── tk/                 ← mirrors src/scaldys_template/tk/
└── integration/            ← full CLI invocations via CliRunner

Download

While primarily created for personal use, it’s available for anyone to use or fork on GitHub: https://github.com/scaldys/scaldys-template