back to "package"

source/development.rst

@@ -260,23 +260,23 @@ There are a few techniques to store the version in your project code without dup
 PyPI mirrors and caches
 =======================
 
-Mirroring or caching of PyPI can be used to speed up local distribution
-installation, allow offline work, handle corporate firewalls or just plain
-Internet flakiness.
+Mirroring or caching of PyPI can be used to speed up local package installation,
+allow offline work, handle corporate firewalls or just plain Internet flakiness.
 
 Three options are available in this area:
 
 1. pip provides local caching options,
 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 distributions.
+3. bandersnatch provides a local complete mirror of all PyPI :term:`packages
+   <Package (Meaning #2)>`.
 
 
 Caching with pip
 ----------------
 
-pip provides a number of facilities for speeding up installation by using
-local cached copies of distributions:
+pip provides a number of facilities for speeding up installation by using local
+cached copies of :term:`packages <Package (Meaning #2)>`:
 
 1. `Fast & local installs
    <https://pip.pypa.io/en/latest/user_guide.html#fast-local-installs>`_ by
@@ -303,14 +303,15 @@ __ http://doc.devpi.net/latest/quickstart-pypimirror.html
 Complete mirror with bandersnatch
 ----------------------------------
 
-bandersnatch will set up a complete local mirror of all PyPI distributions
-(externally-hosted distributions are not mirrored). See the
-`bandersnatch documentation for getting that going`__.
+bandersnatch will set up a complete local mirror of all PyPI :term:`packages
+<Package (Meaning #2)>` (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 distributions
-that are external to PyPI, unlike bandersnatch which will only cache distributions
+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)>`
 hosted on PyPI.
 
 
@@ -328,4 +329,3 @@ Patching & Forking
      - PEP440's local identifiers: http://www.python.org/dev/peps/pep-0440/#local-version-identifiers
   - fork and publish when you need to publish a project that depends on the fork
      (DONT use dependency links)
-

source/distributing.rst

@@ -35,8 +35,8 @@ We recommend the following installation sequence:
 
 1. For building :term:`wheels <Wheel>`: ``pip install wheel`` [1]_
 
-2. For uploading :term:`distributions <Distribution>`: ``pip install twine``
-   [1]_
+2. For uploading :term:`packages <Package (Meaning #2)>`: ``pip install twine``
+[1]_
 
 
 Creating your own Project
@@ -258,9 +258,10 @@ 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 distributions, 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.
+pure-Python :term:`distributions <Distribution>`, 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.
 
 For more information see the distutils section on `Installing Additional Files
 <http://docs.python.org/3.4/distutils/setupscript.html#installing-additional-files>`_.

source/glossary.rst

@@ -33,7 +33,8 @@ Glossary
         :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.
+        and install.  Distributions are often referred to as ":term:`Packages
+        <Package (Meaning #2)>`".
 
     Egg
 
@@ -70,10 +71,12 @@ Glossary
 
     Package (Meaning #1)
 
-        A directory containing an ``__init__.py`` file (ex.
-        ``mypackage/__init__.py``), and also usually containing modules
-        (possibly along with other packages). You can import a package: ``import
-        mypackage``
+        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.
 
 
     Package (Meaning #2)
@@ -88,6 +91,10 @@ Glossary
         called the ":term:`Python Package Index <Python Package Index (PyPI)>`"
         (and not the "Python Distribution Index").
 
+        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.
+
 
     Package Index
 
@@ -212,4 +219,3 @@ Glossary
         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.
-

source/installing.rst

@@ -1,6 +1,6 @@
-====================================
-Tutorial on Installing Distributions
-====================================
+===============================
+Tutorial on Installing Packages
+===============================
 
 :Page Status: Complete
 :Last Reviewed: 2014-09-30
@@ -9,14 +9,22 @@ Tutorial on Installing Distributions
    :local:
 
 This tutorial covers the basics of how to install Python :term:`packages
-<Package (Meaning #2)>`, which are known more formally as
-:term:`distributions <Distribution>`.
+<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, or another larger software distribution like Python itself.
 
 
 .. _installing_setup:
 
-Setup for Installing Distribution Packages
-==========================================
+Setup for Installing Packages
+=============================
 
 This section describes the steps to follow before installing other
 Python packages.  You will want to install :ref:`pip` and
@@ -66,9 +74,9 @@ We recommend the following installation sequence:
 Virtual Environments
 ====================
 
-Python "Virtual Environments" allow Python :term:`distributions <Distribution>`
-to be installed in an isolated location for a particular application, rather
-than being installed globally.
+Python "Virtual Environments" allow Python :term:`packages <Package (Meaning
+#2)>` 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
 application requires version 2. How can you use both these applications? If you
@@ -80,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:`distributions <Distribution>` into the
+Also, what if you can’t install :term:`packages <Package (Meaning #2)>` 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
@@ -116,8 +124,8 @@ For more information, see the `virtualenv <http://virtualenv.pypa.io>`_ docs or
 the `pyvenv`_ docs.
 
 
-Installing Python Distribution Packages
-=======================================
+Installing Python Packages
+==========================
 
 :ref:`pip` is the recommended installer, and supports various requirement forms
 and options.  For details, see the `pip docs
@@ -238,8 +246,8 @@ comparison, see :ref:`Wheel vs Egg`.
 User Installs
 -------------
 
-To install :term:`distributions <Distribution>` that are isolated to the current
-user, use the ``--user`` flag:
+To install :term:`packages <Package (Meaning #2)>` that are isolated to the
+current user, use the ``--user`` flag:
 
 ::
 

source/science.rst

@@ -1,8 +1,8 @@
 .. _`NumPy and the Science Stack`:
 
-===================================
-Installing Scientific Distributions
-===================================
+==============================
+Installing Scientific Packages
+==============================
 
 :Page Status: Incomplete
 :Last Reviewed: 2014-07-24

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:`distributions <Distribution>` from
+notable at the time for installing :term:`packages <Package (Meaning #2)>` from
 :term:`PyPI <Python Package Index (PyPI)>` using requirement specifiers, and
 automatically installing dependencies.
 
@@ -142,12 +142,12 @@ Here's a breakdown of the important differences between pip and easy_install now
 |Installs from :term:`Wheels   |Yes                               |No                             |
 |<Wheel>`                      |                                  |                               |
 +------------------------------+----------------------------------+-------------------------------+
-|Uninstall Distributions       |Yes (``pip uninstall``)           |No                             |
+|Uninstall Packages            |Yes (``pip uninstall``)           |No                             |
 +------------------------------+----------------------------------+-------------------------------+
 |Dependency Overrides          |Yes (:ref:`Requirements Files     |No                             |
 |                              |<pip:Requirements Files>`)        |                               |
 +------------------------------+----------------------------------+-------------------------------+
-|List Installed Distributions  |Yes (``pip list`` and ``pip       |No                             |
+|List Installed Packages       |Yes (``pip list`` and ``pip       |No                             |
 |                              |freeze``)                         |                               |
 +------------------------------+----------------------------------+-------------------------------+
 |:ref:`PEP438 <PEP438s>`       |Yes                               |No                             |
@@ -187,7 +187,7 @@ easy_install and sys.path
 
    FIXME
 
-   - global easy_install'd distributions override --user installs
+   - global easy_install'd packages override --user installs
 
 
 .. _`Wheel vs Egg`:
@@ -288,4 +288,3 @@ Dependency Resolution
 
 .. [3] For more on "Abstract" vs "Concrete" requirements, see
        https://caremad.io/blog/setup-vs-requirement.
-