or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-usage.mdcore-operations.mderror-handling.mdindex.mdtypes-enums.md
tile.json

tessl/pypi-copier

A library for rendering project templates from Git repositories with Jinja2 templating and interactive questionnaires.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/copier@9.10.x

To install, run

npx @tessl/cli install tessl/pypi-copier@9.10.0

index.mddocs/

Copier

A library for rendering project templates from Git repositories with Jinja2 templating and interactive questionnaires. Copier enables developers to create, maintain, and evolve software project scaffolding from templates, supporting both local and remote Git-based templates with dynamic value replacement and project lifecycle management.

Package Information

  • Package Name: copier
  • Language: Python
  • Installation: pip install copier

Core Imports

from copier import run_copy, run_recopy, run_update

For advanced usage:

from copier import Worker, Settings, VcsRef
from copier._types import Phase

For error handling:

from copier.errors import (
    CopierError, UserMessageError, UnsafeTemplateError,
    ConfigFileError, PathError, TaskError
)

For CLI application:

from copier._cli import CopierApp

For package version:

from copier import __version__

CLI Usage

# Install copier as a CLI tool
pipx install copier
# or
uv tool install copier

# Generate a project from a template
copier copy path/to/template path/to/destination
copier copy https://github.com/user/template.git ./my-project

# Update an existing project
copier update ./my-project

# Regenerate from template (discarding evolution)
copier recopy ./my-project

# Use specific template version
copier copy --vcs-ref=v2.0.0 template/ project/

# Provide answers without prompting
copier copy --data project_name="MyApp" template/ project/

Basic Usage

from copier import run_copy, run_recopy, run_update

# Generate a new project from a template
worker = run_copy(
    src_path="https://github.com/copier-org/copier.git",
    dst_path="./my-new-project",
    data={"project_name": "MyProject", "author": "John Doe"}
)

# Update an existing project when template evolves
worker = run_update(
    dst_path="./my-existing-project",
    data={"new_feature": True}
)

# Regenerate project from template (discarding evolution)
worker = run_recopy(
    dst_path="./my-existing-project"
)

Architecture

Copier follows a three-tier architecture:

  • Template Processing: Jinja2-based templating with custom extensions for dynamic file generation
  • Version Control Integration: Git-based template versioning with support for tags, branches, and commits
  • User Interaction: Interactive questionnaires with type validation and answer persistence
  • Project Lifecycle: Support for initial generation, updates, and regeneration workflows

The Worker class serves as the main coordinator, managing template processing, user data collection, and file operations through a context manager pattern.

Capabilities

Core Operations

The primary functions for template processing: generating new projects, updating existing projects with template evolution, and regenerating projects from templates.

def run_copy(
    src_path: str,
    dst_path: StrOrPath = ".",
    data: AnyByStrDict | None = None,
    **kwargs: Any
) -> Worker: ...

def run_update(
    dst_path: StrOrPath = ".",
    data: AnyByStrDict | None = None,
    **kwargs: Any
) -> Worker: ...

def run_recopy(
    dst_path: StrOrPath = ".",
    data: AnyByStrDict | None = None,
    **kwargs: Any
) -> Worker: ...

Core Operations

Advanced Usage

The Worker class for fine-grained control over template processing, and Settings class for user configuration management.

class Worker:
    def __init__(
        self,
        src_path: StrOrPath | None = None,
        dst_path: StrOrPath = ".",
        **kwargs: Any
    ): ...
    
    def run_copy(self) -> Worker: ...
    def run_update(self) -> Worker: ...
    def run_recopy(self) -> Worker: ...

class Settings:
    defaults: dict[str, Any]
    trust: set[str]
    
    @classmethod
    def from_file(cls, path: StrOrPath | None = None) -> Settings: ...

Advanced Usage

Types and Enums

Type definitions, enums, and constants used throughout the copier API for type safety and configuration.

class VcsRef(str, Enum):
    CURRENT = ":current:"

class Phase(str, Enum):
    PROMPT = "prompt"
    TASKS = "tasks"
    MIGRATE = "migrate"
    RENDER = "render"
    UNDEFINED = "undefined"

Types and Enums

Error Handling

Comprehensive exception hierarchy for handling template processing errors, configuration issues, and user interaction problems.

class CopierError(Exception): ...
class UserMessageError(CopierError): ...
class UnsafeTemplateError(CopierError): ...
class ConfigFileError(CopierError): ...
class PathError(CopierError): ...
class TaskError(CopierError): ...

Error Handling

CLI Application

Command-line interface classes for running copier operations from the command line.

class CopierApp:
    """Main CLI application class."""
    
    @classmethod
    def run(cls) -> None: ...

class CopierCopySubApp:
    """Copy subcommand application."""

class CopierRecopySubApp:
    """Recopy subcommand application."""

class CopierUpdateSubApp:
    """Update subcommand application."""

Package Constants

__version__: str  # Package version string

Common Type Aliases

StrOrPath = Union[str, Path]
AnyByStrDict = dict[str, Any]
OptStrOrPath = Optional[StrOrPath]
JSONSerializable = Union[dict, list, str, int, float, bool, None]