Add discussion "Distribution package vs. import package"

Resolves #1425

Author: jeanas

source/discussions/distribution-package-vs-import-package.rst

@@ -0,0 +1,90 @@
+.. _distribution-package-vs-import-package:
+
+=======================================
+Distribution package vs. import package
+=======================================
+
+A number of different concepts are commonly referred to by the word
+"package". This page clarifies the differences between two distinct but
+related meanings in Python packaging, "distribution package" and "import
+package".
+
+What's a distribution package?
+==============================
+
+A distribution package is a piece of software that you can install.
+Most of the time, this is synonymous with "project". When you type ``pip
+install pkg``, or when you write ``dependencies = ["pkg"]`` in your
+``pyproject.toml``, ``pkg`` is the name of a distribution package. When
+you search or browse PyPI_, the most widely known centralized source for
+installing Python software, what you see is a list of distribution
+packages. Alternatively, the term "distribution package" can be used to
+refer to a specific file that contains a certain version of a project.
+
+Note that in the Linux world, "distribution package" refers to a package
+provided by the system package manager, which is a different meaning.
+
+
+What's an import package?
+=========================
+
+An import package is a Python module. Thus, when you write ``import
+pkg`` or ``from pkg import func`` in your Python code, ``pkg`` is the
+name of an import package. More precisely, import packages are special
+Python modules that can contain submodules. For example, the ``numpy``
+package contains modules like ``numpy.linalg`` and
+``numpy.fft``. Usually, an import package is a directory on the file
+system, containing modules as ``.py`` files and subpackages as
+subdirectories.
+
+You can use an import package as soon as you have installed a distribution
+package that provides it.
+
+
+What are the links between distribution packages and import packages?
+=====================================================================
+
+By convention, a distribution package usually provides one single import
+package (or non-package module), with a matching name. For example,
+``pip install numpy`` lets you ``import numpy``.
+
+However, this is only a convention. PyPI and other package indices do
+not enforce any relationship between the name of a distribution package
+and the import packages it provides.
+
+A distribution package could provide an import package with a different
+name. An example of this is the popular Pillow_ library for image
+processing. Its distribution package name is ``Pillow``, but it provides
+the import package ``PIL``. This is for historical reasons: Pillow
+started as a fork of the PIL library, thus it kept the import name
+``PIL`` so that existing PIL users could switch to Pillow with little
+effort. More generally, a fork of an existing library is a common reason
+for differing names between the distribution package and the import
+package.
+
+On a given package index (like PyPI), distribution package names must be
+unique. On the other hand, import packages have no such requirement.
+Import packages with the same name can be provided by several
+distribution packages. Again, forks are a common reason for this.
+
+Conversely, a distribution package can provide several import packages,
+although this is less common.
+
+
+How do distribution package names and import package names compare?
+===================================================================
+
+Import packages should have valid Python identifiers as their name.  In
+particular, they use underscores ``_`` as word separator and they are
+case-sensitive.
+
+On the other hand, distribution packages can use hyphens ``-`` or
+underscores ``.``. They can also contain dots ``.``, which is sometimes
+used for packaging a subpackage of a :ref:`namespace package
+<packaging-namespace-packages>`. For most purposes, they are insensitive
+to case and to ``-`` vs.  ``_`` differences, e.g., ``pip install
+Awesome_Package`` is the same as ``pip install awesome-package``.
+
+
+.. _PyPI: https://pypi.org
+.. _Pillow: https://pypi.org/project/Pillow

source/discussions/index.rst

@@ -12,5 +12,6 @@ specific topic. If you're just trying to get stuff done, see
    pip-vs-easy-install
    install-requires-vs-requirements
    wheel-vs-egg
+   distribution-package-vs-import-package
    src-layout-vs-flat-layout
    setup-py-deprecated

source/glossary.rst

@@ -67,7 +67,8 @@ Glossary
         :term:`Import Package` (which is also commonly called a "package") or
         another kind of distribution (e.g. a Linux distribution or the Python
         language distribution), which are often referred to with the single term
-        "distribution".
+        "distribution". See :ref:`distribution-package-vs-import-package`
+        for a breakdown of the differences.
 
     Egg
 
@@ -103,7 +104,8 @@ Glossary
         An import package is more commonly referred to with the single word
         "package", but this guide will use the expanded term when more clarity
         is needed to prevent confusion with a :term:`Distribution Package` which
-        is also commonly called a "package".
+        is also commonly called a "package". See :ref:`distribution-package-vs-import-package`
+        for a breakdown of the differences.
 
     Module
 

source/guides/packaging-namespace-packages.rst

@@ -1,3 +1,5 @@
+.. _packaging-namespace-packages:
+
 ============================
 Packaging namespace packages
 ============================