scaldys-project 0.10.0__tar.gz

scaldys_project-0.10.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_project-0.10.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: scaldys-project
+Version: 0.10.0
+Summary: A modular build system for Python projects targeting Windows.
+Author-email: Scaldys <scaldys@scaldys.net>
+Classifier: Programming Language :: Python
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.25.0
+Provides-Extra: cython
+Requires-Dist: cython>=3.2.4; extra == "cython"
+Requires-Dist: setuptools>=82.0.1; extra == "cython"
+Provides-Extra: windows
+Requires-Dist: pyinstaller>=6.20.0; extra == "windows"
+Provides-Extra: docs
+Requires-Dist: sphinx>=9.1.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=3.1.0; extra == "docs"
+Dynamic: license-file
+
+# scaldys-project
+
+`scaldys-project` automates the complete Windows distribution pipeline for
+Python projects. A single command takes your source code through Sphinx
+documentation, optional Cython compilation, and — depending on the chosen
+deployment mode — one of three distribution strategies:
+
+- **pyinstaller** (default) — PyInstaller exe + Inno Setup installer
+- **pyruntime** — binary wheel + Inno Setup installer with a managed Python
+  runtime (for apps that coexist with Quarto/Jupyter)
+- **wheel_only** — binary wheel only, no installer (for pip-installable apps)
+
+If you are starting a new project,
+[scaldys-template](https://github.com/scaldys/scaldys-template) provides a
+ready-to-use project scaffold with `scaldys-project` already integrated:
+packaging scripts, Sphinx documentation, CI/CD workflows, and a working
+`scaldys.toml`.
+
+For a full guide on using and integrating `scaldys-project` in your project, see
+the [user documentation](https://github.com/scaldys/scaldys-project).
+
+---
+
+## Development
+
+This section is for contributors working on `scaldys-project` itself.
+
+Project repository and issue tracker: https://github.com/scaldys/scaldys-project
+
+### Quick start
+
+```bash
+git clone https://github.com/scaldys/scaldys-project.git
+cd scaldys-project
+uv sync --group dev
+uv run pytest
+uv run ruff check src tests && uv run pyright
+```
+
+### Further reading
+
+The manual's Developers section covers everything else a contributor needs:
+
+- [Architecture](docs/manual/source/developers/architecture.rst) — module
+  layout, three-class composition pattern, execution flow, configuration
+  loading, and why `compile_runner.py` runs as a subprocess
+- [Extension Points](docs/manual/source/developers/extension_points.rst) —
+  design conventions and how to add Cython modules, build steps, or a new
+  platform builder
+- [Contributing](docs/manual/source/developers/contributing.rst) — linting, type
+  checking, building docs, versioning, and publishing

scaldys_project-0.10.0/README.md

@@ -0,0 +1,51 @@
+# scaldys-project
+
+`scaldys-project` automates the complete Windows distribution pipeline for
+Python projects. A single command takes your source code through Sphinx
+documentation, optional Cython compilation, and — depending on the chosen
+deployment mode — one of three distribution strategies:
+
+- **pyinstaller** (default) — PyInstaller exe + Inno Setup installer
+- **pyruntime** — binary wheel + Inno Setup installer with a managed Python
+  runtime (for apps that coexist with Quarto/Jupyter)
+- **wheel_only** — binary wheel only, no installer (for pip-installable apps)
+
+If you are starting a new project,
+[scaldys-template](https://github.com/scaldys/scaldys-template) provides a
+ready-to-use project scaffold with `scaldys-project` already integrated:
+packaging scripts, Sphinx documentation, CI/CD workflows, and a working
+`scaldys.toml`.
+
+For a full guide on using and integrating `scaldys-project` in your project, see
+the [user documentation](https://github.com/scaldys/scaldys-project).
+
+---
+
+## Development
+
+This section is for contributors working on `scaldys-project` itself.
+
+Project repository and issue tracker: https://github.com/scaldys/scaldys-project
+
+### Quick start
+
+```bash
+git clone https://github.com/scaldys/scaldys-project.git
+cd scaldys-project
+uv sync --group dev
+uv run pytest
+uv run ruff check src tests && uv run pyright
+```
+
+### Further reading
+
+The manual's Developers section covers everything else a contributor needs:
+
+- [Architecture](docs/manual/source/developers/architecture.rst) — module
+  layout, three-class composition pattern, execution flow, configuration
+  loading, and why `compile_runner.py` runs as a subprocess
+- [Extension Points](docs/manual/source/developers/extension_points.rst) —
+  design conventions and how to add Cython modules, build steps, or a new
+  platform builder
+- [Contributing](docs/manual/source/developers/contributing.rst) — linting, type
+  checking, building docs, versioning, and publishing

scaldys_project-0.10.0/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "scaldys-project"
+version = "0.10.0"
+authors = [
+  { name="Scaldys", email="scaldys@scaldys.net" },
+]
+description = "A modular build system for Python projects targeting Windows."
+readme = "README.md"
+requires-python = ">=3.13"
+classifiers = [
+    "Programming Language :: Python",
+    "Operating System :: Microsoft :: Windows",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+]
+license-files = ["LICEN[CS]E*"]
+dependencies = [
+    "rich>=15.0.0",
+    "typer>=0.25.0",
+]
+
+[project.optional-dependencies]
+cython = [
+    "cython>=3.2.4",
+    "setuptools>=82.0.1",
+]
+windows = [
+    "pyinstaller>=6.20.0",
+]
+docs = [
+    "sphinx>=9.1.0",
+    "sphinx-rtd-theme>=3.1.0",
+]
+
+[project.scripts]
+scaldys-project = "scaldys_project.__main__:app"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[dependency-groups]
+dev = [
+    "cython>=3.2.4",
+    "pre-commit>=4.5.0",
+    "pyright>=1.1.409",
+    "pyinstaller>=6.20.0",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.12",
+    "setuptools>=82.0.1",
+    "sphinx>=9.1.0",
+    "sphinx-rtd-theme>=3.1.0",
+]
+
+[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"

scaldys_project-0.10.0/setup.cfg

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

scaldys_project-0.10.0/src/scaldys_project/__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 Builder"
+PACKAGE_NAME = "scaldys-project"
+ORGANIZATION_NAME = "Scaldys"
+
+try:
+    VERSION = version(PACKAGE_NAME)
+except PackageNotFoundError:
+    VERSION = "0.0.0"

scaldys_project-0.10.0/src/scaldys_project/__main__.py

@@ -0,0 +1,120 @@
+"""
+Main entry point for the scaldys-project build system.
+
+Provides a unified CLI for building projects.  Run from the root of the
+consuming project (the directory that contains ``pyproject.toml``)::
+
+    scaldys-project build all       # full build: docs + Windows distribution
+    scaldys-project build docs      # documentation only
+    scaldys-project build windows   # Windows distribution only (mode-dependent)
+    scaldys-project build clean     # remove build/, dist/ and artifacts/
+    scaldys-project check           # verify project compliance
+
+The Windows distribution step is controlled by ``deployment_mode`` in
+``scaldys.toml``:
+
+    pyinstaller  (default) — PyInstaller exe + Inno Setup installer
+    pyruntime              — binary wheel + Inno Setup installer with PythonRuntime
+    wheel_only             — binary wheel only, no installer
+"""
+
+import logging
+from pathlib import Path
+import typer
+from rich.console import Console
+from rich.logging import RichHandler
+
+from scaldys_project.windows.builder import WindowsBuilder
+
+
+def _find_project_root() -> Path:
+    """
+    Walk up from the current directory to find the project root.
+
+    The project root is identified as the first directory containing a
+    ``pyproject.toml`` file.  Falls back to ``cwd`` if none is found.
+    """
+    cwd = Path.cwd()
+    for candidate in [cwd, *cwd.parents]:
+        if (candidate / "pyproject.toml").exists():
+            return candidate
+    return cwd
+
+
+PROJECT_ROOT = _find_project_root()
+
+console = Console()
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(message)s",
+    datefmt="[%X]",
+    handlers=[RichHandler(rich_tracebacks=True, console=console, show_path=False, markup=True)],
+)
+logger = logging.getLogger(__name__)
+
+app = typer.Typer(help="Scaldys Builder", no_args_is_help=True)
+build_app = typer.Typer(help="Build subcommands", no_args_is_help=True)
+
+app.add_typer(build_app, name="build")
+
+
+@build_app.command("all")
+def build_all(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable verbose output."),
+) -> None:
+    """Full build: documentation + Windows distribution."""
+    builder = WindowsBuilder(PROJECT_ROOT, verbose=verbose)
+    builder.main(console=console)
+
+
+@build_app.command("docs")
+def build_docs(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable verbose output."),
+) -> None:
+    """Build documentation only."""
+    builder = WindowsBuilder(PROJECT_ROOT, verbose=verbose)
+    builder.env.pre_flight_checks(require_sphinx=True)
+    builder.build_docs()
+
+
+@build_app.command("windows")
+def build_windows(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable verbose output."),
+) -> None:
+    """Build Windows distribution artifact (behaviour depends on deployment_mode in scaldys.toml)."""
+    builder = WindowsBuilder(PROJECT_ROOT, verbose=verbose)
+    builder.build_distribution(console=console)
+
+
+@build_app.command("clean")
+def build_clean(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable verbose output."),
+) -> None:
+    """Remove build/, dist/ and artifacts/ directories."""
+    builder = WindowsBuilder(PROJECT_ROOT, verbose=verbose)
+    builder.clean()
+
+
+@app.command("check")
+def check(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable verbose output."),
+) -> None:
+    """Check that the current project is compliant with scaldys-project requirements."""
+    try:
+        builder = WindowsBuilder(PROJECT_ROOT, verbose=verbose)
+    except (FileNotFoundError, KeyError) as exc:
+        logger.error(f"[bold red]Cannot read project metadata:[/bold red] {exc}")
+        logger.error(
+            "  [red]\u2717[/red] Ensure a valid 'pyproject.toml' with "
+            "[project] name and version is present at the project root."
+        )
+        raise SystemExit(1) from exc
+
+    mode = builder.env.config.windows.deployment_mode
+    is_wheel_only = mode == "wheel_only"
+    builder.env.check_compliance(require_exe=True, require_installer=not is_wheel_only)
+    logger.info("[bold green]\u2713 Project is compliant.[/bold green]")
+
+
+if __name__ == "__main__":
+    app()

scaldys_project-0.10.0/src/scaldys_project/common/base.py

@@ -0,0 +1,181 @@
+import logging
+import os
+import sys
+import shutil
+import tomllib
+from pathlib import Path
+from subprocess import PIPE, CalledProcessError, run
+from typing import Any
+
+from scaldys_project.common.config import load_config, BuildConfig
+from scaldys_project.common.utils import safe_empty_dir, safe_unlink
+
+logger = logging.getLogger(__name__)
+
+
+class BaseBuildEnvironment:
+    """
+    Handle path discovery, tool location, and command execution.
+
+    This base class manages common paths and tools that are likely to be
+    used across different platforms.
+    """
+
+    def __init__(self, project_path: Path, verbose: bool = False) -> None:
+        """
+        Initialize the build environment.
+
+        Parameters
+        ----------
+        project_path : Path
+            The root directory of the project.
+        verbose : bool, default False
+            If True, set logging level to DEBUG.
+        """
+        if verbose:
+            logger.setLevel(logging.DEBUG)
+
+        self.verbose = verbose
+        self.project_path = project_path.resolve()
+
+        # Read project name and version from pyproject.toml — single source of truth.
+        with open(self.project_path / "pyproject.toml", "rb") as _f:
+            _meta = tomllib.load(_f)["project"]
+        # Raw name (hyphens preserved) — used for exe naming, packaging file names,
+        # and display.  Do not use for Python import paths.
+        self.project_name: str = _meta["name"]
+        # PEP 503/508: package directories must use underscores; hyphens are
+        # valid in pyproject.toml [project] name but illegal in Python imports.
+        self.project_package_name: str = _meta["name"].replace("-", "_")
+        self.version: str = _meta["version"]
+
+        # Load project-specific build configuration from scaldys.toml (defaults if absent).
+        self.config: BuildConfig = load_config(self.project_path)
+
+        self.python_exe_path = Path(sys.executable)
+        self.python_dir_path = self.python_exe_path.parent
+        self.exe_name = self.project_name
+
+        # Core project paths
+        self.build_dir_path = self.project_path.joinpath("build")
+        self.python_version_file_path = self.project_path / ".python-version"
+        self.docs_dir_path = self.project_path.joinpath("docs")
+        self.src_dir_path = self.project_path / self.config.cython.source_root
+        self.dist_dir_path = self.project_path.joinpath("dist")
+        self.artifacts_dir_path = self.project_path.joinpath("artifacts")
+
+        # Executables (find in PATH)
+        self.sphinx_exe_path = self._find_tool(
+            "sphinx-build" + (".exe" if os.name == "nt" else ""), self.python_dir_path
+        )
+        self.sphinx_apidoc_exe_path = self._find_tool(
+            "sphinx-apidoc" + (".exe" if os.name == "nt" else ""), self.python_dir_path
+        )
+
+    def _find_tool(self, name: str, fallback_path: Path) -> Path:
+        """
+        Find a tool in PATH or in a fallback location.
+
+        Parameters
+        ----------
+        name : str
+            The name of the tool executable.
+        fallback_path : Path
+            The directory to look in if the tool is not in PATH.
+
+        Returns
+        -------
+        Path
+            The path to the tool.
+        """
+        tool_path = shutil.which(name)
+        if tool_path:
+            return Path(tool_path)
+        return fallback_path.joinpath(name)
+
+    def run_command(self, cmd: list[str], err_msg: str, cwd: Path | None = None) -> tuple[str, str]:
+        """
+        Run command in subprocess and raise on unexpected exit status.
+
+        Parameters
+        ----------
+        cmd : list of str
+            The command to run.
+        err_msg : str
+            The error message to display if the command fails.
+        cwd : Path, optional
+            The working directory to run the command in.
+
+        Returns
+        -------
+        stdout : str
+            The standard output of the command.
+        stderr : str
+            The standard error of the command.
+
+        Raises
+        ------
+        RuntimeError
+            If the command returns a non-zero exit status.
+        """
+        try:
+            proc = run(
+                cmd,
+                stdout=PIPE,
+                stderr=PIPE,
+                text=True,
+                check=True,
+                cwd=cwd,
+            )
+            return proc.stdout, proc.stderr
+        except CalledProcessError as e:
+            logger.error(f"{err_msg}: {e}")
+            if e.stderr:
+                logger.error(f"Error output: {e.stderr}")
+            raise RuntimeError(err_msg) from e
+        except Exception as e:  # Catch-all for unexpected OS-level errors (FileNotFoundError, etc.)
+            logger.error(f"{err_msg}: {e}")
+            raise RuntimeError(err_msg) from e
+
+
+class BaseBuilder:
+    """
+    Base class for platform-specific builders.
+
+    Orchestrates the build pipeline for a specific platform.
+    """
+
+    def __init__(self, env: BaseBuildEnvironment):
+        """
+        Initialize the builder.
+
+        Parameters
+        ----------
+        env : BaseBuildEnvironment
+            The build environment configuration.
+        """
+        self.env = env
+
+    def pre_flight_checks(self, **kwargs: Any) -> None:
+        """
+        Perform checks before starting the build.
+
+        Parameters
+        ----------
+        **kwargs : Any
+            Arguments passed to the environment's pre-flight checks.
+        """
+        pass
+
+    def clean(self) -> None:
+        """
+        Clean out files generated by previous builds.
+        """
+        target_dirs = [self.env.build_dir_path, self.env.dist_dir_path, self.env.artifacts_dir_path]
+        logger.info("[bold]Cleaning build directories...[/bold]")
+        for path in target_dirs:
+            logger.info(f"  Cleaning directory '{path}'")
+            safe_empty_dir(path)
+
+        for c_file in self.env.src_dir_path.rglob("*.c"):
+            safe_unlink(c_file)

scaldys_project-0.10.0/src/scaldys_project/common/compile_runner.py

@@ -0,0 +1,88 @@
+"""
+Cython compilation runner for scaldys-project.
+
+Invoked as a module by the build system::
+
+    python -P -m scaldys_project.common.compile_runner build_ext --build-lib <path>
+
+Reads the list of modules to compile from ``scaldys.toml`` in the current
+working directory (the consuming project's root).  If no modules are configured
+or ``scaldys.toml`` is absent, exits immediately without error — fully
+supporting pure-Python projects that have no Cython compilation step.
+
+The ``--compiler=msvc`` flag is passed by the build system on Windows because
+the MSVC compiler is required for CPython extension modules.  MinGW is not
+supported for this purpose on Windows builds.
+"""
+
+import os
+import sys
+import tomllib
+from pathlib import Path
+from setuptools import setup, Extension, find_packages
+from setuptools.dist import Distribution
+
+
+class BinaryDistribution(Distribution):
+    """Distribution that always forces a binary package with a platform name."""
+
+    def has_ext_modules(self) -> bool:
+        return True
+
+
+def _load_cython_config() -> tuple[list[str], str]:
+    """
+    Read ``compiled_modules`` and ``source_root`` from ``scaldys.toml`` in cwd.
+
+    Returns
+    -------
+    compiled_modules : list of str
+        Dotted module paths to compile.  Empty list if unconfigured.
+    source_root : str
+        Source directory relative to project root.  Defaults to ``"src"``.
+    """
+    config_file = Path.cwd() / "scaldys.toml"
+    if not config_file.exists():
+        return [], "src"
+    with open(config_file, "rb") as f:
+        data = tomllib.load(f)
+    cython_cfg = data.get("cython", {})
+    return (
+        cython_cfg.get("compiled_modules", []),
+        cython_cfg.get("source_root", "src"),
+    )
+
+
+def _get_extensions(compiled_modules: list[str], source_root: str) -> list[Extension]:
+    extensions = []
+    for module in compiled_modules:
+        source_file = os.path.join(source_root, *module.split(".")) + ".py"
+        extensions.append(Extension(module, sources=[source_file]))
+    return extensions
+
+
+if __name__ == "__main__":
+    # Deferred import: Cython may not be installed in doc-build or pure-Python
+    # environments.  Keeping these imports here ensures the module can be safely
+    # imported without executing it (e.g., by test runners or import scanners).
+    from Cython.Build import cythonize
+    from Cython.Distutils.build_ext import build_ext
+
+    compiled_modules, source_root = _load_cython_config()
+
+    if not compiled_modules:
+        # Nothing to compile; pure-Python project or no modules declared.
+        sys.exit(0)
+
+    setup(
+        name="__compile_runner__",
+        cmdclass={"build_ext": build_ext},
+        ext_modules=cythonize(
+            _get_extensions(compiled_modules, source_root),
+            annotate=False,
+            language_level="3",
+        ),
+        package_dir={"": source_root},
+        packages=find_packages(source_root),
+        distclass=BinaryDistribution,
+    )