Expand jinja environment

[DavidHuber-NOAA]

Description
This adds three new features to the Jinja class:
1. Template.substitute_structure is now available as a filter. This is useful for parsing jinja templates that reference multiple similar variables (e.g. ensemble member directories). A template for the ensemble members can be passed into the jinja context dictionary and used to construct the final variables based on iterators, cycle date/time, etc.
- For example, if 20 ensemble members each have data in data/YYYYMMDD/HH/analysis/mem###, one could define 'ANALYSIS_tmpl' : "data/${YMD}/{HH}/analysis/mem{MEM}", 'current_cycle': datetime.datetime(year=2024, month=5, day=3, hour=6)
- Then in the template:

{% set cycle_YMD = to_YMD(current_cycle) %}
{% set cycle_HH = strftime(current_cycle, "%H") %}
{% for mem in range(1,21) %}
{% set mem3 = '%03d' % mem %}
{% set tmpl_dict = {'YMD': cycle_YMD, 'HH': cycle_HH, 'MEM': mem3} %}
{{ ANALYSIS_tmpl | template_substitute_structure(DOLLAR_CURLY_BRACE, tmpl_dict.get) }}
{% endfor %}

1. Add the jinja.ext.do extension to Jinja. This enables {% do ... %} statements which execute a command for which the output should not be saved. A useful example is appending to a list. Since lists in Python return None, "None" would be written to the parsed jinja template in the following example: {% set a_list = [] %}{{ a_list.append("foo") }}. Instead, one can now use do:

{% set a_list = [] %}
{% do a_list.append("foo") %}

2. Lastly, this updates the lambda function for the add_to_datetime filter so any SilentUndefined input will return a SilentUndefined, preventing obscure failures.

This is needed for NOAA-EMC/global-workflow#2491
Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

How Has This Been Tested?

• pynorms
• pytests

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes need updates to the documentation. I have made corresponding changes to the documentation
• My changes generate no new warnings
• New and existing tests pass with my changes
• Any dependent changes have been merged and published

[codecov]

Codecov Report

Attention: Patch coverage is 50.00000% with 1 lines in your changes are missing coverage. Please review.

Project coverage is 47.87%. Comparing base (2c48c56) to head (1873fee).

Files	Patch %	Lines
src/wxflow/jinja.py	50.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop      #26      +/-   ##
===========================================
+ Coverage    47.84%   47.87%   +0.03%     
===========================================
  Files           18       18              
  Lines         1649     1650       +1     
  Branches       335      335              
===========================================
+ Hits           789      790       +1     
  Misses         801      801              
  Partials        59       59              

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

[DavidHuber-NOAA]

After a conversation with @aerorahul, I removed the Template-based filter. I will instead write a method in the Jinja class to handle substitution using regex in a separate PR.

[aerorahul]

looks good.