gh-105578: Raise DeprecationWarning on typing.AnyStr usage

Author: sobolevn

Doc/deprecations/pending-removal-in-3.18.rst

@@ -11,6 +11,12 @@ Pending removal in Python 3.18
     C implementation, has been deprecated since Python 3.13.
     (Contributed by Serhiy Storchaka in :gh:`89902`.)
 
+* :mod:`typing`:
+
+   * :data:`typing.AnyStr` has been discouraged
+     and deprecated since Python 3.16.
+     Use :pep:`695` syntax instead.
+
 * Deprecations defined by :pep:`829`:
 
   * ``import`` lines in :file:`{name}.pth` files are silently ignored.

Doc/library/typing.rst

@@ -899,8 +899,8 @@ using ``[]``.
       Use ``class A[T: (str, bytes)]: ...`` instead of importing ``AnyStr``. See
       :pep:`695` for more details.
 
-      In Python 3.16, ``AnyStr`` will be removed from ``typing.__all__``, and
-      deprecation warnings will be emitted at runtime when it is accessed or
+      Since Python 3.16, ``AnyStr`` is removed from ``typing.__all__``, and
+      deprecation warnings is emitted at runtime when it is accessed or
       imported from ``typing``. ``AnyStr`` will be removed from ``typing``
       in Python 3.18.
 

Doc/whatsnew/3.16.rst

@@ -195,6 +195,10 @@ Deprecated
     3.9, now issues a deprecation warning on use. This property is slated for
     removal in 3.21. Use ``ast.Tuple.elts`` instead.
 
+* :mod:`typing`:
+
+   * :data:`typing.AnyStr` now raises :exc:`DeprecationWarning` when used.
+
 .. Add deprecations above alphabetically, not here at the end.
 
 

Lib/test/test_typing.py

@@ -20,7 +20,7 @@
 
 from typing import Any, NoReturn, Never, assert_never
 from typing import overload, get_overloads, clear_overloads
-from typing import TypeVar, TypeVarTuple, Unpack, AnyStr
+from typing import TypeVar, TypeVarTuple, Unpack
 from typing import T, KT, VT  # Not in __all__.
 from typing import Union, Optional, Literal
 from typing import Tuple, List, Dict, MutableMapping
@@ -49,6 +49,11 @@
 import weakref
 import types
 
+with warnings.catch_warnings():
+    warnings.simplefilter("ignore", DeprecationWarning)
+
+    from typing import AnyStr
+
 from test.support import (
     captured_stderr, cpython_only, requires_docstrings, import_helper, run_code,
     subTests, EqualToForwardRef,
@@ -9551,12 +9556,16 @@ def test_no_isinstance(self):
 class IOTests(BaseTestCase):
 
     def test_io(self):
-
         def stuff(a: IO) -> AnyStr:
             return a.readline()
 
         a = stuff.__annotations__['a']
-        self.assertEqual(a.__parameters__, (AnyStr,))
+        self.assertEqual(len(a.__parameters__), 1)
+        any_str = a.__parameters__[0]
+        self.assertEqual(repr(any_str), 'AnyStr')
+        self.assertEqual(any_str.__bound__, None)
+        self.assertEqual(any_str.__constraints__, (bytes, str))
+        self.assertEqual(any_str.__constraints__, AnyStr.__constraints__)
 
     def test_textio(self):
 
@@ -11176,13 +11185,20 @@ def test_all_exported_names(self):
                 # there's a few types and metaclasses that aren't exported
                 not k.endswith(('Meta', '_contra', '_co')) and
                 not k.upper() == k and
-                k not in {"ByteString"} and
+                k not in {"ByteString", "AnyStr"} and
                 # but export all other things that have __module__ == 'typing'
                 getattr(v, '__module__', None) == typing.__name__
             )
         }
         self.assertSetEqual(computed_all, actual_all)
 
+    def test_any_str_deprecated(self):
+        # gh-105578
+        fresh = import_helper.import_fresh_module('typing')
+
+        with self.assertWarnsRegex(DeprecationWarning, r'typing\.AnyStr'):
+            fresh.AnyStr
+
 
 class TypeIterationTests(BaseTestCase):
     _UNITERABLE_TYPES = (

Lib/typing.py

@@ -121,7 +121,6 @@
     'TextIO',
 
     # One-off things.
-    'AnyStr',
     'assert_type',
     'assert_never',
     'cast',
@@ -2815,11 +2814,6 @@ class Disjoint3(Disjoint1, Disjoint2): pass  # Type checker error
 CT_co = TypeVar('CT_co', covariant=True, bound=type)
 
 
-# A useful type variable with constraints.  This represents string types.
-# (This one *is* for export!)
-AnyStr = TypeVar('AnyStr', bytes, str)
-
-
 # Various ABCs mimicking those in collections.abc.
 _alias = _SpecialGenericAlias
 
@@ -3523,8 +3517,9 @@ def __ror__(self, other):
 # Constant that's True when type checking, but False here.
 TYPE_CHECKING = False
 
-
-class IO(Generic[AnyStr]):
+# Since `AnyStr` public API is deprecated since 3.16 and will be removed
+# in 3.18, we need to keep `IO` protocol the same as it used to be:
+class IO[AnyStr: (bytes, str)]:
     """Generic base class for TextIO and BinaryIO.
 
     This is an abstract, generic version of the return of open().
@@ -3571,19 +3566,19 @@ def isatty(self) -> bool:
         pass
 
     @abstractmethod
-    def read(self, n: int = -1, /) -> AnyStr:
+    def read(self, n: int = -1, /) -> _AnyStr:
         pass
 
     @abstractmethod
     def readable(self) -> bool:
         pass
 
     @abstractmethod
-    def readline(self, limit: int = -1, /) -> AnyStr:
+    def readline(self, limit: int = -1, /) -> _AnyStr:
         pass
 
     @abstractmethod
-    def readlines(self, hint: int = -1, /) -> list[AnyStr]:
+    def readlines(self, hint: int = -1, /) -> list[_AnyStr]:
         pass
 
     @abstractmethod
@@ -3607,15 +3602,15 @@ def writable(self) -> bool:
         pass
 
     @abstractmethod
-    def write(self, s: AnyStr, /) -> int:
+    def write(self, s: _AnyStr, /) -> int:
         pass
 
     @abstractmethod
-    def writelines(self, lines: list[AnyStr], /) -> None:
+    def writelines(self, lines: list[_AnyStr], /) -> None:
         pass
 
     @abstractmethod
-    def __enter__(self) -> IO[AnyStr]:
+    def __enter__(self) -> IO[_AnyStr]:
         pass
 
     @abstractmethod
@@ -3924,6 +3919,12 @@ def __subclasscheck__(self, cls):
             )
 
         return ByteString
+    elif attr == "AnyStr":
+        import warnings
+
+        warnings._deprecated("typing.AnyStr", remove=(3, 18))
+        AnyStr = globals()["AnyStr"] = TypeVar('AnyStr', bytes, str)
+        return AnyStr
     else:
         raise AttributeError(f"module {__name__!r} has no attribute {attr!r}")
     globals()[attr] = obj

Misc/NEWS.d/next/Library/2026-05-21-16-15-01.gh-issue-105578.oq-0pg.rst

@@ -0,0 +1,2 @@
+Deprecate :data:`typing.AnyStr` type variable and raise a warning, when it
+is imported.