Installation

To install distil, just download this file and copy it to a location on your path. Optionally on POSIX platforms, you can rename it to distil. Make sure its executable bit is set.

On Windows, if you have the Python Launcher installed (included in Python 3.3, or available as a standalone installer here), you should be able to invoke it by just typing distil on the command-line.

Usage overview

All command options are available by invoking distil with the -h parameter:

$ distil -h
usage: distil [-h] [-n] [-q] [-v] [--version] [-e VENVDIR] [-p INTERPRETER]
              [--local-dists DIRPATH]

              {download,graph,help,init,install,link,list,metadata,package,pip,register,remove,uninstall,test,upload}
              ...

Perform operations on Python distributions.

positional arguments:
  {download,graph,help,init,install,link,list,metadata,package,pip,register,remove,uninstall,test,upload}
                        The available commands
    download            Download a distribution
    graph               Show dependency graph for a distribution
    help                Provide help on a command
    init                Create initial metadata for a project
    install             Install distributions
    link                Link to local projects
    list                List one or all installed distributions
    metadata            Show metadata for a package
    package             Create source distributions or wheels
    pip                 Build wheels using pip
    register            Register a project on PyPI
    remove (uninstall)  Remove (uninstall) one or more distributions
    test                Test a distribution
    upload              Upload a release or documentation to PyPI

optional arguments:
  -h, --help            show this help message and exit
  -n, --dry-run         don't actually do anything
  -q, --quiet           run quietly (turn verbosity down)
  -v                    run verbosely (turn verbosity up)
  --version             show program's version number and exit
  -e VENVDIR            Run in the specified virtual environment
  -p INTERPRETER        Run with the specified Python interpreter
  --local-dists DIRPATH
                        Specify path to local wheels and sdists

You can get help on individual commands by invoking distil help <command> or distil <command> -h. Each command is covered in its own section below.

To check the version of distil you have, invoke distil --version:

$ distil --version
Distil Version 0.1.0 (distlib-0.1.1) Copyright (C) 2012-2013 Vinay Sajip.
vcs id: ecbf5a:c5ceac
Python: 2.7

There is NO WARRANTY. This is preliminary software, best used in virtual
environments.

Note that abbreviations can be used for commands, as long as they are unambiguous. For example, distil down is equivalent to distil download.

Pick your Python

By default, distil runs using your system Python. You can choose to run with a specific interpreter by invoking distil with -p, as in the following example:

$ distil -p python3.2 --version
Distil Version 0.1.0 (distlib-0.1.1) Copyright (C) 2012-2013 Vinay Sajip.
vcs id: ecbf5a:c5ceac
Python: 3.2

There is NO WARRANTY. This is preliminary software, best used in virtual
environments.

Run in a virtual environment

You can also choose to run using the Python interpreter in a virtual environment (venv) by invoking with the -e parameter and specifying the root of the venv:

$ pyvenv-3.4 /tmp/venv
$ distil -e /tmp/venv --version
Distil Version 0.1.0 (distlib-0.1.1) Copyright (C) 2012-2013 Vinay Sajip.
vcs id: ecbf5a:c5ceac
Python: 3.4

There is NO WARRANTY. This is preliminary software, best used in virtual
environments.

Getting started (POSIX)

When experimenting with distil, you may want to set up some virtual environments (venvs). This is how I set mine up:

mkdir -p $HOME/projects/scratch
cd $HOME/projects/scratch
virtualenv e2
virtualenv -p python3.2 e3
pyvenv-3.3 e33
cp -r e2 e2.backup
cp -r e3 e3.backup
cp -r e33 e33.backup

This sequence sets up e2 and e3 as virtualenv venvs, with setuptools / distribute and pip, and e33 as a new-style PEP 405 venv with no setuptools, distribute or pip. It also makes backup copies of the newly-created environments, allowing them to be easily reset to this initial state.

If you don’t already have virtualenv, you should install it using your distro’s package manager. If it’s an old version, you may need to specify --no-site-packages in the virtualenv command to ensure that the venv is isolated from your system Python’s libraries.

I also found it useful to define some shell functionality:

PROJECT=$HOME/projects/scratch

function use() { source $PROJECT/$1/bin/activate; }
function reuse() {
  echo $1.backup "->" $1 && rm -rf $PROJECT/$1 && cp -R $PROJECT/$1.backup $PROJECT/$1;
}
complete -C `which distil` distil

If the above is saved as e.g. use-distil, then you can just invoke source use-distil to take advantage of its functionality. This sets up tab-completion (only available on Bash-compatible shells) and allows you to activate one of the test venvs or to reset it to its initial state.

You should replace $HOME/projects/scratch in the above with whichever directory you want to use.

Getting started (Windows)

The steps for getting started on Windows are analogous to those on POSIX. If you don’t have virtualenv, follow the instructions on its PyPI page to see how to get it. Once you have it, use commands like this:

cd c:\Projects\scratch
virtualenv e2
virtualenv -p \Python32\python.exe e3
xcopy /s /i e2 e2.backup
xcopy /s /i e3 e3.backup

You can use the following scripts for use and reuse functionality:

@echo off
rem Put this in use.cmd somewhere in your path
c:\Projects\scratch\%1\Scripts\activate

and:

#!/usr/bin/env python
# Put this in reuse.py somewhere in your path
import os
import shutil
import sys

def main():
    if len(sys.argv) < 2:
        print('usage: reuse venvdir')
    else:
        rootdir = r'c:\Projects\scratch'
        source = os.path.join(rootdir, sys.argv[1] + '.backup')
        target = os.path.join(rootdir, sys.argv[1])
        if not os.path.isdir(source) or not os.path.isdir(target):
            print('Bad env: %s' % sys.argv[1])
        else:
            print('%s -> %s' % (source, target))
            shutil.rmtree(target)
            shutil.copytree(source, target)

if __name__ == '__main__':
    sys.exit(main())

You should replace c:\Projects\scratch in the above with whichever directory you want to use.

Specifying local directories for locating distributions

You can specify local directories where sdists and wheels are located via the --local-dists argument to distil, or through the DISTIL_LOCAL_DISTS environment variable. This should be a list of one or more directories where sdists and wheels may be found. If there is more than one directory, use the platform path separator (os.pathsep) to separate them, as in the following examples – for POSIX:

/home/me/distil/wheels
/home/me/distil/wheels:/home/me/distil/sdists

and for Windows:

C:\Users\Me\distil\wheels
C:\Users\Me\distil\wheels;C:\Users\Me\distil\sdists

When things don’t go as planned

When distil runs commands, it creates a log file called distil.log in your home directory. (If you use tab-completion, it will also create a file called distil-completion.log in your home directory.) If you encounter a situation where distil doesn’t behave as expected, and you’d like to provide feedback about this, please raise an issue, and attach these files if you think they might help or it’s not obvious what the problem is.