parameter

This module defines the Parameter class used for template parameter substitution in the cookiecutter_maker package. It provides functionality for defining, validating, and applying parameter replacements when converting concrete projects to cookiecutter templates.

class cookiecutter_maker.parameter.Parameter(selector: list[str], name: str, default: ~typing.Any | None = None, choice: list[~typing.Any] = <factory>, prompt: str | dict[str, ~typing.Any] | None = None, custom_placeholder: str | None = None, in_cookiecutter_json: bool = True, include: list[str] = <factory>, exclude: list[str] = <factory>)[source]

Defines a parameter for cookiecutter template substitution.

A Parameter represents a value in the concrete project that should be replaced with a cookiecutter variable in the template. Each parameter has a name, a selector list for hierarchical matching, and optional values like default, choices, include/exclude patterns.

The selector is a list of strings used for hierarchical matching, where each string is a substring of the previous. This provides precise control over the replacement process, from more general to more specific matches.

Parameters:

  • selector – A list of strings for hierarchical matching, from broadest to most specific. Each string must be a substring of the previous one.

  • name – The name of the parameter, used in the cookiecutter placeholder.

  • default – The default value for the parameter in the cookiecutter.json file. Required if choice is empty.

  • choice – Optional list of choices for the parameter. If provided, default must be None. See https://cookiecutter.readthedocs.io/en/stable/advanced/choice_variables.html

  • prompt – Optional human readable prompt.

  • custom_placeholder – Optional custom placeholder string for the parameter, this will override the default {{ cookiecutter.name }} format.

  • in_cookiecutter_json – Whether to include this parameter in the cookiecutter.json file. If False, the parameter will be used for replacements but not added to cookiecutter.json. Defaults to True.

  • include – Optional list of file path patterns where this parameter should be applied.

  • exclude – Optional list of file path patterns where this parameter should not be applied.

TODO make parameter level include and exclude really work.

property placeholder: str

Generate the cookiecutter placeholder string for this parameter.

The placeholder is created using the parameter name and selector, following the cookiecutter template format: {{ cookiecutter.param_name }}

property path_matcher: PathMatcher

Create a PathMatcher to determine where this parameter should be applied.

to_cookiecutter_key_value() → tuple[str, Any][source]

Generate a key-value pair for the cookiecutter.json file.

cookiecutter_maker.parameter.replace_with_parameter(text: str, param_list: list[Parameter]) → str[source]

Replace text with parameter placeholders.

This function takes a text string and a list of parameters, and replaces occurrences of each parameter’s selector with its cookiecutter placeholder.