gh-149132: Add module keyword argument to typing.TypeAliasType

Add an optional keyword-only `module` argument to
`typing.TypeAliasType` that overrides the `__module__` attribute
inferred by frame introspection. When omitted, behavior is unchanged.

closes #149132.

Author: ericmarkmartin

Doc/library/typing.rst

@@ -2315,7 +2315,8 @@ without the dedicated syntax, as documented below.
    .. versionadded:: 3.10
 
 
-.. class:: TypeAliasType(name, value, *, type_params=(), qualname=None)
+.. class:: TypeAliasType(name, value, *, type_params=(), qualname=None, \
+                         module=None)
 
    The type of type aliases created through the :keyword:`type` statement.
 
@@ -2327,8 +2328,20 @@ without the dedicated syntax, as documented below.
       >>> type(Alias)
       <class 'typing.TypeAliasType'>
 
+   When *module* is given, it is used as the new alias's
+   :attr:`~TypeAliasType.__module__`. When not given (or when ``None`` is
+   passed explicitly), the module is inferred from the calling frame's
+   globals. Inference can yield ``None`` when no ``__name__`` is in scope
+   (e.g. inside :func:`exec` with a fresh globals dict), or it can yield
+   an unwanted module name when an alias is built inside a factory helper
+   or generated code. Pass *module* explicitly when the inferred module
+   would be wrong or unavailable.
+
    .. versionadded:: 3.12
 
+   .. versionchanged:: 3.15
+      Added the *module* parameter.
+
    .. attribute:: __name__
 
       The name of the type alias:

Lib/test/test_type_aliases.py

@@ -328,6 +328,20 @@ def test_keywords(self):
         self.assertEqual(TA.__type_params__, ())
         self.assertEqual(TA.__module__, __name__)
 
+    def test_with_module(self):
+        TA = TypeAliasType("TA", int, module="my.custom.pkg")
+        self.assertEqual(TA.__module__, "my.custom.pkg")
+
+    def test_with_module_with_exec(self):
+        ns = {}
+        exec(
+            "from typing import TypeAliasType\n"
+            "TA = TypeAliasType('TA', int, module='x.y')",
+            ns,
+            ns,
+        )
+        self.assertEqual(ns["TA"].__module__, "x.y")
+
     def test_errors(self):
         with self.assertRaises(TypeError):
             TypeAliasType()

Misc/NEWS.d/next/Library/2026-04-29-12-00-00.gh-issue-149132.aB3cDe.rst

@@ -0,0 +1,5 @@
+Add an optional keyword-only ``module`` argument to :class:`typing.TypeAliasType`.
+When supplied, it overrides the module inferred from the calling frame, which
+can yield ``None`` (e.g. inside :func:`exec` with a fresh globals dict) or
+an unwanted module (e.g. inside factory helpers). Mirrors the long-standing
+``module`` argument of :class:`enum.Enum`'s functional API.

Objects/clinic/typevarobject.c.h

@@ -2149,14 +2149,16 @@ typealias.__new__ as typealias_new
     *
     type_params: object = NULL
     qualname: object(c_default="NULL") = None
+    module: object(c_default="NULL") = None
 
 Create a TypeAliasType.
 [clinic start generated code]*/
 
 static PyObject *
 typealias_new_impl(PyTypeObject *type, PyObject *name, PyObject *value,
-                   PyObject *type_params, PyObject *qualname)
-/*[clinic end generated code: output=b7f6d9f1c577cd9c input=cbec290f8c4886ef]*/
+                   PyObject *type_params, PyObject *qualname,
+                   PyObject *module)
+/*[clinic end generated code: output=263bf69bc54213c5 input=229c9f63109a44b9]*/
 {
     if (type_params != NULL && !PyTuple_Check(type_params)) {
         PyErr_SetString(PyExc_TypeError, "type_params must be a tuple");
@@ -2179,14 +2181,19 @@ typealias_new_impl(PyTypeObject *type, PyObject *name, PyObject *value,
         }
     }
 
-    PyObject *module = caller();
-    if (module == NULL) {
-        return NULL;
+    PyObject *resolved_module;
+    if (module == NULL || module == Py_None) {
+        resolved_module = caller();
+        if (resolved_module == NULL) {
+            return NULL;
+        }
+    } else {
+        resolved_module = Py_NewRef(module);
     }
 
     PyObject *ta = (PyObject *)typealias_alloc(
-        name, qualname, checked_params, NULL, value, module);
-    Py_DECREF(module);
+        name, qualname, checked_params, NULL, value, resolved_module);
+    Py_DECREF(resolved_module);
     return ta;
 }