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..3854cb9cf 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 @@ -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 + ` 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 `" (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 @@ -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. - diff --git a/source/installing.rst b/source/installing.rst index ec10a5296..766e34bac 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,22 @@ 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 "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 ` -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 +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 ` 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 +124,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 +246,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. -