2. Pysetup Tutorial

2.1. Getting started

Pysetup is a simple script that supports the following features:

• install, remove, list, and verify Python packages;
• search for available packages on PyPI or any Simple Index;
• verify installed packages (md5sum, installed files, version).

2.2. Finding out what’s installed

Pysetup makes it easy to find out what Python packages are installed:

$ pysetup list virtualenv
'virtualenv' 1.6 at '/opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info'

$ pysetup list
'pyverify' 0.8.1 at '/opt/python3.3/lib/python3.3/site-packages/pyverify-0.8.1.dist-info'
'virtualenv' 1.6 at '/opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info'
...

2.3. Installing a distribution

Pysetup can install a Python project from the following sources:

• PyPI and Simple Indexes;
• source directories containing a valid setup.py or setup.cfg;
• distribution source archives (project-1.0.tar.gz, 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

Installing from a distribution source archive:

$ pysetup install project-1.0.tar.gz

Installing from a source directory containing a valid setup.py or setup.cfg:

$ cd path/to/source/directory
$ pysetup install

$ pysetup install path/to/source/directory

Installing from HTTP:

$ pysetup install http://host/packages/project-1.0.tar.gz

2.4. Retrieving metadata

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 metadata virtualenv -f version -f name
Version:
    1.6
Name:
    virtualenv

$ pysetup metadata virtualenv
Metadata-Version:
    1.0
Name:
    virtualenv
Version:
    1.6
Platform:
    UNKNOWN
Summary:
    Virtual Python Environment builder
...

See also

There are three metadata versions, 1.0, 1.1, and 1.2. The following PEPs describe specifics of the field names, and their semantics and usage. 1.0 PEP 241, 1.1 PEP 314, and 1.2 PEP 345

2.5. Removing a distribution

You can remove one or more installed distributions using the pysetup remove command:

$ 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 optional ‘-y’ argument auto confirms, skipping the conformation prompt:

$ pysetup remove virtualenv -y

2.6. Getting help

All pysetup actions take the -h and –help options which prints the commands help string to stdout.

$ pysetup remove -h
Usage: pysetup remove dist [-y]
   or: pysetup remove --help

Uninstall a Python package.

positional arguments:
   dist  installed distribution name

optional arguments:
   -y  auto confirm package removal

Getting a list of all pysetup actions and global options:

$ pysetup --help
Usage: pysetup [options] action [action_options]

Actions:
    run: Run one or several commands
    metadata: Display the metadata of a project
    install: Install a project
    remove: Remove a project
    search: Search for a project in the indexes
    list: List installed projects
    graph: Display a graph
    create: Create a project
    generate-setup: Generate a backward-compatible setup.py

To get more help on an action, use:

    pysetup action --help

Global options:
    --verbose (-v)  run verbosely (default)
    --quiet (-q)    run quietly (turns verbosity off)
    --dry-run (-n)  don't actually do anything
    --help (-h)     show detailed help message
    --no-user-cfg   ignore pydistutils.cfg in your home directory
    --version       Display the version