I agree that the complex cases need to be handled in documentation. Whether or not it’s strictly necessary that the PEP to walk through this under How to Teach This, it would probably be worth calling out the basic scenarios under discussion.
At a minimum, I think it’s important to make sure there’s clear guidance on what maintainers of different packages should be documenting.
- A package with minimal and default dependencies.
- e.g.,
fastapi[standard] - How to install with the default. How to do a minimal install.
- e.g.,
- A package with pluggable backends.
- e.g.,
qtpy(this doesn’t actually define its soft dependencies as extras[1]; does anyone have an example which uses extras?) - How to install with the default. How to do a minimal install. How to select a non-default backend.
- e.g.,
- A package with various non-exclusive soft dependencies.
- e.g.,
sunpy(fantastic example of this, thanks @cadair for weighing in!) - How to install with the default. How to do a minimal install. How to select various options.
- e.g.,
What I’m getting at is that saying “packages have to document it” may be right, but it’s worth thinking through what that documentation will look like and how it will be different for different kinds of packages.
I tend not to either. I find that since I have to document it, I might as well just document the soft dependencies themselves. So I don’t have good examples from any of my own work. ↩︎