API reference

copier

Copier.

Docs: https://copier.readthedocs.io/

Modules:

Name	Description
cli	Deprecated: module is intended for internal use only.
errors	Custom exceptions used by Copier.
jinja_ext	Deprecated: module is intended for internal use only.
main	Deprecated: module is intended for internal use only.
settings	Deprecated: module is intended for internal use only.
subproject	Deprecated: module is intended for internal use only.
template	Deprecated: module is intended for internal use only.
tools	Deprecated: module is intended for internal use only.
types	Deprecated: module is intended for internal use only.
user_data	Deprecated: module is intended for internal use only.
vcs	Deprecated: module is intended for internal use only.

Classes:

Name	Description
Phase	The known execution phases.
Settings	User settings.
VcsRef

Functions:

Name	Description
load_settings	Load settings from a YAML file.
run_copy	Copy a template to a destination, from zero.
run_recopy	Update a subproject from its template, discarding subproject evolution.
run_update	Update a subproject, from its template.

Phase

Bases: str, Enum

The known execution phases.

Methods:

Name	Description
current	Get the current phase.
use	Set the current phase for the duration of a context.

current classmethod

current() -> Phase

Get the current phase.

use classmethod

use(phase: Phase) -> Iterator[None]

Set the current phase for the duration of a context.

Settings dataclass

Settings(defaults: Mapping[str, Any] = dict(), trust: Sequence[str] = list())

User settings.

Attributes:

Name	Type	Description
defaults	Mapping[str, Any]	Default values for questions.
trust	Sequence[str]	Set of trusted repositories or prefixes.

defaults class-attribute instance-attribute

defaults: Mapping[str, Any] = field(default_factory=dict)

Default values for questions.

trust class-attribute instance-attribute

trust: Sequence[str] = field(default_factory=list)

Set of trusted repositories or prefixes.

VcsRef

Bases: Enum

Attributes:

Name	Type	Description
CURRENT		A special value to indicate that the current ref of the existing

CURRENT class-attribute instance-attribute

CURRENT = ':current:'

A special value to indicate that the current ref of the existing template should be used.

load_settings

load_settings(settings_path: Path | None = None) -> Settings

Load settings from a YAML file.

If settings_path is not given, the path is determined from the COPIER_SETTINGS_PATH environment variable or the platform-specific default configuration directory.

Parameters:

Name	Type	Description	Default
settings_path	Path | None	Path to a settings YAML file.	None

Returns:

Type	Description
Settings	Settings loaded from the YAML file.

Raises:

Type	Description
SettingsError	If the settings file is invalid.

run_copy

run_copy(src_path: str, dst_path: Path | str = '.', data: dict[str, Any] | None = None, *, answers_file: Path | str | None = None, vcs_ref: str | VcsRef | None = None, settings: Settings | SettingsModel | None = None, exclude: Sequence[str] = (), use_prereleases: bool = False, skip_if_exists: Sequence[str] = (), cleanup_on_error: bool = True, defaults: bool = False, user_defaults: dict[str, Any] | None = None, overwrite: bool = False, pretend: bool = False, quiet: bool = False, unsafe: bool = False, skip_tasks: bool = False) -> Worker

Copy a template to a destination, from zero.

run_recopy

run_recopy(dst_path: Path | str = '.', data: dict[str, Any] | None = None, *, answers_file: Path | str | None = None, vcs_ref: str | VcsRef | None = None, settings: Settings | SettingsModel | None = None, exclude: Sequence[str] = (), use_prereleases: bool = False, skip_if_exists: Sequence[str] = (), cleanup_on_error: bool = True, defaults: bool = False, user_defaults: dict[str, Any] | None = None, overwrite: bool = False, pretend: bool = False, quiet: bool = False, unsafe: bool = False, skip_answered: bool = False, skip_tasks: bool = False) -> Worker

Update a subproject from its template, discarding subproject evolution.

run_update

run_update(dst_path: Path | str = '.', data: dict[str, Any] | None = None, *, answers_file: Path | str | None = None, vcs_ref: str | VcsRef | None = None, settings: Settings | SettingsModel | None = None, exclude: Sequence[str] = (), use_prereleases: bool = False, skip_if_exists: Sequence[str] = (), cleanup_on_error: bool = True, defaults: bool = False, user_defaults: dict[str, Any] | None = None, overwrite: bool = False, pretend: bool = False, quiet: bool = False, conflict: Literal['inline', 'rej'] = 'inline', context_lines: PositiveInt = 3, unsafe: bool = False, skip_answered: bool = False, skip_tasks: bool = False) -> Worker

Update a subproject, from its template.

errors

Custom exceptions used by Copier.

Classes:

Name	Description
ConfigFileError	Parent class defining problems with the config file.
CopierAnswersInterrupt	CopierAnswersInterrupt is raised during interactive question prompts.
CopierError	Base class for all other Copier errors.
CopierWarning	Base class for all other Copier warnings.
DirtyLocalWarning	Changes and untracked files present in template.
ExtensionNotFoundError	Extensions listed in the configuration could not be loaded.
ForbiddenPathError	The path is forbidden in the given context.
InteractiveSessionError	An interactive session is required to run this program.
InvalidConfigFileError	Indicates that the config file is wrong.
InvalidTypeError	The question type is not among the supported ones.
MissingFileWarning	I still couldn't find what I'm looking for.
MissingSettingsWarning	Settings path has been defined but file is missing.
MultipleConfigFilesError	Both copier.yml and copier.yaml found, and that's an error.
MultipleYieldTagsError	Multiple yield tags are used in one path name, but it is not allowed.
OldTemplateWarning	Template was designed for an older Copier version.
PathError	The path is invalid in the given context.
PathNotAbsoluteError	The path is not absolute, but it should be.
PathNotRelativeError	The path is not relative, but it should be.
ShallowCloneWarning	The template repository is a shallow clone.
TaskError	Exception raised when a task fails.
UnknownCopierVersionWarning	Cannot determine installed Copier version.
UnsafeTemplateError	Unsafe Copier template features are used without explicit consent.
UnsupportedVersionError	Copier version does not support template version.
UserMessageError	Exit the program giving a message to the user.
YieldTagInFileError	A yield tag is used in the file content, but it is not allowed.

ConfigFileError

Bases: ValueError, CopierError

Parent class defining problems with the config file.

CopierAnswersInterrupt

CopierAnswersInterrupt(answers: AnswersMap, last_question: Question, template: Template)

Bases: CopierError, KeyboardInterrupt

CopierAnswersInterrupt is raised during interactive question prompts.

It typically follows a KeyboardInterrupt (i.e. ctrl-c) and provides an opportunity for the caller to conduct additional cleanup, such as writing the partially completed answers to a file.

Attributes:

Name	Type	Description
answers		AnswersMap that contains the partially completed answers object.
last_question		Question representing the last_question that was asked at the time the interrupt was raised.
template		Template that was being processed for answers.

CopierError

Bases: Exception

Base class for all other Copier errors.

CopierWarning

Bases: Warning

Base class for all other Copier warnings.

DirtyLocalWarning

Bases: UserWarning, CopierWarning

Changes and untracked files present in template.

ExtensionNotFoundError

ExtensionNotFoundError(message: str)

Bases: UserMessageError

Extensions listed in the configuration could not be loaded.

ForbiddenPathError

ForbiddenPathError(*, path: Path, hint: str = '')

Bases: PathError

The path is forbidden in the given context.

InteractiveSessionError

InteractiveSessionError(message: str)

Bases: UserMessageError

An interactive session is required to run this program.

InvalidConfigFileError

InvalidConfigFileError(conf_path: Path, quiet: bool)

Bases: ConfigFileError

Indicates that the config file is wrong.

InvalidTypeError

Bases: TypeError, CopierError

The question type is not among the supported ones.

MissingFileWarning

Bases: UserWarning, CopierWarning

I still couldn't find what I'm looking for.

MissingSettingsWarning

Bases: UserWarning, CopierWarning

Settings path has been defined but file is missing.

MultipleConfigFilesError

MultipleConfigFilesError(conf_paths: PathSeq)

Bases: ConfigFileError

Both copier.yml and copier.yaml found, and that's an error.

MultipleYieldTagsError

Bases: CopierError

Multiple yield tags are used in one path name, but it is not allowed.

OldTemplateWarning

Bases: UserWarning, CopierWarning

Template was designed for an older Copier version.

PathError

Bases: CopierError, ValueError

The path is invalid in the given context.

PathNotAbsoluteError

PathNotAbsoluteError(*, path: Path)

Bases: PathError

The path is not absolute, but it should be.

PathNotRelativeError

PathNotRelativeError(*, path: Path)

Bases: PathError

The path is not relative, but it should be.

ShallowCloneWarning

Bases: UserWarning, CopierWarning

The template repository is a shallow clone.

TaskError

TaskError(command: str | Sequence[str], returncode: int, stdout: str | bytes | None, stderr: str | bytes | None)

Bases: CalledProcessError, UserMessageError

Exception raised when a task fails.

Methods:

Name	Description
from_process	Create a TaskError from a CompletedProcess.

from_process classmethod

from_process(process: CompletedProcess[str] | CompletedProcess[bytes]) -> Self

Create a TaskError from a CompletedProcess.

UnknownCopierVersionWarning

Bases: UserWarning, CopierWarning

Cannot determine installed Copier version.

UnsafeTemplateError

UnsafeTemplateError(features: Sequence[str])

Bases: CopierError

Unsafe Copier template features are used without explicit consent.

UnsupportedVersionError

UnsupportedVersionError(message: str)

Bases: UserMessageError

Copier version does not support template version.

UserMessageError

UserMessageError(message: str)

Bases: CopierError

Exit the program giving a message to the user.

YieldTagInFileError

Bases: CopierError

A yield tag is used in the file content, but it is not allowed.