Added decorator to disable run time type checking (#180)

docs/api.rst

@@ -14,6 +14,8 @@ API reference
 
 .. autodecorator:: typechecked
 
+.. autodecorator:: typeguard_ignore
+
 .. autoclass:: TypeChecker
 
 .. autoexception:: TypeHintWarning

docs/userguide.rst

@@ -153,6 +153,17 @@ You can also customize the logic used to select which modules to instrument::
 
     install_import_hook('', cls=CustomFinder)
 
+To exclude specific functions or classes from run time type checking, use the ``@typeguard_ignore`` decorator::
+
+    from typeguard import typeguard_ignore
+
+    @typeguard_ignore
+    def f(x: int) -> int:
+        return str(x)
+
+Unlike :func:`~typing.no_type_check`, this decorator has no effect on static type checking.
+
+
 Using the pytest plugin
 -----------------------
 

docs/versionhistory.rst

@@ -3,6 +3,11 @@ Version history
 
 This library adheres to `Semantic Versioning 2.0 <https://semver.org/#semantic-versioning-200>`_.
 
+**UNRELEASED**
+
+- Added ``@typeguard_ignore`` decorator to exclude specific functions and classes from
+  runtime type checking (PR by Claudio Jolowicz)
+
 **2.11.1 (2021-02-16)**
 
 - Fixed compatibility with Python 3.10

src/typeguard/__init__.py

@@ -1,5 +1,6 @@
 __all__ = ('ForwardRefPolicy', 'TypeHintWarning', 'typechecked', 'check_return_type',
-           'check_argument_types', 'check_type', 'TypeWarning', 'TypeChecker')
+           'check_argument_types', 'check_type', 'TypeWarning', 'TypeChecker',
+           'typeguard_ignore')
 
 import collections.abc
 import gc
@@ -16,7 +17,7 @@
 from typing import (
     Callable, Any, Union, Dict, List, TypeVar, Tuple, Set, Sequence, get_type_hints, TextIO,
     Optional, IO, BinaryIO, Type, Generator, overload, Iterable, AsyncIterable, Iterator,
-    AsyncIterator, AbstractSet)
+    AsyncIterator, AbstractSet, TYPE_CHECKING)
 from unittest.mock import Mock
 from warnings import warn
 from weakref import WeakKeyDictionary, WeakValueDictionary
@@ -61,6 +62,16 @@ def isasyncgenfunction(func):
     evaluate_forwardref = ForwardRef._eval_type
 
 
+if TYPE_CHECKING:
+    _F = TypeVar("_F")
+
+    def typeguard_ignore(f: _F) -> _F:
+        """This decorator is a noop during static type-checking."""
+        return f
+else:
+    from typing import no_type_check as typeguard_ignore
+
+
 _type_hints_map = WeakKeyDictionary()  # type: Dict[FunctionType, Dict[str, Any]]
 _functions_map = WeakValueDictionary()  # type: Dict[CodeType, FunctionType]
 _missing = object()

tests/dummymodule.py

@@ -4,6 +4,8 @@
 
 from typing import no_type_check, no_type_check_decorator
 
+from typeguard import typeguard_ignore
+
 
 @no_type_check_decorator
 def dummy_decorator(func):
@@ -24,6 +26,11 @@ def non_type_checked_decorated_func(x: int, y: str) -> 6:
     return 'foo'
 
 
+@typeguard_ignore
+def non_typeguard_checked_func(x: int, y: str) -> 6:
+    return 'foo'
+
+
 def dynamic_type_checking_func(arg, argtype, return_annotation):
     def inner(x: argtype) -> return_annotation:
         return str(x)

tests/mypy/negative.py

@@ -1,4 +1,4 @@
-from typeguard import check_argument_types, check_return_type, typechecked
+from typeguard import check_argument_types, check_return_type, typechecked, typeguard_ignore
 
 
 @typechecked
@@ -11,6 +11,11 @@ def bar(x: int) -> int:
     return str(x)  # error: Incompatible return value type (got "str", expected "int")
 
 
+@typeguard_ignore
+def non_typeguard_checked_func(x: int) -> int:
+    return str(x)  # error: Incompatible return value type (got "str", expected "int")
+
+
 def returns_str() -> str:
     return bar(0)  # error: Incompatible return value type (got "int", expected "str")
 

tests/mypy/test_type_annotations.py

@@ -45,7 +45,7 @@ def get_expected_errors() -> Dict[int, str]:
             expected[idx + 1] = line[line.index("# error") + 2:]
 
     # Sanity check.  Should update if negative.py changes.
-    assert len(expected) == 8
+    assert len(expected) == 9
     return expected
 
 

tests/test_importhook.py

@@ -50,6 +50,10 @@ def test_non_type_checked_decorated_func(dummymodule):
     assert dummymodule.non_type_checked_decorated_func('bah', 9) == 'foo'
 
 
+def test_typeguard_ignored_func(dummymodule):
+    assert dummymodule.non_typeguard_checked_func('bah', 9) == 'foo'
+
+
 def test_type_checked_method(dummymodule):
     instance = dummymodule.DummyClass()
     pytest.raises(TypeError, instance.type_checked_method, 'bah', 9).\