feat(settings): add user settings support with defaults values (fix #…

…235)

copier/main.py

@@ -38,6 +38,8 @@
 from pydantic_core import to_jsonable_python
 from questionary import unsafe_prompt
 
+from copier.settings import Settings
+
 from .errors import (
     CopierAnswersInterrupt,
     ExtensionNotFoundError,
@@ -58,13 +60,7 @@
     scantree,
     set_git_alternates,
 )
-from .types import (
-    MISSING,
-    AnyByStrDict,
-    JSONSerializable,
-    RelativePath,
-    StrOrPath,
-)
+from .types import MISSING, AnyByStrDict, JSONSerializable, RelativePath, StrOrPath
 from .user_data import DEFAULT_DATA, AnswersMap, Question
 from .vcs import get_git
 
@@ -192,6 +188,7 @@ class Worker:
     answers_file: RelativePath | None = None
     vcs_ref: str | None = None
     data: AnyByStrDict = field(default_factory=dict)
+    settings: Settings = field(default_factory=Settings.from_file)
     exclude: Sequence[str] = ()
     use_prereleases: bool = False
     skip_if_exists: Sequence[str] = ()
@@ -215,12 +212,14 @@ def __enter__(self) -> Worker:
         return self
 
     @overload
-    def __exit__(self, type: None, value: None, traceback: None) -> None: ...
+    def __exit__(self, type: None, value: None, traceback: None) -> None:
+        ...
 
     @overload
     def __exit__(
         self, type: type[BaseException], value: BaseException, traceback: TracebackType
-    ) -> None: ...
+    ) -> None:
+        ...
 
     def __exit__(
         self,
@@ -467,6 +466,7 @@ def _ask(self) -> None:  # noqa: C901
             question = Question(
                 answers=result,
                 jinja_env=self.jinja_env,
+                settings=self.settings,
                 var_name=var_name,
                 **details,
             )

copier/settings.py

@@ -0,0 +1,31 @@
+"""User setttings models and helper functions."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+from platformdirs import user_config_path
+from pydantic import BaseModel, Field
+
+ENV_VAR = "COPIER_SETTINGS_PATH"
+
+
+class Settings(BaseModel):
+    """User settings model."""
+
+    defaults: dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def from_file(cls, settings_path: Path | None = None) -> Settings:
+        """Load settings from a file."""
+        if settings_path is None:
+            if env_path := os.getenv(ENV_VAR):
+                settings_path = Path(env_path)
+            else:
+                settings_path = user_config_path("copier") / "settings.yml"
+        if settings_path.is_file():
+            data = yaml.safe_load(settings_path.read_text())
+            return cls.model_validate(data)
+        return cls()

copier/user_data.py

@@ -23,6 +23,8 @@
 from pygments.lexers.data import JsonLexer, YamlLexer
 from questionary.prompts.common import Choice
 
+from copier.settings import Settings
+
 from .errors import InvalidTypeError, UserMessageError
 from .tools import cast_to_bool, cast_to_str, force_str_end
 from .types import MISSING, AnyByStrDict, MissingType, OptStrOrPath, StrOrPath
@@ -178,6 +180,7 @@ class Question:
     var_name: str
     answers: AnswersMap
     jinja_env: SandboxedEnvironment
+    settings: Settings = field(default_factory=Settings)
     choices: Sequence[Any] | dict[Any, Any] | str = field(default_factory=list)
     multiselect: bool = False
     default: Any = MISSING
@@ -246,7 +249,9 @@ def get_default(self) -> Any:
                 except KeyError:
                     if self.default is MISSING:
                         return MISSING
-                    result = self.render_value(self.default)
+                    result = self.render_value(
+                        self.settings.defaults.get(self.var_name, self.default)
+                    )
         result = self.cast_answer(result)
         return result
 

docs/reference/settings.md

@@ -0,0 +1 @@
+::: copier.settings

docs/settings.md

@@ -0,0 +1,39 @@
+# Settings
+
+Copier settings are stored in `<CONFIG_ROOT>/settings.yml` where `<CONFIG_ROOT>` is the
+standard configuration directory for your platform:
+
+-   `$XDG_CONFIG_HOME/copier` (`~/.config/copier ` in most cases) on Linux as defined by
+    [XDG Base Directory Specifications](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
+-   `~/Library/Application Support/copier` on macOS as defined by
+    [Apple File System Basics](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html)
+-   `%USERPROFILE%\AppData\Local\copier` on Windows as defined in
+    [Known folders](https://docs.microsoft.com/en-us/windows/win32/shell/known-folders)
+
+This location can be overridden by setting the `COPIER_SETTINGS_PATH` environment
+variable.
+
+## User defaults
+
+Users may define some reusable default variables in the `defaults` section of the
+configuration file.
+
+```yaml title="$COPIER_HOME/settings.yml"
+defaults:
+    user_name: "John Doe"
+    user_email: [email protected]
+```
+
+This user data will replace the default value of fields of the same name.
+
+### Well-known variables
+
+To ensure templates efficiently reuse user-defined variables, we invite template authors
+to use the following well-known variables:
+
+| Variable name | Type  | Description            |
+| ------------- | ----- | ---------------------- |
+| `user_name`   | `str` | User's full name       |
+| `user_email`  | `str` | User's email address   |
+| `github_user` | `str` | User's GitHub username |
+| `gitlab_user` | `str` | User's GitLab username |

mkdocs.yml

@@ -11,11 +11,13 @@ nav:
   - Configuring a template: "configuring.md"
   - Generating a project: "generating.md"
   - Updating a project: "updating.md"
+  - Settings: "settings.md"
   - Reference:
       - cli.py: "reference/cli.md"
       - errors.py: "reference/errors.md"
       - jinja_ext.py: "reference/jinja_ext.md"
       - main.py: "reference/main.md"
+      - settings.py: "reference/settings.md"
       - subproject.py: "reference/subproject.md"
       - template.py: "reference/template.md"
       - tools.py: "reference/tools.md"