API

Package copiertv

Validates Copier templates instantiated with various presets.

copiertv.main()

Entrypoint.

Module copiertv.exceptions

Family of exceptions for package API.

exception copiertv.exceptions.ConfigurationAbsence(location=absence.absent)

Bases: Omnierror, FileNotFoundError

Required configuration resource not found.

render_as_markdown()

Parameters:

self

Return type:

tuple[ str, … ]

exception copiertv.exceptions.ConfigurationInvalidity(reason=absence.absent)

Bases: Omnierror, ValueError

Configuration data is invalid or a dependency is missing.

render_as_markdown()

Parameters:

self

Return type:

tuple[ str, … ]

exception copiertv.exceptions.DataInvalidity(path, cause)

Bases: ConfigurationInvalidity

Data file content is invalid.

exception copiertv.exceptions.FileOperationFailure(path, operation='access file')

Bases: Omnierror, OSError

File or directory operation failure.

render_as_markdown()

Parameters:

self

Return type:

tuple[ str, … ]

exception copiertv.exceptions.Omnierror(*posargs, **nomargs)

Bases: Omniexception, Exception

Base for error exceptions raised by package API.

exception copiertv.exceptions.Omniexception(*posargs, **nomargs)

Bases: Omniexception

Base for all exceptions raised by package API.

exception copiertv.exceptions.ValidationCommandFailure(command, returncode, temp_directory=absence.absent, stderr=absence.absent)

Bases: Omnierror

Validation command exited with non-zero status.

render_as_markdown()

Parameters:

self

Return type:

tuple[ str, … ]

Module copiertv.configuration

Configuration loading and management.

class copiertv.configuration.Configuration(*, answers_directory=absence.absent, commands=(), template_directory=absence.absent, preserve=absence.absent, variant_filter=absence.absent, vcs_ref=absence.absent, unsafe=absence.absent)

Bases: DataclassObject

Complete validation configuration.

Variables:

• answers_directory (pathlib.Path | absence.objects.AbsentSingleton) – Directory containing answers-*.yaml files.

• commands (tuple[ copiertv.configuration.ValidationCommand, ... ]) – Validation commands to execute.

• template_directory (pathlib.Path | absence.objects.AbsentSingleton) – Template source directory.

• preserve (bool | absence.objects.AbsentSingleton) – Preserve temporary directories.

• variant_filter (tuple[ str, ... ] | absence.objects.AbsentSingleton) – Only validate these variants.

• vcs_ref (str | absence.objects.AbsentSingleton) – Git ref for copier copy.

• unsafe (bool | absence.objects.AbsentSingleton) – Allow unsafe Copier features.

class copiertv.configuration.ValidationCommand(*, args, cwd=absence.absent)

Bases: DataclassObject

A single validation command with args and working directory.

Variables:

• args (tuple[ str, ... ]) – Argument sequence for the command.

• cwd (str | absence.objects.AbsentSingleton) – Working directory, with placeholder support.

copiertv.configuration.acquire_configuration(appcore_configuration, cli_overrides=absence.absent)

Acquires config from appcore dict and project config.

Merges project configuration with appcore-provided user configuration. CLI overrides take final precedence.

copiertv.configuration.detect_project_root()

Detects project root by walking up for VCS markers.

copiertv.configuration.interpolate_command(command, template_directory, project_directory, temporary_directory, variant)

Interpolates placeholders in command args and cwd.

copiertv.configuration.merge_configurations(base, override)

Merges configurations, override taking precedence.

copiertv.configuration.parse_toml_configuration(path)

Parses configuration from a TOML file.

Module copiertv.engine

Core template validation engine.

class copiertv.engine.ValidationResult(*, variant, temporary_directory, items_attempted, items_generated, preserved)

Bases: DataclassObject

Result of a template validation run.

Variables:

• variant (str)

• temporary_directory (pathlib.Path)

• items_attempted (int)

• items_generated (int)

• preserved (bool)

render_as_markdown()

Renders validation result as Markdown lines.

Parameters:

self

Return type:

tuple[ str, … ]

copiertv.engine.copy_template(answers_file, project_directory, template_directory, vcs_ref=absence.absent, unsafe=False, answers_reader=<function _acquire_answers_file>, copier=absence.absent)

Copies template using Copier Python API.

copiertv.engine.execute_validation_commands(config, template_directory, project_directory, temporary_directory, variant, executor=<function run>)

Executes validation commands sequentially.

copiertv.engine.survey_variants(answers_directory)

Discovers variant names from answers-*.yaml files.

copiertv.engine.validate_variant(variant, config, copier=absence.absent, executor=<function run>)

Validates a single template variant.

Module copiertv.cli

Command-line interface.

copiertv.cli.execute()

Entrypoint for CLI execution.

copiertv.cli.intercept_errors()

Decorator that catches Omnierror for CLI display.

Module copiertv.state

Application state management.

class copiertv.state.Globals(*, application, configuration, directories, distribution, exits, copiertv_configuration)

Bases: Globals

Copiertv-specific global state container.

Extends appcore.Globals with our parsed Configuration object.

Variables:

• application (appcore.application.Information)

• configuration (accretive.dictionaries.Dictionary[ str, typing_extensions.Any ])

• directories (platformdirs.unix.Unix)

• distribution (appcore.distribution.Information)

• exits (contextlib.AsyncExitStack)

• copiertv_configuration (copiertv.configuration.Configuration)