docs: include full _copier_conf attributes list #2127

wgordon17 · 2025-05-05T17:10:11Z

No description provided.

wgordon17 · 2025-05-05T17:12:16Z

Here's the funny thing, I hadn't even noticed the introduction sentence with

_copier_conf includes a representation of the current Copier [Worker](https://copier.readthedocs.io/en/stable/reference/main/#copier._main.Worker) object

until I went back and looked after I had found the Attributes table. Now that I know it's there, this PR is really just intended to give some additional clarity (feel free to close as well if you feel that the extra Note shouldn't be necessary ¯\_(ツ)_/¯ )

sisp · 2025-05-08T10:34:06Z

Thanks for aspiring to improve the docs! 🙇 I agree that the render context isn't documented as well as it could be. There's only one concern I have with this addition: copier.main will become an internal-only module and copier.main.Worker will become an internal-only class. So the API reference will become unavailable. IMO, we should model public interfaces (like the copier.yml content specification and the render context) with Pydantic to have declarative and explicit representations as single source of truth of information, static typing, runtime validation, and (exportable) JSON schema. I've resumed work on this long-standing idea of mine, but it's a quite massive change. In the meantime, how about documenting the render context explicitly and manually? We'll need to keep it synchronous with the actual implementation, but changes are quite infrequent.

wgordon17 · 2025-05-08T19:59:40Z

Hey @sisp, thanks for the review. If y'all are good with ensuring that the docs are just always in-sync, I'm absolutely happy to help copy over the data. Let me do a quick fix, and I'll let you give it another review 😊

wgordon17 · 2025-05-08T20:59:21Z

@sisp I think this should be ready for a review now. Direct link to docs preview: https://copier--2127.org.readthedocs.build/en/2127/creating/#_copier_conf

A few things that I adjusted (if you're OK with that)

Alphabetized the attributes to ideally make it easier to skim, versus the previous order matching _main.py
Included Defaults on the rows where I could easily see what the defaults were in _main.py
Added a NOTE in _main.py to hopefully provide a reminder to folks that any changes there need to also be reflected on the, now static, Attributes table in docs

codecov · 2025-05-08T21:05:20Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.03%. Comparing base (b4b40ad) to head (adca79d).
Report is 5 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2127   +/-   ##
=======================================
  Coverage   98.03%   98.03%           
=======================================
  Files          55       55           
  Lines        6005     6005           
=======================================
  Hits         5887     5887           
  Misses        118      118

Flag	Coverage Δ
unittests	`98.03% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

wgordon17 · 2025-05-15T23:47:06Z

@sisp Just checking if you're good with the changes?

sisp

Thanks for compiling the render context attributes table so meticulously! 🙇 I have a couple of suggestions regarding clarity, consistency, and style.

Seeing this table makes it much clearer (IMO) that the render context and Worker class attributes are not the same and not even as similar as it seemed with the previous documentation. Clarifying the render context is crucial for providing template authors with the necessary information to create good templates. Thanks for taking on this important task! 🙇

docs/creating.md

wgordon17 · 2025-05-16T12:32:04Z

@sisp awesome review, and definitely makes things clearer! I wonder...would it make sense to group setting attributes that are just sets of booleans, and then separate some of the more "in depth" attributes into their own group?

sisp · 2025-05-16T15:10:12Z

I think it's fine to keep all attributes in one table. There, they are sorted alphabetically and references to related settings are provided where applicable. Having a complete overview of all _copier_conf attributes in one table feels more useful than splitting them according to some rule that some may find intuitive and others may not.

I've noticed that the skip_answered setting isn't documented yet, and hence the Markdown reference isn't resolved. I've just created #2152 to add it.

I stumbled over one more thing: The settings attribute is still missing. Could you please add it?

docs/creating.md

Co-authored-by: Sigurd Spieckermann <2206639+sisp@users.noreply.github.com>

sisp

Almost there. 😉

docs/creating.md

Co-authored-by: Sigurd Spieckermann <2206639+sisp@users.noreply.github.com>

wgordon17 · 2025-06-09T15:08:54Z

@sisp 2 questions/thoughts, looking at

Why is Linux capitalized while the others are lowercase? Could/should that be normalized? 🤔 Likely a breaking change 😞
Do you want to use   to keep everything on one-line? Would definitely make the column wider 😞 Not sure if you have a preference ¯\_(ツ)_/¯

wgordon17 · 2025-06-09T15:18:24Z

docs/creating.md

+| `src_path`         | `Path`                                                        | The absolute path to the (cloned/downloaded) template on disk.                                                                                                                                                                                             |
+| `unsafe`           | `bool`                                                        | When `True`, allow usage of unsafe templates.<br>See the [`unsafe`][] setting for related information.                                                                                                                                                     |
+| `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.                                                                                                 |
+| `user_defaults`    | `dict[str, Any]`                                              | Specified user defaults that may override a template's defaults during question prompts.                                                                                                                                                                   |


Should we point to https://copier--2127.org.readthedocs.build/en/2127/settings/#user-defaults? What would that be, See the [User defaults][settings.user-defaults] setting for related information.

user_defaults in the render context is a Worker class attribute that can be passed via API only, but it's not the same as Settings.defaults. It may make sense to document user_defaults in docs/configuring.md in a separate PR.

wgordon17 · 2025-06-09T15:19:40Z

docs/creating.md

+| `exclude`          | `Sequence[str]`                                               | Specified additional [file exclusion patterns][patterns-syntax].<br>See the [`exclude`][] setting for related information.                                                                                                                                 |
+| `os`               | <code>Literal["Linux", "macos", "windows"] &vert; None</code> | The detected operating system, `None` if it could not be detected.                                                                                                                                                                                         |
+| `overwrite`        | `bool`                                                        | When `True`, overwrite files that already exist, without asking.<br>See the [`overwrite`][] setting for related information.                                                                                                                               |
+| `pretend`          | `bool`                                                        | When `True`, produce no real rendering.<br>See the [`pretend`][] setting for related information.                                                                                                                                                          |


Sure, but we should synchronize the descriptions and the Worker class attributes in a separate PR – wherever it makes sense.

wgordon17 · 2025-06-09T15:20:05Z

docs/creating.md

+| `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. |
+| `exclude`          | `Sequence[str]`                                               | Specified additional [file exclusion patterns][patterns-syntax].<br>See the [`exclude`][] setting for related information.                                                                                                                                 |
+| `os`               | <code>Literal["Linux", "macos", "windows"] &vert; None</code> | The detected operating system, `None` if it could not be detected.                                                                                                                                                                                         |
+| `overwrite`        | `bool`                                                        | When `True`, overwrite files that already exist, without asking.<br>See the [`overwrite`][] setting for related information.                                                                                                                               |


Sure, but we should synchronize the descriptions and the Worker class attributes in a separate PR – wherever it makes sense.

wgordon17 · 2025-06-09T15:20:59Z

docs/creating.md

+| `context_lines`    | `PositiveInt`                                                 | Lines of context to consider when solving conflicts in updates.<br>See the [`context_lines`][] setting for related information.                                                                                                                            |
+| `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.                                                            |
+| `defaults`         | `bool`                                                        | When `True`, use default answers to questions.<br>See the [`defaults`][] setting for related information.                                                                                                                                                  |
+| `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. |


Suggested change

| `dst_path` | `Path` | Destination path where to render the subproject. ⚠️ 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. |

| `dst_path` | `Path` | Destination path where to render the subproject. ⚠️ When [updating a project][updating-a-project], this may be a temporary directory, as Copier's update algorithm generates fresh copies using the old and new template versions in temporary locations. |

Sure, but we should synchronize the descriptions and the Worker class attributes in a separate PR – wherever it makes sense.

wgordon17 · 2025-06-09T15:22:52Z

Ok, threw a few more "consistency" suggestions in here as well, WDYT?

sisp

Why is Linux capitalized while the others are lowercase? Could/should that be normalized? 🤔 Likely a breaking change 😞

OMG, that's totally my error. I was typing on mobile and it seems typing correction capitalized it without me noticing. It should be lowercase of course. Thanks for catching this! 🥇

Do you want to use   to keep everything on one-line? Would definitely make the column wider 😞 Not sure if you have a preference ¯\_(ツ)_/¯

It does look better without the line wrap, but then the description column might get squeezed too much. I'd say, your call. We can always change it later. Thanks for paying attention to such details though! 🙇

sisp · 2025-06-10T12:16:34Z

docs/creating.md

+| `src_path`         | `Path`                                                        | The absolute path to the (cloned/downloaded) template on disk.                                                                                                                                                                                             |
+| `unsafe`           | `bool`                                                        | When `True`, allow usage of unsafe templates.<br>See the [`unsafe`][] setting for related information.                                                                                                                                                     |
+| `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.                                                                                                 |
+| `user_defaults`    | `dict[str, Any]`                                              | Specified user defaults that may override a template's defaults during question prompts.                                                                                                                                                                   |


user_defaults in the render context is a Worker class attribute that can be passed via API only, but it's not the same as Settings.defaults. It may make sense to document user_defaults in docs/configuring.md in a separate PR.

sisp · 2025-06-10T12:18:45Z

docs/creating.md

+| `exclude`          | `Sequence[str]`                                               | Specified additional [file exclusion patterns][patterns-syntax].<br>See the [`exclude`][] setting for related information.                                                                                                                                 |
+| `os`               | <code>Literal["Linux", "macos", "windows"] &vert; None</code> | The detected operating system, `None` if it could not be detected.                                                                                                                                                                                         |
+| `overwrite`        | `bool`                                                        | When `True`, overwrite files that already exist, without asking.<br>See the [`overwrite`][] setting for related information.                                                                                                                               |
+| `pretend`          | `bool`                                                        | When `True`, produce no real rendering.<br>See the [`pretend`][] setting for related information.                                                                                                                                                          |


Sure, but we should synchronize the descriptions and the Worker class attributes in a separate PR – wherever it makes sense.

sisp · 2025-06-10T12:18:57Z

docs/creating.md

+| `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. |
+| `exclude`          | `Sequence[str]`                                               | Specified additional [file exclusion patterns][patterns-syntax].<br>See the [`exclude`][] setting for related information.                                                                                                                                 |
+| `os`               | <code>Literal["Linux", "macos", "windows"] &vert; None</code> | The detected operating system, `None` if it could not be detected.                                                                                                                                                                                         |
+| `overwrite`        | `bool`                                                        | When `True`, overwrite files that already exist, without asking.<br>See the [`overwrite`][] setting for related information.                                                                                                                               |


Sure, but we should synchronize the descriptions and the Worker class attributes in a separate PR – wherever it makes sense.

sisp · 2025-06-10T12:19:15Z

docs/creating.md

+| `context_lines`    | `PositiveInt`                                                 | Lines of context to consider when solving conflicts in updates.<br>See the [`context_lines`][] setting for related information.                                                                                                                            |
+| `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.                                                            |
+| `defaults`         | `bool`                                                        | When `True`, use default answers to questions.<br>See the [`defaults`][] setting for related information.                                                                                                                                                  |
+| `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. |


Sure, but we should synchronize the descriptions and the Worker class attributes in a separate PR – wherever it makes sense.

wgordon17 changed the title ~~docs: clarifying _copier_conf attributes reference~~ docs: include full _copier_conf attributes list May 8, 2025

sisp requested changes May 16, 2025

View reviewed changes

wgordon17 force-pushed the patch-2 branch 3 times, most recently from 0d51bf8 to 3b1f596 Compare May 31, 2025 14:05

wgordon17 commented May 31, 2025

View reviewed changes

docs/creating.md Outdated Show resolved Hide resolved

wgordon17 requested a review from sisp May 31, 2025 14:06

wgordon17 force-pushed the patch-2 branch from 3b1f596 to 7bf6fa1 Compare May 31, 2025 14:11

wgordon17 commented May 31, 2025

View reviewed changes

docs/creating.md Outdated Show resolved Hide resolved

wgordon17 commented Jun 7, 2025

View reviewed changes

docs/creating.md Outdated Show resolved Hide resolved

wgordon17 commented Jun 7, 2025

View reviewed changes

docs/creating.md Outdated Show resolved Hide resolved

wgordon17 force-pushed the patch-2 branch 2 times, most recently from 49c34ec to ef463ce Compare June 7, 2025 23:03

docs: clarifying _copier_conf attributes reference

014bfe0

Co-authored-by: Sigurd Spieckermann <2206639+sisp@users.noreply.github.com>

wgordon17 force-pushed the patch-2 branch from ef463ce to 014bfe0 Compare June 7, 2025 23:04

sisp requested changes Jun 9, 2025

View reviewed changes

docs/creating.md Outdated Show resolved Hide resolved

docs/creating.md Outdated Show resolved Hide resolved

wgordon17 and others added 3 commits June 9, 2025 11:01

Update docs/creating.md

fedef4f

Co-authored-by: Sigurd Spieckermann <2206639+sisp@users.noreply.github.com>

Update docs/creating.md

f8dfcea

Co-authored-by: Sigurd Spieckermann <2206639+sisp@users.noreply.github.com>

style: autoformat with pre-commit

adca79d

wgordon17 commented Jun 9, 2025

View reviewed changes

sisp reviewed Jun 10, 2025

View reviewed changes

	\| `pretend` \| `bool` \| When `True`, produce no real rendering.<br>See the [`pretend`][] setting for related information. \|
	\| `pretend` \| `bool` \| When `True`, perform no real rendering.<br>See the [`pretend`][] setting for related information. \|

	\| `overwrite` \| `bool` \| When `True`, overwrite files that already exist, without asking.<br>See the [`overwrite`][] setting for related information. \|
	\| `overwrite` \| `bool` \| When `True`, overwrite files that already exist without asking.<br>See the [`overwrite`][] setting for related information. \|

	\| `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. \|
	\| `dst_path` \| `Path` \| Destination path where to render the subproject.<br>⚠️ When [updating a project][updating-a-project], this may be a temporary directory, as Copier's update algorithm generates fresh copies using the old and new template versions in temporary locations. \|

Uh oh!

docs: include full _copier_conf attributes list #2127

Are you sure you want to change the base?

docs: include full _copier_conf attributes list #2127

Uh oh!

Conversation

wgordon17 commented May 5, 2025

Uh oh!

wgordon17 commented May 5, 2025

Uh oh!

sisp commented May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wgordon17 commented May 8, 2025

Uh oh!

wgordon17 commented May 8, 2025

Uh oh!

codecov bot commented May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

wgordon17 commented May 15, 2025

Uh oh!

sisp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wgordon17 commented May 16, 2025

Uh oh!

sisp commented May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sisp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

wgordon17 commented Jun 9, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wgordon17 commented Jun 9, 2025

Uh oh!

sisp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

sisp commented May 8, 2025 •

edited

Loading

codecov bot commented May 8, 2025 •

edited

Loading

sisp commented May 16, 2025 •

edited

Loading