:mod:`packaging.install` --- Installation tools
===============================================

.. module:: packaging.install
   :synopsis: Download and installation building blocks


Packaging provides a set of tools to deal with downloads and installation of
distributions.  Their role is to download the distribution from indexes, resolve
the dependencies, and provide a safe way to install distributions.  An operation
that fails will cleanly roll back, not leave half-installed distributions on the
system.  Here's the basic process followed:

#. Move all distributions that will be removed to a temporary location.

#. Install all the distributions that will be installed in a temporary location.

#. If the installation fails, move the saved distributions back to their
   location and delete the installed distributions.

#. Otherwise, move the installed distributions to the right location and delete
   the temporary locations.

This is a higher-level module built on :mod:`packaging.database` and
:mod:`packaging.pypi`.


Public functions
----------------

.. function:: get_infos(requirements, index=None, installed=None, \
                        prefer_final=True)

   Return information about what's going to be installed and upgraded.
   *requirements* is a string string containing the requirements for this
   project, for example ``'FooBar 1.1'`` or ``'BarBaz (<1.2)'``.

   .. XXX are requirements comma-separated?

   If you want to use another index than the main PyPI, give its URI as *index*
   argument.

   *installed* is a list of already installed distributions used to find
   satisfied dependencies, obsoleted distributions and eventual conflicts.

   By default, alpha, beta and candidate versions are not picked up.  Set
   *prefer_final* to false to accept them too.

   The results are returned in a dictionary containing all the information
   needed to perform installation of the requirements with the
   :func:`install_from_infos` function:

   >>> get_install_info("FooBar (<=1.2)")
   {'install': [<FooBar 1.1>], 'remove': [], 'conflict': []}

   .. TODO should return tuple or named tuple, not dict
   .. TODO use "predicate" or "requirement" consistently in version and here
   .. FIXME "info" cannot be plural in English, s/infos/info/


.. function:: install(project)


.. function:: install_dists(dists, path, paths=None)

   Safely install all distributions provided in *dists* into *path*.  *paths* is
   a list of paths where already-installed distributions will be looked for to
   find satisfied dependencies and conflicts (default: :data:`sys.path`).
   Returns a list of installed dists.

   .. FIXME dists are instances of what?


.. function:: install_from_infos(install_path=None, install=[], remove=[], \
                                 conflicts=[], paths=None)

   Safely install and remove given distributions.  This function is designed to
   work with the return value of :func:`get_infos`: *install*, *remove* and
   *conflicts* should be list of distributions returned by :func:`get_infos`.
   If *install* is not empty, *install_path* must be given to specify the path
   where the distributions should be installed.  *paths* is a list of paths
   where already-installed distributions will be looked for (default:
   :data:`sys.path`).

   This function is a very basic installer; if *conflicts* is not empty, the
   system will be in a conflicting state after the function completes.  It is a
   building block for more sophisticated installers with conflict resolution
   systems.

   .. TODO document typical value for install_path
   .. TODO document integration with default schemes, esp. user site-packages


.. function:: install_local_project(path)

   Install a distribution from a source directory, which must contain either a
   Packaging-compliant :file:`setup.cfg` file or a legacy Distutils
   :file:`setup.py` script (in which case Distutils will be used under the hood
   to perform the installation).


.. function::  remove(project_name, paths=None, auto_confirm=True)

   Remove one distribution from the system.

   .. FIXME this is the only function using "project" instead of dist/release

..
   Example usage
   --------------

   Get the scheme of what's gonna be installed if we install "foobar":