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 737 – C API to format a type fully qualified name | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0737/"> <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 737 – C API to format a type fully qualified name | peps.python.org'> <meta property="og:description" content="Add new convenient C APIs to format a type fully qualified name. No longer format type names differently depending on how types are implemented."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0737/"> <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="Add new convenient C APIs to format a type fully qualified name. No longer format type names differently depending on how types are implemented."> <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 737</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 737 – C API to format a type fully qualified name</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Victor Stinner <vstinner at python.org></dd> <dt class="field-even">Discussions-To:</dt> <dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/pep-737-unify-type-name-formatting/39872">Discourse thread</a></dd> <dt class="field-odd">Status:</dt> <dd class="field-odd"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-even">Type:</dt> <dd class="field-even"><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-odd">Created:</dt> <dd class="field-odd">29-Nov-2023</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://discuss.python.org/t/pep-737-unify-type-name-formatting/39872" title="Discourse thread">29-Nov-2023</a></dd> <dt class="field-even">Resolution:</dt> <dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/pep-737-unify-type-name-formatting/39872/60">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="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#standard-library">Standard library</a><ul> <li><a class="reference internal" href="#python-code">Python code</a></li> <li><a class="reference internal" href="#c-code">C code</a></li> </ul> </li> <li><a class="reference internal" href="#using-pytypeobject-tp-name-is-inconsistent-with-python">Using PyTypeObject.tp_name is inconsistent with Python</a></li> <li><a class="reference internal" href="#limited-c-api">Limited C API</a></li> <li><a class="reference internal" href="#truncating-type-names-in-c">Truncating type names in C</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#add-pytype-getfullyqualifiedname-function">Add PyType_GetFullyQualifiedName() function</a></li> <li><a class="reference internal" href="#add-pytype-getmodulename-function">Add PyType_GetModuleName() function</a></li> <li><a class="reference internal" href="#add-formats-to-pyunicode-fromformat">Add formats to PyUnicode_FromFormat()</a></li> <li><a class="reference internal" href="#formats-summary">Formats Summary</a></li> <li><a class="reference internal" href="#recommend-using-the-type-fully-qualified-name">Recommend using the type fully qualified name</a></li> <li><a class="reference internal" href="#recommend-not-truncating-type-names">Recommend not truncating type names</a></li> </ul> </li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#id1">Add type.__fully_qualified_name__ attribute</a></li> <li><a class="reference internal" href="#add-type-format-method">Add type.__format__() method</a></li> <li><a class="reference internal" href="#change-str-type">Change str(type)</a></li> <li><a class="reference internal" href="#add-t-formatter-to-get-an-object-type">Add !t formatter to get an object type</a></li> <li><a class="reference internal" href="#add-formats-to-str-args">Add formats to str % args</a></li> <li><a class="reference internal" href="#other-ways-to-format-type-names-in-c">Other ways to format type names in C</a></li> <li><a class="reference internal" href="#use-t-format-with-py-type-pass-a-type">Use %T format with Py_TYPE(): pass a type</a></li> <li><a class="reference internal" href="#other-proposed-apis-to-get-a-type-fully-qualified-name">Other proposed APIs to get a type fully qualified name</a></li> <li><a class="reference internal" href="#include-the-main-module-in-the-type-fully-qualified-name">Include the __main__ module in the type fully qualified name</a></li> </ul> </li> <li><a class="reference internal" href="#discussions">Discussions</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> Add new convenient C APIs to format a type fully qualified name. No longer format type names differently depending on how types are implemented. Recommend using the type fully qualified name in error messages and in <code class="docutils literal notranslate">__repr__()</code> methods in new C code. Recommend not truncating type names in new C code. Add <code class="docutils literal notranslate">%T</code>, <code class="docutils literal notranslate">%#T</code>, <code class="docutils literal notranslate">%N</code> and <code class="docutils literal notranslate">%#N</code> formats to <code class="docutils literal notranslate">PyUnicode_FromFormat()</code> to format the fully qualified, respectively, of an object type and of a type. Make C code safer by avoiding borrowed reference which can lead to crashes. The new C API is compatible with the limited C API. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> <section id="standard-library"> <h3><a class="toc-backref" href="#standard-library" role="doc-backlink">Standard library</a></h3> In the Python standard library, formatting a type name or the type name of an object is a common operation to format an error message and to implement a <code class="docutils literal notranslate">__repr__()</code> method. There are different ways to format a type name which give different outputs. Example with the <code class="docutils literal notranslate">datetime.timedelta</code> type: <ul class="simple"> <li>The type short name (<code class="docutils literal notranslate">type.__name__</code>) and the type qualified name (<code class="docutils literal notranslate">type.__qualname__</code>) are <code class="docutils literal notranslate">'timedelta'</code>.</li> <li>The type module (<code class="docutils literal notranslate">type.__module__</code>) is <code class="docutils literal notranslate">'datetime'</code>.</li> <li>The type fully qualified name is <code class="docutils literal notranslate">'datetime.timedelta'</code>.</li> <li>The type representation (<code class="docutils literal notranslate">repr(type)</code>) contains the fully qualified name: <code class="docutils literal notranslate"><class 'datetime.timedelta'></code>.</li> </ul> <section id="python-code"> <h4><a class="toc-backref" href="#python-code" role="doc-backlink">Python code</a></h4> In Python, <code class="docutils literal notranslate">type.__name__</code> gets the type short name, whereas <code class="docutils literal notranslate">f"{type.__module__}.{type.__qualname__}"</code> formats the type “fully qualified name”. Usually, <code class="docutils literal notranslate">type(obj)</code> or <code class="docutils literal notranslate">obj.__class__</code> are used to get the type of the object obj. Sometimes, the type name is put between quotes. Examples: <ul class="simple"> <li><code class="docutils literal notranslate">raise TypeError("str expected, not %s" % type(value).__name__)</code></li> <li><code class="docutils literal notranslate">raise TypeError("can't serialize %s" % self.__class__.__name__)</code></li> <li><code class="docutils literal notranslate">name = "%s.%s" % (obj.__module__, obj.__qualname__)</code></li> </ul> Qualified names were added to types (<code class="docutils literal notranslate">type.__qualname__</code>) in Python 3.3 by <a class="pep reference internal" href="../pep-3155/" title="PEP 3155 – Qualified name for classes and functions">PEP 3155</a> “Qualified name for classes and functions”. </section> <section id="c-code"> <h4><a class="toc-backref" href="#c-code" role="doc-backlink">C code</a></h4> In C, the most common way to format a type name is to get the <code class="docutils literal notranslate">PyTypeObject.tp_name</code> member of the type. Example: <div class="highlight-c notranslate"><div class="highlight"><pre>PyErr_Format(PyExc_TypeError, "globals must be a dict, not %.100s", Py_TYPE(globals)->tp_name); </pre></div> </div> The type “fully qualified name” is used in a few places: <code class="docutils literal notranslate">PyErr_Display()</code>, <code class="docutils literal notranslate">type.__repr__()</code> implementation, and <code class="docutils literal notranslate">sys.unraisablehook</code> implementation. Using <code class="docutils literal notranslate">Py_TYPE(obj)->tp_name</code> is preferred since it is more convenient than calling <code class="docutils literal notranslate">PyType_GetQualName()</code> which requires <code class="docutils literal notranslate">Py_DECREF()</code>. Moreover, <code class="docutils literal notranslate">PyType_GetQualName()</code> was only added recently, in Python 3.11. Some functions use <code class="docutils literal notranslate">%R</code> (<code class="docutils literal notranslate">repr(type)</code>) to format a type name, the output contains the type fully qualified name. Example: <div class="highlight-c notranslate"><div class="highlight"><pre>PyErr_Format(PyExc_TypeError, "calling %R should have returned an instance " "of BaseException, not %R", type, Py_TYPE(value)); </pre></div> </div> </section> </section> <section id="using-pytypeobject-tp-name-is-inconsistent-with-python"> <h3><a class="toc-backref" href="#using-pytypeobject-tp-name-is-inconsistent-with-python" role="doc-backlink">Using PyTypeObject.tp_name is inconsistent with Python</a></h3> The <code class="docutils literal notranslate">PyTypeObject.tp_name</code> member is different depending on the type implementation: <ul class="simple"> <li>Static types and heap types in C: tp_name is the type fully qualified name.</li> <li>Python class: tp_name is the type short name (<code class="docutils literal notranslate">type.__name__</code>).</li> </ul> So using <code class="docutils literal notranslate">Py_TYPE(obj)->tp_name</code> to format an object type name gives a different output depending if a type is implemented in C or in Python. It goes against <a class="pep reference internal" href="../pep-0399/" title="PEP 399 – Pure Python/C Accelerator Module Compatibility Requirements">PEP 399</a> “Pure Python/C Accelerator Module Compatibility Requirements” principles which recommends code behaves the same way if written in Python or in C. Example: <div class="highlight-pycon notranslate"><div class="highlight"><pre>$ python3.12 >>> import _datetime; c_obj = _datetime.date(1970, 1, 1) >>> import _pydatetime; py_obj = _pydatetime.date(1970, 1, 1) >>> my_list = list(range(3)) >>> my_list[c_obj] # C type TypeError: list indices must be integers or slices, not datetime.date >>> my_list[py_obj] # Python type TypeError: list indices must be integers or slices, not date </pre></div> </div> The error message contains the type fully qualified name (<code class="docutils literal notranslate">datetime.date</code>) if the type is implemented in C, or the type short name (<code class="docutils literal notranslate">date</code>) if the type is implemented in Python. </section> <section id="limited-c-api"> <h3><a class="toc-backref" href="#limited-c-api" role="doc-backlink">Limited C API</a></h3> The <code class="docutils literal notranslate">Py_TYPE(obj)->tp_name</code> code cannot be used with the limited C API, since the <code class="docutils literal notranslate">PyTypeObject</code> members are excluded from the limited C API. The type name should be read using <code class="docutils literal notranslate">PyType_GetName()</code>, <code class="docutils literal notranslate">PyType_GetQualName()</code> and <code class="docutils literal notranslate">PyType_GetModule()</code> functions which are less convenient to use. </section> <section id="truncating-type-names-in-c"> <h3><a class="toc-backref" href="#truncating-type-names-in-c" role="doc-backlink">Truncating type names in C</a></h3> In 1998, when the <code class="docutils literal notranslate">PyErr_Format()</code> function was added, the implementation used a fixed buffer of 500 bytes. The function had the following comment: <div class="highlight-c notranslate"><div class="highlight"><pre>/* Caller is responsible for limiting the format */ </pre></div> </div> In 2001, the function was modified to allocate a dynamic buffer on the heap. Too late, the practice of truncating type names, like using the <code class="docutils literal notranslate">%.100s</code> format, already became a habit, and developers forgot why type names are truncated. In Python, type names are not truncated. Truncating type names in C but not in Python goes against <a class="pep reference internal" href="../pep-0399/" title="PEP 399 – Pure Python/C Accelerator Module Compatibility Requirements">PEP 399</a> “Pure Python/C Accelerator Module Compatibility Requirements” principles which recommends code behaves the same way if written in Python or in C. See the issue: <a class="reference external" href="https://github.com/python/cpython/issues/55042">Replace %.100s by %s in PyErr_Format(): the arbitrary limit of 500 bytes is outdated</a> (2011). </section> </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> <ul class="simple"> <li>Add <code class="docutils literal notranslate">PyType_GetFullyQualifiedName()</code> function.</li> <li>Add <code class="docutils literal notranslate">PyType_GetModuleName()</code> function.</li> <li>Add formats to <code class="docutils literal notranslate">PyUnicode_FromFormat()</code>.</li> <li>Recommend using the type fully qualified name in error messages and in <code class="docutils literal notranslate">__repr__()</code> methods in new C code.</li> <li>Recommend not truncating type names in new C code.</li> </ul> <section id="add-pytype-getfullyqualifiedname-function"> <h3><a class="toc-backref" href="#add-pytype-getfullyqualifiedname-function" role="doc-backlink">Add PyType_GetFullyQualifiedName() function</a></h3> Add the <code class="docutils literal notranslate">PyType_GetFullyQualifiedName()</code> function to get the fully qualified name of a type: similar to <code class="docutils literal notranslate">f"{type.__module__}.{type.__qualname__}"</code>, or <code class="docutils literal notranslate">type.__qualname__</code> if <code class="docutils literal notranslate">type.__module__</code> is not a string or is equal to <code class="docutils literal notranslate">"builtins"</code> or is equal to <code class="docutils literal notranslate">"__main__"</code>. API: <div class="highlight-c notranslate"><div class="highlight"><pre>PyObject* PyType_GetFullyQualifiedName(PyTypeObject *type) </pre></div> </div> On success, return a new reference to the string. On error, raise an exception and return <code class="docutils literal notranslate">NULL</code>. </section> <section id="add-pytype-getmodulename-function"> <h3><a class="toc-backref" href="#add-pytype-getmodulename-function" role="doc-backlink">Add PyType_GetModuleName() function</a></h3> Add the <code class="docutils literal notranslate">PyType_GetModuleName()</code> function to get the module name of a type (<code class="docutils literal notranslate">type.__module__</code> string). API: <div class="highlight-c notranslate"><div class="highlight"><pre>PyObject* PyType_GetModuleName(PyTypeObject *type) </pre></div> </div> On success, return a new reference to the string. On error, raise an exception and return <code class="docutils literal notranslate">NULL</code>. </section> <section id="add-formats-to-pyunicode-fromformat"> <h3><a class="toc-backref" href="#add-formats-to-pyunicode-fromformat" role="doc-backlink">Add formats to PyUnicode_FromFormat()</a></h3> Add the following formats to <code class="docutils literal notranslate">PyUnicode_FromFormat()</code>: <ul class="simple"> <li><code class="docutils literal notranslate">%N</code> formats the fully qualified name of a type, similar to <code class="docutils literal notranslate">PyType_GetFullyQualifiedName(type)</code>; N stands for type Name.</li> <li><code class="docutils literal notranslate">%T</code> formats the type fully qualified name of an object’s type, similar to <code class="docutils literal notranslate">PyType_GetFullyQualifiedName(Py_TYPE(obj))</code>; T stands for object Type.</li> <li><code class="docutils literal notranslate">%#N</code> and <code class="docutils literal notranslate">%#T</code>: the alternative form uses the colon separator (<code class="docutils literal notranslate">:</code>), instead of the dot separator (<code class="docutils literal notranslate">.</code>), between the module name and the qualified name.</li> </ul> For example, the existing code using tp_name: <div class="highlight-c notranslate"><div class="highlight"><pre>PyErr_Format(PyExc_TypeError, "__format__ must return a str, not %.200s", Py_TYPE(result)->tp_name); </pre></div> </div> can be replaced with the <code class="docutils literal notranslate">%T</code> format: <div class="highlight-c notranslate"><div class="highlight"><pre>PyErr_Format(PyExc_TypeError, "__format__ must return a str, not %T", result); </pre></div> </div> Advantages of the updated code: <ul class="simple"> <li>Safer C code: avoid <code class="docutils literal notranslate">Py_TYPE()</code> which returns a borrowed reference.</li> <li>The <code class="docutils literal notranslate">PyTypeObject.tp_name</code> member is no longer read explicitly: the code becomes compatible with the limited C API.</li> <li>The formatted type name no longer depends on the type implementation.</li> <li>The type name is no longer truncated.</li> </ul> Note: The <code class="docutils literal notranslate">%T</code> format is used by <code class="docutils literal notranslate">time.strftime()</code>, but not by <code class="docutils literal notranslate">printf()</code>. </section> <section id="formats-summary"> <h3><a class="toc-backref" href="#formats-summary" role="doc-backlink">Formats Summary</a></h3> <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">C object</th> <th class="head">C type</th> <th class="head">Format</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">%T</code></td> <td><code class="docutils literal notranslate">%N</code></td> <td>Type fully qualified name.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">%#T</code></td> <td><code class="docutils literal notranslate">%#N</code></td> <td>Type fully qualified name, colon separator.</td> </tr> </tbody> </table> </section> <section id="recommend-using-the-type-fully-qualified-name"> <h3><a class="toc-backref" href="#recommend-using-the-type-fully-qualified-name" role="doc-backlink">Recommend using the type fully qualified name</a></h3> The type fully qualified name is recommended in error messages and in <code class="docutils literal notranslate">__repr__()</code> methods in new C code. In non-trivial applications, it is likely to have two types with the same short name defined in two different modules, especially with generic names. Using the fully qualified name helps identifying the type in an unambiguous way. </section> <section id="recommend-not-truncating-type-names"> <h3><a class="toc-backref" href="#recommend-not-truncating-type-names" role="doc-backlink">Recommend not truncating type names</a></h3> Type names should not be truncated in new C code. For example, the <code class="docutils literal notranslate">%.100s</code> format should be avoided: use the <code class="docutils literal notranslate">%s</code> format instead (or <code class="docutils literal notranslate">%T</code> format in C). </section> </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> <ul class="simple"> <li>Pull request: <a class="reference external" href="https://github.com/python/cpython/pull/112133">Add type.__fully_qualified_name__ attribute</a>.</li> <li>Pull request: <a class="reference external" href="https://github.com/python/cpython/pull/111703">Add %T format to PyUnicode_FromFormat()</a>.</li> </ul> </section> <section id="backwards-compatibility"> <h2><a class="toc-backref" href="#backwards-compatibility" role="doc-backlink">Backwards Compatibility</a></h2> Changes proposed in this PEP are backward compatible. Adding new C APIs has no effect on the backward compatibility. Existing C APIs are left unchanged. No Python API is changed. Replacing the type short name with the type fully qualified name is only recommended in new C code. No longer truncating type names is only recommended in new C code. Existing code should be left unchanged and so remains backward compatible. There is no recommendation for Python code. </section> <section id="rejected-ideas"> <h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected Ideas</a></h2> <section id="id1"> <h3><a class="toc-backref" href="#id1" role="doc-backlink">Add type.__fully_qualified_name__ attribute</a></h3> Add <code class="docutils literal notranslate">type.__fully_qualified_name__</code> read-only attribute, the fully qualified name of a type: similar to <code class="docutils literal notranslate">f"{type.__module__}.{type.__qualname__}"</code>, or <code class="docutils literal notranslate">type.__qualname__</code> if <code class="docutils literal notranslate">type.__module__</code> is not a string or is equal to <code class="docutils literal notranslate">"builtins"</code> or is equal to <code class="docutils literal notranslate">"__main__"</code>. The <code class="docutils literal notranslate">type.__repr__()</code> is left unchanged, it only omits the module if the module is equal to <code class="docutils literal notranslate">"builtins"</code>. This change was <a class="reference external" href="https://discuss.python.org/t/pep-737-unify-type-name-formatting/39872/51">rejected by the Steering Council</a>: <blockquote> <div>We can see the usefulness of the C API changes proposed by the PEP and would likely accept those changes as is.We see less justification for the Python level changes. We especially question the need for <code class="docutils literal notranslate">__fully_qualified_name__</code>. </div></blockquote> Thomas Wouters added: <blockquote> <div>If there really is a desire for formatting types the exact same way the C API does it, a utility function would make more sense to me, personally, than <code class="docutils literal notranslate">type.__format__</code>, but I think the SC could be persuaded given some concrete use-cases.</div></blockquote> </section> <section id="add-type-format-method"> <h3><a class="toc-backref" href="#add-type-format-method" role="doc-backlink">Add type.__format__() method</a></h3> Add <code class="docutils literal notranslate">type.__format__()</code> method with the following formats: <ul class="simple"> <li><code class="docutils literal notranslate">N</code> formats the type fully qualified name (<code class="docutils literal notranslate">type.__fully_qualified_name__</code>); <code class="docutils literal notranslate">N</code> stands for Name.</li> <li><code class="docutils literal notranslate">#N</code> (alternative form) formats the type fully qualified name using the colon (<code class="docutils literal notranslate">:</code>) separator, instead of the dot separator (<code class="docutils literal notranslate">.</code>), between the module name and the qualified name.</li> </ul> Examples using f-string: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> import datetime >>> f"{datetime.timedelta:N}" # fully qualified name 'datetime.timedelta' >>> f"{datetime.timedelta:#N}" # fully qualified name, colon separator 'datetime:timedelta' </pre></div> </div> The colon (<code class="docutils literal notranslate">:</code>) separator used by the <code class="docutils literal notranslate">#N</code> format eliminates guesswork when you want to import the name, see <code class="docutils literal notranslate">pkgutil.resolve_name()</code>, <code class="docutils literal notranslate">python -m inspect</code> command line interface, and <code class="docutils literal notranslate">setuptools</code> entry points. This change was <a class="reference external" href="https://discuss.python.org/t/pep-737-unify-type-name-formatting/39872/52">rejected by the Steering Council</a>. </section> <section id="change-str-type"> <h3><a class="toc-backref" href="#change-str-type" role="doc-backlink">Change str(type)</a></h3> The <code class="docutils literal notranslate">type.__str__()</code> method can be modified to format a type name differently. For example, it can return the type fully qualified name. The problem is that it’s a backward incompatible change. For example, <code class="docutils literal notranslate">enum</code>, <code class="docutils literal notranslate">functools</code>, <code class="docutils literal notranslate">optparse</code>, <code class="docutils literal notranslate">pdb</code> and <code class="docutils literal notranslate">xmlrpc.server</code> modules of the standard library have to be updated. <code class="docutils literal notranslate">test_dataclasses</code>, <code class="docutils literal notranslate">test_descrtut</code> and <code class="docutils literal notranslate">test_cmd_line_script</code> tests have to be updated as well. See the <a class="reference external" href="https://github.com/python/cpython/pull/112129">pull request: type(str) returns the fully qualified name</a>. </section> <section id="add-t-formatter-to-get-an-object-type"> <h3><a class="toc-backref" href="#add-t-formatter-to-get-an-object-type" role="doc-backlink">Add !t formatter to get an object type</a></h3> Use <code class="docutils literal notranslate">f"{obj!t:T}"</code> to format <code class="docutils literal notranslate">type(obj).__fully_qualified_name__</code>, similar to <code class="docutils literal notranslate">f"{type(obj):T}"</code>. When the <code class="docutils literal notranslate">!t</code> formatter was proposed in 2018, <a class="reference external" href="https://mail.python.org/archives/list/python-dev@python.org/message/BMIW3FEB77OS7OB3YYUUDUBITPWLRG3U/">Eric Smith was strongly opposed to this</a>; Eric is the author of the f-string <a class="pep reference internal" href="../pep-0498/" title="PEP 498 – Literal String Interpolation">PEP 498</a> “Literal String Interpolation”. </section> <section id="add-formats-to-str-args"> <h3><a class="toc-backref" href="#add-formats-to-str-args" role="doc-backlink">Add formats to str % args</a></h3> It was proposed to add formats to format a type name in <code class="docutils literal notranslate">str % arg</code>. For example, add the <code class="docutils literal notranslate">%T</code> format to format a type fully qualified name. Nowadays, f-strings are preferred for new code. </section> <section id="other-ways-to-format-type-names-in-c"> <h3><a class="toc-backref" href="#other-ways-to-format-type-names-in-c" role="doc-backlink">Other ways to format type names in C</a></h3> The <code class="docutils literal notranslate">printf()</code> function supports multiple size modifiers: <code class="docutils literal notranslate">hh</code> (<code class="docutils literal notranslate">char</code>), <code class="docutils literal notranslate">h</code> (<code class="docutils literal notranslate">short</code>), <code class="docutils literal notranslate">l</code> (<code class="docutils literal notranslate">long</code>), <code class="docutils literal notranslate">ll</code> (<code class="docutils literal notranslate">long long</code>), <code class="docutils literal notranslate">z</code> (<code class="docutils literal notranslate">size_t</code>), <code class="docutils literal notranslate">t</code> (<code class="docutils literal notranslate">ptrdiff_t</code>) and <code class="docutils literal notranslate">j</code> (<code class="docutils literal notranslate">intmax_t</code>). The <code class="docutils literal notranslate">PyUnicode_FromFormat()</code> function supports most of them. Proposed formats using <code class="docutils literal notranslate">h</code> and <code class="docutils literal notranslate">hh</code> length modifiers: <ul class="simple"> <li><code class="docutils literal notranslate">%hhT</code> formats <code class="docutils literal notranslate">type.__name__</code>.</li> <li><code class="docutils literal notranslate">%hT</code> formats <code class="docutils literal notranslate">type.__qualname__</code>.</li> <li><code class="docutils literal notranslate">%T</code> formats <code class="docutils literal notranslate">type.__fully_qualified_name__</code>.</li> </ul> Length modifiers are used to specify the C type of the argument, not to change how an argument is formatted. The alternate form (<code class="docutils literal notranslate">#</code>) changes how an argument is formatted. Here the argument C type is always <code class="docutils literal notranslate">PyObject*</code>. Other proposed formats: <ul class="simple"> <li><code class="docutils literal notranslate">%Q</code></li> <li><code class="docutils literal notranslate">%t</code>.</li> <li><code class="docutils literal notranslate">%lT</code> formats <code class="docutils literal notranslate">type.__fully_qualified_name__</code>.</li> <li><code class="docutils literal notranslate">%Tn</code> formats <code class="docutils literal notranslate">type.__name__</code>.</li> <li><code class="docutils literal notranslate">%Tq</code> formats <code class="docutils literal notranslate">type.__qualname__</code>.</li> <li><code class="docutils literal notranslate">%Tf</code> formats <code class="docutils literal notranslate">type.__fully_qualified_name__</code>.</li> </ul> Having more options to format type names can lead to inconsistencies between different modules and make the API more error prone. About the <code class="docutils literal notranslate">%t</code> format, <code class="docutils literal notranslate">printf()</code> now uses <code class="docutils literal notranslate">t</code> as a length modifier for <code class="docutils literal notranslate">ptrdiff_t</code> argument. The following APIs to be used to format a type: <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head">C API</th> <th class="head">Python API</th> <th class="head">Format</th> </tr> </thead> <tbody> <tr class="row-even"><td><code class="docutils literal notranslate">PyType_GetName()</code></td> <td><code class="docutils literal notranslate">type.__name__</code></td> <td>Type short name.</td> </tr> <tr class="row-odd"><td><code class="docutils literal notranslate">PyType_GetQualName()</code></td> <td><code class="docutils literal notranslate">type.__qualname__</code></td> <td>Type qualified name.</td> </tr> <tr class="row-even"><td><code class="docutils literal notranslate">PyType_GetModuleName()</code></td> <td><code class="docutils literal notranslate">type.__module__</code></td> <td>Type module name.</td> </tr> </tbody> </table> </section> <section id="use-t-format-with-py-type-pass-a-type"> <h3><a class="toc-backref" href="#use-t-format-with-py-type-pass-a-type" role="doc-backlink">Use %T format with Py_TYPE(): pass a type</a></h3> It was proposed to pass a type to the <code class="docutils literal notranslate">%T</code> format, like: <div class="highlight-c notranslate"><div class="highlight"><pre>PyErr_Format(PyExc_TypeError, "object type name: %T", Py_TYPE(obj)); </pre></div> </div> The <code class="docutils literal notranslate">Py_TYPE()</code> functions returns a borrowed reference. Just to format an error, using a borrowed reference to a type looks safe. In practice, it can lead to crash. Example: <div class="highlight-default notranslate"><div class="highlight"><pre>import gc import my_cext class ClassA: pass def create_object(): class ClassB: def __repr__(self): self.__class__ = ClassA gc.collect() return "ClassB repr" return ClassB() obj = create_object() my_cext.func(obj) </pre></div> </div> where <code class="docutils literal notranslate">my_cext.func()</code> is a C function which calls: <div class="highlight-default notranslate"><div class="highlight"><pre>PyErr_Format(PyExc_ValueError, "Unexpected value %R of type %T", obj, Py_TYPE(obj)); </pre></div> </div> <code class="docutils literal notranslate">PyErr_Format()</code> is called with a borrowed reference to <code class="docutils literal notranslate">ClassB</code>. When <code class="docutils literal notranslate">repr(obj)</code> is called by the <code class="docutils literal notranslate">%R</code> format, the last reference to <code class="docutils literal notranslate">ClassB</code> is removed and the class is deallocated. When the <code class="docutils literal notranslate">%T</code> format is proceed, <code class="docutils literal notranslate">Py_TYPE(obj)</code> is already a dangling pointer and Python does crash. </section> <section id="other-proposed-apis-to-get-a-type-fully-qualified-name"> <h3><a class="toc-backref" href="#other-proposed-apis-to-get-a-type-fully-qualified-name" role="doc-backlink">Other proposed APIs to get a type fully qualified name</a></h3> <ul class="simple"> <li>Add <code class="docutils literal notranslate">type.__fullyqualname__</code> attribute: name without underscore between words. Several dunders, including some of the most recently added ones, include an underscore in the word: <code class="docutils literal notranslate">__class_getitem__</code>, <code class="docutils literal notranslate">__release_buffer__</code>, <code class="docutils literal notranslate">__type_params__</code>, <code class="docutils literal notranslate">__init_subclass__</code> and <code class="docutils literal notranslate">__text_signature__</code>.</li> <li>Add <code class="docutils literal notranslate">type.__fqn__</code> attribute: FQN name stands for Fully Qualified Name.</li> <li>Add <code class="docutils literal notranslate">type.fully_qualified_name()</code> method. Methods added to <code class="docutils literal notranslate">type</code> are inherited by all types and so can affect existing code.</li> <li>Add a function to the <code class="docutils literal notranslate">inspect</code> module. Need to import the <code class="docutils literal notranslate">inspect</code> module to use it.</li> </ul> </section> <section id="include-the-main-module-in-the-type-fully-qualified-name"> <h3><a class="toc-backref" href="#include-the-main-module-in-the-type-fully-qualified-name" role="doc-backlink">Include the __main__ module in the type fully qualified name</a></h3> Format <code class="docutils literal notranslate">type.__fully_qualified_name__</code> as <code class="docutils literal notranslate">f"{type.__module__}.{type.__qualname__}"</code>, or <code class="docutils literal notranslate">type.__qualname__</code> if <code class="docutils literal notranslate">type.__module__</code> is not a string or is equal to <code class="docutils literal notranslate">"builtins"</code>. Do not treat the <code class="docutils literal notranslate">__main__</code> module differently: include it in the name. Existing code such as <code class="docutils literal notranslate">type.__repr__()</code>, <code class="docutils literal notranslate">collections.abc</code> and <code class="docutils literal notranslate">unittest</code> modules format a type name with <code class="docutils literal notranslate">f'{obj.__module__}.{obj.__qualname__}'</code> and only omit the module part if the module is equal to <code class="docutils literal notranslate">builtins</code>. Only the <code class="docutils literal notranslate">traceback</code> and <code class="docutils literal notranslate">pdb</code> modules also omit the module if it’s equal to <code class="docutils literal notranslate">"builtins"</code> or <code class="docutils literal notranslate">"__main__"</code>. The <code class="docutils literal notranslate">type.__fully_qualified_name__</code> attribute omits the <code class="docutils literal notranslate">__main__</code> module to produce shorter names for a common case: types defined in a script run with <code class="docutils literal notranslate">python script.py</code>. For debugging, the <code class="docutils literal notranslate">repr()</code> function can be used on a type, it includes the <code class="docutils literal notranslate">__main__</code> module in the type name. Or use <code class="docutils literal notranslate">f"{type.__module__}.{type.__qualname__}"</code> format to always include the module name, even for the <code class="docutils literal notranslate">"builtins"</code> module. Example of script: <div class="highlight-default notranslate"><div class="highlight"><pre>class MyType: pass print(f"name: {MyType.__fully_qualified_name__}") print(f"repr: {repr(MyType)}") </pre></div> </div> Output: <div class="highlight-default notranslate"><div class="highlight"><pre>name: MyType repr: <class '__main__.MyType'> </pre></div> </div> </section> </section> <section id="discussions"> <h2><a class="toc-backref" href="#discussions" role="doc-backlink">Discussions</a></h2> <ul class="simple"> <li>Discourse: <a class="reference external" href="https://discuss.python.org/t/pep-737-unify-type-name-formatting/39872">PEP 737 – Unify type name formatting</a> (2023).</li> <li>Discourse: <a class="reference external" href="https://discuss.python.org/t/enhance-type-name-formatting-when-raising-an-exception-add-t-format-in-c-and-add-type-fullyqualname/38129">Enhance type name formatting when raising an exception: add %T format in C, and add type.__fullyqualname__</a> (2023).</li> <li>Issue: <a class="reference external" href="https://github.com/python/cpython/issues/111696">PyUnicode_FromFormat(): Add %T format to format the type name of an object</a> (2023).</li> <li>Issue: <a class="reference external" href="https://github.com/python/cpython/issues/105970">C API: Investigate how the PyTypeObject members can be removed from the public C API</a> (2023).</li> <li>python-dev thread: <a class="reference external" href="https://mail.python.org/archives/list/python-dev@python.org/thread/HKYUMTVHNBVB5LJNRMZ7TPUQKGKAERCJ/">bpo-34595: How to format a type name?</a> (2018).</li> <li>Issue: <a class="reference external" href="https://github.com/python/cpython/issues/78776">PyUnicode_FromFormat(): add %T format for an object type name</a> (2018).</li> <li>Issue: <a class="reference external" href="https://github.com/python/cpython/issues/55042">Replace %.100s by %s in PyErr_Format(): the arbitrary limit of 500 bytes is outdated</a> (2011).</li> </ul> </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-0737.rst">https://github.com/python/peps/blob/main/peps/pep-0737.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0737.rst">2024-06-01 20:53:34 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="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#standard-library">Standard library</a><ul> <li><a class="reference internal" href="#python-code">Python code</a></li> <li><a class="reference internal" href="#c-code">C code</a></li> </ul> </li> <li><a class="reference internal" href="#using-pytypeobject-tp-name-is-inconsistent-with-python">Using PyTypeObject.tp_name is inconsistent with Python</a></li> <li><a class="reference internal" href="#limited-c-api">Limited C API</a></li> <li><a class="reference internal" href="#truncating-type-names-in-c">Truncating type names in C</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#add-pytype-getfullyqualifiedname-function">Add PyType_GetFullyQualifiedName() function</a></li> <li><a class="reference internal" href="#add-pytype-getmodulename-function">Add PyType_GetModuleName() function</a></li> <li><a class="reference internal" href="#add-formats-to-pyunicode-fromformat">Add formats to PyUnicode_FromFormat()</a></li> <li><a class="reference internal" href="#formats-summary">Formats Summary</a></li> <li><a class="reference internal" href="#recommend-using-the-type-fully-qualified-name">Recommend using the type fully qualified name</a></li> <li><a class="reference internal" href="#recommend-not-truncating-type-names">Recommend not truncating type names</a></li> </ul> </li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#id1">Add type.__fully_qualified_name__ attribute</a></li> <li><a class="reference internal" href="#add-type-format-method">Add type.__format__() method</a></li> <li><a class="reference internal" href="#change-str-type">Change str(type)</a></li> <li><a class="reference internal" href="#add-t-formatter-to-get-an-object-type">Add !t formatter to get an object type</a></li> <li><a class="reference internal" href="#add-formats-to-str-args">Add formats to str % args</a></li> <li><a class="reference internal" href="#other-ways-to-format-type-names-in-c">Other ways to format type names in C</a></li> <li><a class="reference internal" href="#use-t-format-with-py-type-pass-a-type">Use %T format with Py_TYPE(): pass a type</a></li> <li><a class="reference internal" href="#other-proposed-apis-to-get-a-type-fully-qualified-name">Other proposed APIs to get a type fully qualified name</a></li> <li><a class="reference internal" href="#include-the-main-module-in-the-type-fully-qualified-name">Include the __main__ module in the type fully qualified name</a></li> </ul> </li> <li><a class="reference internal" href="#discussions">Discussions</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-0737.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>