Ver código fonte

Merge pull request #23707 from netbox-community/23498-deprecate-template-finalize

Closes #23498: Announce v5.0 removal of finalize on export and config templates
bctiemann 10 horas atrás
pai
commit
304de59418

+ 2 - 2
docs/models/extras/configtemplate.md

@@ -32,9 +32,9 @@ The `undefined` Jinja environment parameter, which must reference a Python class
 }
 ```
 
-!!! note "Changed in NetBox v4.6.1"
+!!! warning "Deprecation Warning"
 
-    The `finalize` parameter is deprecated and cannot be set on new or modified templates. Templates that already have it saved continue to honor it.
+    The `finalize` parameter has been deprecated as of NetBox v4.6.1, and is scheduled for removal in NetBox v5.0. It cannot be set on new or modified templates. Templates that already have it saved continue to honor it until then. Move any `finalize` logic into the template code itself.
 
 ### MIME Type
 

+ 2 - 2
docs/models/extras/exporttemplate.md

@@ -32,9 +32,9 @@ The `undefined` Jinja environment parameter, which must reference a Python class
 }
 ```
 
-!!! note "Changed in NetBox v4.6.1"
+!!! warning "Deprecation Warning"
 
-    The `finalize` parameter is deprecated and cannot be set on new or modified templates. Templates that already have it saved continue to honor it.
+    The `finalize` parameter has been deprecated as of NetBox v4.6.1, and is scheduled for removal in NetBox v5.0. It cannot be set on new or modified templates. Templates that already have it saved continue to honor it until then. Move any `finalize` logic into the template code itself.
 
 ### MIME Type
 

+ 13 - 0
netbox/extras/models/mixins.py

@@ -3,6 +3,7 @@ import importlib.util
 import logging
 import os
 import sys
+import warnings
 from collections import defaultdict
 
 from django.core.exceptions import ValidationError
@@ -26,6 +27,9 @@ __all__ = (
 
 logger = logging.getLogger(__name__)
 
+# (model name, pk) of templates that have already emitted the stored 'finalize' deprecation warning (#23498)
+_stored_finalize_warned = set()
+
 
 class CustomStoragesLoader(importlib.abc.Loader):
     """
@@ -253,6 +257,15 @@ class RenderTemplateMixin(models.Model):
                 type(self).__name__, self.pk,
             )
             return {key: value for key, value in params.items() if key != 'finalize'}
+        # Track warned templates here: the warnings registry resets whenever any code changes the warning filters.
+        warned_key = (type(self).__name__, self.pk)
+        if warned_key not in _stored_finalize_warned:
+            _stored_finalize_warned.add(warned_key)
+            warnings.warn(
+                f'The "finalize" environment parameter stored on {type(self).__name__} (pk={self.pk}) is deprecated '
+                'and will be removed in NetBox v5.0. Move its logic into the template code.',
+                FutureWarning,
+            )
         return {**params, 'finalize': stored_finalize}
 
     def get_environment_params(self):

+ 104 - 0
netbox/extras/tests/test_models.py

@@ -2,6 +2,7 @@ import io
 import os
 import sys
 import tempfile
+import warnings
 from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import patch
@@ -1709,6 +1710,109 @@ class ExportTemplateStoredOnlyFinalizeTestCase(TestCase):
             t.get_environment_params()
 
 
+class StoredFinalizeDeprecationWarningTestCase(TestCase):
+    """
+    A stored 'finalize' stays honored until v5.0, so operators get a once-per-template FutureWarning and unchanged
+    output (#23498).
+    """
+    TEMPLATE_CODE = '{{ "netbox" }}'
+    SHARED_PK = 9001
+
+    def setUp(self):
+        # Start each test with no templates marked as already warned
+        self.enterContext(patch('extras.models.mixins._stored_finalize_warned', set()))
+
+    def _create(self, model, name, **kwargs):
+        # create() does not call clean(). This matches a value stored before clean() blocked it.
+        return model.objects.create(name=name, template_code=self.TEMPLATE_CODE, **kwargs)
+
+    def _create_stored(self, model, name='stored'):
+        return self._create(model, name, environment_params={'finalize': 'builtins.len'})
+
+    def _render_recording(self, *templates):
+        """
+        Use the 'always' filter so any dedupe comes from the template mixin, not from the warnings registry.
+        """
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter('always')
+            for template in templates:
+                template.render()
+        return [w for w in caught if issubclass(w.category, FutureWarning)]
+
+    def test_render_output_unchanged_with_stored_finalize(self):
+        for model in (ExportTemplate, ConfigTemplate):
+            with self.subTest(model=model.__name__):
+                self._create_stored(model)
+                t = model.objects.get(name='stored')
+                with warnings.catch_warnings():
+                    warnings.simplefilter('ignore')
+                    self.assertEqual(t.render(), '6')
+
+    def test_warning_names_model_pk_and_removal_version(self):
+        for model in (ExportTemplate, ConfigTemplate):
+            with self.subTest(model=model.__name__):
+                t = self._create_stored(model, name=f'stored-{model.__name__}')
+                with self.assertNoLogs('extras.models.mixins', 'WARNING'):
+                    caught = self._render_recording(t)
+                self.assertEqual(len(caught), 1)
+                self.assertIs(caught[0].category, FutureWarning)
+                message = str(caught[0].message)
+                self.assertIn(model.__name__, message)
+                self.assertIn(f'pk={t.pk}', message)
+                self.assertIn('v5.0', message)
+                # Must read differently from the "Ignoring the deprecated..." log for in-memory values
+                self.assertNotIn('Ignoring', message)
+
+    def test_warns_once_per_template_per_process(self):
+        first = self._create_stored(ExportTemplate, name='first')
+        second = self._create_stored(ExportTemplate, name='second')
+        caught = self._render_recording(first, first, second, first, second)
+        self.assertEqual(len(caught), 2)
+        self.assertIn(f'pk={first.pk}', str(caught[0].message))
+        self.assertIn(f'pk={second.pk}', str(caught[1].message))
+
+    def test_warns_once_when_warning_filters_change_between_renders(self):
+        """
+        Changing the warning filters (catch_warnings(), filterwarnings(), urllib3.disable_warnings()) clears the
+        warnings registry. The once-per-template dedupe must not depend on it.
+        """
+        t = self._create_stored(ExportTemplate)
+        caught = []
+        for _ in range(3):
+            caught += self._render_recording(t)
+        self.assertEqual(len(caught), 1)
+
+    def test_warns_separately_for_models_sharing_a_pk(self):
+        params = {'finalize': 'builtins.len'}
+        export_template = self._create(ExportTemplate, 'export', pk=self.SHARED_PK, environment_params=params)
+        config_template = self._create(ConfigTemplate, 'config', pk=self.SHARED_PK, environment_params=params)
+        caught = self._render_recording(export_template, config_template)
+        self.assertEqual(len(caught), 2)
+
+    def test_no_warning_without_finalize(self):
+        for model in (ExportTemplate, ConfigTemplate):
+            with self.subTest(model=model.__name__):
+                t = self._create(model, f'plain-{model.__name__}', environment_params={'trim_blocks': True})
+                self.assertEqual(self._render_recording(t), [])
+
+    def test_no_warning_when_finalize_exists_only_in_memory(self):
+        t = self._create(ExportTemplate, 'saved')
+        t.environment_params = {'finalize': 'builtins.len'}
+        with self.assertLogs('extras.models.mixins', 'WARNING'):
+            caught = self._render_recording(t)
+        self.assertEqual(caught, [])
+
+    def test_no_warning_for_unsaved_template(self):
+        t = ExportTemplate(
+            name='unsaved',
+            template_code=self.TEMPLATE_CODE,
+            environment_params={'finalize': 'builtins.len'},
+        )
+        with self.assertLogs('extras.models.mixins', 'WARNING'):
+            caught = self._render_recording(t)
+        self.assertEqual(caught, [])
+
+
 class WebhookPayloadUrlValidationTestCase(TestCase):
     """Tests for Webhook.clean()'s validation of payload_url (#22828)."""