scaldys-template 0.7.0__tar.gz

scaldys_template-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Scaldys
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scaldys_template-0.7.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: scaldys-template
+Version: 0.7.0
+Summary: A skeleton for Python projects by Scaldys.
+Author-email: scaldys-template <scaldys@scaldys.net>
+Classifier: Programming Language :: Python
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: art>=6.5
+Requires-Dist: platformdirs>=4.9.6
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.25.0
+Dynamic: license-file

scaldys_template-0.7.0/README.md

@@ -0,0 +1,355 @@
+# Scaldys Template
+
+![License](https://img.shields.io/github/license/scaldys/scaldys-template)
+
+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.13+
+- 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
+
+## 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
+
+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/
+└── integration/             ← full CLI invocations via CliRunner
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.13 or later
+- Git
+
+### Setup
+
+1. **Get the template:**
+
+   ```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_template` / `Scaldys-Template`
+     (case-sensitive) with your project name
+   - Update file and directory names containing "scaldys_template"
+   - 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:
+
+```bash
+uv run pytest ./tests
+```
+
+While the environment is synced automatically, it may also be explicitly synced
+using `uv sync`:
+
+```bash
+uv sync --group dev
+```
+
+For comprehensive documentation on using `uv`, visit the official documentation:
+https://docs.astral.sh/uv/guides/
+
+### Execute the Application
+
+The CLI entry point is `scaldys_template.__main__:main`, which runs lifecycle
+setup before handing off to the Typer app. Global options (`--log`, `--verbose`)
+must appear **before** the subcommand name:
+
+```bash
+# Show help
+uv run scaldys-template --help
+
+# Show available commands
+uv run scaldys-template --help
+
+# Run the export command with debug logging
+uv run scaldys-template --log debug export config.yml
+
+# Run the process command with verbose output
+uv run scaldys-template --verbose process --num-tasks 20
+
+# Run via python -m (same lifecycle path)
+uv run python -m scaldys_template --log info export config.yml
+
+# Manage the persisted log level
+uv run scaldys-template settings log warning
+uv run scaldys-template settings          # show current level
+```
+
+You can also run directly from the source directory:
+
+```bash
+# using uv
+uv run scaldys-template.py
+
+# using Python directly
+python src/scaldys_template.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`:
+
+```bash
+# Build source distribution and wheel
+uv build
+```
+
+This creates distribution files in the `dist/` directory:
+
+- `scaldys_template-x.y.z.tar.gz` (source distribution)
+- `scaldys_template-x.y.z-py3-none-any.whl` (wheel distribution)
+
+#### Build Options
+
+For more control over the build process:
+
+```bash
+# 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:
+
+```bash
+# List contents of the wheel
+python -m zipfile -l dist/scaldys_template-*.whl
+
+# Install from the local wheel to test
+pip install --force-reinstall dist/scaldys_template-*.whl
+
+# Run a smoke test after installation
+scaldys-template --version
+```
+
+#### Build for Different Environments
+
+For specific target environments:
+
+```bash
+# For a specific Python version
+uv build --python-tag py313
+
+# 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 (scaldys-project)
+
+This template includes a dedicated Windows build system managed by the
+`scaldys-project` CLI command installed by `uv sync`.
+
+**Deployment modes** — controlled by `deployment_mode` in `scaldys.toml`:
+
+| Mode                    | What it builds                                                    | When to use                           |
+| ----------------------- | ----------------------------------------------------------------- | ------------------------------------- |
+| `pyinstaller` (default) | PyInstaller exe + Inno Setup installer                            | Most applications                     |
+| `pyruntime`             | Binary wheel + Inno Setup installer with a managed Python runtime | Apps that coexist with Quarto/Jupyter |
+| `wheel_only`            | Binary wheel only, no installer                                   | Apps distributed via pip/uv           |
+
+**Key features:**
+
+- **Cython compilation:** Critical modules are compiled to `.pyd` extensions for
+  performance and basic obfuscation.
+- **Standalone executable:** (`pyinstaller` mode) Bundles the application into a
+  self-contained directory via PyInstaller.
+- **Managed Python runtime:** (`pyruntime` mode) Deploys a `uv`-managed virtual
+  environment alongside the app, supporting online and offline installer
+  variants.
+- **Professional installer:** (`pyinstaller` / `pyruntime` modes) Creates a
+  Windows setup `.exe` using Inno Setup with desktop shortcuts.
+- **Binary wheel:** (all modes) Built from compiled sources and placed in
+  `dist/` for users with their own environment.
+
+**Build commands:**
+
+```bash
+# Full build: documentation + Windows distribution
+scaldys-project build all
+
+# Documentation only
+scaldys-project build docs
+
+# Windows distribution only (mode-dependent)
+scaldys-project build windows
+
+# Remove build/, dist/ and artifacts/
+scaldys-project build clean
+
+# Verify project compliance
+scaldys-project check
+```
+
+**Prerequisites:**
+
+- **Visual Studio Build Tools:** Required for Cython compilation (all modes).
+- **PyInstaller:** Required for `pyinstaller` mode (`uv sync` installs it).
+- **Inno Setup:** Required for `pyinstaller` and `pyruntime` modes (must be
+  installed separately).
+
+### 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:
+
+```bash
+# Sync dependencies with lock file
+uv sync --group dev
+
+# Run the full test suite
+uv run pytest
+
+# Run only fast unit tests (no filesystem or CLI I/O)
+uv run pytest -m unit
+
+# Run only integration tests
+uv run pytest -m integration
+
+# Exclude slow tests (async pipeline tests with real latency)
+uv run pytest -m "not slow"
+
+# Run tests with coverage report
+uv run pytest --cov=src/scaldys_template --cov-report=term-missing
+
+# 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/user_guide/source docs/_build
+```
+
+#### Test markers
+
+| Marker        | What it covers                                                    | Typical run time          |
+| ------------- | ----------------------------------------------------------------- | ------------------------- |
+| `unit`        | Isolated tests — no real filesystem writes, CLI mocked            | < 1 s                     |
+| `integration` | Full CLI invocations via `CliRunner`, real file I/O in `tmp_path` | ~10 s                     |
+| `slow`        | Tests that run the real async pipeline with simulated latency     | included in `integration` |
+
+### 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.

scaldys_template-0.7.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "scaldys-template"
+version = "0.7.0"
+authors = [
+  { name="scaldys-template", email="scaldys@scaldys.net" },
+]
+description = "A skeleton for Python projects by Scaldys."
+readme = "README.rst"
+requires-python = ">=3.13"
+classifiers = [
+    "Programming Language :: Python",
+    "Operating System :: OS Independent",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Utilities",
+]
+license-files = ["LICEN[CS]E*"]
+dependencies = [
+    "art>=6.5",
+    "platformdirs>=4.9.6",
+    "pydantic>=2.0",
+    "rich>=13.0",
+    "typer>=0.25.0",
+]
+
+[project.scripts]
+scaldys-template = "scaldys_template.__main__:main"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["scaldys_template*"]
+
+[tool.setuptools.package-data]
+scaldys_template = ["py.typed"]
+
+[dependency-groups]
+dev = [
+    "scaldys-project[cython,windows,docs]",
+    "pre-commit>=4.5.0",
+    "pyright>=1.1.409",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=0.25.0",
+    "pytest-cov>=7.1.0",
+    "pytest-mock>=3.14.0",
+    "ruff>=0.15.12",
+    "sphinx>=9.1.0",
+    "sphinx-rtd-theme>=3.1.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "unit: Fast, isolated tests with no external I/O",
+    "integration: Tests that touch the filesystem or invoke the full CLI",
+    "slow: Tests that take significant time (excluded from fast CI runs)",
+]
+
+[tool.uv.sources]
+scaldys-project = { path = "../scaldys-project", editable = true }
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F403"]
+
+[tool.pyright]
+exclude = [".venv"]
+pythonVersion = "3.13"
+venvPath = "."
+venv = ".venv"
+
+#[[tool.uv.index]]
+#name = "testpypi"
+#url = "https://test.pypi.org/simple/"
+#publish-url = "https://test.pypi.org/legacy/"

scaldys_template-0.7.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scaldys_template-0.7.0/src/scaldys_template/__about__.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+
+__all__ = [
+    "APP_NAME",
+    "PACKAGE_NAME",
+    "ORGANIZATION_NAME",
+    "VERSION",
+]
+
+from importlib.metadata import version, PackageNotFoundError
+
+APP_NAME = "Scaldys-Template"
+PACKAGE_NAME = "scaldys_template"
+ORGANIZATION_NAME = "Scaldys"
+
+try:
+    VERSION = version(PACKAGE_NAME)
+except PackageNotFoundError:
+    VERSION = "0.0.0"

scaldys_template-0.7.0/src/scaldys_template/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+
+from scaldys_template.cli import *
+from scaldys_template.common import *