copier.yml

# Copier template: uv-first Python package (optional NumPy/pandas, docs, strict typing)

# -------------------------------------------------------------------------
# Template metadata
# -------------------------------------------------------------------------
# Minimal required Copier version for this template and where the
# template lives inside the repository.
_min_copier_version: "9.11.2"
_subdirectory: template

# Jinja extensions enabled for rendering templates. Add extensions
_jinja_extensions:
  - jinja2_time.TimeExtension
  - jinja2.ext.do
  - jinja2.ext.loopcontrols

# File used to persist answers between runs so re-running copier
# can reuse previously provided values.
_answers_file: ".copier-answers.yml"

# -------------------------------------------------------------------------
# Lifecycle (update safety)
# -------------------------------------------------------------------------
# Files and directories listed here will be preserved on template
# updates to avoid overwriting user edits in generated projects.
_skip_if_exists:
  - docs/
  - .github/CODE_OF_CONDUCT.md
  - .github/ISSUE_TEMPLATE/bug_report.md
  - .github/ISSUE_TEMPLATE/feature_request.md
  - .github/PULL_REQUEST_TEMPLATE.md
  - CLAUDE.md
  - CONTRIBUTING.md
  - env.example
  - mkdocs.yml
  - pyproject.toml
  - README.md
  - SECURITY.md
  - src/{{ package_name }}/__init__.py
  - src/{{ package_name }}/common/bump_version.py



# -------------------------------------------------------------------------
# Questions / Prompts
# -------------------------------------------------------------------------
# Interactive prompts presented when generating a project. Keep
# prompts clear and provide sensible defaults to simplify onboarding.
project_name:
  type: str
  help: Human-readable project name (e.g., "My Library")
  default: "My Library"
  placeholder: "My Library"

project_slug:
  type: str
  default: "{{ project_name | lower | replace(' ', '-') | replace('_', '-') | regex_replace('[^a-z0-9-]', '') }}"
  help: Slug for URLs and package distribution

package_name:
  type: str
  default: "{{ project_name | lower | replace(' ', '_') | replace('-', '_') }}"
  help: Python package name (must be valid Python identifier)
  validator: >-
    {% if not package_name.isidentifier()
       or not package_name.replace('_', '').isalnum() %}
    Package name must be a valid Python identifier (letters, digits, underscores; cannot start with a digit)
    {% endif %}

project_description:
  type: str
  help: Short description of the project
  default: "A Python library"

author_name:
  type: str
  help: Author's full name
  default: "Your Name"

author_email:
  type: str
  help: Author's email
  default: "you@example.com"

github_username:
  type: str
  help: GitHub username or organization
  default: "yourusername"

python_min_version:
  type: str
  help: Minimum Python version
  default: "3.11"
  choices:
    - "3.11"
    - "3.12"
    - "3.13"

license:
  type: str
  help: Project license
  default: MIT
  choices:
    - MIT
    - Apache-2.0
    - BSD-3-Clause
    - GPL-3.0
    - Proprietary

include_docs:
  type: bool
  help: Include MkDocs documentation setup?
  default: true

include_pandas_support:
  type: bool
  help: Include pandas in dependencies?
  default: false

include_numpy:
  type: bool
  help: Include NumPy in dependencies?
  default: false

include_release_workflow:
  type: bool
  help: Add a GitHub Actions release workflow (automated versioning and GitHub Releases)?
  default: true

include_pypi_publish:
  type: bool
  help: "Publish to PyPI on release? (Uses Trusted Publisher / OIDC \u2014 no API token needed)"
  default: false
  when: "{{ include_release_workflow }}"

include_security_scanning:
  type: bool
  help: Add CodeQL security scanning and dependency audit workflow?
  default: true

include_cli:
  type: bool
  help: Generate a Typer-based CLI entry point and console script?
  default: false

include_git_cliff:
  type: bool
  help: Add git-cliff, cliff.toml, and a just changelog recipe for release notes?
  default: true

# -------------------------------------------------------------------------
# Computed values
# -------------------------------------------------------------------------
# Template-generated computed values (not asked interactively).
# Use these for dynamic defaults and CI matrix generation.
current_year:
  type: str
  when: false
  default: "{% now 'utc', '%Y' %}"

# Renders as a JSON array string, e.g. '["3.11", "3.12", "3.13"]'. In workflow templates,
# use fromJson() when passing to a matrix (e.g. matrix.python: ${{ fromJson(...) }}).
github_actions_python_versions:
  type: str
  when: false
  default: >-
    {% if python_min_version == "3.11" -%}
    ["3.11", "3.12", "3.13"]
    {%- elif python_min_version == "3.12" -%}
    ["3.12", "3.13"]
    {%- else -%}
    ["3.13"]
    {%- endif %}

# -------------------------------------------------------------------------
# Post-generation tasks
# -------------------------------------------------------------------------
# Commands run after template rendering.
#
# Notes / rationale:
# - Generated projects are "uv-first" (lock-file-first workflow). These tasks should succeed even
#   when the host Python lacks `ensurepip`/`pip` (common on minimal distro Pythons).
# - To avoid template generation failing on machines without `uv`, we bootstrap `uv` first.
#   We try `pip` if available; otherwise we fall back to Astral's installer script.
# - Keep tasks idempotent.
#
# Copy vs update: these tasks run after both `copier copy` and `copier update` (not gated
# with _copier_operation) so the lockfile and local env stay aligned with the template after
# updates. Consumers may use `copier update --skip-tasks` when they want to skip them.
_tasks:
  - ["git", "init"]
  - command: >-
      sh -c '
      # Bootstrap `uv` if missing.
      #
      # Copier executes tasks via /bin/sh, so this must be POSIX-sh compatible.
      # We try (in order):
      # - existing `uv` on PATH
      # - `python -m pip install uv` (if pip is available)
      # - Astral install script via curl/wget
      if command -v uv >/dev/null 2>&1; then
        exit 0
      fi

      if command -v python >/dev/null 2>&1 && python -m pip --version >/dev/null 2>&1; then
        python -m pip install --upgrade uv && exit 0
      fi

      if command -v python3 >/dev/null 2>&1 && python3 -m pip --version >/dev/null 2>&1; then
        python3 -m pip install --upgrade uv && exit 0
      fi

      if command -v curl >/dev/null 2>&1; then
        curl -LsSf https://astral.sh/uv/install.sh | sh || exit 1
      elif command -v wget >/dev/null 2>&1; then
        wget -qO- https://astral.sh/uv/install.sh | sh || exit 1
      else
        echo "❌ uv is required but was not found. Install from https://docs.astral.sh/uv/ or ensure curl/wget is available." >&2
        exit 1
      fi

      # Astral installer typically drops an env file that prepends ~/.local/bin to PATH.
      if [ -f "$HOME/.local/bin/env" ]; then
        . "$HOME/.local/bin/env"
      fi

      command -v uv >/dev/null 2>&1
      '
  - command: uv lock
  - command: >-
      uv sync --extra dev --extra test
      {%- if include_docs %} --extra docs{% endif -%}
      {%- if include_git_cliff %} --group changelog{% endif %}
  - command: uv run pre-commit install || true
  - command: uv run pre-commit install --hook-type pre-push || true
  - command: uv run ruff check --fix --unsafe-fixes . || true
  - command: uv run basedpyright || true
  - command: sh -c 'rmdir docs 2>/dev/null || true'
    when: "{{ not include_docs }}"
  - command: >-
      sh -c 'find . -type f -empty ! -path "./.git/*" ! -path "./.venv/*" -delete'
  - command: echo "✅ Project {{ project_name }} created successfully!"
  - command: echo "📁 Location $(pwd)"
  - command: echo "🚀 Run 'just ci' to verify everything works"


# -------------------------------------------------------------------------
# Template-only exclusions
# -------------------------------------------------------------------------
# Files and directories present in the template repo that should not
# be copied into generated projects (editor state, virtualenvs, etc.).
_exclude:
  - ".git"
  - ".venv"
  - "__pycache__"
  - "*.pyc"