scaldys 0.2.1

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

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.

# Build source distribution and wheel
uv build

# 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"

# 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

# 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"

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)