Commits

Kelsey Hightower committed f947466

Updating the pysetup tutorial

Comments (0)

Files changed (1)

Doc/packaging/enduser/pysetup/tutorial.rst

 Tutorial
 ========
 
-Installing ``pysetup``
-======================
-
-Pysetup is bundled with the ``packaging`` module, which is included in the standard 
-library as of Python 3.3. If you are running an older version of Python, then 
-download ``distutils2`` from PyPI (*packaging* started out as *distutils2* and
-was later renamed).
-
 
 Getting started
-===============
+---------------
 
 Pysetup is a simple script that supports the following features:
 
 - verify installed packages (md5sum, installed files, version).
 
 
-Searching for available packages
-================================
+Finding out what's installed
+----------------------------
 
-Pysetup support searching configured indexes for available packages::
+Pysetup makes it easy to find out what Python packages are installed::
 
-  $ pysetup search project
-  project version a short description
+   $ pysetup search project
+   virtualenv 1.6 at /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info
+
+   $ pysetup search --all
+   pyverify 0.8.1 at /opt/python3.3/lib/python3.3/site-packages/pyverify-0.8.1.dist-info
+   wsgiref 0.1.2 at /opt/python3.3/lib/python3.3/wsgiref.egg-info
+   ...
 
 
 Installing a package or distribution
-====================================
+------------------------------------
 
 Pysetup can install a Python project from the following sources:
 
 - distribution source archives (:file:`project-1.0.tar.gz`, :file:`project-1.0.zip`);
 - HTTP (http://host/packages/project-1.0.tar.gz).
 
+
 Installing from PyPI and Simple Indexes::
 
-  $ pysetup install project
-  $ pysetup install project==1.0
+   $ pysetup install project
+   $ pysetup install project==1.0
 
 Installing from a distribution source archive::
 
-  $ pysetup install project-1.0.tar.gz
+   $ pysetup install project-1.0.tar.gz
 
 Installing from a source directory containing a valid :file:`setup.py` or :file:`setup.cfg`::
 
-  $ cd path/to/source/directory
-  $ pysetup install
+   $ cd path/to/source/directory
+   $ pysetup install
 
-  $ pysetup install path/to/source/directory
+   $ pysetup install path/to/source/directory
 
 Installing from HTTP::
 
-  $ pysetup install http://host/packages/project-1.0.tar.gz
+   $ pysetup install http://host/packages/project-1.0.tar.gz
 
 
-Removing a package
-==================
+Retrieving metadata
+-------------------
 
-You can remove an installed package by running the following command::
+You can gather metadata from two sources, a project's source directory or an
+installed distribution. The `pysetup metadata` command can retrieve one or
+more metadata fields using the `-f` option and a metadata field as the
+argument.
 
-  $ pysetup remove package
+::
 
+   $ pysetup metadata virtualenv -f version -f name
+   Version:
+       1.6
+   Name:
+       virtualenv
 
-Finding out what's installed
-============================
+   $ pysetup metadata virtualenv --all
+   Metadata-Version:
+       1.0
+   Name:
+       virtualenv
+   Version:
+       1.6
+   Platform:
+       UNKNOWN
+   Summary:
+       Virtual Python Environment builder
+   ...
 
-Pysetup makes it easy to find out what Python packages are installed::
 
-  $ pysetup list --all
-  distribute 0.6.14 at /opt/python3.3/lib/python3.3/site-packages/distribute-0.6.14-py3.3.egg-info
-  ...
+.. seealso::
 
-The above command will attempt to list all installed python packages including
-their version numbers and location.
 
-You can also limit the results by listing a specific distribution::
+      There are three metadata versions, 1.0, 1.1, and 1.2. The following PEPs
+      describes specifics of the field names, and their semantics and usage.
+      1.0 :PEP:`241`, 1.1 :PEP:`314`,  and 1.2 :PEP:`345`
 
-  $ pysetup list distribute
+
+Removing a distribution
+-----------------------
+
+You can remove one or more installed distributions using the pysetup `remove` action::
+
+   $ pysetup remove virtualenv
+   removing 'virtualenv':
+     /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/dependency_links.txt
+     /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/entry_points.txt
+     /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/not-zip-safe
+     /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/PKG-INFO
+     /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/SOURCES.txt
+     /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/top_level.txt
+   Proceed (y/n)? y
+   success: removed 6 files and 1 dirs
+
+The '-y' optional argument auto confirms, skipping the the conformation prompt.::
+
+  $ pysetup remove virtualenv -y
+
+