CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 696 – Type Defaults for Type Parameters | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0696/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 696 – Type Defaults for Type Parameters | peps.python.org'> <meta property="og:description" content="This PEP introduces the concept of type defaults for type parameters, including TypeVar, ParamSpec, and TypeVarTuple, which act as defaults for type parameters for which no type is specified."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0696/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP introduces the concept of type defaults for type parameters, including TypeVar, ParamSpec, and TypeVarTuple, which act as defaults for type parameters for which no type is specified."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 696</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 696 – Type Defaults for Type Parameters</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">James Hilton-Balfe <gobot1234yt at gmail.com></dd> <dt class="field-even">Sponsor:</dt> <dd class="field-even">Jelle Zijlstra <jelle.zijlstra at gmail.com></dd> <dt class="field-odd">Discussions-To:</dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/pep-696-type-defaults-for-typevarlikes/22569">Discourse thread</a></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Topic:</dt> <dd class="field-even"><a class="reference external" href="../topic/typing/">Typing</a></dd> <dt class="field-odd">Created:</dt> <dd class="field-odd">14-Jul-2022</dd> <dt class="field-even">Python-Version:</dt> <dd class="field-even">3.13</dd> <dt class="field-odd">Post-History:</dt> <dd class="field-odd"><a class="reference external" href="https://mail.python.org/archives/list/typing-sig@python.org/thread/7VWBZWXTCX6RAJO6GG67BAXUPFZ24NTC/" title="Typing-SIG thread">22-Mar-2022</a>, <a class="reference external" href="https://discuss.python.org/t/pep-696-type-defaults-for-typevarlikes/22569/" title="Discourse thread">08-Jan-2023</a></dd> <dt class="field-even">Resolution:</dt> <dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/pep-696-type-defaults-for-typevarlikes/22569/34">Discourse message</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#default-ordering-and-subscription-rules">Default Ordering and Subscription Rules</a></li> <li><a class="reference internal" href="#paramspec-defaults"><code class="docutils literal notranslate">ParamSpec</code> Defaults</a></li> <li><a class="reference internal" href="#typevartuple-defaults"><code class="docutils literal notranslate">TypeVarTuple</code> Defaults</a></li> <li><a class="reference internal" href="#using-another-type-parameter-as-default">Using Another Type Parameter as <code class="docutils literal notranslate">default</code></a><ul> <li><a class="reference internal" href="#scoping-rules">Scoping Rules</a></li> <li><a class="reference internal" href="#bound-rules">Bound Rules</a></li> <li><a class="reference internal" href="#constraint-rules">Constraint Rules</a></li> <li><a class="reference internal" href="#type-parameters-as-parameters-to-generics">Type Parameters as Parameters to Generics</a></li> <li><a class="reference internal" href="#specialisation-rules">Specialisation Rules</a></li> </ul> </li> <li><a class="reference internal" href="#generic-typealiases"><code class="docutils literal notranslate">Generic</code> <code class="docutils literal notranslate">TypeAlias</code>es</a></li> <li><a class="reference internal" href="#subclassing">Subclassing</a></li> <li><a class="reference internal" href="#using-bound-and-default">Using <code class="docutils literal notranslate">bound</code> and <code class="docutils literal notranslate">default</code></a></li> <li><a class="reference internal" href="#constraints">Constraints</a></li> <li><a class="reference internal" href="#function-defaults">Function Defaults</a></li> <li><a class="reference internal" href="#defaults-following-typevartuple">Defaults following <code class="docutils literal notranslate">TypeVarTuple</code></a></li> <li><a class="reference internal" href="#subtyping">Subtyping</a></li> <li><a class="reference internal" href="#typevartuples-as-defaults"><code class="docutils literal notranslate">TypeVarTuple</code>s as Defaults</a></li> </ul> </li> <li><a class="reference internal" href="#binding-rules">Binding rules</a></li> <li><a class="reference internal" href="#implementation">Implementation</a><ul> <li><a class="reference internal" href="#grammar-changes">Grammar changes</a></li> </ul> </li> <li><a class="reference internal" href="#rejected-alternatives">Rejected Alternatives</a><ul> <li><a class="reference internal" href="#allowing-the-type-parameters-defaults-to-be-passed-to-type-new-s-kwargs">Allowing the Type Parameters Defaults to Be Passed to <code class="docutils literal notranslate">type.__new__</code>’s <code class="docutils literal notranslate">**kwargs</code></a></li> <li><a class="reference internal" href="#allowing-non-defaults-to-follow-defaults">Allowing Non-defaults to Follow Defaults</a></li> <li><a class="reference internal" href="#having-default-implicitly-be-bound">Having <code class="docutils literal notranslate">default</code> Implicitly Be <code class="docutils literal notranslate">bound</code></a></li> <li><a class="reference internal" href="#allowing-type-parameters-with-defaults-to-be-used-in-function-signatures">Allowing Type Parameters With Defaults To Be Used in Function Signatures</a></li> <li><a class="reference internal" href="#allowing-type-parameters-from-outer-scopes-in-default">Allowing Type Parameters from Outer Scopes in <code class="docutils literal notranslate">default</code></a></li> </ul> </li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <div class="pep-banner canonical-typing-spec sticky-banner admonition attention"> Attention This PEP is a historical document: see <a class="reference external" href="https://typing.readthedocs.io/en/latest/spec/generics.html#type-parameter-defaults" title="(in typing)">Defaults for Type Parameters</a> and <a class="reference external" href="https://docs.python.org/3.13/reference/compound_stmts.html#type-params" title="(in Python v3.13)">Type parameter lists</a> for up-to-date specs and documentation. Canonical typing specs are maintained at the <a class="reference external" href="https://typing.readthedocs.io/en/latest/spec/">typing specs site</a>; runtime typing behaviour is described in the CPython documentation. × See the <a class="reference external" href="https://typing.readthedocs.io/en/latest/spec/meta.html">typing specification update process</a> for how to propose changes to the typing spec. </div> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This PEP introduces the concept of type defaults for type parameters, including <code class="docutils literal notranslate">TypeVar</code>, <code class="docutils literal notranslate">ParamSpec</code>, and <code class="docutils literal notranslate">TypeVarTuple</code>, which act as defaults for type parameters for which no type is specified. Default type argument support is available in some popular languages such as C++, TypeScript, and Rust. A survey of type parameter syntax in some common languages has been conducted by the author of <a class="pep reference internal" href="../pep-0695/" title="PEP 695 – Type Parameter Syntax">PEP 695</a> and can be found in its <a class="pep reference internal" href="../pep-0695/#appendix-a-survey-of-type-parameter-syntax" title="PEP 695 – Type Parameter Syntax § Appendix A: Survey of Type Parameter Syntax">Appendix A</a>. </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> <div class="highlight-default notranslate"><div class="highlight"><pre>T = TypeVar("T", default=int) # This means that if no type is specified T = int @dataclass class Box(Generic[T]): value: T | None = None reveal_type(Box()) # type is Box[int] reveal_type(Box(value="Hello World!")) # type is Box[str] </pre></div> </div> One place this <a class="reference external" href="https://github.com/python/typing/issues/975">regularly comes up</a> is <code class="docutils literal notranslate">Generator</code>. I propose changing the stub definition to something like: <div class="highlight-default notranslate"><div class="highlight"><pre>YieldT = TypeVar("YieldT") SendT = TypeVar("SendT", default=None) ReturnT = TypeVar("ReturnT", default=None) class Generator(Generic[YieldT, SendT, ReturnT]): ... Generator[int] == Generator[int, None] == Generator[int, None, None] </pre></div> </div> This is also useful for a <code class="docutils literal notranslate">Generic</code> that is commonly over one type. <div class="highlight-default notranslate"><div class="highlight"><pre>class Bot: ... BotT = TypeVar("BotT", bound=Bot, default=Bot) class Context(Generic[BotT]): bot: BotT class MyBot(Bot): ... reveal_type(Context().bot) # type is Bot # notice this is not Any which is what it would be currently reveal_type(Context[MyBot]().bot) # type is MyBot </pre></div> </div> Not only does this improve typing for those who explicitly use it, it also helps non-typing users who rely on auto-complete to speed up their development. This design pattern is common in projects like: <ul class="simple"> <li><a class="reference external" href="https://github.com/Rapptz/discord.py">discord.py</a> — where the example above was taken from.</li> <li><a class="reference external" href="https://github.com/numpy/numpy">NumPy</a> — the default for types like <code class="docutils literal notranslate">ndarray</code>’s <code class="docutils literal notranslate">dtype</code> would be <code class="docutils literal notranslate">float64</code>. Currently it’s <code class="docutils literal notranslate">Unknown</code> or <code class="docutils literal notranslate">Any</code>.</li> <li><a class="reference external" href="https://github.com/tensorflow/tensorflow">TensorFlow</a> — this could be used for Tensor similarly to <code class="docutils literal notranslate">numpy.ndarray</code> and would be useful to simplify the definition of <code class="docutils literal notranslate">Layer</code>.</li> </ul> </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> <section id="default-ordering-and-subscription-rules"> <h3><a class="toc-backref" href="#default-ordering-and-subscription-rules" role="doc-backlink">Default Ordering and Subscription Rules</a></h3> The order for defaults should follow the standard function parameter rules, so a type parameter with no <code class="docutils literal notranslate">default</code> cannot follow one with a <code class="docutils literal notranslate">default</code> value. Doing so should ideally raise a <code class="docutils literal notranslate">TypeError</code> in <code class="docutils literal notranslate">typing._GenericAlias</code>/<code class="docutils literal notranslate">types.GenericAlias</code>, and a type checker should flag this as an error. <div class="highlight-default notranslate"><div class="highlight"><pre>DefaultStrT = TypeVar("DefaultStrT", default=str) DefaultIntT = TypeVar("DefaultIntT", default=int) DefaultBoolT = TypeVar("DefaultBoolT", default=bool) T = TypeVar("T") T2 = TypeVar("T2") class NonDefaultFollowsDefault(Generic[DefaultStrT, T]): ... # Invalid: non-default TypeVars cannot follow ones with defaults class NoNonDefaults(Generic[DefaultStrT, DefaultIntT]): ... ( NoNoneDefaults == NoNoneDefaults[str] == NoNoneDefaults[str, int] ) # All valid class OneDefault(Generic[T, DefaultBoolT]): ... OneDefault[float] == OneDefault[float, bool] # Valid reveal_type(OneDefault) # type is type[OneDefault[T, DefaultBoolT = bool]] reveal_type(OneDefault[float]()) # type is OneDefault[float, bool] class AllTheDefaults(Generic[T1, T2, DefaultStrT, DefaultIntT, DefaultBoolT]): ... reveal_type(AllTheDefaults) # type is type[AllTheDefaults[T1, T2, DefaultStrT = str, DefaultIntT = int, DefaultBoolT = bool]] reveal_type(AllTheDefaults[int, complex]()) # type is AllTheDefaults[int, complex, str, int, bool] AllTheDefaults[int] # Invalid: expected 2 arguments to AllTheDefaults ( AllTheDefaults[int, complex] == AllTheDefaults[int, complex, str] == AllTheDefaults[int, complex, str, int] == AllTheDefaults[int, complex, str, int, bool] ) # All valid </pre></div> </div> With the new Python 3.12 syntax for generics (introduced by <a class="pep reference internal" href="../pep-0695/" title="PEP 695 – Type Parameter Syntax">PEP 695</a>), this can be enforced at compile time: <div class="highlight-default notranslate"><div class="highlight"><pre>type Alias[DefaultT = int, T] = tuple[DefaultT, T] # SyntaxError: non-default TypeVars cannot follow ones with defaults def generic_func[DefaultT = int, T](x: DefaultT, y: T) -> None: ... # SyntaxError: non-default TypeVars cannot follow ones with defaults class GenericClass[DefaultT = int, T]: ... # SyntaxError: non-default TypeVars cannot follow ones with defaults </pre></div> </div> </section> <section id="paramspec-defaults"> <h3><a class="toc-backref" href="#paramspec-defaults" role="doc-backlink"><code class="docutils literal notranslate">ParamSpec</code> Defaults</a></h3> <code class="docutils literal notranslate">ParamSpec</code> defaults are defined using the same syntax as <code class="docutils literal notranslate">TypeVar</code> s but use a <code class="docutils literal notranslate">list</code> of types or an ellipsis literal “<code class="docutils literal notranslate">...</code>” or another in-scope <code class="docutils literal notranslate">ParamSpec</code> (see <a class="reference internal" href="#scoping-rules">Scoping Rules</a>). <div class="highlight-default notranslate"><div class="highlight"><pre>DefaultP = ParamSpec("DefaultP", default=[str, int]) class Foo(Generic[DefaultP]): ... reveal_type(Foo) # type is type[Foo[DefaultP = [str, int]]] reveal_type(Foo()) # type is Foo[[str, int]] reveal_type(Foo[[bool, bool]]()) # type is Foo[[bool, bool]] </pre></div> </div> </section> <section id="typevartuple-defaults"> <h3><a class="toc-backref" href="#typevartuple-defaults" role="doc-backlink"><code class="docutils literal notranslate">TypeVarTuple</code> Defaults</a></h3> <code class="docutils literal notranslate">TypeVarTuple</code> defaults are defined using the same syntax as <code class="docutils literal notranslate">TypeVar</code> s but use an unpacked tuple of types instead of a single type or another in-scope <code class="docutils literal notranslate">TypeVarTuple</code> (see <a class="reference internal" href="#scoping-rules">Scoping Rules</a>). <div class="highlight-default notranslate"><div class="highlight"><pre>DefaultTs = TypeVarTuple("DefaultTs", default=Unpack[tuple[str, int]]) class Foo(Generic[*DefaultTs]): ... reveal_type(Foo) # type is type[Foo[DefaultTs = *tuple[str, int]]] reveal_type(Foo()) # type is Foo[str, int] reveal_type(Foo[int, bool]()) # type is Foo[int, bool] </pre></div> </div> </section> <section id="using-another-type-parameter-as-default"> <h3><a class="toc-backref" href="#using-another-type-parameter-as-default" role="doc-backlink">Using Another Type Parameter as <code class="docutils literal notranslate">default</code></a></h3> This allows for a value to be used again when the type parameter to a generic is missing but another type parameter is specified. To use another type parameter as a default the <code class="docutils literal notranslate">default</code> and the type parameter must be the same type (a <code class="docutils literal notranslate">TypeVar</code>’s default must be a <code class="docutils literal notranslate">TypeVar</code>, etc.). <a class="reference external" href="https://github.com/python/typing/issues/159">This could be used on builtins.slice</a> where the <code class="docutils literal notranslate">start</code> parameter should default to <code class="docutils literal notranslate">int</code>, <code class="docutils literal notranslate">stop</code> default to the type of <code class="docutils literal notranslate">start</code> and step default to <code class="docutils literal notranslate">int | None</code>. <div class="highlight-default notranslate"><div class="highlight"><pre>StartT = TypeVar("StartT", default=int) StopT = TypeVar("StopT", default=StartT) StepT = TypeVar("StepT", default=int | None) class slice(Generic[StartT, StopT, StepT]): ... reveal_type(slice) # type is type[slice[StartT = int, StopT = StartT, StepT = int | None]] reveal_type(slice()) # type is slice[int, int, int | None] reveal_type(slice[str]()) # type is slice[str, str, int | None] reveal_type(slice[str, bool, timedelta]()) # type is slice[str, bool, timedelta] T2 = TypeVar("T2", default=DefaultStrT) class Foo(Generic[DefaultStrT, T2]): def __init__(self, a: DefaultStrT, b: T2) -> None: ... reveal_type(Foo(1, "")) # type is Foo[int, str] Foo[int](1, "") # Invalid: Foo[int, str] cannot be assigned to self: Foo[int, int] in Foo.__init__ Foo[int]("", 1) # Invalid: Foo[str, int] cannot be assigned to self: Foo[int, int] in Foo.__init__ </pre></div> </div> When using a type parameter as the default to another type parameter, the following rules apply, where <code class="docutils literal notranslate">T1</code> is the default for <code class="docutils literal notranslate">T2</code>. <section id="scoping-rules"> <h4><a class="toc-backref" href="#scoping-rules" role="doc-backlink">Scoping Rules</a></h4> <code class="docutils literal notranslate">T1</code> must be used before <code class="docutils literal notranslate">T2</code> in the parameter list of the generic. <div class="highlight-default notranslate"><div class="highlight"><pre>T2 = TypeVar("T2", default=T1) class Foo(Generic[T1, T2]): ... # Valid class Foo(Generic[T1]): class Bar(Generic[T2]): ... # Valid StartT = TypeVar("StartT", default="StopT") # Swapped defaults around from previous example StopT = TypeVar("StopT", default=int) class slice(Generic[StartT, StopT, StepT]): ... # ^^^^^^ Invalid: ordering does not allow StopT to be bound </pre></div> </div> Using a type parameter from an outer scope as a default is not supported. </section> <section id="bound-rules"> <h4><a class="toc-backref" href="#bound-rules" role="doc-backlink">Bound Rules</a></h4> <code class="docutils literal notranslate">T1</code>’s bound must be a subtype of <code class="docutils literal notranslate">T2</code>’s bound. <div class="highlight-default notranslate"><div class="highlight"><pre>T1 = TypeVar("T1", bound=int) TypeVar("Ok", default=T1, bound=float) # Valid TypeVar("AlsoOk", default=T1, bound=int) # Valid TypeVar("Invalid", default=T1, bound=str) # Invalid: int is not a subtype of str </pre></div> </div> </section> <section id="constraint-rules"> <h4><a class="toc-backref" href="#constraint-rules" role="doc-backlink">Constraint Rules</a></h4> The constraints of <code class="docutils literal notranslate">T2</code> must be a superset of the constraints of <code class="docutils literal notranslate">T1</code>. <div class="highlight-default notranslate"><div class="highlight"><pre>T1 = TypeVar("T1", bound=int) TypeVar("Invalid", float, str, default=T1) # Invalid: upper bound int is incompatible with constraints float or str T1 = TypeVar("T1", int, str) TypeVar("AlsoOk", int, str, bool, default=T1) # Valid TypeVar("AlsoInvalid", bool, complex, default=T1) # Invalid: {bool, complex} is not a superset of {int, str} </pre></div> </div> </section> <section id="type-parameters-as-parameters-to-generics"> <h4><a class="toc-backref" href="#type-parameters-as-parameters-to-generics" role="doc-backlink">Type Parameters as Parameters to Generics</a></h4> Type parameters are valid as parameters to generics inside of a <code class="docutils literal notranslate">default</code> when the first parameter is in scope as determined by the <a class="reference internal" href="#scoping-rules">previous section</a>. <div class="highlight-default notranslate"><div class="highlight"><pre>T = TypeVar("T") ListDefaultT = TypeVar("ListDefaultT", default=list[T]) class Bar(Generic[T, ListDefaultT]): def __init__(self, x: T, y: ListDefaultT): ... reveal_type(Bar) # type is type[Bar[T, ListDefaultT = list[T]]] reveal_type(Bar[int]) # type is type[Bar[int, list[int]]] reveal_type(Bar[int]()) # type is Bar[int, list[int]] reveal_type(Bar[int, list[str]]()) # type is Bar[int, list[str]] reveal_type(Bar[int, str]()) # type is Bar[int, str] </pre></div> </div> </section> <section id="specialisation-rules"> <h4><a class="toc-backref" href="#specialisation-rules" role="doc-backlink">Specialisation Rules</a></h4> Type parameters currently cannot be further subscripted. This might change if <a class="reference external" href="https://github.com/python/typing/issues/548">Higher Kinded TypeVars</a> are implemented. </section> </section> <section id="generic-typealiases"> <h3><a class="toc-backref" href="#generic-typealiases" role="doc-backlink"><code class="docutils literal notranslate">Generic</code> <code class="docutils literal notranslate">TypeAlias</code>es</a></h3> <code class="docutils literal notranslate">Generic</code> <code class="docutils literal notranslate">TypeAlias</code>es should be able to be further subscripted following normal subscription rules. If a type parameter has a default that hasn’t been overridden it should be treated like it was substituted into the <code class="docutils literal notranslate">TypeAlias</code>. However, it can be specialised further down the line. <div class="highlight-default notranslate"><div class="highlight"><pre>class SomethingWithNoDefaults(Generic[T, T2]): ... MyAlias: TypeAlias = SomethingWithNoDefaults[int, DefaultStrT] # Valid reveal_type(MyAlias) # type is type[SomethingWithNoDefaults[int, DefaultStrT]] reveal_type(MyAlias[bool]()) # type is SomethingWithNoDefaults[int, bool] MyAlias[bool, int] # Invalid: too many arguments passed to MyAlias </pre></div> </div> </section> <section id="subclassing"> <h3><a class="toc-backref" href="#subclassing" role="doc-backlink">Subclassing</a></h3> Subclasses of <code class="docutils literal notranslate">Generic</code>s with type parameters that have defaults behave similarly to <code class="docutils literal notranslate">Generic</code> <code class="docutils literal notranslate">TypeAlias</code>es. That is, subclasses can be further subscripted following normal subscription rules, non-overridden defaults should be substituted in, and type parameters with such defaults can be further specialised down the line. <div class="highlight-default notranslate"><div class="highlight"><pre>class SubclassMe(Generic[T, DefaultStrT]): x: DefaultStrT class Bar(SubclassMe[int, DefaultStrT]): ... reveal_type(Bar) # type is type[Bar[DefaultStrT = str]] reveal_type(Bar()) # type is Bar[str] reveal_type(Bar[bool]()) # type is Bar[bool] class Foo(SubclassMe[float]): ... reveal_type(Foo().x) # type is str Foo[str] # Invalid: Foo cannot be further subscripted class Baz(Generic[DefaultIntT, DefaultStrT]): ... class Spam(Baz): ... reveal_type(Spam()) # type is <subclass of Baz[int, str]> </pre></div> </div> </section> <section id="using-bound-and-default"> <h3><a class="toc-backref" href="#using-bound-and-default" role="doc-backlink">Using <code class="docutils literal notranslate">bound</code> and <code class="docutils literal notranslate">default</code></a></h3> If both <code class="docutils literal notranslate">bound</code> and <code class="docutils literal notranslate">default</code> are passed <code class="docutils literal notranslate">default</code> must be a subtype of <code class="docutils literal notranslate">bound</code>. Otherwise the type checker should generate an error. <div class="highlight-default notranslate"><div class="highlight"><pre>TypeVar("Ok", bound=float, default=int) # Valid TypeVar("Invalid", bound=str, default=int) # Invalid: the bound and default are incompatible </pre></div> </div> </section> <section id="constraints"> <h3><a class="toc-backref" href="#constraints" role="doc-backlink">Constraints</a></h3> For constrained <code class="docutils literal notranslate">TypeVar</code>s, the default needs to be one of the constraints. A type checker should generate an error even if it is a subtype of one of the constraints. <div class="highlight-default notranslate"><div class="highlight"><pre>TypeVar("Ok", float, str, default=float) # Valid TypeVar("Invalid", float, str, default=int) # Invalid: expected one of float or str got int </pre></div> </div> </section> <section id="function-defaults"> <h3><a class="toc-backref" href="#function-defaults" role="doc-backlink">Function Defaults</a></h3> In generic functions, type checkers may use a type parameter’s default when the type parameter cannot be solved to anything. We leave the semantics of this usage unspecified, as ensuring the <code class="docutils literal notranslate">default</code> is returned in every code path where the type parameter can go unsolved may be too hard to implement. Type checkers are free to either disallow this case or experiment with implementing support. <div class="highlight-default notranslate"><div class="highlight"><pre>T = TypeVar('T', default=int) def func(x: int | set[T]) -> T: ... reveal_type(func(0)) # a type checker may reveal T's default of int here </pre></div> </div> </section> <section id="defaults-following-typevartuple"> <h3><a class="toc-backref" href="#defaults-following-typevartuple" role="doc-backlink">Defaults following <code class="docutils literal notranslate">TypeVarTuple</code></a></h3> A <code class="docutils literal notranslate">TypeVar</code> that immediately follows a <code class="docutils literal notranslate">TypeVarTuple</code> is not allowed to have a default, because it would be ambiguous whether a type argument should be bound to the <code class="docutils literal notranslate">TypeVarTuple</code> or the defaulted <code class="docutils literal notranslate">TypeVar</code>. <div class="highlight-default notranslate"><div class="highlight"><pre>Ts = TypeVarTuple("Ts") T = TypeVar("T", default=bool) class Foo(Generic[Ts, T]): ... # Type checker error # Could be reasonably interpreted as either Ts = (int, str, float), T = bool # or Ts = (int, str), T = float Foo[int, str, float] </pre></div> </div> With the Python 3.12 built-in generic syntax, this case should raise a SyntaxError. However, it is allowed to have a <code class="docutils literal notranslate">ParamSpec</code> with a default following a <code class="docutils literal notranslate">TypeVarTuple</code> with a default, as there can be no ambiguity between a type argument for the <code class="docutils literal notranslate">ParamSpec</code> and one for the <code class="docutils literal notranslate">TypeVarTuple</code>. <div class="highlight-default notranslate"><div class="highlight"><pre>Ts = TypeVarTuple("Ts") P = ParamSpec("P", default=[float, bool]) class Foo(Generic[Ts, P]): ... # Valid Foo[int, str] # Ts = (int, str), P = [float, bool] Foo[int, str, [bytes]] # Ts = (int, str), P = [bytes] </pre></div> </div> </section> <section id="subtyping"> <h3><a class="toc-backref" href="#subtyping" role="doc-backlink">Subtyping</a></h3> Type parameter defaults do not affect the subtyping rules for generic classes. In particular, defaults can be ignored when considering whether a class is compatible with a generic protocol. </section> <section id="typevartuples-as-defaults"> <h3><a class="toc-backref" href="#typevartuples-as-defaults" role="doc-backlink"><code class="docutils literal notranslate">TypeVarTuple</code>s as Defaults</a></h3> Using a <code class="docutils literal notranslate">TypeVarTuple</code> as a default is not supported because: <ul class="simple"> <li><a class="reference internal" href="#scoping-rules">Scoping Rules</a> does not allow usage of type parameters from outer scopes.</li> <li>Multiple <code class="docutils literal notranslate">TypeVarTuple</code>s cannot appear in the type parameter list for a single object, as specified in <a class="pep reference internal" href="../pep-0646/#multiple-type-variable-tuples-not-allowed" title="PEP 646 – Variadic Generics § Multiple Type Variable Tuples: Not Allowed">PEP 646</a>.</li> </ul> These reasons leave no current valid location where a <code class="docutils literal notranslate">TypeVarTuple</code> could be used as the default of another <code class="docutils literal notranslate">TypeVarTuple</code>. </section> </section> <section id="binding-rules"> <h2><a class="toc-backref" href="#binding-rules" role="doc-backlink">Binding rules</a></h2> Type parameter defaults should be bound by attribute access (including call and subscript). <div class="highlight-default notranslate"><div class="highlight"><pre>class Foo[T = int]: def meth(self) -> Self: return self reveal_type(Foo.meth) # type is (self: Foo[int]) -> Foo[int] </pre></div> </div> </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> At runtime, this would involve the following changes to the <code class="docutils literal notranslate">typing</code> module. <ul class="simple"> <li>The classes <code class="docutils literal notranslate">TypeVar</code>, <code class="docutils literal notranslate">ParamSpec</code>, and <code class="docutils literal notranslate">TypeVarTuple</code> should expose the type passed to <code class="docutils literal notranslate">default</code>. This would be available as a <code class="docutils literal notranslate">__default__</code> attribute, which would be <code class="docutils literal notranslate">None</code> if no argument is passed and <code class="docutils literal notranslate">NoneType</code> if <code class="docutils literal notranslate">default=None</code>.</li> </ul> The following changes would be required to both <code class="docutils literal notranslate">GenericAlias</code>es: <ul class="simple"> <li>logic to determine the defaults required for a subscription.</li> <li>ideally, logic to determine if subscription (like <code class="docutils literal notranslate">Generic[T, DefaultT]</code>) would be valid.</li> </ul> The grammar for type parameter lists would need to be updated to allow defaults; see below. A reference implementation of the runtime changes can be found at <a class="reference external" href="https://github.com/Gobot1234/cpython/tree/pep-696">https://github.com/Gobot1234/cpython/tree/pep-696</a> A reference implementation of the type checker can be found at <a class="reference external" href="https://github.com/Gobot1234/mypy/tree/TypeVar-defaults">https://github.com/Gobot1234/mypy/tree/TypeVar-defaults</a> Pyright currently supports this functionality. <section id="grammar-changes"> <h3><a class="toc-backref" href="#grammar-changes" role="doc-backlink">Grammar changes</a></h3> The syntax added in <a class="pep reference internal" href="../pep-0695/" title="PEP 695 – Type Parameter Syntax">PEP 695</a> will be extended to introduce a way to specify defaults for type parameters using the “=” operator inside of the square brackets like so: <div class="highlight-default notranslate"><div class="highlight"><pre># TypeVars class Foo[T = str]: ... # ParamSpecs class Baz[**P = [int, str]]: ... # TypeVarTuples class Qux[*Ts = *tuple[int, bool]]: ... # TypeAliases type Foo[T, U = str] = Bar[T, U] type Baz[**P = [int, str]] = Spam[**P] type Qux[*Ts = *tuple[str]] = Ham[*Ts] type Rab[U, T = str] = Bar[T, U] </pre></div> </div> <a class="reference internal" href="../pep-0695/#scoping-behavior">Similarly to the bound for a type parameter</a>, defaults should be lazily evaluated, with the same scoping rules to avoid the unnecessary usage of quotes around them. This functionality was included in the initial draft of <a class="pep reference internal" href="../pep-0695/" title="PEP 695 – Type Parameter Syntax">PEP 695</a> but was removed due to scope creep. The following changes would be made to the grammar: <div class="highlight-default notranslate"><div class="highlight"><pre>type_param: | a=NAME b=[type_param_bound] d=[type_param_default] | a=NAME c=[type_param_constraint] d=[type_param_default] | '*' a=NAME d=[type_param_default] | '**' a=NAME d=[type_param_default] type_param_default: | '=' e=expression | '=' e=starred_expression </pre></div> </div> The compiler would enforce that type parameters without defaults cannot follow type parameters with defaults and that <code class="docutils literal notranslate">TypeVar</code>s with defaults cannot immediately follow <code class="docutils literal notranslate">TypeVarTuple</code>s. </section> </section> <section id="rejected-alternatives"> <h2><a class="toc-backref" href="#rejected-alternatives" role="doc-backlink">Rejected Alternatives</a></h2> <section id="allowing-the-type-parameters-defaults-to-be-passed-to-type-new-s-kwargs"> <h3><a class="toc-backref" href="#allowing-the-type-parameters-defaults-to-be-passed-to-type-new-s-kwargs" role="doc-backlink">Allowing the Type Parameters Defaults to Be Passed to <code class="docutils literal notranslate">type.__new__</code>’s <code class="docutils literal notranslate">**kwargs</code></a></h3> <div class="highlight-default notranslate"><div class="highlight"><pre>T = TypeVar("T") @dataclass class Box(Generic[T], T=int): value: T | None = None </pre></div> </div> While this is much easier to read and follows a similar rationale to the <code class="docutils literal notranslate">TypeVar</code> <a class="reference external" href="https://github.com/python/typing/issues/813">unary syntax</a>, it would not be backwards compatible as <code class="docutils literal notranslate">T</code> might already be passed to a metaclass/superclass or support classes that don’t subclass <code class="docutils literal notranslate">Generic</code> at runtime. Ideally, if <a class="pep reference internal" href="../pep-0637/" title="PEP 637 – Support for indexing with keyword arguments">PEP 637</a> wasn’t rejected, the following would be acceptable: <div class="highlight-default notranslate"><div class="highlight"><pre>T = TypeVar("T") @dataclass class Box(Generic[T = int]): value: T | None = None </pre></div> </div> </section> <section id="allowing-non-defaults-to-follow-defaults"> <h3><a class="toc-backref" href="#allowing-non-defaults-to-follow-defaults" role="doc-backlink">Allowing Non-defaults to Follow Defaults</a></h3> <div class="highlight-default notranslate"><div class="highlight"><pre>YieldT = TypeVar("YieldT", default=Any) SendT = TypeVar("SendT", default=Any) ReturnT = TypeVar("ReturnT") class Coroutine(Generic[YieldT, SendT, ReturnT]): ... Coroutine[int] == Coroutine[Any, Any, int] </pre></div> </div> Allowing non-defaults to follow defaults would alleviate the issues with returning types like <code class="docutils literal notranslate">Coroutine</code> from functions where the most used type argument is the last (the return). Allowing non-defaults to follow defaults is too confusing and potentially ambiguous, even if only the above two forms were valid. Changing the argument order now would also break a lot of codebases. This is also solvable in most cases using a <code class="docutils literal notranslate">TypeAlias</code>. <div class="highlight-default notranslate"><div class="highlight"><pre>Coro: TypeAlias = Coroutine[Any, Any, T] Coro[int] == Coroutine[Any, Any, int] </pre></div> </div> </section> <section id="having-default-implicitly-be-bound"> <h3><a class="toc-backref" href="#having-default-implicitly-be-bound" role="doc-backlink">Having <code class="docutils literal notranslate">default</code> Implicitly Be <code class="docutils literal notranslate">bound</code></a></h3> In an earlier version of this PEP, the <code class="docutils literal notranslate">default</code> was implicitly set to <code class="docutils literal notranslate">bound</code> if no value was passed for <code class="docutils literal notranslate">default</code>. This while convenient, could have a type parameter with no default follow a type parameter with a default. Consider: <div class="highlight-default notranslate"><div class="highlight"><pre>T = TypeVar("T", bound=int) # default is implicitly int U = TypeVar("U") class Foo(Generic[T, U]): ... # would expand to T = TypeVar("T", bound=int, default=int) U = TypeVar("U") class Foo(Generic[T, U]): ... </pre></div> </div> This would have also been a breaking change for a small number of cases where the code relied on <code class="docutils literal notranslate">Any</code> being the implicit default. </section> <section id="allowing-type-parameters-with-defaults-to-be-used-in-function-signatures"> <h3><a class="toc-backref" href="#allowing-type-parameters-with-defaults-to-be-used-in-function-signatures" role="doc-backlink">Allowing Type Parameters With Defaults To Be Used in Function Signatures</a></h3> A previous version of this PEP allowed <code class="docutils literal notranslate">TypeVarLike</code>s with defaults to be used in function signatures. This was removed for the reasons described in <a class="reference internal" href="#id1">Function Defaults</a>. Hopefully, this can be added in the future if a way to get the runtime value of a type parameter is added. </section> <section id="allowing-type-parameters-from-outer-scopes-in-default"> <h3><a class="toc-backref" href="#allowing-type-parameters-from-outer-scopes-in-default" role="doc-backlink">Allowing Type Parameters from Outer Scopes in <code class="docutils literal notranslate">default</code></a></h3> This was deemed too niche a feature to be worth the added complexity. If any cases arise where this is needed, it can be added in a future PEP. </section> </section> <section id="acknowledgements"> <h2><a class="toc-backref" href="#acknowledgements" role="doc-backlink">Acknowledgements</a></h2> Thanks to the following people for their feedback on the PEP: Eric Traut, Jelle Zijlstra, Joshua Butt, Danny Yamamoto, Kaylynn Morgan and Jakub Kuczys </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0696.rst">https://github.com/python/peps/blob/main/peps/pep-0696.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0696.rst">2024-09-03 17:24:02 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#default-ordering-and-subscription-rules">Default Ordering and Subscription Rules</a></li> <li><a class="reference internal" href="#paramspec-defaults"><code class="docutils literal notranslate">ParamSpec</code> Defaults</a></li> <li><a class="reference internal" href="#typevartuple-defaults"><code class="docutils literal notranslate">TypeVarTuple</code> Defaults</a></li> <li><a class="reference internal" href="#using-another-type-parameter-as-default">Using Another Type Parameter as <code class="docutils literal notranslate">default</code></a><ul> <li><a class="reference internal" href="#scoping-rules">Scoping Rules</a></li> <li><a class="reference internal" href="#bound-rules">Bound Rules</a></li> <li><a class="reference internal" href="#constraint-rules">Constraint Rules</a></li> <li><a class="reference internal" href="#type-parameters-as-parameters-to-generics">Type Parameters as Parameters to Generics</a></li> <li><a class="reference internal" href="#specialisation-rules">Specialisation Rules</a></li> </ul> </li> <li><a class="reference internal" href="#generic-typealiases"><code class="docutils literal notranslate">Generic</code> <code class="docutils literal notranslate">TypeAlias</code>es</a></li> <li><a class="reference internal" href="#subclassing">Subclassing</a></li> <li><a class="reference internal" href="#using-bound-and-default">Using <code class="docutils literal notranslate">bound</code> and <code class="docutils literal notranslate">default</code></a></li> <li><a class="reference internal" href="#constraints">Constraints</a></li> <li><a class="reference internal" href="#function-defaults">Function Defaults</a></li> <li><a class="reference internal" href="#defaults-following-typevartuple">Defaults following <code class="docutils literal notranslate">TypeVarTuple</code></a></li> <li><a class="reference internal" href="#subtyping">Subtyping</a></li> <li><a class="reference internal" href="#typevartuples-as-defaults"><code class="docutils literal notranslate">TypeVarTuple</code>s as Defaults</a></li> </ul> </li> <li><a class="reference internal" href="#binding-rules">Binding rules</a></li> <li><a class="reference internal" href="#implementation">Implementation</a><ul> <li><a class="reference internal" href="#grammar-changes">Grammar changes</a></li> </ul> </li> <li><a class="reference internal" href="#rejected-alternatives">Rejected Alternatives</a><ul> <li><a class="reference internal" href="#allowing-the-type-parameters-defaults-to-be-passed-to-type-new-s-kwargs">Allowing the Type Parameters Defaults to Be Passed to <code class="docutils literal notranslate">type.__new__</code>’s <code class="docutils literal notranslate">**kwargs</code></a></li> <li><a class="reference internal" href="#allowing-non-defaults-to-follow-defaults">Allowing Non-defaults to Follow Defaults</a></li> <li><a class="reference internal" href="#having-default-implicitly-be-bound">Having <code class="docutils literal notranslate">default</code> Implicitly Be <code class="docutils literal notranslate">bound</code></a></li> <li><a class="reference internal" href="#allowing-type-parameters-with-defaults-to-be-used-in-function-signatures">Allowing Type Parameters With Defaults To Be Used in Function Signatures</a></li> <li><a class="reference internal" href="#allowing-type-parameters-from-outer-scopes-in-default">Allowing Type Parameters from Outer Scopes in <code class="docutils literal notranslate">default</code></a></li> </ul> </li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0696.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>