# PEP 846: Docstrings for Type Aliases

**URL:** <https://discuss.python.org/t/pep-846-docstrings-for-type-aliases/109116>\
**Category:** PEPs\
**Created:** [September 18, 2026, 5:46pm UTC](https://discuss.python.org/t/pep-846-docstrings-for-type-aliases/109116 "2026-09-18T17:46:00Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![bswck](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/bswck/32/34363_2.png) [@bswck](https://discuss.python.org/u/bswck)\
**Post date:** [September 18, 2026, 5:46pm UTC](https://discuss.python.org/t/pep-846-docstrings-for-type-aliases/109116/1 "2026-09-18T17:46:00Z")

</div>

I am pleased to present PEP 846, a well-received idea to recognize docstrings of type aliases in Python.

What I like the most about it is that it looks like an easy win for the language.

It’s focused, it has support in most relevant tools, and it’s a well-established practice among many Python programmers.

#### Abstract

This PEP proposes preserving a string literal immediately following a [`type`](https://docs.python.org/3/reference/simple_stmts.html#type "(in Python v3.14)") statement as the resulting type alias object’s ` __doc__ ` attribute, exposing that documentation through [`ast`](https://docs.python.org/3/library/ast.html#module-ast "(in Python v3.14)"), and displaying it through [`pydoc`](https://docs.python.org/3/library/pydoc.html#module-pydoc "(in Python v3.14)") and [`help()`](https://docs.python.org/3/builtins/functions.html#help "(in Python v3.14)"). It follows the placement already supported by source-based documentation tools. The parser stores the docstring in a new optional `doc` field on [`ast.TypeAlias`](https://docs.python.org/3/library/ast.html#ast.TypeAlias "(in Python v3.14)") instead of creating a separate [`ast.Expr`](https://docs.python.org/3/library/ast.html#ast.Expr "(in Python v3.14)") node for it. [`ast.get_docstring()`](https://docs.python.org/3/library/ast.html#ast.get_docstring "(in Python v3.14)") retrieves alias docstrings from this field.

#### Full PEP

> **[PEP 846 – Docstrings for Type Aliases | peps.python.org](https://peps.python.org/pep-0846/)**
>
> This PEP proposes preserving a string literal immediately following a type statement as the resulting type alias object’s \_\_doc\_\_ attribute, exposing that documentation through ast, and displaying it through pydoc and help(). It follows the placement...

#### Previous idea discussion

[https://discuss.python.org/t/docstrings-for-type-aliases](https://discuss.python.org/t/docstrings-for-type-aliases) ( **please see this for mentions of a more general “variable docstrings” problem and why this PEP does not address it!** )

#### Play with this

> **[GitHub - johnslavik/cpython at gh-156925](https://github.com/johnslavik/cpython/tree/gh-156925)**
>
> gh-156925

Run with [`every-python`](https://github.com/savannahostrowski/every-python):

```bash
uvx every-python run --repo johnslavik/cpython gh-156925 -- python

```

---

<div class="post-metadata">

**Author:** ![Dutcho](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/dutcho/32/7074_2.png) [@Dutcho](https://discuss.python.org/u/Dutcho)\
**Post date:** [September 18, 2026, 7:48pm UTC](https://discuss.python.org/t/pep-846-docstrings-for-type-aliases/109116/2 "2026-09-18T19:48:24Z")

</div>

Nice.

I see you chose to put _doctest_ support out of scope.  
Please document in _rejected ideas_ including motivation. And perhaps in _how to teach_, that this is an exception to the rule that _docstring_s can have _doctest_s.  
(Or -my preference- make it in scope ☺)

---

<div class="post-metadata">

**Author:** ![mjmikulski](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/mjmikulski/32/37517_2.png) [@mjmikulski](https://discuss.python.org/u/mjmikulski)\
**Post date:** [September 18, 2026, 9:15pm UTC](https://discuss.python.org/t/pep-846-docstrings-for-type-aliases/109116/3 "2026-09-18T21:15:17Z")

</div>

Docstrings for type aliases are useful and worth supporting 💪

PEP 846 reminded me of an old idea: class-like syntax for union type aliases. With that syntax, instead of attaching the following string to a `type` statement, a type alias could optionally have a class-like block with the familiar docstring placement:

```python
type Timeout:
    """Maximum wait in seconds."""
    float
    None

```

with multiple expressions in the block forming a union.

I posted the idea separately here to avoid derailing this PEP discussion:

> [@Class-like syntax for union type aliases and natural docstrings](https://discuss.python.org/t/class-like-syntax-for-union-type-aliases-and-natural-docstrings/109103):
>
> In many type aliases, a union is the outermost operation. The recent PEP 846 (docstrings for type aliases) reminded me of an old idea of mine. That PEP proposes to attach a string statement to the preceding type statement, because the current type statement (unlike class) has no natural place for a docstring. I propose the following class-like syntax that takes the union of all its members. For example, instead of: type Timeout = int | float | None """Maximum wait in seconds; None waits indef…

---

<div class="post-metadata">

**Author:** ![jorenham](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jorenham/32/27806_2.png) [@jorenham](https://discuss.python.org/u/jorenham)\
**Post date:** [September 18, 2026, 10:50pm UTC](https://discuss.python.org/t/pep-846-docstrings-for-type-aliases/109116/4 "2026-09-18T22:50:14Z")

</div>

Thanks, this seems very useful, and I’d love to be able to apply this to the `numpy.typing` type aliases 🙂 .

When reading the “Rejected Ideas” section I had a bit of a déjà vu, which I then realized was the rejected [PEP 727](https://peps.python.org/pep-0727/) from a while back. It proposed a mechanism for documenting type annotations, and therefore also type aliases, using a new dedicated `typing.Doc` class as `typing.Annotated` metadata.  
And since PEP 846 already talks about `Annotated` as a rejected idea, I thought it might also be a good idea to mention PEP 727.

---

<div class="post-metadata">

**Author:** ![pawamoy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/pawamoy/32/5811_2.png) [@pawamoy](https://discuss.python.org/u/pawamoy)\
**Post date:** [September 19, 2026, 9:08am UTC](https://discuss.python.org/t/pep-846-docstrings-for-type-aliases/109116/5 "2026-09-19T09:08:45Z")

</div>

Congrats @bswck!

> Tools that find alias docstrings by looking at the following statement, or that rely on the alias node’s end position, need adjusting when parsing with Python 3.16.

Yep, confirmed:

```python
# pkg.py
type T = int | None
"""Hello."""

```

(assuming Griffe is installed in respective envs)

```console
% python -c 'import griffe; print(griffe.load("pkg")["T"].docstring)'
<griffe._internal.models.Docstring object at 0x7f71caae4ad0>

```

```console
% every-python run gh-156925 --repo johnslavik/cpython -- python -c 'import griffe; print(griffe.load("pkg")["T"].docstring)'
None

```

Added to the backlog 🙂

---

<div class="post-metadata">

**Author:** ![bswck](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/bswck/32/34363_2.png) [@bswck](https://discuss.python.org/u/bswck)\
**Post date:** [September 22, 2026, 1:48pm UTC](https://discuss.python.org/t/pep-846-docstrings-for-type-aliases/109116/6 "2026-09-22T13:48:39Z")

</div>

> [@Dutcho](#):
>
> I see you chose to put _doctest_ support out of scope.  
> Please document in _rejected ideas_ including motivation. And perhaps in _how to teach_, that this is an exception to the rule that _docstring_s can have _doctest_s.  
> (Or -my preference- make it in scope ☺)

I’ve included it in the scope. The update of the PEP should land soon.

---

<div class="post-metadata">

**Author:** ![beauxq](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/beauxq/32/15042_2.png) [@beauxq](https://discuss.python.org/u/beauxq)\
**Post date:** [September 22, 2026, 9:14pm UTC](https://discuss.python.org/t/pep-846-docstrings-for-type-aliases/109116/7 "2026-09-22T21:14:54Z")

</div>

+0 on the change.

> This PEP has no known security implications.

There are tools that automatically look for code in docstrings and run it as tests.

I’m imagining some freak accident where someone puts some code that should never be run in a string in a place where they don’t expect it to be run because they weren’t aware of this change…  
Maybe that string with the bad code has been there for decades and it was never run until this change was made…

I don’t know if it’s worth talking about.