have the glossary use 'import package' and 'distribution package' expanded terms

Author: qwcode

source/current.rst

@@ -14,7 +14,7 @@ what tools are currently recommended, then here it is.
 Installation Tool Recommendations
 =================================
 
-* Use :ref:`pip` to install Python :term:`distributions <Distribution>` from
+* Use :ref:`pip` to install Python :term:`packages <Distribution Package>` from
   :term:`PyPI <Python Package Index (PyPI)>`. [1]_ [2]_
 
 * Use :ref:`virtualenv`, or `pyvenv`_ to isolate application specific

source/development.rst

@@ -269,14 +269,14 @@ Three options are available in this area:
 2. devpi provides higher-level caching option, potentially shared amongst
    many users or machines, and
 3. bandersnatch provides a local complete mirror of all PyPI :term:`packages
-   <Package (Meaning #2)>`.
+   <Distribution Package>`.
 
 
 Caching with pip
 ----------------
 
 pip provides a number of facilities for speeding up installation by using local
-cached copies of :term:`packages <Package (Meaning #2)>`:
+cached copies of :term:`packages <Distribution Package>`:
 
 1. `Fast & local installs
    <https://pip.pypa.io/en/latest/user_guide.html#fast-local-installs>`_ by
@@ -304,14 +304,14 @@ Complete mirror with bandersnatch
 ----------------------------------
 
 bandersnatch will set up a complete local mirror of all PyPI :term:`packages
-<Package (Meaning #2)>` (externally-hosted packages are not mirrored). See
+<Distribution Package>` (externally-hosted packages are not mirrored). See
 the `bandersnatch documentation for getting that going`__.
 
 __ https://bitbucket.org/pypa/bandersnatch/overview
 
 A benefit of devpi is that it will create a mirror which includes
-:term:`packages <Package (Meaning #2)>` that are external to PyPI, unlike
-bandersnatch which will only cache :term:`packages <Package (Meaning #2)>`
+:term:`packages <Distribution Package>` that are external to PyPI, unlike
+bandersnatch which will only cache :term:`packages <Distribution Package>`
 hosted on PyPI.
 
 

source/distributing.rst

@@ -35,7 +35,7 @@ We recommend the following installation sequence:
 
 1. For building :term:`wheels <Wheel>`: ``pip install wheel`` [1]_
 
-2. For uploading :term:`packages <Package (Meaning #2)>`: ``pip install twine``
+2. For uploading :term:`packages <Distribution Package>`: ``pip install twine``
 [1]_
 
 
@@ -130,7 +130,7 @@ from `sampleproject/setup.py
 
   packages=find_packages(exclude=['contrib', 'docs', 'tests*']),
 
-It's required to list the :term:`packages <Package (Meaning #1)>` to be included
+It's required to list the :term:`packages <Import Package>` to be included
 in your project.  Although they can be listed manually,
 ``setuptools.find_packages`` finds them automatically.  Use the ``exclude``
 keyword argument to omit packages that are not intended to be released and
@@ -214,8 +214,7 @@ For more on using "install_requires" see :ref:`install_requires vs Requirements
 Package Data
 ------------
 
-Often, additional files need to be installed into a :term:`package <Package
-(Meaning #1)>`. These files are often data that’s closely related to the
+Often, additional files need to be installed into a :term:`package <Import Package>`. These files are often data that’s closely related to the
 package’s implementation, or text files containing documentation that might be
 of interest to programmers using the package. These files are called "package
 data".
@@ -246,7 +245,7 @@ Data Files
 
 Although configuring :ref:`Package Data` is sufficient for most needs, in some
 cases you may need to place data files *outside* of your :term:`packages
-<Package (Meaning #1)>`.  The ``data_files`` directive allows you to do that.
+<Import Package>`.  The ``data_files`` directive allows you to do that.
 
 from `sampleproject/setup.py
 <https://github.com/pypa/sampleproject/blob/master/setup.py>`_
@@ -258,7 +257,7 @@ from `sampleproject/setup.py
 Each (directory, files) pair in the sequence specifies the installation
 directory and the files to install there. If directory is a relative path, it is
 interpreted relative to the installation prefix (Python’s sys.prefix for
-pure-Python :term:`distributions <Distribution>`, sys.exec_prefix for
+pure-Python :term:`distributions <Distribution Package>`, sys.exec_prefix for
 distributions that contain extension modules). Each file name in files is
 interpreted relative to the ``setup.py`` script at the top of the project source
 distribution.
@@ -295,10 +294,10 @@ Although ``setup.py`` supports a `scripts
 keyword for pointing to pre-made scripts, the recommended approach to achieve
 cross-platform compatibility is to use "console_script" `entry points
 <http://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins>`_
-that register your script interfaces. You can then let the toolchain handle
-the work of turning these interfaces into actual scripts [2]_.  The scripts
-will be generated during the install of your
-:term:`distribution <Distribution>`.
+that register your script interfaces. You can then let the toolchain handle the
+work of turning these interfaces into actual scripts [2]_.  The scripts will be
+generated during the install of your :term:`distribution <Distribution
+Package>`.
 
 For more information, see `Automatic Script Creation
 <http://pythonhosted.org/setuptools/setuptools.html#automatic-script-creation>`_
@@ -345,8 +344,9 @@ Packaging your Project
 ======================
 
 To have your project installable from a :term:`Package Index` like :term:`PyPI
-<Python Package Index (PyPI)>`, you'll need to create a :term:`Distribution`
-(aka ":term:`Package <Package (Meaning #2)>`" ) for your project.
+<Python Package Index (PyPI)>`, you'll need to create a :term:`Distribution
+<Distribution Package>` (aka ":term:`Package <Distribution Package>`" ) for your
+project.
 
 
 

source/glossary.rst

@@ -18,23 +18,29 @@ Glossary
 
     Built Distribution
 
-        A :term:`Distribution` format containing files and metadata that only
-        need to be moved to the correct location on the target system, to be
-        installed. :term:`Wheel` is such a format, whereas distutil's
-        :term:`Source Distribution <Source Distribution (or "sdist")>` is not,
-        in that it requires a build step before it can be installed.  This
-        format does not imply that python files have to be precompiled
-        (:term:`Wheel` intentionally does not include compiled python files).
-
-
-    Distribution
-
-        A Python distribution is a versioned archive file that contains Python
-        :term:`packages <Package (Meaning #1)>`, :term:`modules <module>`, and
-        other resource files that are used to distribute a :term:`Release`. The
-        distribution file is what an end-user will download from the internet
-        and install.  Distributions are often referred to as ":term:`Packages
-        <Package (Meaning #2)>`".
+        A :term:`Distribution <Distribution Package>` format containing files
+        and metadata that only need to be moved to the correct location on the
+        target system, to be installed. :term:`Wheel` is such a format, whereas
+        distutil's :term:`Source Distribution <Source Distribution (or
+        "sdist")>` is not, in that it requires a build step before it can be
+        installed.  This format does not imply that python files have to be
+        precompiled (:term:`Wheel` intentionally does not include compiled
+        python files).
+
+
+    Distribution Package
+
+        A versioned archive file that contains Python :term:`packages <Import
+        Package>`, :term:`modules <module>`, and other resource files that are
+        used to distribute a :term:`Release`. The distribution file is what an
+        end-user will download from the internet and install.
+
+        A distribution package is more commonly referred to with the single
+        words "package" or "distribution", but this guide may use the expanded
+        term when more clarity is needed to prevent confusion with an
+        :term:`Import Package` which is also commonly called a "package", or
+        another kind of distribution (e.g. Linux or Python itself), which often
+        use the single term "distribution".
 
     Egg
 
@@ -63,61 +69,45 @@ Glossary
         multiple individual distributions.
 
 
-    Module
-
-        The basic unit of code reusability in Python, existing in one of two
-        types: :term:`Pure Module`, or :term:`Extension Module`.
-
-
-    Package (Meaning #1)
+    Import Package
 
         A Python module which can contain other modules or recursively, other
-        packages. You can import a package: ``import mypackage``.
-
-        For the purpose of distinguishing from the :term:`second meaning
-        <Package (Meaning #2)>` of "package", this guide may use the phrase
-        "Import Package" for clarity.
-
+        packages.
 
-    Package (Meaning #2)
+        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".
 
-        A synonym for :term:`Distribution`. It is common in Python to refer to a
-        distribution using the term "package". While the two meanings of the
-        term "package" is not always 100% unambigous, the context of the term
-        "package" is usually sufficient to distinguish the meaning of the
-        word. For example, the python installation tool :ref:`pip` is an acronym
-        for "pip installs packages". while technically the tool installs
-        distributions. Even the site where distributions are distributed at is
-        called the ":term:`Python Package Index <Python Package Index (PyPI)>`"
-        (and not the "Python Distribution Index").
+    Module
 
-        For the purpose of distinguishing from the :term:`first meaning<Package
-        (Meaning #1)>` of "package", this guide may use the phrase "Distribution
-        Package" for clarity.
+        The basic unit of code reusability in Python, existing in one of two
+        types: :term:`Pure Module`, or :term:`Extension Module`.
 
 
     Package Index
 
         A repository of distributions with a web interface to automate
-        :term:`Distribution` discovery and consumption.
+        :term:`package <Distribution Package>` discovery and consumption.
 
 
     Project
 
         A library, framework, script, plugin, application, or collection of data
         or other resources, or some combination thereof that is intended to be
-        packaged into a :term:`Distribution`.
+        packaged into a :term:`Distribution <Distribution Package>`.
 
-        Since most projects create :term:`Distributions <Distribution>` using
-        :ref:`distutils` or :ref:`setuptools`, another practical way to define
-        projects currently is something that contains a :term:`setup.py` at the
-        root of the project src directory, where "setup.py" is the project
-        specification filename used by :ref:`distutils` and :ref:`setuptools`.
+        Since most projects create :term:`Distributions <Distribution Package>`
+        using :ref:`distutils` or :ref:`setuptools`, another practical way to
+        define projects currently is something that contains a :term:`setup.py`
+        at the root of the project src directory, where "setup.py" is the
+        project specification filename used by :ref:`distutils` and
+        :ref:`setuptools`.
 
         Python projects must have unique names, which are registered on
         :term:`PyPI <Python Package Index (PyPI)>`. Each project will then
         contain one or more :term:`Releases <Release>`, and each release may
-        comprise one or more :term:`distributions <Distribution>`.
+        comprise one or more :term:`distributions <Distribution Package>`.
 
         Note that there is a strong convention to name a project after the name
         of the package that is imported to run that project. However, this
@@ -153,14 +143,14 @@ Glossary
         by a version identifier.
 
         Making a release may entail the publishing of multiple
-        :term:`Distributions <Distribution>`.  For example, if version 1.0 of a
-        project was released, it could be available in both a source
+        :term:`Distributions <Distribution Package>`.  For example, if version
+        1.0 of a project was released, it could be available in both a source
         distribution format and a Windows installer distribution format.
 
 
     Requirement
 
-       A specification for a :term:`package <Package (Meaning #2)>` to be
+       A specification for a :term:`package <Distribution Package>` to be
        installed.  :ref:`pip`, the :term:`PYPA <Python Packaging Authority
        (PyPA)>` recommended installer, allows various forms of specification
        that can all be considered a "requirement". For more information, see the
@@ -188,10 +178,10 @@ Glossary
 
     Source Distribution (or "sdist")
 
-        A :term:`distribution <Distribution>` format (usually generated using
-        ``python setup.py sdist``) that provides metadata and the essential
-        source files needed for installing by a tool like :ref:`pip`, or for
-        generating a :term:`Built Distribution`.
+        A :term:`distribution <Distribution Package>` format (usually generated
+        using ``python setup.py sdist``) that provides metadata and the
+        essential source files needed for installing by a tool like :ref:`pip`,
+        or for generating a :term:`Built Distribution`.
 
 
     System Package
@@ -215,7 +205,7 @@ Glossary
 
     Working Set
 
-        A collection of :term:`distributions <Distribution>` available for
-        importing. These are the distributions that are on the `sys.path`
-        variable. At most, one :term:`Distribution` for a project is possible in
-        a working set.
+        A collection of :term:`distributions <Distribution Package>` available
+        for importing. These are the distributions that are on the `sys.path`
+        variable. At most, one :term:`Distribution <Distribution Package>` for a
+        project is possible in a working set.

source/installing.rst

@@ -9,15 +9,15 @@ Tutorial on Installing Packages
    :local:
 
 This tutorial covers the basics of how to install Python :term:`packages
-<Package (Meaning #2)>`.
-
-It's important to note that the term ":term:`package <Package (Meaning #2)>`" in
-this context is being used as a synonym for a :term:`distribution` (i.e. a
-bundle of software to be installed), not to refer to the kind of :term:`package
-<Package (Meaning #1)>` that you import in your Python source code (i.e. a
-directory of modules). It is common in the Python community to refer to a
-:term:`distribution` using the term "package".  Using the term "distribution" is
-often not preferred, because it can easily be confused with a Linux
+<Distribution Package>`.
+
+It's important to note that the term "package" in this context is being used as
+a synonym for a :term:`distribution <Distribution Package>` (i.e. a bundle of
+software to be installed), not to refer to the kind of :term:`package <Import
+Package>` that you import in your Python source code (i.e. a container of
+modules). It is common in the Python community to refer to a :term:`distribution
+<Distribution Package>` using the term "package".  Using the term "distribution"
+is often not preferred, because it can easily be confused with a Linux
 distribution, or another larger software distribution like Python itself.
 
 
@@ -74,8 +74,8 @@ We recommend the following installation sequence:
 Virtual Environments
 ====================
 
-Python "Virtual Environments" allow Python :term:`packages <Package (Meaning
-#2)>` to be installed in an isolated location for a particular application,
+Python "Virtual Environments" allow Python :term:`packages <Distribution
+Package>` to be installed in an isolated location for a particular application,
 rather than being installed globally.
 
 Imagine you have an application that needs version 1 of LibFoo, but another
@@ -88,7 +88,7 @@ Or more generally, what if you want to install an application and leave it be?
 If an application works, any change in its libraries or the versions of those
 libraries can break the application.
 
-Also, what if you can’t install :term:`packages <Package (Meaning #2)>` into the
+Also, what if you can’t install :term:`packages <Distribution Package>` into the
 global site-packages directory? For instance, on a shared host.
 
 In all these cases, virtual environments can help you. They have their own
@@ -214,7 +214,7 @@ default, pip only finds stable versions.
 Wheels
 ------
 
-:term:`Wheel` is a pre-built :term:`distribution <Distribution>` format that
+:term:`Wheel` is a pre-built :term:`distribution <Distribution Package>` format that
 provides faster installation compared to :term:`Source Distributions (sdist)
 <Source Distribution (or "sdist")>`, especially when a project contains compiled
 extensions.
@@ -246,7 +246,7 @@ comparison, see :ref:`Wheel vs Egg`.
 User Installs
 -------------
 
-To install :term:`packages <Package (Meaning #2)>` that are isolated to the
+To install :term:`packages <Distribution Package>` that are isolated to the
 current user, use the ``--user`` flag:
 
 ::

source/projects.rst

@@ -277,9 +277,9 @@ User irc:#pypa  |
 Dev irc:#pypa-dev
 
 A package in the Python Standard Library that has support for creating and
-installing :term:`distributions <Distribution>`. :ref:`Setuptools` provides
-enhancements to distutils, and is much more commonly used than just using
-distutils by itself.
+installing :term:`distributions <Distribution Package>`. :ref:`Setuptools`
+provides enhancements to distutils, and is much more commonly used than just
+using distutils by itself.
 
 
 .. _venv:

source/technical.rst

@@ -122,7 +122,7 @@ pip vs easy_install
 ===================
 
 `easy_install` was released in 2004, as part of :ref:`setuptools`.  It was
-notable at the time for installing :term:`packages <Package (Meaning #2)>` from
+notable at the time for installing :term:`packages <Distribution Package>` from
 :term:`PyPI <Python Package Index (PyPI)>` using requirement specifiers, and
 automatically installing dependencies.
 
@@ -197,7 +197,7 @@ Wheel vs Egg
 
 * :term:`Wheel` has an :ref:`official PEP <PEP427s>`. :term:`Egg` did not.
 
-* :term:`Wheel` is a :term:`distribution <Distribution>` format, i.e a packaging
+* :term:`Wheel` is a :term:`distribution <Distribution Package>` format, i.e a packaging
   format. [2]_ :term:`Egg` was both a distribution format and a runtime
   installation format (if left zipped), and was designed to be importable.