clean_files

Deletes the specified files. Intended for use after create_files(). Use delete_files() if wildcards are required.

Signature:

def clean_files(paths: Sequence[Path], verbose:bool=True) -> None:

paths:
    files to delete

verbose:
    whether to print information

Example:

from pretf import workflow


def pretf_workflow():
    created = workflow.create_files()
    proc = workflow.execute_terraform()
    workflow.clean_files(created)
    return proc

create_files

Creates *.tf.json and *.tfvars.json files in target_dir from *.tf.py and *.tfvars.py in source_dirs.

target_dir defaults to the current working directory and source_dirs defaults to a list containing target_dir.

If multiple source_dirs are specified, and there are duplicate file names, the files in the latter directories take precedence.

It is recommended to call create() only once. Pass in multiple source_dirs rather than calling it multiple times. Pretf parses variables from files in the current directory and the source_dirs. Calling it multiple times with different source_dirs could give Pretf a different set of files to parse each time it is called, resulting in different variables each time.

Signature:

def create_files(
    target_dir: Union[Path, str] = "",
    source_dirs: Sequence[Union[Path, str]] = [],
    verbose: bool = True,
) -> List[Path]:

Example:

from pretf import workflow


def pretf_workflow():
    workflow.create_files()
    return workflow.execute_terraform()

custom

Calls the pretf_workflow() function from the specified Python file. This is useful for having a custom workflow that is used by multiple pretf.workflow.py files in different directories.

Signature:

def custom(module_path: Union[PurePath, str], context: Optional[dict] = None) -> int:

module_path:
    file path for the Python module
context:
    dictionary to pass into the pretf_workflow() function

returns:
    exit code for when pretf finishes

Example:

from pretf import workflow


def pretf_workflow():
    return workflow.custom("../src/pretf_workflow.py")

default

This is the default Pretf workflow. This is automatically used when there is no pretf.workflow.py file in the current directory, or it can be called directly from a custom workflow function if it just needs to do something before or after the default workflow.

Signature:

def default(
    clean: bool = True,
    created: list = [],
    verbose: bool = True,
) -> CompletedProcess:

clean:
    whether to delete created files afterwards

created:
    extra files to delete afterwards

verbose:
    whether to print information

returns:
    exit code for when pretf finishes

Example:

from pretf import workflow


def pretf_workflow():
    workflow.create_files()
    return workflow.default()

delete_files

Deletes matching files from the current directory. Defaults to deleting files normally created by the create() function. Optionally exclude files matching a specified pattern.

Signature:

def delete_files(
    *path_patterns: str,
    exclude_name_patterns: Sequence[str] = [],
    cwd: Optional[Union[Path, str]] = None,
    verbose: bool = True,
) -> List[Path]:

path_patterns:
    path glob patterns to mirror into the current directory
    defaults to ("*.tf.json", "*.tfvars.json")
exclude_name_patterns:
    name glob patterns to exclude
cwd:
    current directory
verbose:
    whether to print information

returns:
    removed files

Example:

from pretf import workflow


def pretf_workflow():
    workflow.delete_files()
    return workflow.execute_terraform()

delete_links

Deletes symlinks from the current directory.

Signature:

def delete_files(
    cwd: Optional[Union[Path, str]] = None,
    verbose: bool = True,
) -> List[Path]:

cwd:
    current directory
verbose:
    whether to print information

returns:
    removed files

Example:

from pretf import workflow


def pretf_workflow():
    workflow.delete_links()
    workflow.link_files("*.tf.py")
    return workflow.execute_terraform()

execute_terraform

Executes Terraform and waits for it to finish. Command line arguments are passed through to Terraform. Returns the exit code from Terraform.

Signature:

def execute_terraform(verbose: bool = True) -> int:

verbose:
    whether to print the command

returns:
    exit code from the process

Example:

from pretf import workflow


def pretf_workflow():
    return workflow.execute_terraform()

load_parent

Looks for the closest pretf.workflow.py file in parent directories and calls the pretf_workflow() function. Errors if there are no pretf.workflow.py files in any parent directories.

Signature:

def load_parent(**kwargs: Any) -> CompletedProcess:

kwargs:
    keyword arguments to pass into the pretf_workflow() function

returns:
    exit code for when pretf finishes

Example:

from pretf import workflow


def pretf_workflow():
    workflow.require_files("terraform.tfvars")
    return workflow.load_parent()

link_files

Creates symlinks from all files and directories matching the source patterns into the current directory.

Signature:

def mirror_files(
    *path_patterns: Union[Path, str],
    exclude_name_patterns: Sequence[str] = [".*", "_*", "pretf.workflow.py"],
    cwd: Optional[Union[Path, str]] = None,
    verbose: bool = True,
) -> List[Path]:

path_patterns:
    paths or path glob patterns to mirror into the current directory
exclude_name_patterns:
    name glob patterns to exclude
cwd:
    current directory
verbose:
    whether to print information

returns:
    created symlinks

Example:

from pretf import workflow


def pretf_workflow():
    workflow.delete_links()
    workflow.link_files("*.tf.py")
    return workflow.execute_terraform()

link_module

Creates symlinks from all files and directories in a module into the current directory. Remote modules are first downloaded into a cache directory.

Signature:

def link_module(
    source: Union[Path,str],
    version: Optional[str] = None,
    update: bool = False,
    cache_dir: Optional[Union[Path, str]] = None,
    cwd: Optional[Union[Path, str]] = None,
    verbose: bool = True,
) -> List[Path]:

source:
    location of module to mirror into the current directory
version:
    the module version (if using registry)
update:
    whether to fetch the module every time, or use a cached copy
cache_dir:
    location to use for caching modules
cwd:
    current directory
verbose:
    whether to print information

returns:
    created symlinks

Example:

from pretf import workflow


def pretf_workflow():
    workflow.delete_links()
    workflow.link_module("claranet/vpc-modules/aws", version="1.1.0")
    return workflow.execute_terraform()

mirror_files

This function will be removed in a future version. Use delete_links and link_files instead.

Creates symlinks from all files and directories matching the source patterns into the current directory. Deletes all pre-existing symlinks in the current directory.

Signature:

def mirror_files(
    *path_patterns: Union[Path, str],
    exclude_name_patterns: Sequence[str] = [".*", "_*", "pretf.workflow.py"],
    include_directories: bool = True,
    cwd: Optional[Union[Path, str]] = None,
    verbose: bool = True,
) -> List[Path]:

path_patterns:
    paths or path glob patterns to mirror into the current directory
exclude_name_patterns:
    name glob patterns to exclude
cwd:
    current directory
verbose:
    whether to print information

returns:
    created symlinks

Example:

from pretf import workflow


def pretf_workflow():
    workflow.mirror_files("../src/*")
    return workflow.execute_terraform()

require_files

Raises an exception if the specified files are not found in the current directory. Pretf will catch this exception, display an error message, and show other directories that do contain the files.

This can be used to restrict where Pretf/Terraform can run, while informing users where it can run if they make a mistake.

If multiple patterns are provided, the directory must contain files that match all patterns (performing an AND search).

def require_files(*name_patterns: str) -> None:

name_patterns:
    name glob patterns to require

Example:

from pretf import workflow


def pretf_workflow():
    workflow.require_files("*.tfvars")
    return workflow.default()