.. _getting_started:
.. _installing:

============
Installation
============

Installing with pip
-------------------

Taurus can be installed using pip. The following command will automatically
download and install the latest release of Taurus (see ``pip --help`` for
options)::

    pip install taurus

You can test the installation by running::

    python -c "import taurus; print(taurus.Release.version)"

Some optional Taurus features have additional dependencies_.


Linux (Debian-based)
--------------------

Taurus is available in the official Debian repositories. Install the Python 3
package with::

    apt install python3-taurus

For plotting support, Debian also provides::

    apt install python3-taurus-pyqtgraph

The exact Taurus version depends on the Debian release. If you need a newer
version, consider using a conda environment or pip instead.


Installing in a conda environment
---------------------------------

In a conda environment (we recommend creating one specifically for Taurus)::

    conda install -c conda-forge taurus taurus_pyqtgraph

Optionally, you may also want to install Tango::

    conda install -c conda-forge pytango

.. warning::

   There is a known issue with PyQt5 versions >= 5.15.4 where Taurus Designer is
   not showing Taurus widgets. See :ref:`Designer known issues<designer_pyqt515_issue>`
   for possible workarounds.


With Pixi
---------

`Pixi <https://pixi.sh/>`_ can be used to create a development environment
directly from the Taurus repository.

After installing Pixi, clone the Taurus repository and run:

.. code-block:: console

```
$ pixi install
```

The default environment includes Taurus with Tango and PyQt5 support.

Additional environments are available for other model schemes, Qt bindings,
and compatibility configurations. For example:

.. code-block:: console

```
$ pixi run -e epics test
$ pixi run -e tango-pyqt6 test
$ pixi run -e tango-pyside6 test
$ pixi run -e tango95 test
```

The selected environment can also be used to run Taurus commands directly.
For example, to open a Taurus form using the Tango model scheme and the
PySide6 binding:

.. code-block:: console

```
$ pixi run -e tango-pyside6 taurus form sys/tg_test/1/double_scalar
```

The documentation and code checks can be run with:

.. code-block:: console

```
$ pixi run doc
$ pixi run precommit
```

See the `pixi.toml` file in the repository root for the complete list of
available environments and their definitions.


Working from Git source directly (in develop mode)
--------------------------------------------------

If you intend to do changes to Taurus itself, or want to try the latest
developments, it is convenient to work directly from the git source in
"develop" (aka "editable") mode, so that you do not need to re-install on each
change::

    # optional: if using a conda environment, pre-install dependencies:
    # e.g, for basic dependencies:
    conda install -c conda-forge python=3 click numpy pint pyqt ply lxml plotpy pyqtgraph
    # ... and some extra dependencies (pick the ones you need)
    conda install -c conda-forge pytango pyepics spyder pymca
    # ... and if you want to run the test suite:
    conda install -c conda-forge pytest pytest-qt pytest-xvfb pytest-forked pytest-xdist flaky
    # ... and for auto-checking code style for contributing:
    conda install -c conda-forge pre-commit
    # ... and for building the docs:
    conda install -c conda-forge sphinx sphinx_rtd_theme graphviz

    # install taurus in develop mode
    git clone https://gitlab.com/taurus-org/taurus.git
    pip install -e ./taurus  # <-- Note the -e !!

    # install taurus_pyqtgraph in develop mode
    git clone https://gitlab.com/taurus-org/taurus_pyqtgraph.git
    pip install -e ./taurus_pyqtgraph  # <-- Note the -e !!


.. _dependencies:

Dependencies
------------

Strictly speaking, Taurus only depends on numpy_, click_, and pint_, but that
will leave out most of the features normally expected of Taurus (which are
considered "extras"). For example:

- Interacting with a Tango controls system requires PyTango_.
- Interacting with an Epics controls system requires pyepics_.
- Using the Taurus Qt_ widgets requires a supported Qt Python binding. Taurus
  is primarily developed and tested with PyQt_.
- The image widgets require the plotpy_ library.
- The JDraw synoptics widgets require the PLY_ package.
- The NeXus browser widget requires PyMca5_.
- The TaurusEditor widget requires spyder_.
- The TaurusGui module requires lxml_.

For a complete list of "extra" features and their corresponding requirements,
execute the following command::

    taurus check-deps

How you install the required dependencies depends on your preferred
installation method:

- On GNU/Linux, dependencies can be installed from the distribution
  repositories when available, or in an isolated Conda_ environment.
- On Windows, using a Conda_ environment is recommended.

Optional dependencies can be installed using pip extras:

================ ======================================================
Extra            Description
================ ======================================================
``qt``           Common dependencies for Taurus Qt functionality
``pyqt5``        Qt dependencies with the PyQt5 binding
``pyqt6``        Qt dependencies with the PyQt6 binding
``pyside6``      Qt dependencies with the PySide6 binding
``tango``        Tango model support
``epics``        EPICS model support
``h5file``       HDF5 file support
``qt-editor``    TaurusEditor widget support (spyder_) [deprecated]
================ ======================================================

For example::

    pip install "taurus[pyqt6,tango]"


The former ``taurus-*`` extra names are kept temporarily for backward
compatibility.


.. _numpy: https://numpy.org/
.. _pint: https://pint.readthedocs.io/
.. _PLY: https://www.dabeaz.com/ply/
.. _Tango: https://www.tango-controls.org/
.. _PyTango: https://tango-controls.readthedocs.io/projects/pytango/en/latest/
.. _Qt: https://www.qt.io/
.. _PyQt: https://www.riverbankcomputing.com/software/pyqt/
.. _PySide: https://doc.qt.io/qtforpython-6/
.. _taurus_pyqtgraph: https://gitlab.com/taurus-org/taurus_pyqtgraph
.. _plotpy: https://plotpy.readthedocs.io/en/latest/
.. _PyMca5: https://www.silx.org/doc/PyMca/latest/
.. _pyepics: https://pyepics.github.io/pyepics/
.. _spyder: https://docs.spyder-ide.org/
.. _lxml: https://lxml.de/
.. _Conda: https://docs.conda.io/
.. _click: https://click.palletsprojects.com/