Add jbotDeprecated directive with dictionary as single argument.

This can be used when you move templates and want an existing jbot
override for the old template path to still work.

Example:

* You move `old_package/test.pt` to `new_package/test.pt`.
* You register a dictionary with: `{"old_package.test.pt": "new_package.test.pt"}`
* If a third party package has a template override `old_package.test.pt`, we display a warning that the package should use `new_package.test.pt`.
* The override with the old name still works: instead of `new_package/test.pt`, the override is used.
* Of course an override with the new name works as well.

Sample warning for a template that is moved from plone.app.layout to plone.classicui:

UserWarning: Template /Users/maurits/zeelandia/plone60/src/zeelandia.theme/src/zeelandia/theme/browser/overrides/plone.app.layout.viewlets.searchbox.pt deprecated, use plone.classicui.viewlets.searchbox.pt

For background, see plone/plone.classicui#7

CHANGES.rst

@@ -4,7 +4,10 @@ Changes
 2.2 (unreleased)
 ----------------
 
-- Nothing changed yet.
+- Add ``jbotDeprecated`` directive with ``dictionary`` as single argument.
+  This can be used when you move templates and want an existing jbot
+  override for the old template path to still work.
+  [maurits]
 
 
 2.1 (2024-11-29)

src/z3c/jbot/manager.py

@@ -1,5 +1,6 @@
 import os
 import sys
+import warnings
 
 from zope.interface import implementer
 
@@ -9,6 +10,14 @@
 
 IGNORE = object()
 DELETE = object()
+# Dictionary of templates that have been moved to a new location,
+# and for which we want an override for the old location to still work
+# for the new location as well.
+DEPRECATED_TEMPLATES_DICT = {}
+
+
+def update_deprecated_templates_dict(dictionary):
+    DEPRECATED_TEMPLATES_DICT.update(dictionary)
 
 
 def normalize(filepath):
@@ -97,9 +106,15 @@ def registerDirectory(self, directory):
 
         for filename in os.listdir(directory):
             filename = os.path.normcase(filename)
-            self.paths[filename] = normalize(
-                "%s%s%s" %
-                (directory, os.path.sep, filename))
+            full_path = normalize(f"{directory}{os.path.sep}{filename}")
+            self.paths[filename] = full_path
+            canonical_filename = DEPRECATED_TEMPLATES_DICT.get(filename)
+            if canonical_filename:
+                warnings.warn(
+                    f"Template {full_path} deprecated, "
+                    f"use {canonical_filename} instead."
+                )
+                self.paths[canonical_filename] = full_path
 
         for template, filename in list(self.templates.items()):
             if filename is IGNORE:

src/z3c/jbot/meta.zcml

@@ -16,6 +16,12 @@
          handler=".metaconfigure.templateOverridesDirective"
          />
 
+      <meta:directive
+         name="jbotDeprecated"
+         schema=".metadirectives.IDeprecatedTemplatesDirective"
+         handler=".metaconfigure.deprecatedTemplatesDirective"
+         />
+
     </meta:directives>
 
 </configure>

src/z3c/jbot/metaconfigure.py

@@ -2,6 +2,8 @@
 from zope import interface
 from zope.publisher.interfaces.browser import IBrowserPublisher
 
+from .manager import update_deprecated_templates_dict
+
 
 try:
     from plone.resource.file import FilesystemFile
@@ -60,3 +62,13 @@ def templateOverridesDirective(_context, directory, layer=interface.Interface):
         callable=handler,
         args=(directory, layer),
     )
+
+
+def deprecatedTemplatesDirective(_context, dictionary):
+    # Discriminators must be hashable.
+    dict_discriminator = "-".join(sorted(dictionary.keys()))
+    _context.action(
+        discriminator=('jbot', dict_discriminator),
+        callable=update_deprecated_templates_dict,
+        args=(dictionary,),
+    )

src/z3c/jbot/metadirectives.py

@@ -16,3 +16,27 @@ class ITemplateOverridesDirective(Interface):
         description="By default overrides are used for all layers.",
         required=False,
     )
+
+
+class IDeprecatedTemplatesDirective(Interface):
+    """Directive which registers a dictionary with deprecated templates.
+
+    This can be used when you move templates and want an existing jbot
+    override for the old template path to still work.
+
+    Example:
+
+    * You move old_package/test.pt to new_package/test.pt.
+    * You register a dictionary with:
+      {"old_package.test.pt": "new_package.test.pt"}
+    * If a third party package has a template override old_package.test.pt,
+      we display a warning that the package should use new_package.test.pt.
+    * The override with the old name still works:
+      instead of new_package/test.pt, the override is used.
+    * Of course an override with the new name works as well.
+    """
+
+    dictionary = GlobalObject(
+        title="Python path to dictionary",
+        required=True,
+    )