.. _section_python_anaconda:

================================
Anaconda with Conda Installation
================================

.. A couple of points about the above label and heading:
    1.  The DEFAULT link text for refs like ":ref:`section_python_anaconda` is "Anaconda with Conda Installation"
        However, I DO NOT recommend links that use defaults like that.  What if someone later puts a typo or something
        stupid in the title?  Then your link text will have the typo or stupidity.
        So, decide what link text you want, and put it in there.  See the :ref: call later in this document.

..  2.  The label name section_python_anaconda seems sufficiently unambiguous.
        It also starts with the word "section," which is good, because that may make it easier
        to find in some situations, like use of the msphinx tool.  I checked the log and was not warned of a duplicate
        although there were other label-related warnings in the build that I then went off to fix.

..  Not relevant to labels BUT:
    1. Every Sphinx document should/must start with a "title," which is nothing
    more or less than the first heading that appears in the file.  Here, the title is "Anaconda with Conda Installation."
    That title will be the entry in the HTML navigation, for example, in the left-hand nav bar or other
    displays of the navigation.
    2. Sphinx and RST do not have a hierarchy of labels like H1, H2, and so on.  Instead, the Sphinx builder
    for HTML or PDF or whatever figures out and assigns positions in the hierarchy, starting with this first one.
    3. The Sphinx builder uses the overlining/underlining characters in the titles to decide what is what
    in the hierarchy, so be consistent, within a file, the way you use them.
    4. There is a HIGHLY RECOMMENDED convention used by the Python documentation for new material written
    in Sphinx/RST: https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html#headings





The Anaconda package can be downloaded from
`the Anaconda Distribution page <https://www.anaconda.com/download>`_ for Windows, macOS and Linux
platforms. Follow the very simple instructions given there for
installation.
For first time users we also recommend reading
`Getting started with conda <https://docs.anaconda.com/anaconda/user-guide/getting-started/index.html>`_ and print out the
`Conda user cheat sheet <http://know.continuum.io/rs/387-XNW-688/images/conda-cheatsheet.pdf>`_
reference.

..  Notice that it is easy to put http links in a Sphinx document.  The first example here will just put
    it in using the URL as the link text.  The next two examples substitute the author's preferred
    link text.   You need to put in a bit of extra time and test http links.

..  Oops!  That first cross-ref to the Getting Started document for conda was broken.  Such is life
    with other peoples' documentation that is not (or probably not) built with Sphinx.  So I had to text
    and fix the URL.  I picked one that is 1) relevant and 2) an official Conda document.  Maybe the original
    author wanted some different document....

.. note::

   We recommend the installation of PYTHON 3 Anaconda packages.
   This version will default to Python 3 when creating new
   environments and building packages.

..  note::

   While Anaconda is available free of charge for personal use, users may need to purchase an Anaconda license if
   they are doing commercial development.
   Please check the `Anaconda license terms <https://www.anaconda.com/anaconda-commercial-edition>`_.

.. hint::

   We recommend using the Anaconda package, which is a complete suite
   containing hundreds of open source Python packages.
   If disk-space is limited, we recommend the mini version of Anaconda,
   namely, *Miniconda*. *Miniconda* includes conda, its dependencies and
   Python.

   The *Miniconda* package can be downloaded from
   `Anaconda's Miniconda page <http://conda.pydata.org/miniconda.html>`_ for Windows, macOS and Linux
   platforms.

..  There used to be a second link to a miniconda install page, but it was broken. The new first link
    has installation instructions right there.  So for the time being, we don't need more than that one.

..  You may be way ahead of me, but:  a best practice would be to limit external HTTP links to specific places
    and cross-reference those with intersphinx.  Then we have to test and fix broken links in only one place.

   All the instructions for installing the OpenEye Python Toolkit
   are identical whether using the  Anaconda or *Miniconda* packages.

After downloading and installing Anaconda, the OpenEye Python
Toolkit package can be installed by the following steps:

#. First create a new conda environment::

      $ conda create -n oepython python=3

      Collecting package metadata (current_repodata.json): done
      Solving environment: done

      ## Package Plan ##

        environment location: /anaconda3/envs/oepython

        added / updated specs:
          - python=3


      The following packages will be downloaded:

          package                    |            build
          ---------------------------|-----------------
          libffi-3.2.1               |       h0a44026_6          43 KB
          ncurses-6.2                |       h0a44026_1         749 KB
          ------------------------------------------------------------
                                                 Total:         792 KB

      The following NEW packages will be INSTALLED:

        ca-certificates    pkgs/main/osx-64::ca-certificates-2020.1.1-0
        certifi            pkgs/main/osx-64::certifi-2020.4.5.1-py38_0
        libcxx             pkgs/main/osx-64::libcxx-4.0.1-hcfea43d_1
        libcxxabi          pkgs/main/osx-64::libcxxabi-4.0.1-hcfea43d_1
        libedit            pkgs/main/osx-64::libedit-3.1.20181209-hb402a30_0
        libffi             pkgs/main/osx-64::libffi-3.2.1-h0a44026_6
        ncurses            pkgs/main/osx-64::ncurses-6.2-h0a44026_1
        openssl            pkgs/main/osx-64::openssl-1.1.1g-h1de35cc_0
        pip                pkgs/main/osx-64::pip-20.0.2-py38_1
        python             pkgs/main/osx-64::python-3.8.2-hc70fcce_0
        readline           pkgs/main/osx-64::readline-8.0-h1de35cc_0
        setuptools         pkgs/main/osx-64::setuptools-46.1.3-py38_0
        sqlite             pkgs/main/osx-64::sqlite-3.31.1-h5c1f38d_1
        tk                 pkgs/main/osx-64::tk-8.6.8-ha441bb4_0
        wheel              pkgs/main/osx-64::wheel-0.34.2-py38_0
        xz                 pkgs/main/osx-64::xz-5.2.5-h1de35cc_0
        zlib               pkgs/main/osx-64::zlib-1.2.11-h1de35cc_3


      Proceed ([y]/n)?


   After entering "y" to proceed, a new 'oepython' environment
   will be created with Python 3.8.

#. Activate the newly created 'oepython' environment::

      $ source activate oepython
      (oepython) $

   .. warning::

      It is very important to activate a work environment before performing
      any additional installations, otherwise packages will be installed
      into the global Python environment.

#. Install the OpenEye Python Toolkits into the new environment::


      (oepython) $ conda install -c openeye openeye-toolkits
      Solving environment: done
      ...

      The following NEW packages will be INSTALLED:

      attrs:            17.3.0-py35h20e33bf_0
      ca-certificates:  2017.08.26-h1d4fec5_0
      coverage:         4.4.2-py35h8fc71f1_0
      hypothesis:       3.38.5-py35h785bf34_0
      libgcc-ng:        7.2.0-h7cc24e2_2
      openeye-toolkits: 2018.2b2-py35_0       openeye
      pluggy:           0.6.0-py35hb428803_0
      py:               1.5.2-py35hfe8c5ce_0
      pympler:          0.5-py35hc09b5c8_0
      pytest:           3.3.2-py35_0
      six:              1.11.0-py35h423b573_1
      zope:             1.0-py35_0
      zope.interface:   4.4.3-py35h9cef842_0

      Proceed ([y]/n)? y

      ...

#. Run the OpenEye example `oecheminfo.py` to verify the installation
   has completed successfully::


      (oepython) $ oecheminfo.py
      Installed OEChem version: |oechemversion| platform: linux-g++4.x-x64 built: |builddate|
      ...

.. warning::

   Setting the environment variable ``PYTHONPATH`` will override the path
   to the Python modules installed in a conda environment.
   Make sure ``PYTHONPATH`` is **not** set when using a virtual environment.

.. seealso::

  See :ref:`Integration Testing <section_python_test_linux>` for post-installation testing of the
  OpenEye Python Toolkits.

..  I fixed the old markup, to put in explicit link text for the section labeled by "section_python_test."

