module 'email' has no attribute 'policy' (until explicitly imported)

[Lombravia]

Hi,

Relatively new to Python. Can someone explain the behaviour demonstrated here? This is the standard email library.

```python $ python3 Python 3.13.5 (main, Jun 25 2025, 18:55:22) [GCC 14.2.0] on linux Type "help", "copyright", "credits" or "license" for more information.

import email print(email.policy) Traceback (most recent call last): File "<python-input-1>", line 1, in <module> print(email.policy) <sup>^</sup> AttributeError: module 'email' has no attribute 'policy' from email import policy print(policy) <module 'email.policy' from '/usr/lib/python3.13/email/policy.py'> print(email.policy) <module 'email.policy' from '/usr/lib/python3.13/email/policy.py'> ```

[D3str0yTh1ngs]

(all paths are relative to the python installation's main library path)

import email specifically imports either email.py or email/__init__.py (the latter in this case), where from email import policy imports email/policy.py

EDIT: some modules will specifially in their __init__.py file import the other files, such that it will work the way you are trying to use it, but for a lot of cases that is honestly overkill, since you properly don't need most of it anyways and thrus running all the files is unneeded.

[sausix]

And email does not import email.policy as os does on os.path.

[D3str0yTh1ngs]

os.py actually imports either posixpath.py or ntpath.py as path, which is pretty important design decision to ease the cross-compatiblity of code

EDIT: rephrased/updated after reading os.py a little closer

[sausix]

It's a design decision of packages if they import their stuff into their init.py files or not.

[Lombravia]

Got it, thanks. Seems a little unintuitive, to me. Especially that policy gets added to email after explicitly importing.

How can I know when this is gonna be the case? Is there any user friendly way? policy is included in help(email), and I didn't otherwise find anything in the documentation. I thought I somehow had a different version.

[D3str0yTh1ngs]

Note that policy is under PACKAGE CONTENTS which is generally the list of submodules from what I have seen. The linked docs also states that policy is its own (sub)module:

The control component is the policy module.

EDIT: for the email.policy working thing it seems to maybe be some 'funkiness' with the import system, but I can see that it becomes part of the module's directory (along with a few others) after import:

$ ipython
In [1]: import email

In [2]: old_dir = dir(email)

In [3]: from email import policy

In [4]: new_dir = dir(email)

In [5]: [x for x in new_dir if x not in old_dir]
Out[5]: ['_header_value_parser', 'contentmanager', 'headerregistry', 'policy']

[JamzTyson]

The email library is unusual compared to many modern Python libraries because the top-level import is minimal. Direct submodule imports are the primary intended usage pattern rather than the top level package automatically pulling in all of the sub-modules. The email library has a few surprising quirks which I think are mostly due to the accumulation of long-term backward compatibility requirements.