pypa / pypa/packaging.python.org

Suggestion for disambiguation re import expectations and __init__.py

Open
#1,929 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
1.7k
Forks
1.7k
Avg merge
3d 12h
Merged PRs (30d)
4

Description

Issue Description

Having just gone through the tutorial, I found myself confused because once the project is packaged and installed, and then imported, the add_one() function seemed unavailable.

  • "import example_package" was without error, but attempting to use example_package.add_one(3) gave AttributeError: module 'example_package' has no attribute 'add_one'

  • "from example_package import add_one" gives ImportError: cannot import name 'add_one' from 'example_package'

  • "from example_package import *" runs without error, but then attempting to use add_one gives NameError: name 'add_one' is not defined

The only way I have been able to run "add_one()" has been as
"from example_package.example import add_one".

While this is understandable as the function is defined in the top level example.py file, it definitely violated my expectations as almost every package I use would allow me to use "import example_package" and then "example_package.add_one()" or "from example_package import add_one" and then run "add_one()"

I am suggesting either an example of loading the package and using the function, or the addition of modifying the init.py to add "from .example import add_one"

Code of Conduct
  • I am aware that participants in this repository must follow the PSF Code of Conduct.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the tutorial's example_package/example.py and init.py files and read the surrounding packaging instructions. Decide whether the tutorial should document the nested import or expose add_one from init.py, then verify the documented import commands against the packaged example.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.