add message parameter to @deprecated

Author: LostInDarkMath

CHANGELOG.md

@@ -1,7 +1,8 @@
 # Changelog
 ## Pedantic 2.4.0
 - migrate from unittest to pytest
-- exclude tests from package
+- exclude tests from package deployment
+- add an optional `message` argument to `@deprecated` decorator
 
 ## Pedantic 2.3.3
 - [fixed validation error message in MinLength validator](https://github.com/LostInDarkMath/pedantic-python-decorators/issues/111)

docs/pedantic/decorators/fn_deco_deprecated.html

@@ -45,37 +45,53 @@ <h1 class="title">Module <code>pedantic.decorators.fn_deco_deprecated</code></h1
 <h2 class="section-title" id="header-functions">Functions</h2>
 <dl>
 <dt id="pedantic.decorators.fn_deco_deprecated.deprecated"><code class="name flex">
-<span>def <span class="ident">deprecated</span></span>(<span>func: Callable[..., ~ReturnType]) ‑> Callable[..., ~ReturnType]</span>
+<span>def <span class="ident">deprecated</span></span>(<span>func: Callable[..., ~ReturnType] | None = None, message: str = '') ‑> Callable[..., ~ReturnType] | Callable[[Callable[..., ~ReturnType]], Callable[..., ~ReturnType]]</span>
 </code></dt>
 <dd>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
-<pre><code class="python">def deprecated(func: F) -&gt; F:
+<pre><code class="python">def deprecated(func: F | None = None, message: str = &#39;&#39;) -&gt; F | Callable[[F], F]:
     &#34;&#34;&#34;
         Use this decorator to mark a function as deprecated. It will raise a warning when the function is called.
+        You can specify an optional reason or message to display with the warning.
 
         Example:
-
         &gt;&gt;&gt; @deprecated
         ... def my_function(a, b, c):
         ...     pass
-        &gt;&gt;&gt; my_function(5, 4, 3)
+        &gt;&gt;&gt; my_function(5, 4, 3)  # doctest: +SKIP
+        &gt;&gt;&gt; @deprecated(message=&#39;Will be removed soon. Please use my_function_new_instead.&#39;)
+        ... def my_function(a, b, c):
+        ...     pass
+        &gt;&gt;&gt; my_function(5, 4, 3)  # doctest: +SKIP
     &#34;&#34;&#34;
 
-    @wraps(func)
-    def wrapper(*args: Any, **kwargs: Any) -&gt; ReturnType:
-        _raise_warning(msg=f&#39;Call to deprecated function {func.__qualname__}.&#39;, category=DeprecationWarning)
-        return func(*args, **kwargs)
-    return wrapper</code></pre>
+    def decorator(fun: F) -&gt; F:
+        @wraps(fun)
+        def wrapper(*args: Any, **kwargs: Any) -&gt; ReturnType:
+            msg = f&#39;Call to deprecated function {fun.__qualname__}.&#39;
+
+            if message:
+                msg += f&#39;\nReason: {message}&#39;
+
+            warnings.warn(message=msg, category=DeprecationWarning, stacklevel=2)
+            return fun(*args, **kwargs)
+        return wrapper
+    return decorator if func is None else decorator(func)</code></pre>
 </details>
-<div class="desc"><p>Use this decorator to mark a function as deprecated. It will raise a warning when the function is called.</p>
+<div class="desc"><p>Use this decorator to mark a function as deprecated. It will raise a warning when the function is called.
+You can specify an optional reason or message to display with the warning.</p>
 <p>Example:</p>
 <pre><code class="language-python-repl">&gt;&gt;&gt; @deprecated
 ... def my_function(a, b, c):
 ...     pass
-&gt;&gt;&gt; my_function(5, 4, 3)
+&gt;&gt;&gt; my_function(5, 4, 3)  # doctest: +SKIP
+&gt;&gt;&gt; @deprecated(message='Will be removed soon. Please use my_function_new_instead.')
+... def my_function(a, b, c):
+...     pass
+&gt;&gt;&gt; my_function(5, 4, 3)  # doctest: +SKIP
 </code></pre></div>
 </dd>
 </dl>

docs/pedantic/index.html

@@ -64,10 +64,6 @@ <h2 class="section-title" id="header-submodules">Sub-modules</h2>
 <dd>
 <div class="desc"></div>
 </dd>
-<dt><code class="name"><a title="pedantic.helper_methods" href="helper_methods.html">pedantic.helper_methods</a></code></dt>
-<dd>
-<div class="desc"></div>
-</dd>
 <dt><code class="name"><a title="pedantic.mixins" href="mixins/index.html">pedantic.mixins</a></code></dt>
 <dd>
 <div class="desc"></div>
@@ -102,7 +98,6 @@ <h2 class="section-title" id="header-submodules">Sub-modules</h2>
 <li><code><a title="pedantic.examples" href="examples/index.html">pedantic.examples</a></code></li>
 <li><code><a title="pedantic.exceptions" href="exceptions.html">pedantic.exceptions</a></code></li>
 <li><code><a title="pedantic.get_context" href="get_context.html">pedantic.get_context</a></code></li>
-<li><code><a title="pedantic.helper_methods" href="helper_methods.html">pedantic.helper_methods</a></code></li>
 <li><code><a title="pedantic.mixins" href="mixins/index.html">pedantic.mixins</a></code></li>
 <li><code><a title="pedantic.models" href="models/index.html">pedantic.models</a></code></li>
 <li><code><a title="pedantic.type_checking_logic" href="type_checking_logic/index.html">pedantic.type_checking_logic</a></code></li>

pedantic/decorators/cls_deco_frozen_dataclass.py

@@ -142,8 +142,3 @@ def validate_types(self, *, _context: Dict[str, Type] = None) -> None:
         return decorator
 
     return decorator(cls_=cls)
-
-
-if __name__ == '__main__':
-    import doctest
-    doctest.testmod(verbose=False, optionflags=doctest.ELLIPSIS)

pedantic/decorators/fn_deco_count_calls.py

@@ -30,8 +30,3 @@ def wrapper(*args: Any, **kwargs: Any) -> ReturnType:
 
     wrapper.num_calls = 0
     return wrapper
-
-
-if __name__ == "__main__":
-    import doctest
-    doctest.testmod(verbose=False, optionflags=doctest.ELLIPSIS)

pedantic/decorators/fn_deco_deprecated.py

@@ -1,29 +1,40 @@
+import warnings
 from functools import wraps
-from typing import Any
+from typing import Any, Callable, overload
 
 from pedantic.constants import F, ReturnType
-from pedantic.helper_methods import _raise_warning
 
+@overload
+def deprecated(func: F) -> F: ...
 
-def deprecated(func: F) -> F:
+@overload
+def deprecated(*, message: str = '') -> Callable[[F], F]: ...
+
+def deprecated(func: F | None = None, message: str = '') -> F | Callable[[F], F]:
     """
         Use this decorator to mark a function as deprecated. It will raise a warning when the function is called.
+        You can specify an optional reason or message to display with the warning.
 
         Example:
-
         >>> @deprecated
         ... def my_function(a, b, c):
         ...     pass
-        >>> my_function(5, 4, 3)
+        >>> my_function(5, 4, 3)  # doctest: +SKIP
+        >>> @deprecated(message='Will be removed soon. Please use my_function_new_instead.')
+        ... def my_function(a, b, c):
+        ...     pass
+        >>> my_function(5, 4, 3)  # doctest: +SKIP
     """
 
-    @wraps(func)
-    def wrapper(*args: Any, **kwargs: Any) -> ReturnType:
-        _raise_warning(msg=f'Call to deprecated function {func.__qualname__}.', category=DeprecationWarning)
-        return func(*args, **kwargs)
-    return wrapper
+    def decorator(fun: F) -> F:
+        @wraps(fun)
+        def wrapper(*args: Any, **kwargs: Any) -> ReturnType:
+            msg = f'Call to deprecated function {fun.__qualname__}.'
 
+            if message:
+                msg += f'\nReason: {message}'
 
-if __name__ == "__main__":
-    import doctest
-    doctest.testmod(verbose=False, optionflags=doctest.ELLIPSIS)
+            warnings.warn(message=msg, category=DeprecationWarning, stacklevel=2)
+            return fun(*args, **kwargs)
+        return wrapper
+    return decorator if func is None else decorator(func)

pedantic/decorators/fn_deco_does_same_as_function.py

@@ -52,8 +52,3 @@ async def async_wrapper(*args: Any, **kwargs: Any) -> ReturnType:
             return wrapper
 
     return decorator
-
-
-if __name__ == "__main__":
-    import doctest
-    doctest.testmod(verbose=False, optionflags=doctest.ELLIPSIS)

pedantic/decorators/fn_deco_in_subprocess.py

@@ -120,9 +120,3 @@ def _inner(tx: Connection, fun: Callable[..., Union[T, Awaitable[T]]], *a, **kw_
         tx.send(SubprocessError(ex=ex))
     else:
         tx.send(res)
-
-
-if __name__ == '__main__':
-    import doctest
-
-    doctest.testmod(verbose=False, optionflags=doctest.ELLIPSIS)

pedantic/decorators/fn_deco_mock.py

@@ -36,8 +36,3 @@ async def async_wrapper(*args: Any, **kwargs: Any) -> ReturnType:
         else:
             return wrapper
     return decorator
-
-
-if __name__ == "__main__":
-    import doctest
-    doctest.testmod(verbose=False, optionflags=doctest.ELLIPSIS)

pedantic/decorators/fn_deco_overrides.py

@@ -29,8 +29,3 @@ def decorator(func: F) -> F:
                 f'Base class "{base_class.__name__}" does not have such a method "{name}".')
         return func
     return decorator
-
-
-if __name__ == "__main__":
-    import doctest
-    doctest.testmod(verbose=False, optionflags=doctest.ELLIPSIS)