Repository: falconry/falcon
Pull request #1971 (2021-10-15 14:36:22)

chore: deprecate func compile_uri_template()
# Summary of Changes

First timer, I don't know if this is a correct for this so please advise. 

Add deprecated warning for func compile_uri_template()


# Related Issues
#1967

# Pull Request Checklist

This is just a reminder about the most common mistakes.  Please make sure that you tick all *appropriate* boxes.  But please read our [contribution guide](../CONTRIBUTING.md) at least once; it will save you a few review cycles!

If an item doesn't apply to your pull request, **check it anyway** to make it apparent that there's nothing to do.

- [x] Applied changes to both WSGI and ASGI code paths and interfaces (where applicable).
- [x] Added **tests** for changed code.
- [x] Prefixed code comments with GitHub nick and an appropriate prefix.
- [x] Coding style is consistent with the rest of the framework.
- [x] Updated **documentation** for changed code.
    - [x] Added docstrings for any new classes, functions, or modules.
    - [x] Updated docstrings for any modifications to existing code.
    - [x] Updated both WSGI and ASGI docs (where applicable).
    - [x] Added references to new classes, functions, or modules to the relevant RST file under `docs/`.
    - [x] Updated all relevant supporting documentation files under `docs/`.
    - [x] A copyright notice is included at the top of any new modules (using your own name or the name of your organization).
    - [x] Changed/added classes/methods/functions have appropriate `versionadded`, `versionchanged`, or `deprecated` [directives](http://www.sphinx-doc.org/en/stable/usage/restructuredtext/directives.html?highlight=versionadded#directive-versionadded).
- [x] Changes (and possible deprecations) have [towncrier](https://towncrier.readthedocs.io/en/actual-freaking-docs/index.html) news fragments under `docs/_newsfragments/`, with the file name format `{issue_number}.{fragment_type}.rst`. (Run `towncrier --draft` to ensure it renders correctly.)

If you have *any* questions to *any* of the points above, just **submit and ask**! This checklist is here to *help* you, not to deter you from contributing!

*PR template inspired by the attrs project.*


CaselIT: Thanks for the pr!


CaselIT: > Furthermore, we need to either wrap all tests in `tests/test_uri_templates_legacy.py` with `pytest.warns(...)`, or add a rule to ignore this warning, because we don't want to get spam in the test output about this.

it may make sense to make pytest fail the test if a warning gets raised, so that's explicitly handled
vytas7: @nix010 Just checking whether you are still working on this PR? We'd need to clean up the tests etc to make all CI gates pass as a first step, and check there are no new warnings introduced.

Patch:
diff --git a/docs/_newsfragments/1967.misc.rst b/docs/_newsfragments/1967.misc.rst
new file mode 100644
index 0000000..6285459
--- /dev/null
+++ b/docs/_newsfragments/1967.misc.rst
@@ -0,0 +1,6 @@
+The :func:`~falcon.routing.compile_uri_template` utility method has been
+deprecated and will be removed in Falcon 4.0. This function was only employed
+in the early versions of the framework, and is expected to have been fully
+supplanted by the :class:`~falcon.routing.CompiledRouter`. In the unlikely case
+it is still in active use, its source code can be simply copied into an
+affected application.
diff --git a/falcon/response.py b/falcon/response.py
index 031a63a..6ebcd67 100644
--- a/falcon/response.py
+++ b/falcon/response.py
@@ -38,11 +38,6 @@ from falcon.util.uri import encode_value_check_escaped as uri_encode_value
 
 GMT_TIMEZONE = TimezoneGMT()
 
-_ADD_LINK_DEPRECATED_MSG = (
-    'The add_link() method has been deprecated and will be removed in Falcon 4.0. '
-    'Please use append_link() instead.'
-)
-
 _STREAM_LEN_REMOVED_MSG = (
     'The deprecated stream_len property was removed in Falcon 3.0. '
     'Please use Response.set_stream() or Response.content_length instead.'
@@ -922,7 +917,9 @@ class Response:
             _headers['link'] = value
 
     # NOTE(kgriffs): Alias deprecated as of 3.0
-    add_link = deprecated(_ADD_LINK_DEPRECATED_MSG, method_name='add_link')(append_link)
+    add_link = deprecated('Please use append_link() instead.', method_name='add_link')(
+        append_link
+    )
 
     cache_control = header_property(
         'Cache-Control',
diff --git a/falcon/routing/util.py b/falcon/routing/util.py
index d9edc5b..b4f1fd8 100644
--- a/falcon/routing/util.py
+++ b/falcon/routing/util.py
@@ -18,6 +18,7 @@ import re
 
 from falcon import constants
 from falcon import responders
+from falcon.util.deprecation import deprecated
 
 
 class SuffixedMethodNotFoundError(Exception):
@@ -27,6 +28,7 @@ class SuffixedMethodNotFoundError(Exception):
 
 
 # NOTE(kgriffs): Published method; take care to avoid breaking changes.
+@deprecated('This method will be removed in Falcon 4.0.')
 def compile_uri_template(template):
     """Compile the given URI template string into a pattern matcher.
 
@@ -66,6 +68,8 @@ def compile_uri_template(template):
 
     Returns:
         tuple: (template_field_names, template_regex)
+
+    .. deprecated:: 3.1
     """
 
     if not isinstance(template, str):


Test patch:
diff --git a/tests/test_uri_templates_legacy.py b/tests/test_uri_templates_legacy.py
index 023a891..e7a19ea 100644
--- a/tests/test_uri_templates_legacy.py
+++ b/tests/test_uri_templates_legacy.py
@@ -2,8 +2,10 @@ import pytest
 
 import falcon
 from falcon import routing
+from falcon.util.deprecation import DeprecatedWarning
 
 
+@pytest.mark.filterwarnings('ignore:Call to deprecated function compile_uri_template')
 class TestUriTemplates:
     @pytest.mark.parametrize('value', (42, falcon.App))
     def test_string_type_required(self, value):
@@ -107,3 +109,10 @@ class TestUriTemplates:
         result = pattern.match('/one/{1b}/x/3')
         assert result
         assert result.groupdict() == {'a': 'one', 'c': '3'}
+
+    def test_deprecated_warning(self):
+        with pytest.warns(
+            DeprecatedWarning,
+            match='Call to deprecated function compile_uri_template().',
+        ):
+            routing.compile_uri_template('/')