pypa / pypa/packaging.python.org
Should include guidance on how to handle missing optional dependencies / extras at runtime
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.7k
- Forks
- 1.7k
- Avg merge
- 3d 12h
- Merged PRs (30d)
- 4
Description
A common problem for packages with optional dependencies / extras is that the default user experience when these dependencies haven't been installed by the package consumer isn't great: the end user will just get an ordinary ModuleNotFoundError stemming from the first import of a missing module, without a hint that this module is part of an extra or how to fix it.
As a result, authors of packages with optional dependencies often want to introduce custom handling for missing dependencies, such as raising a more helpful exception that includes the name of the extra that is missing in case of libraries, or showing a more helpful message to the end user in case of applications.
I believe it would make a lot of sense to include guidance on how to do this in the Packaging Guide.
One problem is that there doesn't currently seem to be a good good way of doing this until https://github.com/pypa/packaging-problems/issues/317 has been fixed, but a guide showing the various bad ways and pointing to tickets relevant to future improvements is better than users having to piece the information together from 10 different StackOverflow answers and GitHub issues.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the Packaging Guide and the related packaging-problems issue 317. Document practical guidance for handling missing optional dependencies at runtime, including current approaches and their limitations, and link to relevant future improvements. Done means users can understand how to provide a more helpful message and where the current guidance remains imperfect.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100