Breaking change introduced in Python 3.14 for `typing.Union.__doc__` without deprecation

[user27182]

Documentation

This is related to #91309 (comment)

Python 3.14 introduced a breaking change to Union.__doc__ and has made it read-only:

from typing import Union
alias = Union[int | str]
alias.__doc__ = 'My custom type alias'

Traceback (most recent call last):
  File "<input>", line 3, in <module>
AttributeError: 'typing.Union' object attribute '__doc__' is read-only

Note that I use the term "breaking" a bit loosely, as it seems that it's unclear if this was actually explicitly documented as a feature before. E.g. looking through the 3.13 Data Model docs https://docs.python.org/3.13/reference/datamodel.html, I see some parts of the data model state that __doc__ is explicitly writeable (e.g. function.__doc__ is writeable), but __doc__ for built in functions is explicitly read-only. I am not sure what category typing.Union falls under, so it may be unclear what to expect with respect to __doc__ for this object.

I tried looking at the release notes https://docs.python.org/3/whatsnew/changelog.html, but couldn't find anything related to __doc__ and Union that mentioned anything related to making this read-only.

Unfortunately, making __doc__ read only not only broke documentation for downstream projects, (see pyvista/pyvista#8102), but it also created compatibility issues since Python 3.14 raises an error for an otherwise valid installation (see pyvista/pyvista#8112). In this case, it would have been better if Python issued a deprecation warning about setting __doc__ instead of raising an AttributeError.

In terms of resolving this issue, I think it would be best to simply keep typing.Union.__doc__ as writeable, which is in-line with the goals of #91309. If this is not an option, then I think the documentation should be updated to make it clearer to users which objects have a writeable __doc__ attribute, and which ones are read-only.

[StanFromIreland]

Seems to be a side-effect of dc6d66f.

CC @JelleZijlstra

[hauntsaninja]

From Python 3.14's What's New:

It is no longer possible to set any attributes on Union objects. This only ever worked for dunder attributes on previous versions, was never documented to work, and was subtly broken in many cases.

[user27182]

From Python 3.14's What's New:

It is no longer possible to set any attributes on Union objects. This only ever worked for dunder attributes on previous versions, was never documented to work, and was subtly broken in many cases.

Thank you for highlighting this. This change is unfortunate, I guess there are no plans to make it writeable then?

I still think there may be a documentation issue related to this. In general, how am I supposed to know if a python object's __doc__ is officially writeable, and not subject to future breakage? Should I assume __doc__ is read-only for all built-in python objects from all modules unless otherwise explicitly stated in the docs? If so, perhaps the data model docs can be updated to clearly indicate this.