---

    Linux & OS X
    ************

    Installing Python
    =================

    Python is pre-installed on OS X, but may need to be installed for your Linux system.
    For Linux, it is preferable to use your system's default package manager, such as
    ``yum`` or ``apt``.

    Alternatively, you could download the Python installer appropriate for your system from
    http://www.python.org/download/, and follow the given directions for installation.

    Download the OpenEye Python Toolkit
    ===================================

    You must download the tarball that matches the python version,
    operating system, and architecture of your target machine's
    configuration.

    Download from http://www.eyesopen.com/downloads.

    .. note::

       In order to follow the `PEP 440
       <http://www.python.org/dev/peps/pep-0440>`_ guidelines on version
       numbers you will notice the version number of the toolkit is
       altered from |pkgversion| to |pypkgversion|.


    Installation options for the OpenEye Python Toolkit
    ===================================================

    There are multiple ways to install the OpenEye Python Toolkit. From the 2013.Oct release we have adopted to conform
    with the Python standards for packaging, our previous installation method is still available.

    #. The recommended installation path is to use virtualenv and pip follow :ref:`Virtual Environment Installation <python-pip>`.
    #. Alternatively you can install with pip follow :ref:`Python Package Management Installation <python-global-pip>`.
    #. You can now install via ``setup.py`` see :ref:`Global Python Installation <python-setup>`.
    #. If you do not have root access or do not want to use pip you can continue to use PYTHONPATH see :ref:`PYTHONPATH Installation <python-pythonpath>`.
    #. For installation on a cluster with multiple Python versions follow :ref:`Heterogenous Linux Cluster Installation <python-cluster>`.

    .. _python-pip:

    Virtual Environment Installation
    --------------------------------

    .. tip::

       It is considered harmful to install packages into your global
       python installation, known as ``site-packages``. The recommended
       way to install any Python packages is using virtual environments.

    `virtualenv
    <http://www.virtualenv.org/en/latest/>`_ creates safe, isolated python
    environments in user space, also alleviating the need for root-access
    to install python packages. `virtualenvwrapper
    <http://virtualenvwrapper.readthedocs.org/en/latest/>`_ offers a shell
    environment making it easier to work with virtual environments. 

    Assuming you have virtualenv and virtulenvwrapper installed the
    following example will create a new virtualenv called ``oepython`` and
    install the OpenEye Python Toolkits into it.

    .. parsed-literal::

       $ mkvirtualenv oepython
       (oepython) $ pip install OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|.tar.gz
       ...
       (oepython) $ which oecheminfo.py
       ~/.virtualenvs/oepython/bin/oecheminfo.py
       (oepython) $ deactivate
       $

    .. warning::

       ``PYTHONPATH`` will still override the modules installed into a
       virtual environment. Make sure ``PYTHONPATH`` is not set when using
       a virtual environment.

    .. _python-global-pip:

    Python Package Management Installation
    --------------------------------------

    The recommended tool for managing Python packages is `PIP
    <http://www.pip-installer.org/>`_. The OpenEye Python Toolkit
    distribution is compatible with pip, the following is equivalent to
    doing what is described in the above section:

    .. parsed-literal::

       $ sudo pip install OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|.tar.gz

    Using PIP for managing your Python packages also allows for packages
    to be easily uninstalled as well. Uninstalling the package installed
    above would be the following command:

    .. parsed-literal::

       $ sudo pip uninstall OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|

    .. _python-setup:

    Global Python Installation
    --------------------------

    The Python toolkits are provided as a traditional Python distribution
    with a ``setup.py`` file to install the distribution into the
    ``site-packages`` folder for your Python interpreter. After unpacking
    the tarball and changing into the resulting directory, do the
    following the install the distribution::

      $ sudo python setup.py install

    You can verify that the install worked correctly by starting a python
    prompt and doing the following:

    .. parsed-literal::

       $ python
       Python 2.7.3 (default, Aug  1 2012, 05:14:39) 
       [GCC 4.6.3] on linux2
       Type "help", "copyright", "credits" or "license" for more information.
       >>> from openeye.oechem import OEChemGetRelease
       >>> OEChemGetRelease()
       '|oechemversion|'
       >>> exit()


    The Python toolkit distribution will install all the example programs
    into a ``bin`` directory in your ``PATH``. This allows you to run the
    ``oecheminfo.py`` example to also verify that your distribution is
    working correctly:

    .. parsed-literal::

       $ oecheminfo.py 
       Installed OEChem version: |oechemversion| platform: ubuntu-14.04-g++4.8-x64 built: |builddate|
       ...

    .. _python-pythonpath:

    PYTHONPATH Installation
    -----------------------

    If using any of the above techniques are unavailable, the
    OpenEye Python Toolkits can also be used by pointing the python
    interpreter at the appropriate directory. Untarring the downloaded
    distribution tarball will yield a directory structure like the
    following:

    .. parsed-literal::

       OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|/
          openeye/
             libs/
                python2.7-ubuntu-14.04-x64/
             docexamples/
             examples/

    The Python interpreter just needs to know where the ``openeye``
    directory is, for example, by setting the ``PYTHONPATH`` environment
    variable in your shell startup script ``~/.bashrc``. The syntax and
    location may vary if you use a shell other than ``bash``. For example,
    if you untarred the distribution into ``/usr/local``, the ``bash``
    syntax would be the following:

    .. parsed-literal::

       PYTHONPATH=/usr/local/OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|
       export PYTHONPATH

    The equivalent could be done in  Python code as well like the following:

    .. parsed-literal::

       import sys
       sys.path.append("/usr/local/OpenEye-toolkits-python2.7-ubuntu-14.04-x64-|pypkgversion|")

    If you un-tarred in a different parent directory, you
    would use that actual location rather than ``/usr/local``.

    All the toolkit examples can then be found in the ``examples`` directory.
    From the ``examples`` directory on the command line,
    the examples can be run using a command such as
    ``python oechem/oecheminfo.py``.

    .. _python-cluster:

    Heterogenous Linux Cluster Installation
    ---------------------------------------

    On Linux you can untar multiple versions of the toolkit into the same
    directory, for example RHEL6 Python 2.6 and RHEL7 Python 2.7. When the
    module is imported the correct version will be selected automatically
    by the openeye runtime. ``PYTHONPATH`` need only be set to point at
    the top-level ``openeye`` directory. For example, installing both the
    RHEL6 and RHEL7 versions into the same NFS directory named
    ``/nfsdir/oepython`` could be accomplished by doing the following:

    .. parsed-literal::

       $ mkdir /nfsdir/oepython-|pkgversion|
       $ cd /nfsdir/oepython-|pkgversion|
       $ tar --strip-components 1 -vzxf /path/to/OpenEye-toolkits-python2.6-redhat-6-x64-|pypkgversion|.tar.gz OpenEye-toolkits-python2.6-redhat-6-x64-|pypkgversion|/openeye/
       $ tar --strip-components 1 -vzxf /path/to/OpenEye-toolkits-python2.7-redhat-7-x64-|pypkgversion|.tar.gz OpenEye-toolkits-python2.7-redhat-7-x64-|pypkgversion|/openeye/
       $ export PYTHONPATH=/nfsdir/oepython-|pkgversion|

    Using the above tar commands also strips out the extraneous files like
    ``setup.py`` and ``MANIFEST.in``. These files are only required by
    python packaging systems and are not needed when explicitly setting
    ``PYTHONPATH``.


    Integration Testing
    ===================

    The OpenEye Python toolkits ship with a simple set of integration
    tests to make sure all the libraries are functioning as intended. The
    test suite is not as exhaustive as the test suite used internally, it
    is just meant to ensure the OpenEye Python toolkit infrastructure is
    working as intended. To run the integration test suite, run the
    following with the same python interpreter the toolkit were installed into::

       $ python -m openeye.examples.openeye_tests

    A message like the following will be shown if all the tests were run
    successfully::

       test_bfactor2img (tests.test_grapheme.TestGrapheme) ... ok
       test_fp2oeb (tests.test_graphsim.TestGraphSim) ... ok
       ...
       test_example1 (tests.test_szybki.TestSzybki) ... ok
       test_zap_forces (tests.test_zap.TestZap) ... ok

       ----------------------------------------------------------------------
       Ran 33 tests in 34.004s

       OK