From a4b95f7ee7a5f53d731362be49128b2ee1ddb44c Mon Sep 17 00:00:00 2001 From: Marcus Smith Date: Tue, 28 Oct 2014 22:17:06 -0700 Subject: [PATCH 1/7] back to "package" and all it's ambiguity --- source/development.rst | 24 ++++++++++++------------ source/distributing.rst | 11 ++++++----- source/glossary.rst | 4 ++-- source/installing.rst | 36 +++++++++++++++++++++--------------- source/science.rst | 6 +++--- source/technical.rst | 9 ++++----- 6 files changed, 48 insertions(+), 42 deletions(-) diff --git a/source/development.rst b/source/development.rst index a3f1188e8..faa726adf 100644 --- a/source/development.rst +++ b/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 + `. 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 `: 1. `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 +` (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 ` that are external to PyPI, unlike +bandersnatch which will only cache :term:`packages ` 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) - diff --git a/source/distributing.rst b/source/distributing.rst index c6088fb19..03c51c205 100644 --- a/source/distributing.rst +++ b/source/distributing.rst @@ -35,8 +35,8 @@ We recommend the following installation sequence: 1. For building :term:`wheels `: ``pip install wheel`` [1]_ -2. For uploading :term:`distributions `: ``pip install twine`` - [1]_ +2. For uploading :term:`packages `: ``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 `, 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 `_. diff --git a/source/glossary.rst b/source/glossary.rst index 7179a7901..20f457024 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -33,7 +33,8 @@ Glossary :term:`packages `, :term:`modules `, 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 + `". Egg @@ -212,4 +213,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. - diff --git a/source/installing.rst b/source/installing.rst index ec10a5296..a41a8536f 100644 --- a/source/installing.rst +++ b/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,20 @@ Tutorial on Installing Distributions :local: This tutorial covers the basics of how to install Python :term:`packages -`, which are known more formally as -:term:`distributions `. +`. + +It's important to note that the term ":term:`package `" 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 +` 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 ":term:`package `". .. _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 +72,9 @@ We recommend the following installation sequence: Virtual Environments ==================== -Python "Virtual Environments" allow Python :term:`distributions ` -to be installed in an isolated location for a particular application, rather -than being installed globally. +Python "Virtual Environments" allow Python :term:`packages ` 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 +86,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 ` into the +Also, what if you can’t install :term:`packages ` 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 +122,8 @@ For more information, see the `virtualenv `_ 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 +244,8 @@ comparison, see :ref:`Wheel vs Egg`. User Installs ------------- -To install :term:`distributions ` that are isolated to the current -user, use the ``--user`` flag: +To install :term:`packages ` that are isolated to the +current user, use the ``--user`` flag: :: diff --git a/source/science.rst b/source/science.rst index 430b445d9..3b4db1613 100644 --- a/source/science.rst +++ b/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 diff --git a/source/technical.rst b/source/technical.rst index 9274523e0..c85ded72e 100644 --- a/source/technical.rst +++ b/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 ` from +notable at the time for installing :term:`packages ` from :term:`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 | |` | | | +------------------------------+----------------------------------+-------------------------------+ -|Uninstall Distributions |Yes (``pip uninstall``) |No | +|Uninstall Packages |Yes (``pip uninstall``) |No | +------------------------------+----------------------------------+-------------------------------+ |Dependency Overrides |Yes (:ref:`Requirements Files |No | | |`) | | +------------------------------+----------------------------------+-------------------------------+ -|List Installed Distributions |Yes (``pip list`` and ``pip |No | +|List Installed Packages |Yes (``pip list`` and ``pip |No | | |freeze``) | | +------------------------------+----------------------------------+-------------------------------+ |:ref:`PEP438 ` |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. - From 6c09ec7f06b844488fcd8f792cad5ee11988a7ff Mon Sep 17 00:00:00 2001 From: Marcus Smith Date: Tue, 28 Oct 2014 22:27:51 -0700 Subject: [PATCH 2/7] explain why "distribution" is not preferred --- source/installing.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/installing.rst b/source/installing.rst index a41a8536f..15c697be9 100644 --- a/source/installing.rst +++ b/source/installing.rst @@ -17,6 +17,9 @@ bundle of software to be installed), not to refer to the kind of :term:`package ` 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 ":term:`package `". +Using the term "distribution" is often not preferred, because it can easily be +confused with a Linux distribution, or another larger distribution like Python +itself. .. _installing_setup: From feefde6e25dff213cb068355a32c2c494a8732e6 Mon Sep 17 00:00:00 2001 From: Marcus Smith Date: Sat, 1 Nov 2014 14:45:47 -0700 Subject: [PATCH 3/7] meaning #1 --- source/installing.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/source/installing.rst b/source/installing.rst index 15c697be9..4c230cc72 100644 --- a/source/installing.rst +++ b/source/installing.rst @@ -14,12 +14,11 @@ This tutorial covers the basics of how to install Python :term:`packages It's important to note that the term ":term:`package `" 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 -` that you import in your Python source code (i.e. a +` 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 ":term:`package `". -Using the term "distribution" is often not preferred, because it can easily be -confused with a Linux distribution, or another larger distribution like Python -itself. +: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 distribution like Python itself. .. _installing_setup: From 4850cd5a9c0477a28ed5ab17215225dde27d7de4 Mon Sep 17 00:00:00 2001 From: Marcus Smith Date: Sat, 1 Nov 2014 14:47:25 -0700 Subject: [PATCH 4/7] "larger software distribution" --- source/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/installing.rst b/source/installing.rst index 4c230cc72..766e34bac 100644 --- a/source/installing.rst +++ b/source/installing.rst @@ -18,7 +18,7 @@ bundle of software to be installed), not to refer to the kind of :term:`package 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 distribution like Python itself. +distribution, or another larger software distribution like Python itself. .. _installing_setup: From d756e184372f4946e9c866feface88937aabfeca Mon Sep 17 00:00:00 2001 From: Marcus Smith Date: Sat, 1 Nov 2014 14:52:21 -0700 Subject: [PATCH 5/7] add "Import Package" and "Distribution Package" names --- source/glossary.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/glossary.rst b/source/glossary.rst index 20f457024..430aec04e 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -70,6 +70,7 @@ Glossary Package (Meaning #1) + Import Package A directory containing an ``__init__.py`` file (ex. ``mypackage/__init__.py``), and also usually containing modules @@ -78,6 +79,7 @@ Glossary Package (Meaning #2) + Distribution 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 From 890eadbd332324a4674e4c0c2ec42acfae987fc3 Mon Sep 17 00:00:00 2001 From: Marcus Smith Date: Sun, 2 Nov 2014 09:17:50 -0800 Subject: [PATCH 6/7] a simple definition of packages which doesn't conflict with PEP420 --- source/glossary.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/source/glossary.rst b/source/glossary.rst index 430aec04e..2e95af2d4 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -72,10 +72,8 @@ Glossary Package (Meaning #1) Import Package - 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``. Package (Meaning #2) From d1443210e6784aade1a6d9630a0d04a63dc29b5b Mon Sep 17 00:00:00 2001 From: Marcus Smith Date: Sun, 2 Nov 2014 09:39:01 -0800 Subject: [PATCH 7/7] explain the use of "Import Package" and "Distribution Package" --- source/glossary.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/source/glossary.rst b/source/glossary.rst index 2e95af2d4..3854cb9cf 100644 --- a/source/glossary.rst +++ b/source/glossary.rst @@ -70,14 +70,16 @@ Glossary 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 + ` of "package", this guide may use the phrase + "Import Package" for clarity. + Package (Meaning #2) - Distribution 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 @@ -89,6 +91,10 @@ Glossary called the ":term:`Python Package Index `" (and not the "Python Distribution Index"). + For the purpose of distinguishing from the :term:`first meaning` of "package", this guide may use the phrase "Distribution + Package" for clarity. + Package Index