======================================
INSTALL: pydabu -- Python data bubble
======================================

:Version: 2021-12-06
:Author: Daniel Mohr
:Email: daniel.mohr@dlr.de

.. contents::

.. footer::

   ###Page### / ###Total###


INSTALL: pydabu
+++++++++++++++


info
====


before you install
==================


Modules
-------

pydabu needs the following Python modules (most of them are standard and
already in your Python installation from a package management)

 * argparse
 * distutils

and the own modules which comes with this package. Most of the modules
are only necessary at runtime and only in some components.

You can also asked the installation routine/script for the Python modules::

  env python3 setup.py --help
  env python3 setup.py --requires

There is also a small extra command to check for availability of
necessary Python modules::

  env python3 setup.py check_modules

If you want to use this complete software you should have no modules
which are not available.

The following modules are optional:

  * cfchecker.cfchecks
  * netCDF4


unittests
---------

You can run a few unittests::

  env python3 setup.py run_unittest --src local

But the scripts are not tested before installing.
After installation you can run unittests on the scripts as well
(see :ref:`after you install.unittests`).

pytest
------

Instead of the standard module unittest you can also use pytest to run
all available unittests (including scripts)::

  env python3 setup.py run_pytest --src local

But the scripts are not tested before installing.
After installation you can run these tests on the scripts as well
(see :ref:`after you install.pytest`).


install by setup.py with distutils
==================================

global-install
--------------
To install this software global to / the following steps are to perform::

  tar xzf pydabu-*.tar.*
  cd pydabu-*/
  env python3 setup.py install

You can also store the installed files, e. g.::

  env python3 setup.py install --record installed_files.txt

Then you can uninstall with this information.


home-install
------------
To install this software to your $HOME the following steps are to perform::

  tar xzf pydabu-*.tar.*
  cd pydabu-*/
  env python3 setup.py install --home=~

You can also store the installed files, e. g.::

  env python3 setup.py install --home=~ --record installed_files.txt

Then you can uninstall with this information.


uninstall (distutils)
---------------------

If you have done the above installation and recorded the installed files,
you can just remove them to uninstall, e. g.::

  cat installed_files.txt | xargs rm -rf

In principle there is a problem with extraordinary file names, e. g. if
spaces are part of. This should not be the case here.


hints (distutils)
-----------------

Keep in mind to have the right paths.

  For the above installation to $HOME the software installs in::

    ~/bin
    ~/lib/python

  Please make sure to have these paths in $PATH and $PYTHONPATH, respectively.
  For example::

    export PATH=$PATH:~/bin
    export PYTHONPATH=~/lib/python


install with pip
================

You can also use the Python package manager system pip. This allows you to
handle dependencies, too.


install (pip)
-------------

You can use pip to install::

  pip3 install .

For older versions of pip you need to choose explicit a home install::

  pip3 install --user .


uninstall (pip)
---------------

You can use pip to uninstall::

  pip3 uninstall pydabu


hints (pip)
-----------

Keep in mind to have the right paths.

  For the above installation to $HOME the software installs in::

    ~/.local/bin
    ~/.local/lib/python*

  Please make sure to have these paths in $PATH and $PYTHONPATH, respectively.
  For example::

    export PATH=$PATH:~/.local/bin
    export PYTHONPATH=~/.local/lib/python3.6


after you install
=================

.. _after you install.unittests:

unittests (after installation)
------------------------------

Now you can run all available unittests (including scripts)::

  env python3 setup.py run_unittest

.. _after you install.pytest:

pytest (after installation)
---------------------------

Instead of the standard module unittest you can also use pytest to run
all available unittests (including scripts)::

  env python3 setup.py run_pytest

This command has a few interesting parameters, e. g.::

  env python3 setup.py run_pytest --parallel --coverage


hints
=====

Ubuntu 18.04
------------

You can find most necessary modules in the package management of Ubuntu 18.04, e. g. ::

    sudo apt install python3-jsonschema
    sudo apt install python3-netcdf4
    sudo apt install python3-sphinx python3-sphinx-argparse python3-recommonmark
    sudo apt install python3-pytest python3-pytest-cov python3-pytest-xdist

The command check_netcdf_file of :program:`pydabu` needs the package
cfchecker.cfchecks which is not in the package management.
You can install it with pip, e. g.::

    pip3 install cfchecker

To build the documentation you do not only need the above packages. In addition
we use sphinx-jsonschema, e. g.::

    pip3 install sphinx-jsonschema

SuSE 15.3
---------

The command check_netcdf_file of :program:`pydabu` needs the package
cfchecker.cfchecks which is not in the package management.
You can install it with pip, e. g.::

    pip3 install --user cfchecker

But you need udunits2 from the package managment from SuSE to use cfunits,
which is required by cfchecker.