documentation missing information on objects in submodules

[rappjens]

BPO	45722
Nosy	@terryjreedy

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2021-11-05.07:32:21.296>
labels = ['type-feature', 'docs']
title = 'documentation missing information on objects in submodules'
updated_at = <Date 2021-11-06.02:13:33.219>
user = 'https://bugs.python.org/rappjens'

bugs.python.org fields:

activity = <Date 2021-11-06.02:13:33.219>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-11-05.07:32:21.296>
creator = 'rapp.jens'
dependencies = []
files = []
hgrepos = []
issue_num = 45722
keywords = []
message_count = 2.0
messages = ['405769', '405842']
nosy_count = 3.0
nosy_names = ['terry.reedy', 'docs@python', 'rapp.jens']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue45722'
versions = []

[rappjens]

Documentation 5.4.2. Submodules tells what happens to modules which are imported inside __init__.py of a package>

from .foo import Foo
from .bar import Bar

then executing the following puts a name binding to foo and bar in the spam module:

>>

>>> import spam
>>> spam.foo
<module 'spam.foo' from '/tmp/imports/spam/foo.py'>
>>> spam.bar
<module 'spam.bar' from '/tmp/imports/spam/bar.py'>

I miss information on what happes to Foo and Bar.
is it directly usable under spam.Bar() or does one have to use spam.bar.Bar()?

To my mind, that example should tell this.

[terryjreedy]

https://docs.python.org/3/reference/import.html#submodules

The point of the section is that even though the names 'for' and 'bar' are not directly importing into 'spam', they get attached to 'spam' any way as indirect effect of 'from'. 'Foo' and 'Bar are directly imported and so are also bound. How about

"Executing the following puts a name binding to foo and bar (as well as Foo and Bar) in the spam module:

>>> spam.Foo
<class spam.foo.Foo>
(This should be checked in case the .foo changes the report.)

I think one example showing both foo and Foo would be enough.