python-package-copier-template 0.4.3__tar.gz

python_package_copier_template-0.4.3/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.3
+Name: python-package-copier-template
+Version: 0.4.3
+Summary: A Copier template for modern Python projects.
+Author: Martín Gaitán
+Author-email: Martín Gaitán <gaitan@gmail.com>
+Requires-Dist: copier>=9.11.0
+Requires-Dist: copier-templates-extensions>=0.3.2
+Requires-Dist: ruff>=0.14.9
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Modern Python package template
+
+[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-purple.json)](https://github.com/copier-org/copier)
+[![CI](https://github.com/mgaitan/python-package-copier-template/actions/workflows/ci.yml/badge.svg)](https://github.com/mgaitan/python-package-copier-template/actions/workflows/ci.yml)
+[![Changelog](https://img.shields.io/github/v/release/mgaitan/python-package-copier-template)](https://github.com/mgaitan/python-package-copier-template/releases)
+
+A [Copier](https://github.com/copier-org/copier) template
+for modern Python projects. 
+
+Demo repo generated from this template: [mgaitan/yet-another-demo](https://github.com/mgaitan/yet-another-demo)
+
+## Features
+
+- 🐍 Modern Python package (3.12+)
+- 📦 Build and dependency management with [uv](https://docs.astral.sh/uv/), split by groups (dev/qa/docs)
+- 🧊 Dependency cooldowns enabled by default in `uv` (`[tool.uv].exclude-newer = "1 week"`), with targeted overrides when needed (for example `ty`) to reduce supply-chain risk without blocking QA tools
+- 🧹 Linting and formatting via [Ruff](https://docs.astral.sh/ruff/) with a broad set of rules enabled
+- ✅ Type checking via [ty](https://github.com/astral-sh/ty)
+- 🪝 Optional pre-commit style QA orchestration via [prek](https://github.com/j178/prek) as an external tool (`uv tool install prek`; hooks include `check-ast`, `check-yaml`, `check-toml`, Ruff, Ty)
+- 🧪 Tests with [pytest](https://docs.pytest.org/en/stable/), [coverage.py](https://coverage.readthedocs.io/en/latest/) and extensions
+- 📚 Docs with [Sphinx](https://www.sphinx-doc.org/en/master/), [MyST](https://myst-parser.readthedocs.io/en/stable/) and a few extensions, deployed to [GitHub Pages](https://pages.github.com/)
+- 👀 Automatic docs preview deployment for PRs that modify documentation (`/_preview/pr-<PR_NUMBER>/` on GitHub Pages)
+- 🧭 Generated docs follow [Diataxis](https://diataxis.fr/) and document rationale in [`about_the_docs`](project/docs/about_the_docs.md.jinja)
+- 🏗️ Use of [GitHub CLI](https://cli.github.com/) for autotic project creation 
+- ⚙️ CI workflow on [GitHub Actions](https://github.com/features/actions)
+- 🚀 Automated releases to PyPI via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
+- 🧠 Sensible defaults via introspection to minimize answers during the initial setup
+- 🛠️ Makefile with shortcuts for common tasks
+- 📄 Generation of generic docs such as `LICENSE`, `CODE_OF_CONDUCT`, etc.
+- 🤖 Heavily curated [AGENTS.md](https://agents.md/)
+- 🌀 Initial setup of the development environment and git repo
+- 🔁 Scheduled template refresh workflow that opens a PR every 20 days when updates are available
+- ♻️ Projects updatable with [`copier update`](https://copier.readthedocs.io/en/stable/updating/)
+
+Please read [my blog post](https://mgaitan.github.io/en/posts/opinionated-python-project-scaffolding/) to learn about the details of the decisions I made and the alternatives I considered.
+
+## Package Documentation
+
+The package now includes a Diataxis-based docs set under `docs/` that expands this README:
+
+- [Tutorial: Getting started](docs/getting_started.md)
+- [How-to: Maintain the template](docs/maintain_template.md)
+- [Reference: Configuration](docs/configuration.md)
+- [Explanation: About these docs](docs/about_the_docs.md)
+- [Explanation: Design decisions](docs/design_decisions.md)
+
+## Quick setup and usage
+
+Quick shortcut (auto-detects copy vs update):
+
+```bash
+uvx python-package-copier-template [PATH_TO_PROJECT]
+```
+
+This runs `copier copy --defaults --unsafe` to `PATH_TO_PROJECT` (or `.` if omitted) when no `.copier-answers.yml` is present, or `copier update --defaults --unsafe` when it is.
+Check the installed version with `uvx python-package-copier-template --version`.
+When installed from PyPI, the wrapper copies from the matching template release instead of always using `main`.
+
+If you want the latest development version straight from this repository instead of the latest published release, use:
+
+```bash
+uvx git+https://github.com/mgaitan/python-package-copier-template [PATH_TO_PROJECT]
+```
+
+You can check that wrapper version with `uvx git+https://github.com/mgaitan/python-package-copier-template -- --version`.
+
+Start a new project explicitly with Copier if you want to bypass the wrapper:
+
+```bash
+uvx --with=copier-template-extensions copier copy --trust "gh:mgaitan/python-package-copier-template" /path/to/your/new/project
+```
+
+To upgrade an existing project created from this template to the latest version, run:
+
+```bash
+uvx --with=copier-template-extensions copier update . --trust 
+```
+
+This will fetch the latest template version and guide you through updating your project, preserving your customizations whenever possible.
+
+The generated project also ships a `Template Update` GitHub Actions workflow that runs every 20 days (or on manual dispatch) to execute `uvx copier update --trust --defaults .` and open a pull request with the changes and template version bump.
+
+To test a local development version of the template, clone the repository and run:
+
+```bash
+uv sync
+uv run copier copy --trust  --vcs-ref=HEAD . /path/to/your/test/project
+```
+
+If you create the GitHub repository via the `gh` CLI prompt, the template will attempt to enable GitHub Pages (using the Actions build type) so documentation deployments succeed. If Pages is unavailable (for example, with some private repositories or account policies), the docs workflow will keep failing until Pages is allowed.
+
+
+To publish a release of your project to PyPI, you need to [register the project with trusted publishing](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/). Read more about how this workflow works [here](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/).
+
+This repository's own release workflow also refreshes the demo repository after a successful publish. That step requires the `DEMO_REPO_TOKEN` GitHub Actions secret, documented in [Configuration](docs/configuration.md).
+
+Then
+
+```
+$ make bump    # optional
+$ make release
+```
+
+
+### Acknowledgement
+
+This project template started as a fork of [pawamoy/copier-uv](https://github.com/pawamoy/copier-uv). Then I simplified and changed it to fit my needs.

python_package_copier_template-0.4.3/README.md

@@ -0,0 +1,107 @@
+# Modern Python package template
+
+[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-purple.json)](https://github.com/copier-org/copier)
+[![CI](https://github.com/mgaitan/python-package-copier-template/actions/workflows/ci.yml/badge.svg)](https://github.com/mgaitan/python-package-copier-template/actions/workflows/ci.yml)
+[![Changelog](https://img.shields.io/github/v/release/mgaitan/python-package-copier-template)](https://github.com/mgaitan/python-package-copier-template/releases)
+
+A [Copier](https://github.com/copier-org/copier) template
+for modern Python projects. 
+
+Demo repo generated from this template: [mgaitan/yet-another-demo](https://github.com/mgaitan/yet-another-demo)
+
+## Features
+
+- 🐍 Modern Python package (3.12+)
+- 📦 Build and dependency management with [uv](https://docs.astral.sh/uv/), split by groups (dev/qa/docs)
+- 🧊 Dependency cooldowns enabled by default in `uv` (`[tool.uv].exclude-newer = "1 week"`), with targeted overrides when needed (for example `ty`) to reduce supply-chain risk without blocking QA tools
+- 🧹 Linting and formatting via [Ruff](https://docs.astral.sh/ruff/) with a broad set of rules enabled
+- ✅ Type checking via [ty](https://github.com/astral-sh/ty)
+- 🪝 Optional pre-commit style QA orchestration via [prek](https://github.com/j178/prek) as an external tool (`uv tool install prek`; hooks include `check-ast`, `check-yaml`, `check-toml`, Ruff, Ty)
+- 🧪 Tests with [pytest](https://docs.pytest.org/en/stable/), [coverage.py](https://coverage.readthedocs.io/en/latest/) and extensions
+- 📚 Docs with [Sphinx](https://www.sphinx-doc.org/en/master/), [MyST](https://myst-parser.readthedocs.io/en/stable/) and a few extensions, deployed to [GitHub Pages](https://pages.github.com/)
+- 👀 Automatic docs preview deployment for PRs that modify documentation (`/_preview/pr-<PR_NUMBER>/` on GitHub Pages)
+- 🧭 Generated docs follow [Diataxis](https://diataxis.fr/) and document rationale in [`about_the_docs`](project/docs/about_the_docs.md.jinja)
+- 🏗️ Use of [GitHub CLI](https://cli.github.com/) for autotic project creation 
+- ⚙️ CI workflow on [GitHub Actions](https://github.com/features/actions)
+- 🚀 Automated releases to PyPI via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
+- 🧠 Sensible defaults via introspection to minimize answers during the initial setup
+- 🛠️ Makefile with shortcuts for common tasks
+- 📄 Generation of generic docs such as `LICENSE`, `CODE_OF_CONDUCT`, etc.
+- 🤖 Heavily curated [AGENTS.md](https://agents.md/)
+- 🌀 Initial setup of the development environment and git repo
+- 🔁 Scheduled template refresh workflow that opens a PR every 20 days when updates are available
+- ♻️ Projects updatable with [`copier update`](https://copier.readthedocs.io/en/stable/updating/)
+
+Please read [my blog post](https://mgaitan.github.io/en/posts/opinionated-python-project-scaffolding/) to learn about the details of the decisions I made and the alternatives I considered.
+
+## Package Documentation
+
+The package now includes a Diataxis-based docs set under `docs/` that expands this README:
+
+- [Tutorial: Getting started](docs/getting_started.md)
+- [How-to: Maintain the template](docs/maintain_template.md)
+- [Reference: Configuration](docs/configuration.md)
+- [Explanation: About these docs](docs/about_the_docs.md)
+- [Explanation: Design decisions](docs/design_decisions.md)
+
+## Quick setup and usage
+
+Quick shortcut (auto-detects copy vs update):
+
+```bash
+uvx python-package-copier-template [PATH_TO_PROJECT]
+```
+
+This runs `copier copy --defaults --unsafe` to `PATH_TO_PROJECT` (or `.` if omitted) when no `.copier-answers.yml` is present, or `copier update --defaults --unsafe` when it is.
+Check the installed version with `uvx python-package-copier-template --version`.
+When installed from PyPI, the wrapper copies from the matching template release instead of always using `main`.
+
+If you want the latest development version straight from this repository instead of the latest published release, use:
+
+```bash
+uvx git+https://github.com/mgaitan/python-package-copier-template [PATH_TO_PROJECT]
+```
+
+You can check that wrapper version with `uvx git+https://github.com/mgaitan/python-package-copier-template -- --version`.
+
+Start a new project explicitly with Copier if you want to bypass the wrapper:
+
+```bash
+uvx --with=copier-template-extensions copier copy --trust "gh:mgaitan/python-package-copier-template" /path/to/your/new/project
+```
+
+To upgrade an existing project created from this template to the latest version, run:
+
+```bash
+uvx --with=copier-template-extensions copier update . --trust 
+```
+
+This will fetch the latest template version and guide you through updating your project, preserving your customizations whenever possible.
+
+The generated project also ships a `Template Update` GitHub Actions workflow that runs every 20 days (or on manual dispatch) to execute `uvx copier update --trust --defaults .` and open a pull request with the changes and template version bump.
+
+To test a local development version of the template, clone the repository and run:
+
+```bash
+uv sync
+uv run copier copy --trust  --vcs-ref=HEAD . /path/to/your/test/project
+```
+
+If you create the GitHub repository via the `gh` CLI prompt, the template will attempt to enable GitHub Pages (using the Actions build type) so documentation deployments succeed. If Pages is unavailable (for example, with some private repositories or account policies), the docs workflow will keep failing until Pages is allowed.
+
+
+To publish a release of your project to PyPI, you need to [register the project with trusted publishing](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/). Read more about how this workflow works [here](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/).
+
+This repository's own release workflow also refreshes the demo repository after a successful publish. That step requires the `DEMO_REPO_TOKEN` GitHub Actions secret, documented in [Configuration](docs/configuration.md).
+
+Then
+
+```
+$ make bump    # optional
+$ make release
+```
+
+
+### Acknowledgement
+
+This project template started as a fork of [pawamoy/copier-uv](https://github.com/pawamoy/copier-uv). Then I simplified and changed it to fit my needs.

python_package_copier_template-0.4.3/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "python-package-copier-template"
+version = "0.4.3"
+description = "A Copier template for modern Python projects."
+readme = "README.md"
+authors = [{ name = "Martín Gaitán", email = "gaitan@gmail.com" }]
+requires-python = ">=3.12"
+dependencies = [
+    "copier>=9.11.0",
+    "copier-templates-extensions>=0.3.2",
+    "ruff>=0.14.9",
+]
+
+[project.scripts]
+python-package-copier-template = "python_package_copier_template.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "python_package_copier_template"
+module-root = ""
+
+[tool.ty.src]
+exclude = [".worktrees/", ".external-worktrees/"]
+
+[tool.ruff]
+line-length = 120
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]
+docs = [
+    "myst-parser>=4.0.1",
+    "richterm[sphinx]>=0.2.0",
+    "sphinx>=8.2.3",
+    "sphinx-book-theme>=1.1.4",
+    "sphinxcontrib-mermaid>=1.0.0",
+]
+qa = [
+    "ty>=0.0.27",
+]

python_package_copier_template-0.4.3/python_package_copier_template/__init__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+__all__ = ["main"]

python_package_copier_template-0.4.3/python_package_copier_template/cli.py

@@ -0,0 +1,119 @@
+import argparse
+import json
+import os
+import subprocess
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, distribution, version
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+from copier import run_copy, run_update
+
+from python_package_copier_template import extensions
+
+TEMPLATE_SRC = "gh:mgaitan/python-package-copier-template"
+ANSWER_FILES: tuple[str, ...] = (".copier-answers.yml", ".copier-answers.yaml")
+
+
+@dataclass(frozen=True)
+class TemplateTarget:
+    src_path: str
+    vcs_ref: str | None = None
+
+
+def get_version() -> str:
+    try:
+        return version("python-package-copier-template")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+def has_answers(dst: Path) -> bool:
+    return any((dst / filename).exists() for filename in ANSWER_FILES)
+
+
+def get_local_git_head(path: str) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "-C", path, "rev-parse", "HEAD"],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        return None
+
+    return result.stdout.strip() or None
+
+
+def resolve_template_target() -> TemplateTarget:
+    try:
+        dist = distribution("python-package-copier-template")
+    except PackageNotFoundError:
+        return TemplateTarget(src_path=TEMPLATE_SRC)
+
+    direct_url_text = dist.read_text("direct_url.json")
+    if direct_url_text:
+        direct_url = json.loads(direct_url_text)
+        url = direct_url.get("url", "")
+        parsed_url = urlparse(url)
+
+        if parsed_url.scheme == "file":
+            path = unquote(parsed_url.path)
+            return TemplateTarget(src_path=path, vcs_ref=get_local_git_head(path))
+
+        if vcs_info := direct_url.get("vcs_info"):
+            return TemplateTarget(
+                src_path=TEMPLATE_SRC,
+                vcs_ref=vcs_info.get("commit_id") or vcs_info.get("requested_revision"),
+            )
+
+    return TemplateTarget(src_path=TEMPLATE_SRC, vcs_ref=dist.version)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python-package-copier-template",
+        description=(
+            "Apply the template via Copier. If the destination has a .copier-answers file, run update; "
+            "otherwise run copy."
+        ),
+    )
+    parser.add_argument(
+        "destination",
+        nargs="?",
+        help="Destination directory.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {get_version()}")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    copy_defaults = os.environ.get("COPIER_TEMPLATE_DEFAULTS") == "1"
+    if not args.destination:
+        parser.error("Destination path is required. Use Copier directly if you want interactive prompts.")
+
+    dst = Path(args.destination).expanduser()
+    if has_answers(dst):
+        with extensions.update_mode():
+            run_update(
+                dst_path=str(dst),
+                defaults=True,
+                unsafe=True,
+                overwrite=True,
+                skip_answered=True,
+            )
+    else:
+        template_target = resolve_template_target()
+        run_copy(
+            src_path=template_target.src_path,
+            dst_path=str(dst),
+            defaults=copy_defaults,
+            unsafe=True,
+            vcs_ref=template_target.vcs_ref,
+        )
+
+    return 0

python_package_copier_template-0.4.3/python_package_copier_template/extensions.py

@@ -0,0 +1,140 @@
+import re
+import shutil
+import subprocess
+import unicodedata
+import urllib.error
+import urllib.request
+from contextlib import contextmanager
+from contextvars import ContextVar
+from datetime import date
+from pathlib import Path
+
+from jinja2.ext import Extension
+
+_UPDATE_MODE: ContextVar[bool] = ContextVar("copier_template_update_mode", default=False)
+
+
+@contextmanager
+def update_mode():
+    """Mark the current execution context as an update operation."""
+
+    token = _UPDATE_MODE.set(True)
+    try:
+        yield
+    finally:
+        _UPDATE_MODE.reset(token)
+
+
+def git_user_name(default: str) -> str:
+    return subprocess.getoutput("git config user.name").strip() or default
+
+
+def git_user_email(default: str) -> str:
+    return subprocess.getoutput("git config user.email").strip() or default
+
+
+def gh_user_login(default: str) -> str:
+    """Return the authenticated GitHub username via the GH CLI when available."""
+
+    try:
+        completed = subprocess.run(
+            ["gh", "api", "user", "-q", ".login"],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        login = completed.stdout.strip()
+        if login:
+            return login
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        return default
+
+    return default
+
+
+def command_available(command: str) -> bool:
+    """Return True if the command exists on PATH."""
+
+    return shutil.which(command) is not None
+
+
+def slugify(value, separator="-"):
+    value = unicodedata.normalize("NFKD", str(value)).encode("ascii", "ignore").decode("ascii")
+    value = re.sub(r"[^\w\s-]", "", value.lower())
+    return re.sub(r"[-_\s]+", separator, value).strip("-_")
+
+
+def path_exists(path: str) -> bool:
+    """Return True when ``path`` exists relative to the destination."""
+
+    return Path(path).expanduser().exists()
+
+
+def is_update(defaults: bool | None = None) -> bool:
+    """Return True when running under `copier update`."""
+
+    return bool(defaults)
+
+
+def pypi_distribution_exists(name: str) -> bool:
+    """Return True if a distribution with ``name`` is present on PyPI.
+
+    Uses the lightweight JSON endpoint and handles network failures gracefully
+    by treating them as "not found" so template execution is not blocked.
+    """
+
+    # During updates we keep the previously selected distribution name and
+    # should not block on global PyPI availability checks.
+    if _UPDATE_MODE.get():
+        return False
+
+    if not name:
+        return False
+
+    url = f"https://pypi.org/pypi/{name}/json"
+    request = urllib.request.Request(url, method="HEAD")
+    try:
+        with urllib.request.urlopen(request, timeout=3):
+            return True
+    except (urllib.error.HTTPError, OSError):
+        return False
+
+
+def suggest_pypi_distribution_name(name: str) -> str:
+    """Return a PyPI-safe distribution name, adding a suffix if needed."""
+
+    base = slugify(name)
+    if not base:
+        base = "package"
+
+    candidate = base
+    suffix = 1
+    while pypi_distribution_exists(candidate) and suffix < 50:
+        candidate = f"{base}-{suffix}"
+        suffix += 1
+    return candidate
+
+
+class GitExtension(Extension):
+    def __init__(self, environment):
+        super().__init__(environment)
+        environment.filters["git_user_name"] = git_user_name
+        environment.filters["git_user_email"] = git_user_email
+        environment.filters["gh_user_login"] = gh_user_login
+        environment.filters["command_available"] = command_available
+        environment.filters["path_exists"] = path_exists
+        environment.filters["is_update"] = is_update
+
+
+class SlugifyExtension(Extension):
+    def __init__(self, environment):
+        super().__init__(environment)
+        environment.filters["slugify"] = slugify
+        environment.filters["pypi_exists"] = pypi_distribution_exists
+        environment.filters["pypi_suggest_name"] = suggest_pypi_distribution_name
+
+
+class CurrentYearExtension(Extension):
+    def __init__(self, environment):
+        super().__init__(environment)
+        environment.globals["current_year"] = date.today().year