types

Datatypes for templates.

Templates are a representation of source templates used to generate projects.

Classes

Locality

Bases: str, Enum

The locality of a template.

Template dataclass

Template(
    repo: TemplateRepo,
    directory: str = "",
    _context: Optional[OrderedDict] = None,
)

A template is the combination of a template repository and a directory containing a cookiecutter.json file.

Attributes

cached_path property

cached_path: Path

The path to the cached template.

context property

context: dict

The context of the template.

context_file_path property

context_file_path: Path

The path to the template’s context file.

directory class-attribute instance-attribute

directory: str = ''

The directory within the repository that contains the cookiecutter.json file.

name property

name: str

The name of the template.

repo instance-attribute

repo: TemplateRepo

The source of the template.

Functions

cleanup

cleanup() -> None

Remove the cached template if it is a Zipfile.

TemplateFormat

Bases: str, Enum

The format of a template.

Attributes

PLAIN class-attribute instance-attribute

PLAIN = 'plain'

A plain directory that isn’t under version control.

TemplateRepo dataclass

TemplateRepo(
    source: str,
    cached_source: Path,
    format: TemplateFormat,
    locality: Locality,
    checkout: Optional[str] = None,
    password: Optional[str] = None,
)

A template repository is a source of one or more templates.

Attributes

cached_source instance-attribute

cached_source: Path

The path to the locally cached template.

checkout class-attribute instance-attribute

checkout: Optional[str] = None

The branch, tag or commit for the template to track.

current_sha property

current_sha: Optional[str]

If the template is a git repository, return the current commit hash.

format instance-attribute

format: TemplateFormat

The format of the template.

latest_sha property

latest_sha: Optional[str]

Return the latest SHA of this template’s repo.

If the template is not a git repository, it will always return None.

Returns:

Optional[str]

The latest hexsha of the template or None if the template isn’t a git repo

locality instance-attribute

locality: Locality

Is the template local or remote?

password class-attribute instance-attribute

password: Optional[str] = None

The password to use if template is a password-protected Zip archive.

source instance-attribute

source: str

The original path or URL to the template.

Functions

render_source

render_source(
    output_dir: Optional[Path] = None,
    commit: Optional[str] = None,
) -> Iterator[Path]

A context manager that provides the source from which to render the template.

For git repositories, this will create a temporary working tree of the repository and yield the path to the working tree.

For Zip archives, this will extract the archive to a temporary directory and yield the path

For plain repos, it will yield the path to the directory.

Parameters:

output_dir

The directory to extract the template to. If not provided, a temporary directory will be used.

TYPE: Optional[Path]

DEFAULT: None

commit

The commit to checkout if the template is a git repository.

TYPE: Optional[str]

DEFAULT: None

YIELDS	DESCRIPTION
Path	The path to the rendered template

Functions

get_template_name

get_template_name(
    path_or_url: str,
    directory: Optional[str] = None,
    checkout: Optional[str] = None,
) -> str

Get the name of the template using the path or URL.

Parameters:

path_or_url

The URL or path to the template

TYPE: str

directory

Directory within a git repository template that holds the cookiecutter.json file.

TYPE: Optional[str]

DEFAULT: None

checkout

The branch, tag or commit to use if template is a git repository.

TYPE: Optional[str]

DEFAULT: None

Raises:

ValueError

If the path_or_url is not parsable

Returns:

str

The name of the template without extensions