scaldys 0.2.1

A skeleton for Python projects by Scaldys.

A modern Python project template with best practices.

This template provides a solid foundation for Python projects with integrated testing, documentation, and quality assurance tools. While primarily created for personal use, it’s available for anyone to use or fork on GitHub: https://github.com/scaldys/scaldys-template

Features

• Modern Python development with Python 3.12+

• Command-line interface (CLI) built with Typer for intuitive and feature-rich applications

• Fast dependency management with uv

• Comprehensive testing with pytest and coverage reporting

• Code quality verification with ruff (linting & formatting) and pyright (type checking)

• Documentation with reStructuredText and sphinx using ReadTheDocs theme

• Windows build infrastructure with Cython, PyInstaller and Inno Setup

• GitHub Actions workflows for CI/CD and PyPI publishing

Getting Started

Prerequisites

• Python 3.12 or later

• Git

Setup

1. Get the template:

   # Option 1: Download as ZIP
   # Download from https://github.com/scaldys/scaldys-template/archive/refs/heads/main.zip
   
   # Option 2: Clone with Git
   git clone https://github.com/scaldys/scaldys-template.git your-project-name
   cd your-project-name
   rm -rf .git
   git init

2. Customize the template:

   • Replace all occurrences of scaldys (case-sensitive) with your project name

   • Update file and directory names containing “scaldys”

   • Modify package metadata in pyproject.toml

3. Set up your repository:

   • Create a new repository on GitHub/GitLab

   • Follow their instructions to push your local repository

   • Set up required GitHub environments for trusted publishing

Development Workflow

Installation

uv will automatically install development dependencies when running a command, for instance run the tests.

uv run pytest ./tests

While the environment is synced automatically, it may also be explicitly synced using uv sync:

uv sync

For comprehensive documentation on using uv, visit the official documentation: https://docs.astral.sh/uv/guides/ .

Execute the Application

Execute the application with the following command:

uv run ./src/scaldys.py

or from within the source directory :

# using uv
uv run scaldys.py

# using Python directly
python scaldys.py

Building the Application

You can build distribution packages for your application to share or deploy it. The build process creates both source distributions (sdist) and binary wheel distributions.

Basic Build

To build the application using uv:

# Build source distribution and wheel
uv build

This creates distribution files in the dist/ directory: - scaldys-x.y.z.tar.gz (source distribution) - scaldys-x.y.z-py3-none-any.whl (wheel distribution)

Build Options

For more control over the build process:

# Build only the wheel
uv build --wheel

# Build only the source distribution
uv build --sdist

# Clean previous builds first
rm -rf dist/ build/
uv build

# Include development extras in the build
uv build --config-setting="--extras=dev"

Verify the Build

You can verify your build artifacts before distribution:

# List contents of the wheel
python -m zipfile -l dist/scaldys-*.whl

# Install from the local wheel to test
pip install --force-reinstall dist/scaldys-*.whl

# Run a smoke test after installation
scaldys --version

Build for Different Environments

For specific target environments:

# For a specific Python version
uv build --python-tag py312

# For specific platforms (when using C extensions)
uv build --config-setting="--plat-name=manylinux2014_x86_64"

Automated Builds

The project includes GitHub Actions workflows that automatically build packages when you create a new release. See the workflow file at .github/workflows/release.yml for details.

Windows Packaging (Cython + PyInstaller + Inno Setup)

This template includes a dedicated Windows build system to create compiled, standalone executables and a professional installer.

Key features: * Cythonization: Critical core modules are compiled to C for performance and basic obfuscation. * Stand-alone Executable: Bundles the application and all dependencies into a single directory using PyInstaller. * Professional Installer: Creates a Windows setup (.exe) using Inno Setup, including desktop shortcuts and PATH integration.

The Windows build system is managed by the packaging/windows/windows_builder.py script, which is exposed via the CLI.

Available Build Commands:

# Run the full end-to-end build (docs, exe, and installer)
uv run python packaging/windows/windows_builder.py build windows all

# Build only the standalone executable
uv run python packaging/windows/windows_builder.py build windows exe

# Build only the setup installer (requires Inno Setup installed)
uv run python packaging/windows/windows_builder.py build windows installer

# Build Windows-specific documentation
uv run python packaging/windows/windows_builder.py build windows docs

# Clean build and dist directories
uv run python packaging/windows/windows_builder.py build windows clean

Prerequisites for Windows Build: * Inno Setup: Must be installed and available in your PATH to build the installer. * Visual Studio Build Tools: Required for Cython compilation.

Code Quality Verification

The project includes automated code quality checks that run when you push changes to GitHub. These checks are defined in .github/workflows/release.yml and include:

• Building the project with uv build

• (Optional) Smoke tests for the wheel and source distribution packages

You can also run quality checks locally before committing:

# Sync dependencies with lock file
uv sync

# Run tests
uv run pytest

# Check test coverage
uv run coverage run -m pytest

# Lint and check formatting
uv run ruff check ./src

# Format code
uv run ruff format ./src

# Check types
uv run pyright ./src

# Build documentation
uv run sphinx-build docs/manual/source docs/_build

Publishing to PyPI

This template supports trusted publishing to PyPI using GitHub Actions:

1. Read the Packaging Python Projects guide: https://packaging.python.org/en/latest/tutorials/packaging-projects/

2. For trusted publishing details, see uv’s trusted publishing examples: https://github.com/astral-sh/trusted-publishing-examples

3. For testing purposes, use TestPyPI: modify the run step in .github/workflows/release.yml to use TestPyPI

4. Configure trusted publishing:

   • Log in to PyPI (https://pypi.org/) or TestPyPI (https://test.pypi.org/)

   • Go to “Your projects” → “Publishing” → “Trusted Publisher Management”

   • Click “Add a new pending publisher” and configure: * Project name: Your package name * Owner: Your GitHub username * Repository: Your repository name * Workflow name: release.yml * Environment name: release (configure this in your GitHub repository settings)

License

This project template is distributed under the MIT license. See the LICENSE file for details.