I was confused by the first line in the docs for __future__
__future__ is a real module, and serves three purposes:
What does it mean by a “real” module? What are modules that aren’t “real”?
It merely means that the line
from __future__ import annotations
in your source code is not just “interpreter boilerplate” or a special instruction but imports a Python object annotations from a Python module __future__.
1 Like
It means it’s a built-in module, not something created ad hoc by developers.
1 Like
I believe this doc was copied from an older version of the module docstring, propagating its confusing wording.
First, __future__ imports are special code interpreted by the python compiler to change its behaviour: 7. Simple statements — Python 3.12.0 documentation
Second, it’s also a real module, an importable python file, so that the import system does not need to special-case it, and to provide information at run time (usable by python code that imports it). It’s an elegant idea, but the doc is strange for everyone who reads it for the first time!
7 Likes
I’d say “real module” is strange all the time, and we don’t need it. "import __future__" serves three purposes is good.
What I would mostly like to change on that page is to document what each import does. The page spends a lot of words explaining the _Feature objects, which no one uses, but doesn’t say what (for example) from __future__ import annotations actually does. It links off to PEPs that are good historical records of decision making, but aren’t good ways to explain what Python does right now.
9 Likes
Please feel free to open a ticket for this (tag me please), it could be an easy first contribution for someone.