add test for CONTEXTS; restore CONTEXTS related documentation (im…

…proved)

CHANGES.rst

@@ -10,12 +10,11 @@ https://zope.readthedocs.io/en/2.13/CHANGES.html
 4.4.5 (unreleased)
 ------------------
 
-- support the ``attrs`` predefined template variable again (as
+- Support the ``attrs`` predefined template variable again (as
   far as ``chameleon`` allows it)
   (`#860 <https://github.com/zopefoundation/Zope/issues/860>`_).
 
-- in the "Zope Book" remove ``CONTEXTS`` from the list of predefined
-  template variables (because it was never implemented).
+- Improve documentation of ``CONTEXTS`` in the "Zope Book".
 
 - Update dependencies to the latest releases that still support Python 2.
 

docs/zopebook/AppendixC.rst

@@ -698,6 +698,13 @@ Note that the (popular) ``chameleon`` template engine implements ``attrs``
 and ``default`` not as standard variables but in a special way.
 Trying to change their value may have undefined effects.
 
+Note that beside variables you can use ``CONTEXTS``
+as initial element in a path expression. Its value is a mapping
+from predefined variable names to their value. This can be used to
+access the predefined variable when it is hidden by a user defined
+definition for its name. Again, `attrs` is special; it is not covered
+by `CONTEXTS`.
+
 
 TALES Exists expressions
 ========================

src/Products/PageTemplates/tests/testVariables.py

@@ -19,6 +19,27 @@ class TestPredefinedVariables(PlacelessSetup, TestCase):
     as documented by
     `<https://zope.readthedocs.io/en/latest/zopebook/AppendixC.html#built-in-names`_
     """
+
+    # variables documented in the Zope Book
+    VARIABLES = set((
+        "nothing",
+        "default",
+        "options",
+        "repeat",
+        # "attrs",  # special -- not contained in ``CONTEXTS``
+        "root",
+        "context",
+        "container",
+        "template",
+        "request",
+        "user",
+        "modules",
+        #   special
+        #     - only usable as initial component in path expr
+        #     - not contained in ``CONTEXTS``
+        # "CONTEXTS",
+        ))  # noqa: E123
+
     def setUp(self):
         super(TestPredefinedVariables, self).setUp()
 
@@ -87,6 +108,24 @@ def test_user(self):
     def test_modules(self):
         self.check("modules")
 
+    def test_CONTEXTS(self):
+        # the "Zope Book" describes ``CONTEXTS`` as a variable.
+        # But, in fact, it is not a (regular) variable but a special
+        # case of the initial component of a (sub)path expression.
+        # As a consequence, it cannot be used in a Python expression
+        # but only as the first component in a path expression
+        # Therefore, we cannot use ``check`` to access it.
+        t = self.g.t
+        t.write("""<div tal:define="
+                x CONTEXTS;
+                dummy python:options['acc'].append(x)" />""")
+        acc = []
+        t(acc=acc)
+        ctx = acc[0]
+        self.assertIsInstance(ctx, dict)
+        # all variables included?
+        self.assertEqual(len(self.VARIABLES - set(ctx)), 0)
+
     def check(self, what):
         t = self.g.t
         t.write("<div attr='attr' "