****************
Scaldys Template
****************

.. image:: https://img.shields.io/github/license/scaldys/scaldys-template
   :alt: License
   :target: https://github.com/scaldys/scaldys-template/blob/main/LICENSE

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+
* 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
* GitHub Actions workflows for CI/CD and PyPI publishing


Getting Started
===============

Prerequisites
-------------

* Python 3.12 or later
* Git

Setup
-----

1. **Get the template:**

   .. code-block:: bash

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

.. code-block:: bash

   uv run pytest ./tests

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

.. code-block:: bash

   uv sync

Please refer to the ``uv`` documentation : https://docs.astral.sh/uv/guides/


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:

.. code-block:: bash

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