Conditional transclusion: Issue #1076

[RR5555]

Feature

Issue #1076 proposed the following feature:

A conditional to be used "when" a file is to be included will be nice:

!include env/dev.yml
when: "{{ env_type == 'dev' }}"

This PR thus proposes an implementation of this feature (with a small syntax change so as not to break the handling of !include):

!include env/dev.yml
when "{{ env_type == 'dev' }}"

Implementation idea

The idea is the following: when a file transclusion is conditioned on a condition condition, everything in that file will be subsequently jinja conditioned on condition. The variables will be defaulted to falsy values of the corresponding type with a False when when the condition is False, so as to reproduce the behavior of non-existing variable.

Potential current shortcomings

• I do not know, and did not check, if all the values of the settings (those that can be used in a copier.yml) are interpreted by jinja, if they are not, these settings would require additional work to be conditioned
• Though the condition is applied to all the values of all the settings (those that can be used in a copier.yml) (that, I did test), I did not test the execution of the settings exhaustively: only tested the correct execution of _exclude
• Setting variables to falsy values might not be ideal, if so, type, when when is False, could be changed to str with an empty str as value

Potential required improvement

• Add a test in which the transcluded file contains all the possible settings (which can be used in a copier.yml), which then test whether they are correctly applied or ignored depending on the condition

Tests

To run the tests only for the new feature, I have added a temporary pytest marker conditional_transclusion:

uv run poe test -m conditional_transclusion

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.14%. Comparing base (4c1d4c0) to head (474ff5b).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2332      +/-   ##
==========================================
+ Coverage   97.07%   97.14%   +0.06%     
==========================================
  Files          55       55              
  Lines        6158     6294     +136     
==========================================
+ Hits         5978     6114     +136     
  Misses        180      180              

Flag	Coverage Δ
unittests	97.14% <100.00%> (+0.06%)	⬆️

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.

[sisp]

This looks like a pretty massive change for a seemingly small feature. 🙈

I'm not sure about the alternative syntax:

!include env/dev.yml
when "{{ env_type == 'dev' }}"

If

!include env/dev.yml
when: "{{ env_type == 'dev' }}"

doesn't work, I'd prefer moving back to the design discussion. There was already another suggestion, although I think _include looks like the opposite of _exclude, but the two are semantically unrelated. Ideally, we'd use a widely adopted syntax, but it might not exist.