user_data.py

Functions used to load user data.

AnswersMap dataclass

Object that gathers answers from different sources.

Attributes:

Name	Type	Description
local	Dict[str, Any]	Local overrides to other answers.
user	Dict[str, Any]	Answers provided by the user, interactively.
init	Dict[str, Any]	Answers provided on init. This will hold those answers that come from --data in CLI mode. See data.
metadata	Dict[str, Any]	Data used to be able to reproduce the template. It comes from copier.template.Template.metadata.
last	Dict[str, Any]	Data from the answers file.
default	Dict[str, Any]	Default data from the template. See copier.template.Template.default_answers.
user_defaults	Dict[str, Any]	Default data from the user e.g. previously completed and restored data. See copier.main.Worker.

Source code in copier/user_data.py

class AnswersMap:
    """Object that gathers answers from different sources.

    Attributes:
        local:
            Local overrides to other answers.

        user:
            Answers provided by the user, interactively.

        init:
            Answers provided on init.

            This will hold those answers that come from `--data` in
            CLI mode.

            See [data][].

        metadata:
            Data used to be able to reproduce the template.

            It comes from [copier.template.Template.metadata][].

        last:
            Data from [the answers file][the-copier-answersyml-file].

        default:
            Default data from the template.

            See [copier.template.Template.default_answers][].

        user_defaults:
            Default data from the user e.g. previously completed and restored data.

            See [copier.main.Worker][].
    """

    # Private
    local: AnyByStrDict = field(default_factory=dict, init=False)

    # Public
    user: AnyByStrDict = field(default_factory=dict)
    init: AnyByStrDict = field(default_factory=dict)
    metadata: AnyByStrDict = field(default_factory=dict)
    last: AnyByStrDict = field(default_factory=dict)
    user_defaults: AnyByStrDict = field(default_factory=dict)
    default: AnyByStrDict = field(default_factory=dict)

    @cached_property
    def combined(self) -> t_ChainMap[str, Any]:
        """Answers combined from different sources, sorted by priority."""
        return ChainMap(
            self.local,
            self.user,
            self.init,
            self.metadata,
            self.last,
            self.user_defaults,
            self.default,
            DEFAULT_DATA,
        )

    def old_commit(self) -> OptStr:
        return self.last.get("_commit")

combined: ChainMap[str, Any] cached property writable

Answers combined from different sources, sorted by priority.

Question dataclass

One question asked to the user.

All attributes are init kwargs.

Attributes:

Name	Type	Description
choices	Union[Dict[Any, Any], List[Any]]	Selections available for the user if the question requires them. Can be templated.
default	Any	Default value presented to the user to make it easier to respond. Can be templated.
help	str	Additional text printed to the user, explaining the purpose of this question. Can be templated.
multiline	Union[str, bool]	Indicates if the question should allow multiline input. Defaults to True for JSON and YAML questions, and to False otherwise. Only meaningful for str-based questions. Can be templated.
placeholder	str	Text that appears if there's nothing written in the input field, but disappears as soon as the user writes anything. Can be templated.
secret	bool	Indicates if the question should be removed from the answers file. If the question type is str, it will hide user input on the screen by displaying asterisks: ****.
type_name		The type of question. Affects the rendering, validation and filtering. Can be templated.
var_name	str	Question name in the answers dict.
when	Union[str, bool]	Condition that, if False, skips the question. Can be templated. If it is a boolean, it is used directly. If it is a str, it is converted to boolean using a parser similar to YAML, but only for boolean values.

Source code in copier/user_data.py

class Question:
    """One question asked to the user.

    All attributes are init kwargs.

    Attributes:
        choices:
            Selections available for the user if the question requires them.
            Can be templated.

        default:
            Default value presented to the user to make it easier to respond.
            Can be templated.

        help:
            Additional text printed to the user, explaining the purpose of
            this question. Can be templated.

        multiline:
            Indicates if the question should allow multiline input. Defaults
            to `True` for JSON and YAML questions, and to `False` otherwise.
            Only meaningful for str-based questions. Can be templated.

        placeholder:
            Text that appears if there's nothing written in the input field,
            but disappears as soon as the user writes anything. Can be templated.

        secret:
            Indicates if the question should be removed from the answers file.
            If the question type is str, it will hide user input on the screen
            by displaying asterisks: `****`.

        type_name:
            The type of question. Affects the rendering, validation and filtering.
            Can be templated.

        var_name:
            Question name in the answers dict.

        when:
            Condition that, if `False`, skips the question. Can be templated.
            If it is a boolean, it is used directly. If it is a str, it is
            converted to boolean using a parser similar to YAML, but only for
            boolean values.
    """

    var_name: str
    answers: AnswersMap
    jinja_env: SandboxedEnvironment
    choices: Union[Dict[Any, Any], List[Any]] = field(default_factory=list)
    default: Any = None
    help: str = ""
    ask_user: bool = False
    multiline: Union[str, bool] = False
    placeholder: str = ""
    secret: bool = False
    type: str = ""
    when: Union[str, bool] = True

    @validator("var_name")
    def _check_var_name(cls, v):
        if v in DEFAULT_DATA:
            raise ValueError("Invalid question name")
        return v

    @validator("type", always=True)
    def _check_type(cls, v, values):
        if v == "":
            default_type_name = type(values.get("default")).__name__
            v = default_type_name if default_type_name in CAST_STR_TO_NATIVE else "yaml"
        return v

    def get_default(self) -> Any:
        """Get the default value for this question, casted to its expected type."""
        cast_fn = self.get_cast_fn()
        try:
            result = self.answers.init[self.var_name]
        except KeyError:
            try:
                result = self.answers.last[self.var_name]
            except KeyError:
                try:
                    result = self.answers.user_defaults[self.var_name]
                except KeyError:
                    result = self.render_value(self.default)
        result = cast_answer_type(result, cast_fn)
        return result

    def get_default_rendered(self) -> Union[bool, str, Choice, None]:
        """Get default answer rendered for the questionary lib.

        The questionary lib expects some specific data types, and returns
        it when the user answers. Sometimes you need to compare the response
        to the rendered one, or viceversa.

        This helper allows such usages.
        """
        default = self.get_default()
        # If there are choices, return the one that matches the expressed default
        if self.choices:
            for choice in self._formatted_choices:
                if choice.value == default:
                    return choice
            return None
        # Yes/No questions expect and return bools
        if isinstance(default, bool) and self.get_type_name() == "bool":
            return default
        # Emptiness is expressed as an empty str
        if default is None:
            return ""
        # JSON and YAML dumped depending on mutliline setting
        if self.get_type_name() == "json":
            return json.dumps(default, indent=2 if self.get_multiline() else None)
        if self.get_type_name() == "yaml":
            return yaml.safe_dump(
                default, default_flow_style=not self.get_multiline(), width=2147483647
            ).strip()
        # All other data has to be str
        return str(default)

    @cached_property
    def _formatted_choices(self) -> List[Choice]:
        """Obtain choices rendered and properly formatted."""
        result = []
        choices = self.choices
        if isinstance(self.choices, dict):
            choices = list(self.choices.items())
        for choice in choices:
            # If a choice is a dict, it can be used raw
            if isinstance(choice, dict):
                name = choice["name"]
                value = choice["value"]
            # ... or a value pair
            elif isinstance(choice, (tuple, list)):
                name, value = choice
            # However, a choice can also be a single value...
            else:
                name = value = choice
            # The name must always be a str
            name = str(self.render_value(name))
            # The value can be templated
            value = self.render_value(value)
            result.append(Choice(name, value))
        return result

    def filter_answer(self, answer) -> Any:
        """Cast the answer to the desired type."""
        if answer == self.get_default_rendered():
            return self.get_default()
        return cast_answer_type(answer, self.get_cast_fn())

    def get_message(self) -> str:
        """Get the message that will be printed to the user."""
        message = ""
        if self.help:
            rendered_help = self.render_value(self.help)
            message = force_str_end(rendered_help)
        message += f"{self.var_name}? Format: {self.get_type_name()}"
        return message

    def get_placeholder(self) -> str:
        """Render and obtain the placeholder."""
        return self.render_value(self.placeholder)

    def get_questionary_structure(self) -> AnyByStrDict:
        """Get the question in a format that the questionary lib understands."""
        lexer = None
        result: AnyByStrDict = {
            "default": self.get_default_rendered(),
            "filter": self.filter_answer,
            "message": self.get_message(),
            "mouse_support": True,
            "name": self.var_name,
            "qmark": "🕵️" if self.secret else "🎤",
            "when": self.get_when,
        }
        questionary_type = "input"
        type_name = self.get_type_name()
        if type_name == "bool":
            questionary_type = "confirm"
        if self.choices:
            questionary_type = "select"
            result["choices"] = self._formatted_choices
        if questionary_type == "input":
            if self.secret:
                questionary_type = "password"
            elif type_name == "yaml":
                lexer = PygmentsLexer(YamlLexer)
            elif type_name == "json":
                lexer = PygmentsLexer(JsonLexer)
            if lexer:
                result["lexer"] = lexer
            result["multiline"] = self.get_multiline()
            placeholder = self.get_placeholder()
            if placeholder:
                result["placeholder"] = placeholder
            result["validate"] = self.validate_answer
        result.update({"type": questionary_type})
        return result

    def get_cast_fn(self) -> Callable:
        """Obtain function to cast user answer to desired type."""
        type_name = self.get_type_name()
        if type_name not in CAST_STR_TO_NATIVE:
            raise InvalidTypeError("Invalid question type")
        return CAST_STR_TO_NATIVE.get(type_name, parse_yaml_string)

    def get_type_name(self) -> str:
        """Render the type name and return it."""
        return self.render_value(self.type)

    def get_multiline(self) -> bool:
        """Get the value for multiline."""
        multiline = self.render_value(self.multiline)
        multiline = cast_answer_type(multiline, cast_str_to_bool)
        return bool(multiline)

    def validate_answer(self, answer) -> bool:
        """Validate user answer."""
        cast_fn = self.get_cast_fn()
        try:
            cast_fn(answer)
            return True
        except Exception:
            return False

    def get_when(self, answers) -> bool:
        """Get skip condition for question."""
        if (
            # Skip on --defaults
            not self.ask_user
            # Skip on --data=this_question=some_answer
            or self.var_name in self.answers.init
        ):
            return False
        when = self.when
        when = self.render_value(when)
        when = cast_answer_type(when, cast_str_to_bool)
        return bool(when)

    def render_value(self, value: Any) -> str:
        """Render a single templated value using Jinja.

        If the value cannot be used as a template, it will be returned as is.
        """
        try:
            template = self.jinja_env.from_string(value)
        except TypeError:
            # value was not a string
            return value
        try:
            return template.render(**self.answers.combined)
        except UndefinedError as error:
            raise UserMessageError(str(error)) from error

filter_answer(self, answer)

Cast the answer to the desired type.

Source code in copier/user_data.py

def filter_answer(self, answer) -> Any:
    """Cast the answer to the desired type."""
    if answer == self.get_default_rendered():
        return self.get_default()
    return cast_answer_type(answer, self.get_cast_fn())

get_cast_fn(self)

Obtain function to cast user answer to desired type.

Source code in copier/user_data.py

def get_cast_fn(self) -> Callable:
    """Obtain function to cast user answer to desired type."""
    type_name = self.get_type_name()
    if type_name not in CAST_STR_TO_NATIVE:
        raise InvalidTypeError("Invalid question type")
    return CAST_STR_TO_NATIVE.get(type_name, parse_yaml_string)

get_default(self)

Get the default value for this question, casted to its expected type.

Source code in copier/user_data.py

def get_default(self) -> Any:
    """Get the default value for this question, casted to its expected type."""
    cast_fn = self.get_cast_fn()
    try:
        result = self.answers.init[self.var_name]
    except KeyError:
        try:
            result = self.answers.last[self.var_name]
        except KeyError:
            try:
                result = self.answers.user_defaults[self.var_name]
            except KeyError:
                result = self.render_value(self.default)
    result = cast_answer_type(result, cast_fn)
    return result

get_default_rendered(self)

Get default answer rendered for the questionary lib.

The questionary lib expects some specific data types, and returns it when the user answers. Sometimes you need to compare the response to the rendered one, or viceversa.

This helper allows such usages.

Source code in copier/user_data.py

def get_default_rendered(self) -> Union[bool, str, Choice, None]:
    """Get default answer rendered for the questionary lib.

    The questionary lib expects some specific data types, and returns
    it when the user answers. Sometimes you need to compare the response
    to the rendered one, or viceversa.

    This helper allows such usages.
    """
    default = self.get_default()
    # If there are choices, return the one that matches the expressed default
    if self.choices:
        for choice in self._formatted_choices:
            if choice.value == default:
                return choice
        return None
    # Yes/No questions expect and return bools
    if isinstance(default, bool) and self.get_type_name() == "bool":
        return default
    # Emptiness is expressed as an empty str
    if default is None:
        return ""
    # JSON and YAML dumped depending on mutliline setting
    if self.get_type_name() == "json":
        return json.dumps(default, indent=2 if self.get_multiline() else None)
    if self.get_type_name() == "yaml":
        return yaml.safe_dump(
            default, default_flow_style=not self.get_multiline(), width=2147483647
        ).strip()
    # All other data has to be str
    return str(default)

get_message(self)

Get the message that will be printed to the user.

Source code in copier/user_data.py

def get_message(self) -> str:
    """Get the message that will be printed to the user."""
    message = ""
    if self.help:
        rendered_help = self.render_value(self.help)
        message = force_str_end(rendered_help)
    message += f"{self.var_name}? Format: {self.get_type_name()}"
    return message

get_multiline(self)

Get the value for multiline.

Source code in copier/user_data.py

def get_multiline(self) -> bool:
    """Get the value for multiline."""
    multiline = self.render_value(self.multiline)
    multiline = cast_answer_type(multiline, cast_str_to_bool)
    return bool(multiline)

get_placeholder(self)

Render and obtain the placeholder.

Source code in copier/user_data.py

def get_placeholder(self) -> str:
    """Render and obtain the placeholder."""
    return self.render_value(self.placeholder)

get_questionary_structure(self)

Get the question in a format that the questionary lib understands.

Source code in copier/user_data.py

def get_questionary_structure(self) -> AnyByStrDict:
    """Get the question in a format that the questionary lib understands."""
    lexer = None
    result: AnyByStrDict = {
        "default": self.get_default_rendered(),
        "filter": self.filter_answer,
        "message": self.get_message(),
        "mouse_support": True,
        "name": self.var_name,
        "qmark": "🕵️" if self.secret else "🎤",
        "when": self.get_when,
    }
    questionary_type = "input"
    type_name = self.get_type_name()
    if type_name == "bool":
        questionary_type = "confirm"
    if self.choices:
        questionary_type = "select"
        result["choices"] = self._formatted_choices
    if questionary_type == "input":
        if self.secret:
            questionary_type = "password"
        elif type_name == "yaml":
            lexer = PygmentsLexer(YamlLexer)
        elif type_name == "json":
            lexer = PygmentsLexer(JsonLexer)
        if lexer:
            result["lexer"] = lexer
        result["multiline"] = self.get_multiline()
        placeholder = self.get_placeholder()
        if placeholder:
            result["placeholder"] = placeholder
        result["validate"] = self.validate_answer
    result.update({"type": questionary_type})
    return result

get_type_name(self)

Render the type name and return it.

Source code in copier/user_data.py

def get_type_name(self) -> str:
    """Render the type name and return it."""
    return self.render_value(self.type)

get_when(self, answers)

Get skip condition for question.

Source code in copier/user_data.py

def get_when(self, answers) -> bool:
    """Get skip condition for question."""
    if (
        # Skip on --defaults
        not self.ask_user
        # Skip on --data=this_question=some_answer
        or self.var_name in self.answers.init
    ):
        return False
    when = self.when
    when = self.render_value(when)
    when = cast_answer_type(when, cast_str_to_bool)
    return bool(when)

render_value(self, value)

Render a single templated value using Jinja.

If the value cannot be used as a template, it will be returned as is.

Source code in copier/user_data.py

def render_value(self, value: Any) -> str:
    """Render a single templated value using Jinja.

    If the value cannot be used as a template, it will be returned as is.
    """
    try:
        template = self.jinja_env.from_string(value)
    except TypeError:
        # value was not a string
        return value
    try:
        return template.render(**self.answers.combined)
    except UndefinedError as error:
        raise UserMessageError(str(error)) from error

validate_answer(self, answer)

Validate user answer.

Source code in copier/user_data.py

def validate_answer(self, answer) -> bool:
    """Validate user answer."""
    cast_fn = self.get_cast_fn()
    try:
        cast_fn(answer)
        return True
    except Exception:
        return False

cast_answer_type(answer, type_fn)

Cast answer to expected type.

Source code in copier/user_data.py

def cast_answer_type(answer: Any, type_fn: Callable) -> Any:
    """Cast answer to expected type."""
    # Skip casting None into "None"
    if type_fn is str and answer is None:
        return answer
    try:
        return type_fn(answer)
    except (TypeError, AttributeError):
        # JSON or YAML failed because it wasn't a string; no need to convert
        return answer

load_answersfile_data(dst_path, answers_file=None)

Load answers data from a $dst_path/$answers_file file if it exists.

Source code in copier/user_data.py

def load_answersfile_data(
    dst_path: StrOrPath,
    answers_file: OptStrOrPath = None,
) -> AnyByStrDict:
    """Load answers data from a `$dst_path/$answers_file` file if it exists."""
    try:
        with open(Path(dst_path) / (answers_file or ".copier-answers.yml")) as fd:
            return yaml.safe_load(fd)
    except FileNotFoundError:
        return {}

parse_yaml_string(string)

Parse a YAML string and raise a ValueError if parsing failed.

This method is needed because :meth:prompt requires a ValueError to repeat failed questions.

Source code in copier/user_data.py

def parse_yaml_string(string: str) -> Any:
    """Parse a YAML string and raise a ValueError if parsing failed.

    This method is needed because :meth:`prompt` requires a ``ValueError``
    to repeat failed questions.
    """
    try:
        return yaml.safe_load(string)
    except yaml.error.YAMLError as error:
        raise ValueError(str(error))