Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 1 | :mod:`packaging.install` --- Installation tools |
| 2 | =============================================== |
| 3 | |
| 4 | .. module:: packaging.install |
| 5 | :synopsis: Download and installation building blocks |
| 6 | |
| 7 | |
| 8 | Packaging provides a set of tools to deal with downloads and installation of |
| 9 | distributions. Their role is to download the distribution from indexes, resolve |
| 10 | the dependencies, and provide a safe way to install distributions. An operation |
| 11 | that fails will cleanly roll back, not leave half-installed distributions on the |
| 12 | system. Here's the basic process followed: |
| 13 | |
| 14 | #. Move all distributions that will be removed to a temporary location. |
| 15 | |
| 16 | #. Install all the distributions that will be installed in a temporary location. |
| 17 | |
| 18 | #. If the installation fails, move the saved distributions back to their |
| 19 | location and delete the installed distributions. |
| 20 | |
| 21 | #. Otherwise, move the installed distributions to the right location and delete |
| 22 | the temporary locations. |
| 23 | |
| 24 | This is a higher-level module built on :mod:`packaging.database` and |
| 25 | :mod:`packaging.pypi`. |
| 26 | |
| 27 | |
| 28 | Public functions |
| 29 | ---------------- |
| 30 | |
| 31 | .. function:: get_infos(requirements, index=None, installed=None, \ |
| 32 | prefer_final=True) |
| 33 | |
| 34 | Return information about what's going to be installed and upgraded. |
| 35 | *requirements* is a string string containing the requirements for this |
| 36 | project, for example ``'FooBar 1.1'`` or ``'BarBaz (<1.2)'``. |
| 37 | |
| 38 | .. XXX are requirements comma-separated? |
| 39 | |
| 40 | If you want to use another index than the main PyPI, give its URI as *index* |
| 41 | argument. |
| 42 | |
| 43 | *installed* is a list of already installed distributions used to find |
| 44 | satisfied dependencies, obsoleted distributions and eventual conflicts. |
| 45 | |
| 46 | By default, alpha, beta and candidate versions are not picked up. Set |
| 47 | *prefer_final* to false to accept them too. |
| 48 | |
| 49 | The results are returned in a dictionary containing all the information |
| 50 | needed to perform installation of the requirements with the |
| 51 | :func:`install_from_infos` function: |
| 52 | |
| 53 | >>> get_install_info("FooBar (<=1.2)") |
| 54 | {'install': [<FooBar 1.1>], 'remove': [], 'conflict': []} |
| 55 | |
| 56 | .. TODO should return tuple or named tuple, not dict |
| 57 | .. TODO use "predicate" or "requirement" consistently in version and here |
| 58 | .. FIXME "info" cannot be plural in English, s/infos/info/ |
| 59 | |
| 60 | |
| 61 | .. function:: install(project) |
| 62 | |
| 63 | |
| 64 | .. function:: install_dists(dists, path, paths=None) |
| 65 | |
| 66 | Safely install all distributions provided in *dists* into *path*. *paths* is |
| 67 | a list of paths where already-installed distributions will be looked for to |
| 68 | find satisfied dependencies and conflicts (default: :data:`sys.path`). |
| 69 | Returns a list of installed dists. |
| 70 | |
| 71 | .. FIXME dists are instances of what? |
| 72 | |
| 73 | |
| 74 | .. function:: install_from_infos(install_path=None, install=[], remove=[], \ |
| 75 | conflicts=[], paths=None) |
| 76 | |
| 77 | Safely install and remove given distributions. This function is designed to |
| 78 | work with the return value of :func:`get_infos`: *install*, *remove* and |
| 79 | *conflicts* should be list of distributions returned by :func:`get_infos`. |
| 80 | If *install* is not empty, *install_path* must be given to specify the path |
| 81 | where the distributions should be installed. *paths* is a list of paths |
| 82 | where already-installed distributions will be looked for (default: |
| 83 | :data:`sys.path`). |
| 84 | |
| 85 | This function is a very basic installer; if *conflicts* is not empty, the |
| 86 | system will be in a conflicting state after the function completes. It is a |
| 87 | building block for more sophisticated installers with conflict resolution |
| 88 | systems. |
| 89 | |
| 90 | .. TODO document typical value for install_path |
| 91 | .. TODO document integration with default schemes, esp. user site-packages |
| 92 | |
| 93 | |
| 94 | .. function:: install_local_project(path) |
| 95 | |
| 96 | Install a distribution from a source directory, which must contain either a |
| 97 | Packaging-compliant :file:`setup.cfg` file or a legacy Distutils |
| 98 | :file:`setup.py` script (in which case Distutils will be used under the hood |
| 99 | to perform the installation). |
| 100 | |
| 101 | |
| 102 | .. function:: remove(project_name, paths=None, auto_confirm=True) |
| 103 | |
| 104 | Remove one distribution from the system. |
| 105 | |
| 106 | .. FIXME this is the only function using "project" instead of dist/release |
| 107 | |
| 108 | .. |
| 109 | Example usage |
| 110 | -------------- |
| 111 | |
| 112 | Get the scheme of what's gonna be installed if we install "foobar": |