Skip to content

pattern

Model definitions relating to Pattern configurations.

A pattern consists of a set of template files and a configuration file. The configuration file defines the context required to render the template and the rendering rules.

Patterns are meant to be focused and reusable. Patterns are combined with other patterns using a composition.

Patterns are renderable as-is. They do not need to be a part of a composition.

Attributes

Classes

Choice pydantic-model

Bases: BaseModel

A choice to a Question.

Show JSON schema: 
{
  "description": "A choice to a Question.",
  "properties": {
    "label": {
      "description": "The label for this choice when prompted to the user.",
      "pattern": "[a-zA-Z_][\\w_]*",
      "title": "Label",
      "type": "string"
    },
    "value": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "The value used when this choice is selected. It should match the questions's type.",
      "title": "Value"
    },
    "skip_when": {
      "default": "",
      "description": "A template string that will render as `True` if the choice is not valid based on previous context values.\n\nTake care to have at least one option without a `skip_when` clause to avoid accidentally creating a situation with no valid choices.",
      "title": "Skip When",
      "type": "string"
    }
  },
  "required": [
    "label",
    "value"
  ],
  "title": "Choice",
  "type": "object"
}

Fields:

Validators:

Attributes

label pydantic-field 
label: str

The label for this choice when prompted to the user.

skip_when pydantic-field 
skip_when: str = ''

A template string that will render as True if the choice is not valid based on previous context values.

Take care to have at least one option without a skip_when clause to avoid accidentally creating a situation with no valid choices.

value pydantic-field 
value: ScalarType

The value used when this choice is selected. It should match the questions’s type.

Functions

convert_scalar_to_choice pydantic-validator 
convert_scalar_to_choice(value: Any) -> Any

Convert a scalar value to a Choice object.

Pattern pydantic-model

Bases: BaseModel

The configuration of a pattern.

Show JSON schema: 
{
  "$defs": {
    "Choice": {
      "description": "A choice to a Question.",
      "properties": {
        "label": {
          "description": "The label for this choice when prompted to the user.",
          "pattern": "[a-zA-Z_][\\w_]*",
          "title": "Label",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "integer"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "description": "The value used when this choice is selected. It should match the questions's type.",
          "title": "Value"
        },
        "skip_when": {
          "default": "",
          "description": "A template string that will render as `True` if the choice is not valid based on previous context values.\n\nTake care to have at least one option without a `skip_when` clause to avoid accidentally creating a situation with no valid choices.",
          "title": "Skip When",
          "type": "string"
        }
      },
      "required": [
        "label",
        "value"
      ],
      "title": "Choice",
      "type": "object"
    },
    "Location": {
      "description": "The location of a file or directory.\n\nA location supports referencing the file or directory using:\n\n- relative path\n- absolute path\n- git URL\n- git URL plus revision/tag/branch plus path in the repo\n\nWhen `url` is specified, the `path` is relative to the root of the repository.\n\nAt least one of `path` or `url` must be specified.",
      "properties": {
        "path": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The relative or absolute path to the location.",
          "title": "Path"
        },
        "url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The Git URL to the location.",
          "title": "Url"
        }
      },
      "title": "Location",
      "type": "object"
    },
    "Question": {
      "description": "A question for a pattern.",
      "properties": {
        "name": {
          "description": "The name of the variable used in the template.",
          "pattern": "[a-zA-Z_][\\w_]*",
          "title": "Name",
          "type": "string"
        },
        "type": {
          "default": "str",
          "description": "The type of this variable.",
          "enum": [
            "int",
            "float",
            "bool",
            "str",
            "multiline",
            "secret",
            "yaml",
            "json"
          ],
          "title": "Type",
          "type": "string"
        },
        "prompt": {
          "default": "",
          "description": "The message to ask the user for this information. If no prompt is provided, 'What is the <name>?' is used.",
          "title": "Prompt",
          "type": "string"
        },
        "help": {
          "default": "",
          "description": "Additional information to explain how to answer this question.",
          "title": "Help",
          "type": "string"
        },
        "choices": {
          "description": "A list of choice values or `choice` objects",
          "items": {
            "$ref": "#/$defs/Choice"
          },
          "title": "Choices",
          "type": "array"
        },
        "multiselect": {
          "default": false,
          "description": "When `true` allow multiple selections. The type of this context element will then be a list of this question's `type`",
          "title": "Multiselect",
          "type": "boolean"
        },
        "default": {
          "default": null,
          "description": "Provide a default to save them from typing. \n\nWhen using `choices`, the default must be the choice _value_, not its _key_, and must match its _type_. Leave this empty to force the user to answer.\n\nThis value may also be a template string rendered using the context so far. This allows you to provide defaults based on previous context elements.",
          "title": "Default"
        },
        "validator": {
          "default": "",
          "description": "Template string to validate the user input. \n\nThis template is rendered using the context so far; it should render _nothing_ if the value is valid and an error message to show to the user otherwise.",
          "title": "Validator",
          "type": "string"
        },
        "force_default": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "boolean"
            }
          ],
          "default": false,
          "description": "A condition that, if `True`, will not prompt the user for a value and uses the `default`.\n\n`bool` values are used directly. Setting this to `True` is a good way to make this value a computed value.\n\n`str` values should be template strings that evaluate to a boolean value.",
          "title": "Force Default"
        }
      },
      "required": [
        "name"
      ],
      "title": "Question",
      "type": "object"
    }
  },
  "description": "The configuration of a pattern.",
  "properties": {
    "questions": {
      "description": "A list of question objects that define the available context variables for project generation.",
      "items": {
        "$ref": "#/$defs/Question"
      },
      "title": "Questions",
      "type": "array"
    },
    "template_location": {
      "$ref": "#/$defs/Location",
      "description": "The location of the root directory of the templates. This directory's name will be rendered using the context. "
    },
    "extra_context": {
      "description": "Static Key-Values. Values may be template strings.",
      "title": "Extra Context",
      "type": "object"
    },
    "template_engine": {
      "const": "default",
      "default": "default",
      "description": "The template engine required to render the templates.",
      "title": "Template Engine",
      "type": "string"
    },
    "template_engine_ops": {
      "description": "Options to pass to the template engine before rendering.",
      "title": "Template Engine Ops",
      "type": "object"
    },
    "skip": {
      "description": "A list of paths or glob patterns of files to exclude from writing to the destination.",
      "items": {
        "type": "string"
      },
      "title": "Skip",
      "type": "array"
    },
    "copy_only": {
      "description": "A list of paths or glob patterns of files to write to the destination without rendering.",
      "items": {
        "type": "string"
      },
      "title": "Copy Only",
      "type": "array"
    },
    "migrations": {
      "description": "TBD",
      "items": {},
      "title": "Migrations",
      "type": "array"
    }
  },
  "required": [
    "template_location"
  ],
  "title": "Pattern",
  "type": "object"
}

Fields:

Validators:

Attributes

copy_only pydantic-field 
copy_only: List[str]

A list of paths or glob patterns of files to write to the destination without rendering.

extra_context pydantic-field 
extra_context: Dict[str, Any]

Static Key-Values. Values may be template strings.

migrations pydantic-field 
migrations: List

TBD

questions pydantic-field 
questions: List[Question]

A list of question objects that define the available context variables for project generation.

skip pydantic-field 
skip: List[str]

A list of paths or glob patterns of files to exclude from writing to the destination.

template_engine pydantic-field 
template_engine: TemplateEngine = 'default'

The template engine required to render the templates.

template_engine_ops pydantic-field 
template_engine_ops: Dict[str, Any]

Options to pass to the template engine before rendering.

template_location pydantic-field 
template_location: Location

The location of the root directory of the templates. This directory’s name will be rendered using the context.

Functions

get_process_mode 
get_process_mode(path: Path) -> ProcessMode

Calculates the process mode for a path based on the pattern’s skip and copy_only attributes.

validate_template_location pydantic-validator 
validate_template_location(
    value: Union[str, Location], info: ValidationInfo
) -> Location

Check that the template_location exists.

Question pydantic-model

Bases: BaseModel

A question for a pattern.

Show JSON schema: 
{
  "$defs": {
    "Choice": {
      "description": "A choice to a Question.",
      "properties": {
        "label": {
          "description": "The label for this choice when prompted to the user.",
          "pattern": "[a-zA-Z_][\\w_]*",
          "title": "Label",
          "type": "string"
        },
        "value": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "integer"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "description": "The value used when this choice is selected. It should match the questions's type.",
          "title": "Value"
        },
        "skip_when": {
          "default": "",
          "description": "A template string that will render as `True` if the choice is not valid based on previous context values.\n\nTake care to have at least one option without a `skip_when` clause to avoid accidentally creating a situation with no valid choices.",
          "title": "Skip When",
          "type": "string"
        }
      },
      "required": [
        "label",
        "value"
      ],
      "title": "Choice",
      "type": "object"
    }
  },
  "description": "A question for a pattern.",
  "properties": {
    "name": {
      "description": "The name of the variable used in the template.",
      "pattern": "[a-zA-Z_][\\w_]*",
      "title": "Name",
      "type": "string"
    },
    "type": {
      "default": "str",
      "description": "The type of this variable.",
      "enum": [
        "int",
        "float",
        "bool",
        "str",
        "multiline",
        "secret",
        "yaml",
        "json"
      ],
      "title": "Type",
      "type": "string"
    },
    "prompt": {
      "default": "",
      "description": "The message to ask the user for this information. If no prompt is provided, 'What is the <name>?' is used.",
      "title": "Prompt",
      "type": "string"
    },
    "help": {
      "default": "",
      "description": "Additional information to explain how to answer this question.",
      "title": "Help",
      "type": "string"
    },
    "choices": {
      "description": "A list of choice values or `choice` objects",
      "items": {
        "$ref": "#/$defs/Choice"
      },
      "title": "Choices",
      "type": "array"
    },
    "multiselect": {
      "default": false,
      "description": "When `true` allow multiple selections. The type of this context element will then be a list of this question's `type`",
      "title": "Multiselect",
      "type": "boolean"
    },
    "default": {
      "default": null,
      "description": "Provide a default to save them from typing. \n\nWhen using `choices`, the default must be the choice _value_, not its _key_, and must match its _type_. Leave this empty to force the user to answer.\n\nThis value may also be a template string rendered using the context so far. This allows you to provide defaults based on previous context elements.",
      "title": "Default"
    },
    "validator": {
      "default": "",
      "description": "Template string to validate the user input. \n\nThis template is rendered using the context so far; it should render _nothing_ if the value is valid and an error message to show to the user otherwise.",
      "title": "Validator",
      "type": "string"
    },
    "force_default": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "boolean"
        }
      ],
      "default": false,
      "description": "A condition that, if `True`, will not prompt the user for a value and uses the `default`.\n\n`bool` values are used directly. Setting this to `True` is a good way to make this value a computed value.\n\n`str` values should be template strings that evaluate to a boolean value.",
      "title": "Force Default"
    }
  },
  "required": [
    "name"
  ],
  "title": "Question",
  "type": "object"
}

Fields:

Validators:

Attributes

choices pydantic-field 
choices: List[Choice]

A list of choice values or choice objects

default pydantic-field 
default: Any = None

Provide a default to save them from typing.

When using choices, the default must be the choice value, not its key, and must match its type. Leave this empty to force the user to answer.

This value may also be a template string rendered using the context so far. This allows you to provide defaults based on previous context elements.

force_default pydantic-field 
force_default: Union[str, bool] = False

A condition that, if True, will not prompt the user for a value and uses the default.

bool values are used directly. Setting this to True is a good way to make this value a computed value.

str values should be template strings that evaluate to a boolean value.

help pydantic-field 
help: str = ''

Additional information to explain how to answer this question.

multiselect pydantic-field 
multiselect: bool = False

When true allow multiple selections. The type of this context element will then be a list of this question’s type

name pydantic-field 
name: str

The name of the variable used in the template.

prompt pydantic-field 
prompt: str = ''

The message to ask the user for this information. If no prompt is provided, ‘What is the ?’ is used.

type pydantic-field 
type: QuestionType = 'str'

The type of this variable.

validator pydantic-field 
validator: str = ''

Template string to validate the user input.

This template is rendered using the context so far; it should render nothing if the value is valid and an error message to show to the user otherwise.

Functions

choice_values_match_question_type pydantic-validator 
choice_values_match_question_type() -> Question

Ensure that all choice values match this question’s type.

use_name_if_missing_prompt pydantic-validator 
use_name_if_missing_prompt() -> Question

Use the name of the question as the prompt if prompt is empty.

Functions

find_template_root 

find_template_root(
    root_path: Path, prefix: str = "{{"
) -> Path

Search for a directory within root_path that starts with prefix.

read_pattern_file 

read_pattern_file(path: Union[str, Path]) -> Pattern

Read, parse, and validate the contents of a pattern file.