diff --git a/src/7-to-8/major-changes/compatibility-mode.rst b/src/7-to-8/major-changes/compatibility-mode.rst index 2d19dea402..ac83959324 100644 --- a/src/7-to-8/major-changes/compatibility-mode.rst +++ b/src/7-to-8/major-changes/compatibility-mode.rst @@ -59,7 +59,7 @@ See :ref:`below ` for an example. ``cylc validate`` operates on the processed ``suite.rc``, which means it will not detect any deprecated syntax that is inside a - currently-unused Jinja2/EmPy ``if...else`` branch. + currently-unused Jinja2 ``if...else`` branch. Some workflows may require modifications to either upgrade to Cylc 8 or make interoperable with Cylc 8 backward compatibility mode. Read on for more details. diff --git a/src/7-to-8/major-changes/config-changes.rst b/src/7-to-8/major-changes/config-changes.rst index ea304c2c28..18bdfdd4b3 100644 --- a/src/7-to-8/major-changes/config-changes.rst +++ b/src/7-to-8/major-changes/config-changes.rst @@ -9,7 +9,7 @@ The old configurations are now deprecated, but still supported. These will be highlighted upon ``cylc validate`` after renaming ``suite.rc`` to ``flow.cylc``. -Because some workflows use Jinja2 or EmPy branches which may not be switched on at +Because some workflows use Jinja2 branches which may not be switched on at the time of the initial ``cylc validate`` we have also provided a script, :ref:`cylc lint -r 728 ` to check for Cylc 7 syntax which may be deprecated. diff --git a/src/7-to-8/major-changes/template-vars.rst b/src/7-to-8/major-changes/template-vars.rst index a97836bada..70cedae1ce 100644 --- a/src/7-to-8/major-changes/template-vars.rst +++ b/src/7-to-8/major-changes/template-vars.rst @@ -7,16 +7,16 @@ Template Variables Read this section if you set Cylc template variables on the command line using the ``-s``, ``--set`` or ``-set-file`` options. - This does *not* affect the Rose ``jinja2:suite.rc`` and - ``empy:suite.rc`` variables set using the ``-S`` option to the + This does *not* affect the Rose ``jinja2:suite.rc`` + variables set using the ``-S`` option to the ``rose suite-run`` command. Overview -------- -Template variables are passed to :ref:`Jinja2 ` or -:ref:`EmPy ` for parsing the workflow definition in the +Template variables are passed to :ref:`Jinja2 ` +for parsing the workflow definition in the :cylc:conf:`flow.cylc` file. In Cylc 7 template variables could only be strings, in Cylc 8 they can be any diff --git a/src/dictionaries/proper_nouns b/src/dictionaries/proper_nouns index 51eb2e3861..6fb9253318 100644 --- a/src/dictionaries/proper_nouns +++ b/src/dictionaries/proper_nouns @@ -8,8 +8,6 @@ Conda Cylc cylc Datapoint -Empy -EmPy Exeter Gantt Gedit diff --git a/src/glossary.rst b/src/glossary.rst index bd1aaa8b34..023825673a 100644 --- a/src/glossary.rst +++ b/src/glossary.rst @@ -1266,8 +1266,7 @@ Glossary tasks. Other ways of consolidating configuration include :term:`runtime - inheritance` and templating with :ref:`Jinja2 ` or :ref:`Empy - `. + inheritance` and templating with :ref:`Jinja2 `. .. code-block:: cylc diff --git a/src/hyperlinks.rst.include b/src/hyperlinks.rst.include index 9a22b11f2e..e1a6ea728a 100644 --- a/src/hyperlinks.rst.include +++ b/src/hyperlinks.rst.include @@ -9,7 +9,6 @@ .. _Cylc Discourse Forum (7-to-8 topic): https://cylc.discourse.group/c/cylc/7-to-8/13 .. _DataPoint: https://www.metoffice.gov.uk/services/data/datapoint .. _Discourse: https://cylc.discourse.group/ -.. _EmPy: https://pypi.org/project/empy/ .. _FCM User Guide: http://metomi.github.io/fcm/doc/user_guide/ .. _FCM: https://metomi.github.io/fcm/doc/ .. _INI: https://en.wikipedia.org/wiki/INI_file diff --git a/src/installation.rst b/src/installation.rst index 0b72501bf9..11fb29a942 100644 --- a/src/installation.rst +++ b/src/installation.rst @@ -69,9 +69,6 @@ install: .. code-block:: sub - # EmPy support - $ pip install 'cylc-flow[empy]' - # Support for running the tutorial workflows $ pip install 'cylc-flow[tutorial]' diff --git a/src/plugins/install/index.rst b/src/plugins/install/index.rst index 335c07b3c4..ea313e127b 100644 --- a/src/plugins/install/index.rst +++ b/src/plugins/install/index.rst @@ -99,10 +99,10 @@ following keys: A dictionary of environment variables to be exported to the scheduler environment. ``template_variables`` - A dictionary of template variables to be used by Jinja2 or EmPy when + A dictionary of template variables to be used by Jinja2 when templating the workflow configuration files. ``templating_detected`` - ``jinja2`` | ``empy`` to be used when templating. N.b: This will result in + ``jinja2`` to be used when templating. N.b: This will result in failure if the templating language set does not match the shebang line of the ``flow.cylc`` file. diff --git a/src/reference/changes.rst b/src/reference/changes.rst index 0138bd8c26..23595584d3 100644 --- a/src/reference/changes.rst +++ b/src/reference/changes.rst @@ -22,6 +22,28 @@ For more detail see the component changelogs: ---------- + +Cylc 8.4 +-------- + +.. TODO - fix before release + + .. admonition:: Cylc Components + :class: hint + + :cylc-flow: `8.3 `__ + :cylc-ui: `2.5 `__ + :cylc-uiserver: `1.5 `__ + :cylc-rose: `1.4 `__ + :rose: `2.3 `__ + +EmPy Support Removed +^^^^^^^^^^^^^^^^^^^^ + +Support for the EmPy template processor (an alternative to Jinja2) has been +removed. + + Cylc 8.3 -------- diff --git a/src/user-guide/troubleshooting.rst b/src/user-guide/troubleshooting.rst index 57897507c2..7e7f7a0a5a 100644 --- a/src/user-guide/troubleshooting.rst +++ b/src/user-guide/troubleshooting.rst @@ -494,7 +494,7 @@ workflows: ``cylc view`` Prints workflow configurations before full parsing by Cylc. This can include :ref:`Jinja2 ` (use ``-j``) - or Empy template processing. + processing. Include files can be inlined (use ``-i``). diff --git a/src/user-guide/writing-workflows/configuration.rst b/src/user-guide/writing-workflows/configuration.rst index a02c64ede1..8e196627ee 100644 --- a/src/user-guide/writing-workflows/configuration.rst +++ b/src/user-guide/writing-workflows/configuration.rst @@ -19,10 +19,9 @@ The configurations you can use are documented in :ref:`workflow-configuration`. .. _template processors: https://en.wikipedia.org/wiki/Template_processor -Cylc also supports two `template processors`_ for use in the ``flow.cylc`` file: - -* `Jinja2`_ -* `EmPy`_ +Cylc also supports the `Jinja2`_ +`template processor `_ +for use in the `flow.cylc` file. .. _WorkflowDefinitionDirectories: @@ -70,12 +69,12 @@ Understanding Code in Workflow Configurations A workflow configuration is not executable code. It configures the scheduler program to run your workflow. A `flow.cylc` file may contain: -- Embedded Python-like Jinja2 or EmPy templating code, such as +- Embedded Python-like Jinja2 templating code, such as ``{% set PLANET = "earth" %}`` - Bash shell variable assignments and scripting, such as ``script = "run-model.exe /path/to/data"`` -Jinja2 (or EmPy) templating code gets executed as a preprocessing step, to +Jinja2 templating code gets executed as a preprocessing step, to programmatically generate the workflow configuration for the scheduler. To see the result after template processing: diff --git a/src/user-guide/writing-workflows/empy.rst b/src/user-guide/writing-workflows/empy.rst deleted file mode 100644 index c006107e21..0000000000 --- a/src/user-guide/writing-workflows/empy.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. _User Guide EmPy: - -EmPy -==== - -Cylc also supports the EmPy template processor in workflow configurations. -Like :ref:`User Guide Jinja2`, EmPy provides variables, mathematical -expressions, loop control structures, conditional logic, etc., that gets -expanded to generate the final workflow configuration seen - which must must be -valid Cylc syntax. See `EmPy`_ documentation -for details of its templating features and how to use them. - -.. note:: - - EmPy is not included in the standard Cylc installation. If installing - with ``pip`` run ``pip install cylc-flow[empy]`` to install it. - -.. TODO: update this when the conda instructions change - -To enable EmPy place an ``empy`` hash-bang comment on the first line of -the ``flow.cylc`` file: - -.. code-block:: cylc - - #!empy - - -As an example, here is the "cities" workflow from the previous section, -implemented with Empy instead of Jinja2. - -.. literalinclude:: ../../workflows/empy/cities/flow.cylc - :language: cylc - -For basic usage, the difference between Jinja2 and EmPy amounts to little more than -a different markup syntax. EmPy might be preferable, however, in cases needing -more complicated processing logic. - -*EmPy is a system for embedding Python expressions and statements in template -text. It makes the full power of Python language and its ecosystem easily -accessible from within the template. This might be desirable for several -reasons:* - -- No need to learn a different language just for writing template logic -- Availability of lambda functions, lists, and dictionary comprehensions - can make template code smaller and more readable compared to Jinja2 -- Natural and straightforward integration with the Python package ecosystem -- No two-language barrier between writing template logic and processing - extensions makes it easier to refactor and maintain the template code - as its complexity grows. Inline Python code can be gathered into subroutines - and eventually into separate modules and packages in a seamless manner. - - -Workflow files and Context Variables ------------------------------------- - -The EmPy processor has the same access as Jinja2 to -:ref:`workflow files ` and -:ref:`workflow context variables `. diff --git a/src/user-guide/writing-workflows/index.rst b/src/user-guide/writing-workflows/index.rst index e1aa3351ee..8c10fb0716 100644 --- a/src/user-guide/writing-workflows/index.rst +++ b/src/user-guide/writing-workflows/index.rst @@ -9,7 +9,6 @@ Writing Workflows runtime parameterized-tasks jinja2 - empy external-triggers suicide-triggers scheduler diff --git a/src/user-guide/writing-workflows/parameterized-tasks.rst b/src/user-guide/writing-workflows/parameterized-tasks.rst index 73633344e9..756099122b 100644 --- a/src/user-guide/writing-workflows/parameterized-tasks.rst +++ b/src/user-guide/writing-workflows/parameterized-tasks.rst @@ -15,8 +15,8 @@ values. Uses for this include: .. note:: - Cylc supports use of :ref:`Jinja2 ` and :ref:`Empy - ` templating for programmatic generation of workflow + Cylc supports use of :ref:`Jinja2 ` + templating for programmatic generation of workflow configurations. The built-in parameterization system described here is a cleaner and easier alternative *for generating tasks and families over a range of parameters*, but unlike general templating it can only be diff --git a/src/user-guide/writing-workflows/runtime.rst b/src/user-guide/writing-workflows/runtime.rst index 6363a7248b..df545cd222 100644 --- a/src/user-guide/writing-workflows/runtime.rst +++ b/src/user-guide/writing-workflows/runtime.rst @@ -105,7 +105,7 @@ task-specific settings. .. note:: :ref:`Task parameters ` or template processing (see - :ref:`User Guide Jinja2` and :ref:`User Guide EmPy`) can be used to + :ref:`User Guide Jinja2`) can be used to programmatically generate family members and associated dependencies. diff --git a/src/workflows/empy/cities/flow.cylc b/src/workflows/empy/cities/flow.cylc deleted file mode 100644 index 748a037f60..0000000000 --- a/src/workflows/empy/cities/flow.cylc +++ /dev/null @@ -1,52 +0,0 @@ -#!EmPy -[meta] - title = "EmPy city workflow example." - description = """ - Illustrates use of variables and math expressions, and programmatic - generation of groups of related dependencies and runtime properties. - """ - -[scheduler] - allow implicit tasks = True - -@{ -HOST = "SuperComputer" -CITIES = 'NewYork', 'Philadelphia', 'Newark', 'Houston', 'SantaFe', 'Chicago' -CITYJOBS = 'one', 'two', 'three', 'four' -LIMIT_MINS = 20 -CLEANUP = True -} - -[scheduling] - initial cycle point = 2011-08-08T12 - [[graph]] -@[ if CLEANUP ] - T23 = clean -@[ end if ] - T00,T12 = """ - setup => get_lbc & get_ic # foo -@[ for CITY in CITIES ]@# comment - get_lbc => @(CITY)_one - get_ic => @(CITY)_two - @(CITY)_one & @(CITY)_two => @(CITY)_three & @(CITY)_four - @[ if CLEANUP ] - @(CITY)_three & @(CITY)_four => cleanup - @[ end if ] -@[ end for ] - """ -[runtime] - [[on_@HOST ]] - [[[remote]]] - host = @HOST - # (remote cylc directory is set in site/user config for this host) - [[[directives]]] - wall_clock_limit = "00:@(LIMIT_MINS + 2):00,00:@(LIMIT_MINS):00" - -@[ for CITY in CITIES ] - [[ @(CITY) ]] - inherit = on_@(HOST) - @[ for JOB in CITYJOBS ] - [[ @(CITY)_@(JOB) ]] - inherit = @CITY - @[ end for ] -@[ end for ]