added note about PYTHONPATH & CYLC_PYTHONPATH (#665)

added note about PYTHONPATH & CYLC_PYTHONPATH --------- Co-authored-by: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com>
cylc · Nov 15, 2023 · 83d8b53 · 83d8b53
1 parent 6d2e882
commit 83d8b53
Show file tree

Hide file tree

Showing 4 changed files with 18 additions and 4 deletions.
diff --git a/src/reference/changes.rst b/src/reference/changes.rst
@@ -38,6 +38,14 @@ Cylc 8.3.0
    :cylc-uiserver: `1.4 <https://github.com/cylc/cylc-uiserver/blob/1.4.x/CHANGES.md>`__
    :cylc-rose: `1.4 <https://github.com/cylc/cylc-rose/blob/1.4.x/CHANGES.md>`__
 
+Cylc ignores ``$PYTHONPATH``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Cylc now ignores ``$PYTHONPATH`` to make it more robust to task
+environments which set this value. If you want to add to the Cylc
+environment itself, e.g. to install a Cylc extension,
+use a custom xtrigger, or event handler use ``$CYLC_PYTHONPATH``.
+
 
 Upgrade To The Latest Jupyter Releases
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -156,11 +164,11 @@ Combined Commands
 
 Two new commands have been added as short-cuts for common working patterns:
 
-``cylc vip`` 
+``cylc vip``
    Validate, install and plays a workflow, equivalent to:
 
    .. code-block:: bash
-   
+
       cylc validate <path>
       cylc install <path>
       cylc play <id>

diff --git a/src/user-guide/writing-workflows/external-triggers.rst b/src/user-guide/writing-workflows/external-triggers.rst
@@ -237,7 +237,7 @@ properties:
 - they can be located either:
 
   - in ``<workflow-dir>/lib/python/``;
-  - or anywhere in your Python library path.
+  - or anywhere in your ``$CYLC_PYTHONPATH``.
 
 - they can take arbitrary positional and keyword arguments
 - workflow and task identity, and cycle point, can be passed to trigger

diff --git a/src/user-guide/writing-workflows/runtime.rst b/src/user-guide/writing-workflows/runtime.rst
@@ -325,7 +325,7 @@ as it is running, these can be placed in:
 * ``share/bin/`` - for executables. This location is automatically added to ``PATH``
   (before the top-level ``bin/`` in the run dir).
 * ``share/lib/python/`` - for Python modules. This location is automatically added
-  to ``PYTHONPATH`` (before the top-level ``lib/python/`` in the run dir).
+  to ``$PYTHONPATH`` (before the top-level ``lib/python/`` in the run dir).
 
 .. note::
 

diff --git a/src/user-guide/writing-workflows/scheduler.rst b/src/user-guide/writing-workflows/scheduler.rst
@@ -120,6 +120,12 @@ when a workflow is started:
        [[events]]
            startup handlers = my-handler %(workflow)s %(host) %(port)
 
+
+.. note::
+
+   If you wish to use custom Python Libraries in an event handler you
+   need to add these to ``CYLC_PYTHONPATH`` rather than ``PYTHONPATH``.
+
 .. _workflow_event_template_variables:
 
 Workflow Event Template Variables