tessl/pypi-copier

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Core Operations

Name: tessl/pypi-copier
Author: tessl

The primary functions for template processing in Copier. These functions provide the essential operations for project generation and maintenance workflows.

Capabilities

Project Generation

Generate a new project from a template source (local path or Git repository).

def run_copy(
    src_path: str,
    dst_path: StrOrPath = ".",
    data: AnyByStrDict | None = None,
    **kwargs: Any
) -> Worker:
    """
    Copy a template to a destination from zero.
    
    Parameters:
    - src_path (str): Template source path (local or Git URL)
    - dst_path (StrOrPath): Destination path for the new project
    - data (dict, optional): Answers to template questions
    - **kwargs: Additional configuration options
    
    Returns:
    Worker: Configured worker instance after generation
    """

Usage examples:

from copier import run_copy

# Generate from Git repository
worker = run_copy(
    src_path="https://github.com/copier-org/copier.git",
    dst_path="./my-project",
    data={"project_name": "MyApp", "author": "Jane Doe"}
)

# Generate from local template
worker = run_copy(
    src_path="./my-template",
    dst_path="./new-project",
    data={"version": "1.0.0"}
)

# Use specific Git ref
worker = run_copy(
    src_path="https://github.com/user/template.git",
    dst_path="./project",
    vcs_ref="v2.0.0",
    data={"feature_enabled": True}
)

Project Updates

Update an existing project when the template evolves, preserving local changes and applying template updates.

def run_update(
    dst_path: StrOrPath = ".",
    data: AnyByStrDict | None = None,
    **kwargs: Any
) -> Worker:
    """
    Update a subproject from its template with evolution.
    
    Parameters:
    - dst_path (StrOrPath): Path to existing project to update
    - data (dict, optional): New or updated answers
    - **kwargs: Additional configuration options
    
    Returns:
    Worker: Configured worker instance after update
    """

Usage examples:

from copier import run_update

# Update current directory project
worker = run_update()

# Update specific project with new data
worker = run_update(
    dst_path="./my-project",
    data={"new_feature": True, "version": "2.0.0"}
)

# Update to specific template version
worker = run_update(
    dst_path="./my-project",
    vcs_ref="v3.0.0"
)

Project Regeneration

Regenerate a project from its template, discarding evolution but keeping user answers.

def run_recopy(
    dst_path: StrOrPath = ".",
    data: AnyByStrDict | None = None,
    **kwargs: Any
) -> Worker:
    """
    Update a subproject from its template, discarding evolution.
    
    Parameters:
    - dst_path (StrOrPath): Path to existing project to regenerate
    - data (dict, optional): Updated answers for regeneration
    - **kwargs: Additional configuration options
    
    Returns:
    Worker: Configured worker instance after regeneration
    """

Usage examples:

from copier import run_recopy

# Regenerate current directory project
worker = run_recopy()

# Regenerate with updated answers
worker = run_recopy(
    dst_path="./my-project",
    data={"template_version": "latest", "cleanup": True}
)

Common Configuration Options

All core operations accept these common keyword arguments:

vcs_ref (str): Git tag, branch, or commit to use
answers_file (str): Path to answers file (default: ".copier-answers.yml")
exclude (list): File patterns to exclude from processing
skip_if_exists (list): File patterns to skip if they exist
overwrite (bool): Whether to overwrite existing files
defaults (bool): Use default answers without prompting
pretend (bool): Perform dry run without actual changes
quiet (bool): Suppress output during processing
cleanup_on_error (bool): Delete destination on error
unsafe (bool): Allow potentially unsafe template features

Return Value

All core operations return a Worker instance that can be used for:

Accessing generated project metadata
Retrieving template processing results
Chaining additional operations
Context manager usage for cleanup

# Using returned worker
worker = run_copy("template/", "project/")
print(f"Template used: {worker.template}")
print(f"Answers: {worker.data}")

# Context manager usage
with run_copy("template/", "project/") as worker:
    # Additional processing
    pass

Install with Tessl CLI