Getting Started¶

System Requirements¶

Dripline-python is developed specifically for container-based workflows, including development and deployment, and that is the only approach we encourage or fully support.

Dripline-python has also been used directly on host systems including MacOS and Debian/Ubuntu Linux. It has not been tested on Windows systems.

We have not attempted to fully track compatible versions of all dependencies, or minimal versions. We do, however, know the following:

Dripline-python requires Python >= 3.6 because it leverages the f-string feature
When not explicitly pinned in the setup.py file or Dockerfile, the “current” versions are installed from PyPI when developing and testing
Tagged container images are believed to work, you should be able to run any of them and use pip freeze to check the full set of versions from the time of any available tag.

If you are using Dripline in a Docker container, please go directly to Docker containers.

Non-Python Dependencies¶

Dripline-python is wraps and extends the C++ package dripline-cpp. To install dripline-cpp, please consult its installation instructions (use the “standalone” option). We recommend you set the CMake variable PBUILDER_PY_INSTALL_IN_SITELIB to TRUE so that the scarab python package is installed in the Python site-packages directory. If you install dripline-cpp in a non-system installation location (e.g. with the default install prefix, which is inside the build directory), you will need to know the location of the installed CMake config files for the dripline-python build below (usually [prefix]/lib/cmake/Dripline). As an alternative, you could make a system-wide install at /usr/local.

Dripline-cpp currently requires (all versions are minima): C++17 (via gcc or clang), CMake v3.12, Boost 1.46, rapidjson 1.0, yaml-cpp, rabbitmq-c, and quill. Everything should be available from standard package managers, except Quill, which is not in apt (for Ubuntu/Debian).

The Python wrapping of C++ code is done with Pybind11. Version 2.6.0 or higher is required, and it must be on the smart_holder branch. The smart_holder branch closely tracks the master branch but includes the critical smart_holder feature. See the smart_holder docs for more info.

You will need CMake to build the C++ wrappers. Version 3.12 or higher is required. It can be installed from most package managers or by following their instructions. Note that this is not included as a dependency in the Python installation process. See pyproject.toml for more details.

Python Libraries¶

If working with containers, the dependencies should all be installed (generally from PyPI). If installing on a host machine, you will need to be careful about the potential for conflicting dependency versions (which, ideally, should be done in a virtual environment).

Required¶

The following dependencies are required for core functionality and thus non-optional.

PyYAML is used to read yaml formatted configuration files.

asteval is used to process python statements presented as strings (sometimes provided as strings in start-up configurations or as part of calibration definitions).

Building Docs [doc]¶

Sphinx is required to compile this documentation.

Color Output¶

Colorlog is completely aesthetic. The logging module is used throughout dripline and this allows for colorized format of log messages.

Helpful Python Packages¶

The following packages are not actually dependencies for any aspect of dripline. They are, however, highly recommended (especially for anyone relatively new to python).

ipython and ipdb are both highly recomended for all non-production workflows. The expanded tab completion, command and output history, and doc access make it a powerful python interpretor for developing or manually interacting with dripline components.

Installation¶

We highly recommend using dripline-python in a Docker container. However, there is nothing to prevent installing and running directly on your host system. For using Docker containers, see the next section. For installing on a host machine, skip to Direct installation.

Docker containers¶

If you’re new to containers, consider starting with the getting started docs from Docker Inc.; most contributors develop using the OS-native “desktop application” available there.

The easiest way to get started with dripline is simply to use a container image from the dockerhub repository. These are built automatically based on tagged releases, as well as merges into the main or develop branch. Images are automatically built for both x86 and armv7 architectures, and a container manifest allows use of common tag references to resolve to the architectures-specific images.

You may also use the Dockerfile located in the dripline-python GitHub repository’s root directory to build the image yourself (the full repository is the required build context). Note that the Dockerfile provides arguments for specifing the base image details, the defaults there will hopefully be kept current, but the automatic build configurations actively pass overrides based on the GitHub Actions publish.yaml file (.github/workflows/publish.yaml).

Direct installation¶

We highly recommend using a virtual environment for this installation (e.g. virtualenv or conda).

First, clone the dripline-python repository:

> git clone git@github.com:driplineorg/dripline-python

or download a zip file of the source from GitHub and unpack it.

From the top directory of dripline-python, build with pip. You have a few options for what that command looks like:

If dripline-cpp was installed in a system location (e.g. /usr/local), that will look like:

> pip install .

If you want to install so that you can edit the dripline-python code, use the -e option:

> pip install -e .

If you need to specify the location of dripline-cpp, set the Dripline_DIR environment variable first, e.g.:

> Dripline_DIR=/install/prefix/lib/cmake/Dripline pip install .

CMake-Only Build¶

Note

This section is intended for developers working on the Python bindings. Do not use these instructions if you’re intending to have a full dripline-python installation.

If you want to build the python bindings directly with CMake we recommend these steps:

Create a build directory and go into that directory.
Configure the build with cmake or ccmake:

> cmake ..

If you want to specify a local installation of dripline-cpp, you can set an environment variable:

> Dripline_DIR=/install/prefix/lib/cmake/Dripline cmake ..

or a CMake variable:

> cmake -DDripline_DIR=/install/prefix/lib/cmake/Dripline ..

Build:

> make