PEP 713 – Callable Modules
- Amethyst Reese <amethyst at n7.gg>
- Łukasz Langa <lukasz at python.org>
- Discourse thread
- Standards Track
- Discourse message
The Steering Council didn’t feel that there was a compelling reason to have this PEP, even though it clearly could be done from a consistency point of view. If this idea comes up again in the future, this is a useful prior discussion to refer to.
Modules are currently not directly callable. Classes can define a
method that makes instance objects callable, but defining a similarly named
function in the global module scope has no effect, and that function can
only be called by importing or referencing it directly as
PEP 562 added support for
__dir__() for modules, but
__getattr__ to return a value for
__call__ still does not
make a module callable.
This PEP proposes support for making modules directly callable by defining
__call__ object in the module’s global namespace, either as a standard
function, or an arbitrary callable object.
Many modules have only a single primary interface to their functionality. In many cases, that interface is a single callable object, where being able to import and use the module directly as a callable provides a more “Pythonic” interface for users:
Currently, providing this style of interface requires modifying the module object at runtime to make it callable.
This is commonly done by replacing the module object in
a callable alternative (such as a function or class instance):
sys.modules[__name__] = fancy
This has the effect of making the original module effectively unreachable
without further hooks from the author, even with
from module import member.
It also results in a “module” object that is missing all of the special module
Alternatively, a module author can choose to override the module’s
property with a custom type that provides a callable interface:
def __call__(self, ...):
sys.modules[__name__].__class__ = FancyModule
The downside of either approach is that it not only results in extra boilerplate, but also results in type checker failures because they don’t recognize that the module is callable at runtime:
$ mypy user.py
user.py:3: error: Module not callable [operator]
Found 1 error in 1 file (checked 1 source file)
When a module object is called, and a
__call__ object is found (either
as the result of a
__dict__ lookup), then that object
will be called with the given arguments.
__call__ object is not found, then a
TypeError will be raised,
matching the existing behavior.
All of these examples would be considered valid, callable modules:
__call__ = Hello
if name == "__call__":
The first two styles should generally be preferred, as it allows for easier static analysis from tools like type checkers, though the third form would be allowed in order to make the implementation more consistent.
The intent is to allow arbitrary callable object to be assigned to the module’s
__call__ property or returned by the module’s
enabling module authors to pick the most suitable mechanism for making their
module callable by users.
Backwards Compatibility and Impact on Performance
This PEP is not expected to cause any backwards incompatibility. Any modules
that already contain a
__call__ object will continue to function the same
as before, though with the additional ability to be called directly. It is
considered unlikely that modules with an existing
__call__ object would
depend on the existing behavior of raising
TypeError when called.
Performance implications of this PEP are minimal, as it defines a new interface.
Calling a module would trigger a lookup for the name
__call__ on a module
object. Existing workarounds for creating callable modules already depend on
this behavior for generic objects, resulting in similar performance for these
Type checkers will likely need to be updated accordingly to treat modules with
__call__ object as callable. This should be possible to support in type
checkers when checking code targeted at older Python versions that do not
support callable modules, with the expectation that these modules would also
include one of the workarounds mentioned earlier to make the module callable.
How to Teach This
The documentation for callable types will
include modules in the list, with a link to
The Emulating callable objects documentation will include a section
covering callable modules, with example code, similar to the section for
customizing module attribute access.
The proposed implementation of callable modules is available in CPython PR #103742.
Given the introduction of
__dir__, and the proposal
to enable use of
__call__, it was considered if it was worth allowing use
of all Special method names for modules, such as
__iter__. While this would not be completely undesired, it increases
the potential for backward compatibility concerns, and these other special
methods are likely to provide less utility to library authors in comparison
This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.
Last modified: 2023-09-09 17:39:29 GMT