test_ok1/doc/install.txt

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

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

**Pythons**: 2.4, 2.5, 2.6, 2.7, 3.0, 3.1.x, Jython-2.5.1, PyPy-1.2

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

**Requirements**: setuptools_ or Distribute_

**Installers**: easy_install_ and pip_ or `standalone`_ (new for 1.2)

**Distribution names**:

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

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

**hg repository**: https://bitbucket.org/hpk42/py-trunk

.. _`bin`: bin.html


.. _`easy_install`:

Installation using easy_install
===================================================

Both `Distribute`_ and setuptools_ provide the ``easy_install``
installation tool with which you can type into a command line window::

    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.
Note that setuptools works ok with Python2 interpreters while `Distribute`_
additionally works with Python3 and also avoid some issues on Windows.

Known issues:

- **Windows**: If "easy_install" or "py.test" are not found
  please see here for preparing your environment for running
  command line tools: `Python for Windows`_.  You may alternatively
  use an `ActivePython install`_ which makes command line tools
  automatically available under Windows.

.. _`ActivePython install`: http://www.activestate.com/activepython/downloads

.. _`Jython does not create command line launchers`: http://bugs.jython.org/issue1491

- **Jython2.5.1 on Windows XP**: `Jython does not create command line launchers`_
  so ``py.test`` will not work correctly.  You may install py.test on
  CPython and type ``py.test --genscript=mytest`` and then use
  ``jython mytest`` to run py.test for your tests to run in Jython.

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


.. _quickstart: test/quickstart.html


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

.. _standalone:

Generating a py.test standalone Script
============================================

If you are a maintainer or application developer and want users
to run tests you can use a facility to generate a standalone
"py.test" script that you can tell users to run::

    py.test --genscript=mytest

will generate a ``mytest`` script that is, in fact, a ``py.test`` under
disguise.  You can tell people to download and then e.g. run it like this::

    python mytest --pastebin=all

and ask them to send you the resulting URL.  The resulting script has
all core features and runs unchanged under Python2 and Python3 interpreters.

.. _`Python for Windows`: http://www.imladris.com/Scripts/PythonForWindows.html

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