592 lines
46 KiB
HTML
592 lines
46 KiB
HTML
|
||
<!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 729 – Typing governance process | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0729/">
|
||
<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 729 – Typing governance process | peps.python.org'>
|
||
<meta property="og:description" content="This PEP proposes a new way to govern the Python type system: a council that is responsible for maintaining and developing the Python type system. The council will maintain a specification and conformance test suite and will initially be appointed by th...">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0729/">
|
||
<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 proposes a new way to govern the Python type system: a council that is responsible for maintaining and developing the Python type system. The council will maintain a specification and conformance test suite and will initially be appointed by th...">
|
||
<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 729</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>
|
||
<span class="visually-hidden">Toggle light / dark / auto colour theme</span>
|
||
</button>
|
||
</header>
|
||
<article>
|
||
<section id="pep-content">
|
||
<h1 class="page-title">PEP 729 – Typing governance process</h1>
|
||
<dl class="rfc2822 field-list simple">
|
||
<dt class="field-odd">Author<span class="colon">:</span></dt>
|
||
<dd class="field-odd">Jelle Zijlstra <jelle.zijlstra at gmail.com>, Shantanu Jain <hauntsaninja at gmail.com></dd>
|
||
<dt class="field-even">Discussions-To<span class="colon">:</span></dt>
|
||
<dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/pep-729-typing-governance-process/35362">Discourse thread</a></dd>
|
||
<dt class="field-odd">Status<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><abbr title="Currently valid informational guidance, or an in-use process">Active</abbr></dd>
|
||
<dt class="field-even">Type<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Normative PEP describing or proposing a change to a Python community process, workflow or governance">Process</abbr></dd>
|
||
<dt class="field-odd">Topic<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="../topic/governance/">Governance</a>, <a class="reference external" href="../topic/typing/"> Typing</a></dd>
|
||
<dt class="field-even">Created<span class="colon">:</span></dt>
|
||
<dd class="field-even">19-Sep-2023</dd>
|
||
<dt class="field-odd">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/pep-729-typing-governance-process/35362" title="Discourse thread">04-Oct-2023</a>,
|
||
<a class="reference external" href="https://discuss.python.org/t/proposed-new-typing-governance-process/34244" title="Discourse thread">20-Sep-2023</a></dd>
|
||
<dt class="field-even">Resolution<span class="colon">:</span></dt>
|
||
<dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/pep-729-typing-governance-process/35362/12">20-Nov-2023</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><ul>
|
||
<li><a class="reference internal" href="#peps-are-the-only-specification">PEPs are the only specification</a></li>
|
||
<li><a class="reference internal" href="#it-s-hard-to-evolve-the-specification">It’s hard to evolve the specification</a></li>
|
||
<li><a class="reference internal" href="#the-type-system-is-underspecified">The type system is underspecified</a></li>
|
||
<li><a class="reference internal" href="#the-steering-council-is-not-well-placed-to-solve-the-above-problems">The Steering Council is not well-placed to solve the above problems</a></li>
|
||
<li><a class="reference internal" href="#endorsements">Endorsements</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#mandate">Mandate</a></li>
|
||
<li><a class="reference internal" href="#operations-and-process">Operations and process</a><ul>
|
||
<li><a class="reference internal" href="#relationship-with-the-steering-council">Relationship with the Steering Council</a></li>
|
||
<li><a class="reference internal" href="#relationship-with-type-checkers">Relationship with type checkers</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#projects">Projects</a><ul>
|
||
<li><a class="reference internal" href="#conformance-test-suite">Conformance test suite</a></li>
|
||
<li><a class="reference internal" href="#specification-for-the-type-system">Specification for the type system</a></li>
|
||
<li><a class="reference internal" href="#user-facing-reference-for-the-type-system">User-facing reference for the type system</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#amendments">Amendments</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#rejected-ideas">Rejected ideas</a><ul>
|
||
<li><a class="reference internal" href="#writing-the-specification-from-scratch">Writing the specification from scratch</a></li>
|
||
<li><a class="reference internal" href="#alternate-governance-mechanisms">Alternate governance mechanisms</a></li>
|
||
<li><a class="reference internal" href="#do-nothing">Do nothing</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#contact">Contact</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
</details></section>
|
||
<section id="abstract">
|
||
<h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2>
|
||
<p>This PEP proposes a new way to govern the Python type system: a council that is responsible
|
||
for maintaining and developing the Python type system. The council will maintain a
|
||
specification and conformance test suite and will initially be appointed by the Python Steering Council.</p>
|
||
</section>
|
||
<section id="motivation">
|
||
<h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2>
|
||
<p>The Python type system was created by <a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a>, almost ten years ago. The type
|
||
system is now widely used, and typing has become an important tool for writing
|
||
good, maintainable Python code. Many changes have been made to the type system to cover
|
||
more use cases and improve usability. Several type checkers have been created, each
|
||
with their own strengths. The type annotation syntax has driven several major innovations
|
||
in the Python ecosystem, such as the popular <a class="reference external" href="https://docs.python.org/3/library/dataclasses.html#module-dataclasses" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dataclasses</span></code></a> module, runtime type
|
||
checking and validation by packages such as <a class="reference external" href="https://docs.pydantic.dev/latest/">Pydantic</a>,
|
||
and static compilation by tools such as <a class="reference external" href="https://mypyc.readthedocs.io/en/latest/">mypyc</a>.</p>
|
||
<p>However, as the type system has grown, several interrelated problems with the current
|
||
way to manage the type system have become apparent.</p>
|
||
<section id="peps-are-the-only-specification">
|
||
<h3><a class="toc-backref" href="#peps-are-the-only-specification" role="doc-backlink">PEPs are the only specification</a></h3>
|
||
<p>The Python type system was initially created by a PEP (<a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a>), and
|
||
changes to the type system are still made by PEPs. The specification for
|
||
the Python type system, to the extent there is one, consists of this series
|
||
of PEPs. But Standards Track PEPs aren’t meant to be living documents
|
||
or specifications; they are change proposals.</p>
|
||
<p>An example may illustrate the problem here. Around the same time
|
||
as the introduction of the <a class="reference external" href="https://docs.python.org/3/library/typing.html#module-typing" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code></a> module by <a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a>, <a class="pep reference internal" href="../pep-3156/" title="PEP 3156 – Asynchronous IO Support Rebooted: the “asyncio” Module">PEP 3156</a>
|
||
introduced the <a class="reference external" href="https://docs.python.org/3/library/asyncio.html#module-asyncio" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> module, another major new feature that has
|
||
been instrumental to the success of Python 3. Both modules
|
||
have evolved greatly since their initial creation and inspired changes to the
|
||
core language.</p>
|
||
<p>However, <a class="reference external" href="https://docs.python.org/3/library/asyncio.html#module-asyncio" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> and <a class="reference external" href="https://docs.python.org/3/library/typing.html#module-typing" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code></a> are different in an essential aspect:
|
||
a user who uses <a class="reference external" href="https://docs.python.org/3/library/asyncio.html#module-asyncio" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> interacts only with the standard library itself,
|
||
while a user of <a class="reference external" href="https://docs.python.org/3/library/typing.html#module-typing" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code></a> has to also think about an external tool, the type
|
||
checker. The Python language reference covers the symbols in the typing module, but does
|
||
not (and should not) go into detail on how the full type system should be
|
||
interpreted by type checkers. That material currently exists only in the PEPs.</p>
|
||
<p>This problem is shared by the packaging ecosystem, which attempts to solve it
|
||
by maintaining a separate set of <a class="reference external" href="https://packaging.python.org/en/latest/specifications/">PyPA specifications</a>.</p>
|
||
</section>
|
||
<section id="it-s-hard-to-evolve-the-specification">
|
||
<h3><a class="toc-backref" href="#it-s-hard-to-evolve-the-specification" role="doc-backlink">It’s hard to evolve the specification</a></h3>
|
||
<p>Because the PEPs are the only specification we have, anything that could be seen
|
||
as a change to the specification would theoretically require a new PEP. But that
|
||
is often too heavy a process for a small change. Sometimes changes are made
|
||
directly to old PEPs instead, but that goes against the idea that accepted and
|
||
implemented PEPs become historical documents that should no longer be changed.</p>
|
||
<p>Some concrete examples include:</p>
|
||
<ul class="simple">
|
||
<li><a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a> explicitly says that <a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.NoReturn" title="(in Python v3.13)"><code class="xref py py-data docutils literal notranslate"><span class="pre">typing.NoReturn</span></code></a> cannot be used in
|
||
argument annotations. Nevertheless, type checkers have long accepted such
|
||
usage.</li>
|
||
<li>A <a class="reference external" href="https://discuss.python.org/t/pep-561-clarification-regarding-n/32875">2023 discussion</a>
|
||
noted that <a class="pep reference internal" href="../pep-0561/" title="PEP 561 – Distributing and Packaging Type Information">PEP 561</a>’s description of partial stubs is unclear, and
|
||
major type checkers did not implement it exactly as specified.</li>
|
||
<li>The widely used third-party <code class="docutils literal notranslate"><span class="pre">typing_extensions</span></code> package provides backports of new
|
||
type system features. Type checkers are expected to treat symbols in this
|
||
module the same as symbols in <a class="reference external" href="https://docs.python.org/3/library/typing.html#module-typing" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code></a>, but this is not explicitly
|
||
specified in any of the PEPs.</li>
|
||
</ul>
|
||
</section>
|
||
<section id="the-type-system-is-underspecified">
|
||
<h3><a class="toc-backref" href="#the-type-system-is-underspecified" role="doc-backlink">The type system is underspecified</a></h3>
|
||
<p>While the PEPs provide a specification, they are often not sufficiently precise
|
||
(sometimes intentionally so). This is especially true as the combinatorial
|
||
complexity of the type system has grown.</p>
|
||
<p>It ends up falling to individual type checkers to decide how to navigate
|
||
underspecified areas. In cases where type checkers informally coordinate, this
|
||
results in de facto standards that aren’t clearly recorded anywhere, making
|
||
the type system less accessible to newcomers. For example:</p>
|
||
<ul class="simple">
|
||
<li>How <code class="docutils literal notranslate"><span class="pre">@overload</span></code> matching works</li>
|
||
<li>How <code class="docutils literal notranslate"><span class="pre">ParamSpec</span></code> <a class="reference external" href="https://github.com/python/typing/discussions/946">should work</a> <a class="reference external" href="https://github.com/microsoft/pyright/issues/3954#issuecomment-1250098464">with methods</a></li>
|
||
<li>The concept of <a class="reference external" href="https://github.com/python/typing/issues/182">recursive aliases</a></li>
|
||
<li>Semantics of <a class="reference external" href="https://mail.python.org/archives/list/typing-sig@python.org/thread/GYVM5KEE6URE6PAH7UTK6324M7GWSFQS/#SY3KPJCAW4UTOOCH3XRJYROSGDEGOTWI">variable initialization</a></li>
|
||
<li><a class="reference external" href="https://github.com/python/mypy/issues/15158#issuecomment-1677915108">Reachability semantics</a>
|
||
of annotations on <code class="docutils literal notranslate"><span class="pre">__exit__</span></code></li>
|
||
<li><a class="reference external" href="https://mail.python.org/archives/list/typing-sig@python.org/thread/YLJPWECBNPD2K4TRIBRIPISNUZJCRREY/#OX4GLBQOOCMRE5YPZEY3R3XNV6DD7XLW">Symbol visibility</a></li>
|
||
<li>Use of <a class="reference external" href="https://github.com/python/mypy/issues/5818">NoReturn for exhaustiveness checking</a></li>
|
||
</ul>
|
||
</section>
|
||
<section id="the-steering-council-is-not-well-placed-to-solve-the-above-problems">
|
||
<h3><a class="toc-backref" href="#the-steering-council-is-not-well-placed-to-solve-the-above-problems" role="doc-backlink">The Steering Council is not well-placed to solve the above problems</a></h3>
|
||
<p>The SC has the entire language in its remit, and is not well-placed to make
|
||
decisions that are purely about the type system – if only because they don’t have
|
||
the time to deal with type system arcana alongside their other responsibilities.
|
||
This is similar in spirit to the reasons why the Steering Council sometimes uses
|
||
PEP delegation.</p>
|
||
</section>
|
||
<section id="endorsements">
|
||
<h3><a class="toc-backref" href="#endorsements" role="doc-backlink">Endorsements</a></h3>
|
||
<p>This PEP was endorsed by maintainers of all major
|
||
type checkers, including <a class="reference external" href="https://discuss.python.org/t/pep-729-typing-governance-process/35362/3">Rebecca Chen (pytype)</a>,
|
||
<a class="reference external" href="https://discuss.python.org/t/pep-729-typing-governance-process/35362/4">Eric Traut (Pyright)</a>,
|
||
and privately by maintainers of mypy and Pyre.</p>
|
||
</section>
|
||
</section>
|
||
<section id="specification">
|
||
<h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2>
|
||
<p>We propose the creation of a new group, the Typing Council. This group will
|
||
be responsible for developing and maintaining the Python type system, and
|
||
for solving the above problems.</p>
|
||
<p>The “operations and process” section describes how this group would operate and
|
||
be governed.</p>
|
||
<p>The more exciting “projects” section describes solutions to the above problems
|
||
that the Typing Council could shepherd.</p>
|
||
<section id="mandate">
|
||
<h3><a class="toc-backref" href="#mandate" role="doc-backlink">Mandate</a></h3>
|
||
<p>The Typing Council’s mandate is to ensure that the Python type system is:</p>
|
||
<ul class="simple">
|
||
<li><strong>Useful</strong>: The type system should serve common use cases. As identified
|
||
by <a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a>, the primary use case is static analysis, but there are others,
|
||
such as runtime type checking, static compilation, IDE support, and documentation.
|
||
The Typing Council should consider all of these use cases when making decisions,
|
||
and be open to supporting additional use cases as they come up.</li>
|
||
<li><strong>Usable</strong>: The type system should be easy to use for Python developers. It
|
||
should be ergonomic to write well-typed Python code that is accepted by type
|
||
checkers. There should be good documentation for the type system.</li>
|
||
<li><strong>Stable</strong>: As the type system matures, users should be able to rely on their
|
||
typed code continuing to work and be able to trust their mental model for the
|
||
type system. Changes should be made with care and in a way
|
||
that minimizes disruption. Nevertheless, the type system should be able to
|
||
evolve, and it does not make sense to use the same compatibility guidelines
|
||
for type checker behavior as for Python itself. Of course, the existence
|
||
and runtime behavior of objects in the <a class="reference external" href="https://docs.python.org/3/library/typing.html#module-typing" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code></a> module does follow
|
||
Python’s standard compatibility policy in <a class="pep reference internal" href="../pep-0387/" title="PEP 387 – Backwards Compatibility Policy">PEP 387</a>.</li>
|
||
</ul>
|
||
</section>
|
||
<section id="operations-and-process">
|
||
<h3><a class="toc-backref" href="#operations-and-process" role="doc-backlink">Operations and process</a></h3>
|
||
<p>The council would have three to five members, comprised of prominent community members,
|
||
such as Python core developers and maintainers of major type checkers. The members
|
||
should include people affiliated with a variety of projects related to type checking,
|
||
which may include type checkers, CPython, typeshed, or other projects.</p>
|
||
<p>The initial members of the council are:</p>
|
||
<ul class="simple">
|
||
<li>Eric Traut (Pyright; author of <a class="pep reference internal" href="../pep-0647/" title="PEP 647 – User-Defined Type Guards">PEP 647</a>, <a class="pep reference internal" href="../pep-0681/" title="PEP 681 – Data Class Transforms">PEP 681</a>, and <a class="pep reference internal" href="../pep-0695/" title="PEP 695 – Type Parameter Syntax">PEP 695</a>)</li>
|
||
<li>Guido van Rossum (core developer; author of <a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a> and <a class="pep reference internal" href="../pep-0526/" title="PEP 526 – Syntax for Variable Annotations">PEP 526</a>)</li>
|
||
<li>Jelle Zijlstra (core developer; typeshed; pyanalyze; author of <a class="pep reference internal" href="../pep-0688/" title="PEP 688 – Making the buffer protocol accessible in Python">PEP 688</a> and <a class="pep reference internal" href="../pep-0702/" title="PEP 702 – Marking deprecations using the type system">PEP 702</a>)</li>
|
||
<li>Rebecca Chen (pytype)</li>
|
||
<li>Shantanu Jain (core developer; typeshed; mypy)</li>
|
||
</ul>
|
||
<p>Current membership of the council is recorded in the
|
||
<a class="reference external" href="https://github.com/python/typing-council/">python/typing-council</a> repository.</p>
|
||
<p>There is no term
|
||
limit for council members. Council members may resign their position at any time.
|
||
There is an expectation that each member serves at most five consecutive years
|
||
before resigning.</p>
|
||
<p>If there is a vacancy and there are three or more remaining members, it is up
|
||
to the Council to decide whether to appoint a new member.
|
||
To determine replacements, nominations will be collected from the typing
|
||
community. Self-nominations are allowed. The existing Typing Council will then decide
|
||
the replacement member(s) from the nominees. The expectation is that this would
|
||
be done by fiat, but the Typing Council can choose a replacement by any means
|
||
they see fit, including a vote.</p>
|
||
<p>The Typing Council remains accountable to the Steering Council. At any point,
|
||
for any reason, the Steering Council could (publicly or privately) make a
|
||
specific change or request a non-specific change to the composition of the
|
||
Typing Council.</p>
|
||
<p>We acknowledge that this is a not particularly democratic structure and puts
|
||
a lot of faith in the Typing Council. However, the Python community has a long
|
||
history of success with not particularly democratic structures! We believe
|
||
self-governance, cycling of membership, and accountability to the
|
||
Steering Council will be sufficient to ensure that the Typing Council is meeting
|
||
the needs of the community.</p>
|
||
<p>The council would operate primarily through reviews of GitHub PRs. Regular
|
||
meetings are likely not necessary, but the council may set up video calls, a
|
||
private chat, or whatever other mechanism they decide upon internally.</p>
|
||
<p>The council should aim for transparency, posting all decisions publicly on
|
||
<a class="reference external" href="https://discuss.python.org/c/typing/32">discuss.python.org</a>, with a
|
||
rationale if possible. Before making a decision, the council should give
|
||
all interested community members a chance to weigh in. There should be at
|
||
least a week between the start of a discussion and the council’s decision.</p>
|
||
<p>Members of the council will be eligible to sponsor PEPs. If this PEP is accepted,
|
||
<a class="pep reference internal" href="../pep-0001/" title="PEP 1 – PEP Purpose and Guidelines">PEP 1</a> should be amended to note this fact.</p>
|
||
<section id="relationship-with-the-steering-council">
|
||
<h4><a class="toc-backref" href="#relationship-with-the-steering-council" role="doc-backlink">Relationship with the Steering Council</a></h4>
|
||
<p>Just like today, the Python Steering Council would remain responsible for the
|
||
overall direction of the Python language and would continue to decide on
|
||
typing-related PEPs. The Typing Council would provide written opinions and
|
||
recommendations to the Steering Council on typing-related PEPs.</p>
|
||
<p>However, smaller changes to the type system could be made
|
||
by the Typing Council directly. The Steering Council could also choose
|
||
to delegate decisions on some PEPs to the Typing Council (exactly as any other
|
||
PEP delegation).</p>
|
||
<p>Some examples of how past and recent issues could have been handled under this model:</p>
|
||
<ul class="simple">
|
||
<li>A PEP like <a class="pep reference internal" href="../pep-0695/" title="PEP 695 – Type Parameter Syntax">PEP 695</a> (type parameter syntax), which changes the language
|
||
syntax, would need to be decided upon by the Steering Council; the Typing
|
||
Council would merely provide opinion or endorsement. Similarly, PEPs
|
||
like <a class="pep reference internal" href="../pep-0702/" title="PEP 702 – Marking deprecations using the type system">PEP 702</a> (deprecations) would be decided upon by the Steering
|
||
Council, because it concerns runtime behaviour beyond pure typing. Other examples
|
||
that would need to be decided by the SC include <a class="pep reference internal" href="../pep-0718/" title="PEP 718 – Subscriptable functions">PEP 718</a> (subscriptable
|
||
functions) and <a class="pep reference internal" href="../pep-0727/" title="PEP 727 – Documentation in Annotated Metadata">PEP 727</a> (documentation metadata).</li>
|
||
<li>A PEP like <a class="pep reference internal" href="../pep-0698/" title="PEP 698 – Override Decorator for Static Typing">PEP 698</a> (<code class="docutils literal notranslate"><span class="pre">@override</span></code>), which affects only users of type
|
||
checkers and does not change the overall language, would also by default
|
||
be decided upon by the Steering Council. However, such PEPs could be
|
||
delegated to the Typing Council for a decision (like any other PEP delegation).
|
||
Other examples of PEPs that could potentially be delegated include
|
||
<a class="pep reference internal" href="../pep-0647/" title="PEP 647 – User-Defined Type Guards">PEP 647</a> (type guards), <a class="pep reference internal" href="../pep-0655/" title="PEP 655 – Marking individual TypedDict items as required or potentially-missing">PEP 655</a> (individual required <code class="docutils literal notranslate"><span class="pre">TypedDict</span></code> items),
|
||
<a class="pep reference internal" href="../pep-0673/" title="PEP 673 – Self Type">PEP 673</a> (<code class="docutils literal notranslate"><span class="pre">Self</span></code>), and <a class="pep reference internal" href="../pep-0675/" title="PEP 675 – Arbitrary Literal String Type">PEP 675</a> (<code class="docutils literal notranslate"><span class="pre">Literal</span></code>).</li>
|
||
<li>Adding a smaller feature, such as <a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Never" title="(in Python v3.13)"><code class="xref py py-data docutils literal notranslate"><span class="pre">typing.Never</span></code></a> as an alias for
|
||
<a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.NoReturn" title="(in Python v3.13)"><code class="xref py py-data docutils literal notranslate"><span class="pre">typing.NoReturn</span></code></a>, would be done by means of a PR to the spec and
|
||
conformance test suite. The Typing
|
||
Council would then decide whether or not to merge the PR. They may ask for the
|
||
feature to be specified and discussed in a PEP if they feel that is warranted.</li>
|
||
<li>If there is confusion about the interpretation of some part of the spec, like
|
||
happened recently with <a class="reference external" href="https://discuss.python.org/t/pep-561-clarification-regarding-n/32875/27">partial stubs in PEP
|
||
561</a>,
|
||
somebody would make a PR to the typing specification to clarify the
|
||
spec, and then the Typing Council would decide on the spec change.</li>
|
||
</ul>
|
||
<p>The runtime <a class="reference external" href="https://docs.python.org/3/library/typing.html#module-typing" title="(in Python v3.13)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code></a> module will continue to be maintained by the
|
||
CPython core developer team. However, any changes to the runtime module that
|
||
affect type checker behavior should be made in conjunction with a change
|
||
to the specification (see below) and should be approved by the Typing Council.
|
||
For example, in Python 3.11 the core developers added the new function
|
||
<a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.assert_type" title="(in Python v3.13)"><code class="xref py py-func docutils literal notranslate"><span class="pre">typing.assert_type()</span></code></a>. If the Typing Council had been in place, this
|
||
change would require a matching change to the specification and approval
|
||
by the Typing Council. On the other hand, Python 3.11 also added the
|
||
<a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.get_overloads" title="(in Python v3.13)"><code class="xref py py-func docutils literal notranslate"><span class="pre">typing.get_overloads()</span></code></a> introspection helper. As this function does not
|
||
affect type checker behavior, it would not require approval by the Typing
|
||
Council. However, as support for runtime type checkers is within the remit
|
||
of the Council, they should monitor such changes and provide feedback when
|
||
appropriate.</p>
|
||
</section>
|
||
<section id="relationship-with-type-checkers">
|
||
<h4><a class="toc-backref" href="#relationship-with-type-checkers" role="doc-backlink">Relationship with type checkers</a></h4>
|
||
<p>The Typing Council has no direct authority over type checkers; it cannot
|
||
force them to implement particular features or make behavior changes. Type
|
||
checkers are incentivized to follow the specification set out by the Council
|
||
because it allows them to take advantage of shared resources, such as
|
||
libraries that expose typing information that follows the specification,
|
||
the stub files in typeshed, the <code class="docutils literal notranslate"><span class="pre">typing</span></code> standard library module, and
|
||
user documentation that covers the standard type system.
|
||
Type checkers are free to extend the type system or deviate from the
|
||
specification, but they should document such differences clearly.</p>
|
||
<p>The fact that type checkers need to implement any decisions made by the
|
||
Typing Council acts as a useful brake on the Council, ensuring that its
|
||
decisions are conservative and well-considered. Individual type checkers
|
||
remain free to innovate as they see fit, and successful innovations can
|
||
be incorporated into the standard type system.</p>
|
||
</section>
|
||
</section>
|
||
<section id="projects">
|
||
<h3><a class="toc-backref" href="#projects" role="doc-backlink">Projects</a></h3>
|
||
<p>Here are some efforts a Typing Council would be responsible for.</p>
|
||
<section id="conformance-test-suite">
|
||
<h4><a class="toc-backref" href="#conformance-test-suite" role="doc-backlink">Conformance test suite</a></h4>
|
||
<p>A conformance test suite would provide machine checkable documentation for how
|
||
type checkers should check Python code, accompanied by the results of major type
|
||
checker implementations on the test suite. A rough sketch for what this could
|
||
look like was <a class="reference external" href="https://github.com/hauntsaninja/type_checker_consistency">created by Shantanu</a>.</p>
|
||
<p>This would contain prescriptive tests from behavior prescribed by previous PEPs
|
||
and descriptive tests that let us document behavior of existing implementations
|
||
in areas that are not prescribed by any standard. These descriptions would be
|
||
useful to inform efforts below and to identify areas of focus for
|
||
standardization.</p>
|
||
</section>
|
||
<section id="specification-for-the-type-system">
|
||
<h4><a class="toc-backref" href="#specification-for-the-type-system" role="doc-backlink">Specification for the type system</a></h4>
|
||
<p>A specification would initially be created by stitching together the
|
||
specification sections from the existing PEPs, and then gradually improved to
|
||
clarify points of confusion and cover more areas. A draft of such a
|
||
stitched-together spec was <a class="reference external" href="https://github.com/JelleZijlstra/typing-spec">created by Jelle</a>.</p>
|
||
<p>The specification has a few audiences:</p>
|
||
<ul class="simple">
|
||
<li>For type checkers, it provides a description of how an idealized type checker
|
||
should behave. Individual type checkers have different goals and technical
|
||
constraints and they are free to deviate from the spec if they do not have the
|
||
resources to fully implement it or if they believe a different behavior better
|
||
serves their users. However, they should document such deviations from the
|
||
spec.</li>
|
||
<li>For projects such as typeshed, or libraries that want to be compatible with
|
||
multiple type checkers, it provides a set of rules that they can follow to
|
||
make their code understood by type checkers.</li>
|
||
<li>For people who want to propose changes to the type system, it provides a
|
||
foundation for any new proposals.</li>
|
||
</ul>
|
||
<p>Notably, the specification is not aimed at application developers who use
|
||
typing. Such users typically do not
|
||
need to worry about compatibility across type checkers. They
|
||
are better served by a more informal user-facing reference, which is discussed
|
||
in the next section.</p>
|
||
<p>There are different opinions within the community about how formal such a
|
||
specification should be. While this document recommends an incremental
|
||
approach that builds off existing specification, it does not aim to
|
||
prescribe a final state. The Typing Council would provide a mechanism
|
||
to allow the specification to evolve to meet the level of formality that
|
||
the community desires, for instance, by incorporating parts of
|
||
Kevin Millikin’s <a class="reference external" href="https://docs.google.com/document/d/1mVCU-nVPT_zVfqivVdMY1aOOZqJ9lsgOLweO1U3uwUM/edit">document on “Python Static Types”</a>
|
||
as a means to achieve a better formalisation of the spec.</p>
|
||
<p>Proposed changes to the specification, including PEPs, should
|
||
generally be accompanied by the following:</p>
|
||
<ul class="simple">
|
||
<li>Buy-in from type checker maintainers to confirm that the
|
||
change can be implemented and maintained within their type
|
||
checkers.</li>
|
||
<li>For changes to existing features, a survey of the behavior
|
||
of existing type checkers. If existing type checkers
|
||
behave roughly similarly, that is evidence that their shared
|
||
behavior should be made part of the specification.</li>
|
||
<li>Changes to the conformance test suite that demonstrate the
|
||
specified behavior.</li>
|
||
</ul>
|
||
</section>
|
||
<section id="user-facing-reference-for-the-type-system">
|
||
<h4><a class="toc-backref" href="#user-facing-reference-for-the-type-system" role="doc-backlink">User-facing reference for the type system</a></h4>
|
||
<p>Documentation is important for the success of the Python type system, so
|
||
the Typing Council should ensure that there is good documentation for the
|
||
type system.</p>
|
||
<p>As mentioned previously, PEPs are point in time change proposals aimed at
|
||
multiple audiences that are hard to clarify. This makes them ill-suited as user
|
||
documentation. The specification discussed in the previous section would
|
||
be a living document, but it would likely be too technical to serve as
|
||
documentation for normal usage.</p>
|
||
<p>Therefore, a separate user-facing reference for the type system would be
|
||
useful. Such an effort could expand the documentation on
|
||
<a class="reference external" href="https://typing.readthedocs.io/en/latest/">typing.readthedocs.io</a> and
|
||
reuse material from the documentation sections of individual type checkers
|
||
and the CPython documentation.</p>
|
||
</section>
|
||
</section>
|
||
<section id="amendments">
|
||
<h3><a class="toc-backref" href="#amendments" role="doc-backlink">Amendments</a></h3>
|
||
<p>This PEP serves as a charter for the Typing Council. Changes to its operation
|
||
can be made either through a new PEP or through a change to this PEP. In either
|
||
case, the change would be decided upon by the Steering Council after discussion
|
||
in the community.</p>
|
||
</section>
|
||
</section>
|
||
<section id="rejected-ideas">
|
||
<h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected ideas</a></h2>
|
||
<section id="writing-the-specification-from-scratch">
|
||
<h3><a class="toc-backref" href="#writing-the-specification-from-scratch" role="doc-backlink">Writing the specification from scratch</a></h3>
|
||
<p>This PEP proposes creating the typing specification by starting from the
|
||
existing PEPs, then clarifying and improving the specification as necessary.
|
||
Some members of the community prefer to start from scratch, writing a new,
|
||
more formal specification covering the entire type system. This could
|
||
provide a more solid basis for the specification.</p>
|
||
<p>However, this would be a much larger undertaking. The existing formalization
|
||
effort by Kevin Millikin is a good start, but so far covers only a subset of
|
||
PEP 484. Covering the rest of the type system would likely require several
|
||
times more effort when we consider that major type system features such
|
||
as <a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Protocol" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate"><span class="pre">typing.Protocol</span></code></a>, <code class="xref py py-class docutils literal notranslate"><span class="pre">typing.Literal</span></code>, and <a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.TypedDict" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate"><span class="pre">typing.TypedDict</span></code></a>
|
||
were introduced only after PEP 484. It is not clear that there is even energy
|
||
in the community for such a huge undertaking. Even if someone steps up to
|
||
do all the work of putting together a specification, lots of effort would be
|
||
required from community members and type checker maintainers to consider
|
||
whether the specification accurately reflects current behavior, and if not,
|
||
whether the specification or the type checkers should change.</p>
|
||
<p>Starting with the existing PEPs creates a lower-quality specification,
|
||
but it means that the Typing Council can immediately start making a difference
|
||
anywhere in the type system by improving and clarifying the specification.
|
||
A formalization effort can still proceed by gradually replacing sections of the
|
||
specification.</p>
|
||
</section>
|
||
<section id="alternate-governance-mechanisms">
|
||
<h3><a class="toc-backref" href="#alternate-governance-mechanisms" role="doc-backlink">Alternate governance mechanisms</a></h3>
|
||
<p>An earlier draft of this PEP suggested that the Steering Council appoint
|
||
members of the Typing Council each year. The current Steering Council suggested
|
||
that it would be better to have the Typing Council self-organise and avoid
|
||
the need for the Steering Council to continuously supervise the Typing Council.</p>
|
||
<p>Alternate governance mechanisms are possible, including more democratic ones,
|
||
but these typically raise several thorny questions, require much heavier
|
||
amounts of process and are potentially more divisive. For example, see the PEP
|
||
8000 series, or recent discussions about alternative governance in other Python
|
||
subcommunities. Ultimately, the Typing Council exists under the authority of the
|
||
Steering Council, and so can rely on it to bootstrap governance and serve as an
|
||
accountability mechanism.</p>
|
||
</section>
|
||
<section id="do-nothing">
|
||
<h3><a class="toc-backref" href="#do-nothing" role="doc-backlink">Do nothing</a></h3>
|
||
<p>We are hopeful substantial progress will be made on projects that improve the
|
||
type system regardless of whether this PEP is accepted. We anticipate projects
|
||
like specification or the potential for PEP delegation would benefit more from a
|
||
Typing Council, and projects like end user documentation would benefit less.
|
||
Certainly the bottleneck is likely to be contributor effort, not governance.</p>
|
||
<p>However, currently the tools available to the community to resolve potential
|
||
contention are either establishment of approximate consensus or the exercise of
|
||
power by individual projects or contributors. While very valuable, the former is
|
||
a slow process that can often end in inaction. The latter can result in a less
|
||
consistent ecosystem. Finally, easily legible governance structures make the
|
||
community more accessible and equitable.</p>
|
||
</section>
|
||
</section>
|
||
<section id="contact">
|
||
<h2><a class="toc-backref" href="#contact" role="doc-backlink">Contact</a></h2>
|
||
<p>To ask the Typing Council for a decision,
|
||
community members may open an issue in the
|
||
<a class="reference external" href="https://github.com/python/typing-council/">python/typing-council</a>
|
||
repository.</p>
|
||
</section>
|
||
<section id="copyright">
|
||
<h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2>
|
||
<p>This document is placed in the public domain or under the
|
||
CC0-1.0-Universal license, whichever is more permissive.</p>
|
||
</section>
|
||
</section>
|
||
<hr class="docutils" />
|
||
<p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0729.rst">https://github.com/python/peps/blob/main/peps/pep-0729.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0729.rst">2024-10-17 12:49:39 GMT</a></p>
|
||
|
||
</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><ul>
|
||
<li><a class="reference internal" href="#peps-are-the-only-specification">PEPs are the only specification</a></li>
|
||
<li><a class="reference internal" href="#it-s-hard-to-evolve-the-specification">It’s hard to evolve the specification</a></li>
|
||
<li><a class="reference internal" href="#the-type-system-is-underspecified">The type system is underspecified</a></li>
|
||
<li><a class="reference internal" href="#the-steering-council-is-not-well-placed-to-solve-the-above-problems">The Steering Council is not well-placed to solve the above problems</a></li>
|
||
<li><a class="reference internal" href="#endorsements">Endorsements</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#mandate">Mandate</a></li>
|
||
<li><a class="reference internal" href="#operations-and-process">Operations and process</a><ul>
|
||
<li><a class="reference internal" href="#relationship-with-the-steering-council">Relationship with the Steering Council</a></li>
|
||
<li><a class="reference internal" href="#relationship-with-type-checkers">Relationship with type checkers</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#projects">Projects</a><ul>
|
||
<li><a class="reference internal" href="#conformance-test-suite">Conformance test suite</a></li>
|
||
<li><a class="reference internal" href="#specification-for-the-type-system">Specification for the type system</a></li>
|
||
<li><a class="reference internal" href="#user-facing-reference-for-the-type-system">User-facing reference for the type system</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#amendments">Amendments</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#rejected-ideas">Rejected ideas</a><ul>
|
||
<li><a class="reference internal" href="#writing-the-specification-from-scratch">Writing the specification from scratch</a></li>
|
||
<li><a class="reference internal" href="#alternate-governance-mechanisms">Alternate governance mechanisms</a></li>
|
||
<li><a class="reference internal" href="#do-nothing">Do nothing</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#contact">Contact</a></li>
|
||
<li><a class="reference internal" href="#copyright">Copyright</a></li>
|
||
</ul>
|
||
|
||
<br>
|
||
<a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0729.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> |