Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 1 | .. _packaging-pysetup: |
| 2 | |
| 3 | ================ |
| 4 | Pysetup Tutorial |
| 5 | ================ |
| 6 | |
| 7 | Getting started |
| 8 | --------------- |
| 9 | |
| 10 | Pysetup is a simple script that supports the following features: |
| 11 | |
| 12 | - install, remove, list, and verify Python packages; |
| 13 | - search for available packages on PyPI or any *Simple Index*; |
| 14 | - verify installed packages (md5sum, installed files, version). |
| 15 | |
| 16 | |
| 17 | Finding out what's installed |
| 18 | ---------------------------- |
| 19 | |
| 20 | Pysetup makes it easy to find out what Python packages are installed:: |
| 21 | |
Éric Araujo | cde6576 | 2011-09-12 16:45:38 +0200 | [diff] [blame] | 22 | $ pysetup list virtualenv |
| 23 | 'virtualenv' 1.6 at '/opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info' |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 24 | |
Éric Araujo | cde6576 | 2011-09-12 16:45:38 +0200 | [diff] [blame] | 25 | $ pysetup list |
| 26 | 'pyverify' 0.8.1 at '/opt/python3.3/lib/python3.3/site-packages/pyverify-0.8.1.dist-info' |
| 27 | 'virtualenv' 1.6 at '/opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info' |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 28 | ... |
| 29 | |
| 30 | |
| 31 | Installing a distribution |
| 32 | ------------------------- |
| 33 | |
| 34 | Pysetup can install a Python project from the following sources: |
| 35 | |
| 36 | - PyPI and Simple Indexes; |
| 37 | - source directories containing a valid :file:`setup.py` or :file:`setup.cfg`; |
| 38 | - distribution source archives (:file:`project-1.0.tar.gz`, :file:`project-1.0.zip`); |
| 39 | - HTTP (http://host/packages/project-1.0.tar.gz). |
| 40 | |
| 41 | |
| 42 | Installing from PyPI and Simple Indexes:: |
| 43 | |
| 44 | $ pysetup install project |
| 45 | $ pysetup install project==1.0 |
| 46 | |
| 47 | Installing from a distribution source archive:: |
| 48 | |
| 49 | $ pysetup install project-1.0.tar.gz |
| 50 | |
| 51 | Installing from a source directory containing a valid :file:`setup.py` or |
| 52 | :file:`setup.cfg`:: |
| 53 | |
| 54 | $ cd path/to/source/directory |
| 55 | $ pysetup install |
| 56 | |
| 57 | $ pysetup install path/to/source/directory |
| 58 | |
| 59 | Installing from HTTP:: |
| 60 | |
| 61 | $ pysetup install http://host/packages/project-1.0.tar.gz |
| 62 | |
| 63 | |
| 64 | Retrieving metadata |
| 65 | ------------------- |
| 66 | |
| 67 | You can gather metadata from two sources, a project's source directory or an |
| 68 | installed distribution. The `pysetup metadata` command can retrieve one or |
| 69 | more metadata fields using the `-f` option and a metadata field as the |
| 70 | argument. :: |
| 71 | |
| 72 | $ pysetup metadata virtualenv -f version -f name |
| 73 | Version: |
| 74 | 1.6 |
| 75 | Name: |
| 76 | virtualenv |
| 77 | |
Éric Araujo | fb63929 | 2011-08-29 22:03:46 +0200 | [diff] [blame] | 78 | $ pysetup metadata virtualenv |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 79 | Metadata-Version: |
| 80 | 1.0 |
| 81 | Name: |
| 82 | virtualenv |
| 83 | Version: |
| 84 | 1.6 |
| 85 | Platform: |
| 86 | UNKNOWN |
| 87 | Summary: |
| 88 | Virtual Python Environment builder |
| 89 | ... |
| 90 | |
| 91 | .. seealso:: |
| 92 | |
| 93 | There are three metadata versions, 1.0, 1.1, and 1.2. The following PEPs |
| 94 | describe specifics of the field names, and their semantics and usage. 1.0 |
| 95 | :PEP:`241`, 1.1 :PEP:`314`, and 1.2 :PEP:`345` |
| 96 | |
| 97 | |
| 98 | Removing a distribution |
| 99 | ----------------------- |
| 100 | |
| 101 | You can remove one or more installed distributions using the `pysetup remove` |
| 102 | command:: |
| 103 | |
| 104 | $ pysetup remove virtualenv |
| 105 | removing 'virtualenv': |
| 106 | /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/dependency_links.txt |
| 107 | /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/entry_points.txt |
| 108 | /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/not-zip-safe |
| 109 | /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/PKG-INFO |
| 110 | /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/SOURCES.txt |
| 111 | /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/top_level.txt |
| 112 | Proceed (y/n)? y |
| 113 | success: removed 6 files and 1 dirs |
| 114 | |
| 115 | The optional '-y' argument auto confirms, skipping the conformation prompt:: |
| 116 | |
| 117 | $ pysetup remove virtualenv -y |
| 118 | |
| 119 | |
| 120 | Getting help |
| 121 | ------------ |
| 122 | |
| 123 | All pysetup actions take the `-h` and `--help` options which prints the commands |
| 124 | help string to stdout. :: |
| 125 | |
| 126 | $ pysetup remove -h |
| 127 | Usage: pysetup remove dist [-y] |
| 128 | or: pysetup remove --help |
| 129 | |
| 130 | Uninstall a Python package. |
| 131 | |
| 132 | positional arguments: |
| 133 | dist installed distribution name |
| 134 | |
| 135 | optional arguments: |
| 136 | -y auto confirm package removal |
| 137 | |
| 138 | Getting a list of all pysetup actions and global options:: |
| 139 | |
| 140 | $ pysetup --help |
| 141 | Usage: pysetup [options] action [action_options] |
| 142 | |
| 143 | Actions: |
| 144 | run: Run one or several commands |
| 145 | metadata: Display the metadata of a project |
| 146 | install: Install a project |
| 147 | remove: Remove a project |
Éric Araujo | cde6576 | 2011-09-12 16:45:38 +0200 | [diff] [blame] | 148 | search: Search for a project in the indexes |
| 149 | list: List installed projects |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 150 | graph: Display a graph |
Éric Araujo | cde6576 | 2011-09-12 16:45:38 +0200 | [diff] [blame] | 151 | create: Create a project |
Éric Araujo | bfc9729 | 2011-11-14 18:18:15 +0100 | [diff] [blame] | 152 | generate-setup: Generate a backward-compatible setup.py |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 153 | |
| 154 | To get more help on an action, use: |
| 155 | |
| 156 | pysetup action --help |
| 157 | |
| 158 | Global options: |
| 159 | --verbose (-v) run verbosely (default) |
| 160 | --quiet (-q) run quietly (turns verbosity off) |
| 161 | --dry-run (-n) don't actually do anything |
| 162 | --help (-h) show detailed help message |
| 163 | --no-user-cfg ignore pydistutils.cfg in your home directory |
| 164 | --version Display the version |