packaging.python.org
packaging.python.org copied to clipboard
pypa
New tutorials: write section to define and describe "package"
(For more information about this issue, please see #194).
We need a short section to follow the prerequisites section (see #196) (i.e., as its own file). It should satisfy the following goals:
- explain what a distribution package is
- explain how a distribution package differs from import packages and modules
- use the terminology that the wider Python Packaging User Guide uses, so the terminology is familiar if the reader turns to another part of the guide
I also think it would be helpful if the section could illustrate each point with some kind of example, either a made-up example or a real-world example, if it's not too complicated.
When opening pull requests for this issue, please submit to the develop branch. If you have questions that concern contributing more generally, please use issue #194. Otherwise, feel free to comment with questions or feedback. Thanks!
Relevant background info:
The typical case for a distribution package shipping multiple import packages is shipping a single top-level import package that contains multiple subpackages. For example, django.core and django.db are separate import packages provided by the django distribution package.
More uncommonly, a single distribution package may ship multiple top level import packages. For example, the setuptools distribution package ships both the setuptools and pkg_resources import packages.
The reason the latter practice has fallen out of favour is because it hurts discoverability - installing the "django" distribution package to be able to import "django.core" is relatively obvious, but needing to install "setuptools" to be able to import "pkg_resources" is entirely unintuitive.
@ddbeck I will work on this document. In regard to the examples, is it acceptable to write a scenario of the types of files that are contained in a distribution vs import package and why the package type was chosen, or do you want something more specific?
@dsmatlak That sounds fine. I think this should be a breezy, high-level overview, so any examples should be too (an outline of files and directories might be helpful, but a long, detailed source code sample wouldn't be—the reader will get a chance to make a package themselves in a later section anyway).
I had planned to work on #199 but other life events are taking precedence, so I do not have the bandwidth at this time.
