test_ok1/doc/install.txt

.. 
    ==============
    Downloading
    ==============

.. _`index page`: http://pypi.python.org/pypi/py/


py.test/pylib installation info in a nutshell
===================================================

**Pythons**: 2.4, 2.5, 2.6, 3.0, 3.1, Jython-2.5.1, PyPy-1.1

**Operating systems**: Linux, Windows, OSX, Unix 

**Requirements**: setuptools_ or Distribute_ 

**Installers**: easy_install_ and pip_

**Distribution names**:

* PyPI name: ``py`` (see `index page`_ for versions)
* redhat fedora: ``pylib``
* debian: ``python-codespeak-lib``
* gentoo: ``pylib``

**Installed scripts**: see `bin`_ for which scripts are installed. 

.. _`bin`: bin.html


Best practise: install tool and dependencies virtually
===========================================================

It is recommended to work with virtual environments 
(e.g. virtualenv_ or buildout_ based) and use easy_install_
(or pip_) for installing py.test/pylib and any dependencies 
you need to run your tests.  Local virtual Python environments 
(as opposed to system-wide "global" environments) make for a more 
reproducible and reliable test environment. 


.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
.. _`buildout`: http://www.buildout.org/
.. _pip: http://pypi.python.org/pypi/pip
.. _`easy_install`:

using easy_install (from setuptools or Distribute)
===================================================

Both `Distribute`_ and setuptools_ provide the ``easy_install``
installation tool.  While setuptools should work ok with 
Python2 interpreters, `Distribute`_ also works with Python3 
and it avoids some issues on Windows.  In both cases you
can open a command line window and then type::

    easy_install -U py 

to install the latest release of the py lib and py.test.  The ``-U`` switch
will trigger an upgrade if you already have an older version installed. 

If you now type::

    py.test --version

you should see the version number and the import location of the tool.
Maybe you want to head on with the `quickstart`_ now? 

.. _quickstart: test/quickstart.html

Troubleshooting
========================

**On Linux**: If ``easy_install`` fails because it needs to run
as the superuser you are trying to install things globally 
and need to put ``sudo`` in front of the command. 

**On Windows**: If "easy_install" or "py.test" are not found
please see here: `How do i run a Python program under Windows?`_

.. _`How do i run a Python program under Windows?`: http://www.python.org/doc/faq/windows/#how-do-i-run-a-python-program-under-windows  

.. _mercurial: http://mercurial.selenic.com/wiki/
.. _`Distribute`: 
.. _`Distribute for installation`: http://pypi.python.org/pypi/distribute#installation-instructions
.. _`distribute installation`: http://pypi.python.org/pypi/distribute
.. _checkout:
.. _tarball:

Working from version control or a tarball 
=================================================

To follow development or start experiments, checkout the 
complete code and documentation source with mercurial_::

    hg clone https://bitbucket.org/hpk42/py-trunk/

Development takes place on the 'trunk' branch.

You can also go to the python package index and
download and unpack a TAR file::

    http://pypi.python.org/pypi/py/


activating a checkout with setuptools 
--------------------------------------------

With a working `Distribute`_ or setuptools_ installation you can type::

    python setup.py develop 

in order to work inline with the tools and the lib of your checkout. 

.. _`no-setuptools`:

.. _`directly use a checkout`: 

directly use a checkout or tarball / avoid setuptools 
-------------------------------------------------------------

Get a checkout_ or tarball_ and add paths to your environment variables:

* ``PYTHONPATH`` needs to contain the root directory (where ``py`` resides)
* ``PATH`` needs to contain ``ROOT/bin`` or ``ROOT\bin\win32`` respectively. 

There also are helper scripts that set the variables accordingly.  On windows 
execute::

    # inside autoexec.bat or shell startup
    c:\\path\to\checkout\bin\env.cmd

on linux/OSX add this to your shell initialization:: 

    # inside e.g. .bashrc 
    eval `python ~/path/to/checkout/bin/env.py` 

both of which which will get you good settings.  If you install 
the pylib this way you can easily ``hg pull && hg up`` or download
a new tarball_ to follow the development tree.


Note that the scripts manually added like this will look for 
py libs in the chain of parent directories of the current working dir.  
For example, if you have a layout like this::

    mypkg/
        subpkg1/
            tests/
        tests/
    py/

issuing ``py.test subpkg1`` will use the py lib
from that projects root directory.   If in doubt over where
the pylib comes from you can always do::

    py.test --version

to see where py.test is imported from. 

.. _`command line scripts`: bin.html
.. _contact: contact.html

.. _`RPM`: http://translate.sourceforge.net/releases/testing/fedora/pylib-0.9.2-1.fc9.noarch.rpm

.. _`setuptools`: http://pypi.python.org/pypi/setuptools