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 
-------------------------------------------------------------

Once you got yourself a checkout_ or tarball_ it is usually a good 
idea to add the parent directory of the ``py`` package directory 
to your ``PYTHONPATH`` and ``py/bin`` or ``py\bin\win32`` to your 
system wide ``PATH`` settings.  There are helper scripts that 
set ``PYTHONPATH`` and ``PATH`` on your system: 

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 .bashrc 
    eval `python ~/path/to/checkout/bin/env.py` 

both of which which will get you good settings 
for ``PYTHONPATH`` and ``PATH``.

If you install ``py.test`` this way you can easily
``hg pull && hg up`` your checkout to follow the
development tree.

note: scripts look for "nearby" py-lib 
-----------------------------------------------------

Note that all `command line scripts`_ will look 
for "nearby" py libs, so 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.   Giving the
state of Python packaging there can be confusion
in which case issuing::

    py.test --version

tells you both version and import location of the tool.

.. _`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