Skip to content

Commit 014bfe0

Browse files
wgordon17sisp
wgordon17
and
sisp
committed
docs: clarifying _copier_conf attributes reference
Co-authored-by: Sigurd Spieckermann <[email protected]>
1 parent b4b40ad commit 014bfe0

File tree

2 files changed

+36
-20
lines changed

2 files changed

+36
-20
lines changed

‎copier/_main.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -217,6 +217,9 @@ class Worker:
217217
When `True`, skip template tasks execution.
218218
"""
219219

220+
# NOTE: attributes are fully documented in [creating.md](../docs/creating.md)
221+
# make sure to update documentation upon any changes.
222+
220223
src_path: str | None = None
221224
dst_path: Path = Path()
222225
answers_file: RelativePath | None = None

‎docs/creating.md

Lines changed: 33 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -95,27 +95,40 @@ suitable to [autoupdate your project safely][the-copier-answersyml-file]:
9595

9696
### `_copier_conf`
9797

98-
`_copier_conf` includes a representation of the current Copier
99-
[Worker][copier.main.Worker] object, also slightly modified:
100-
101-
- It only contains JSON-serializable data.
102-
- You can serialize it with `{{ _copier_conf|to_json }}`.
103-
- ⚠️ It contains secret answers inside its `.data` key.
104-
- Modifying it doesn't alter the current rendering configuration.
105-
106-
Furthermore, the following keys are added:
107-
108-
#### `os` { #\_copier_conf.os }
109-
110-
The detected operating system, either `"linux"`, `"macos"`, `"windows"` or `None`.
111-
112-
#### `sep` { #\_copier_conf.sep }
113-
114-
The operating system-specific directory separator.
115-
116-
#### `vcs_ref_hash` { #\_copier_conf.vcs_ref_hash }
98+
!!! note
11799

118-
The current commit hash from the template.
100+
- `_copier_conf` contains JSON-serializable data.
101+
- `_copier_conf` can be serialized with `{{ _copier_conf|to_json }}`.
102+
- ⚠️ `_copier_conf` may contain secret answers inside its `.data` key.
103+
- Modifying `_copier_conf` doesn't alter the current rendering configuration.
104+
105+
Attributes:
106+
107+
| Name | Type | Description |
108+
| ------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
109+
| `answers_file` | `Path` | The path for [the answers file][the-copier-answersyml-file] relative to `dst_path`.<br>See the [`answers_file`][] setting for related information. |
110+
| `cleanup_on_error` | `bool` | When `True`, delete `dst_path` if there's an error.<br>See the [`cleanup_on_error`][] setting for related information. |
111+
| `conflict` | `Literal["inline", "rej"]` | The output format of a diff code hunk when [updating][updating-a-project] a file yields conflicts.<br>See the [`conflict`][] setting for related information. |
112+
| `context_lines` | `PositiveInt` | Lines of context to consider when solving conflicts in updates.<br>See the [`context_lines`][] setting for related information. |
113+
| `data` | `dict[str, Any]` | Answers to the questionnaire, defined in the template, provided via CLI (`-d,--data`) or API (`data`).<br>See the [`data`][] setting for related information.<br>⚠️ May contain secret answers. |
114+
| `defaults` | `bool` | When `True`, use default answers to questions.<br>See the [`defaults`][] setting for related information. |
115+
| `dst_path` | `Path` | Destination path where to render the subproject.<br>⚠️ When [updating a project][updating-a-project], it may be a temporary directory, as Copier's update algorithm generates fresh copies using the old and new template versions in temporary locations. |
116+
| `exclude` | `Sequence[str]` | Specified additional [file exclusion patterns][patterns-syntax].<br>See the [`exclude`][] setting for related information. |
117+
| `os` | `str` | The detected operating system, either `"linux"`, `"macos"`, `"windows"` or `None`. |
118+
| `overwrite` | `bool` | When `True`, overwrite files that already exist, without asking.<br>See the [`overwrite`][] setting for related information. |
119+
| `pretend` | `bool` | When `True`, produce no real rendering.<br>See the [`pretend`][] setting for related information. |
120+
| `quiet` | `bool` | When `True`, disable all output.<br>See the [`quiet`][] setting for related information. |
121+
| `sep` | `str` | The operating system-specific directory separator. |
122+
| `settings` | [`copier.settings.Settings`][] | Specified settings that control copier's behavior.<br>See the [`settings`][] page for related information. |
123+
| `skip_answered` | `bool` | When `True`, skip questions that have already been answered.<br>See the [`skip_answered`][] setting for related information. |
124+
| `skip_if_exists` | `Sequence[str]` | Specified additional [file skip patterns][patterns-syntax].<br>See the [`skip_if_exists`][] setting for related information. |
125+
| `skip_tasks` | `bool` | When `True`, skip [template tasks execution][tasks].<br>See the [`skip_tasks`][] setting for related information. |
126+
| `src_path` | `Path` | The absolute path to the (cloned/downloaded) template on disk. |
127+
| `unsafe` | `bool` | When `True`, allow usage of unsafe templates.<br>See the [`unsafe`][] setting for related information. |
128+
| `use_prereleases` | `bool` | When `True`, `vcs_ref`/`vcs_ref_hash` may refer to a prerelease version of the template.<br>See the [`use_prereleases`][] setting for related information. |
129+
| `user_defaults` | `dict[str, Any]` | Specified user defaults that may override a template's defaults during question prompts. |
130+
| `vcs_ref` | <code>str &vert; None</code> | The VCS tag/commit of the template, `None` if the template is not VCS-tracked.<br>See the [`vcs_ref`][] setting for related information. |
131+
| `vcs_ref_hash` | <code>str &vert; None</code> | The VCS commit hash of the template, `None` if the template is not VCS-tracked. |
119132

120133
### `_copier_python`
121134

0 commit comments

Comments
 (0)