.. _installation: 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: 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 `` or ``distil -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 ~~~~~~~~~~~~~~~~ .. index:: single: Python; selecting version to run with 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: single: Virtual environment; specifying one to run in 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. .. _local-dists: 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 .. _troubleshooting: When things don't go as planned ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. index:: single: Troubleshooting 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.