Install Caproto

You can install caproto using pip or from source.

First verify that you have Python 3.6+.

python3 --version

If necessary, install it by your method of choice (apt, Homebrew, conda, etc.).

Installation Using Pip

python3 -m pip install -U "caproto[complete]"

Minimal Installation Using Pip

The complete installation includes several optional dependences. For an extremely lightweight installation, install caproto alone:

python3 -m pip install -U caproto

Caproto’s command-line, synchronous, and threading clients will work in this mode, as will its asyncio server, because these rely only on built-in Python modules. Caproto’s trio and curio servers will not work unless trio and curio are installed.

If numpy is not installed, caproto falls back on Python’s built-in array module. This choice can be manually controlled via caproto.select_backend('numpy') and caproto.select_backend('array').

Other, intermediate combinations are also conveniently available:

python3 -m pip install -U "caproto[standard]"  # includes numpy, netifaces
python3 -m pip install -U "caproto[async]"  # includes the async libs

Development Installation

git clone https://github.com/caproto/caproto
cd caproto
pip install -e .

To install all the optional dependencies as well, use:

pip install -e .[complete]

Development

For development, you will also want the dependencies for running the tests and building the documentation:

pip install -Ur requirements-test.txt
pip install -Ur requirements-doc.txt

You may also want to use pre-commit. This is optional. It streamlines compliance with code style requirements. If you are a first-time contributor or unfamiliar with “precommit” tools, feel free to ignore.

pip install pre-commit
pre-commit install

This uses git hooks to check the changed files every time code is committed.

echo "blah" >> setup.py
git commit -am "test"   # fails due to linting

Use the git option --no-verify or -n to skip the checks.

git commit -nam "test"  # commits anyway

You can run the checks manually on all files.

# run on all files
pre-commit run --all-files

To run the tests:

python run_tests.py

Any argument will be passed through to pytest. These are arguments are commonly useful:

  • -v verbose

  • -s Do not capture stdout/err per test.

  • -k EXPRESSION Filter tests by pattern-matching test name.

Many of the tests test caproto against EPICS’ reference implementation. They expect caget, caput, and softIoc executables to be available and for EPICS_BASE to be set.

A small number of the tests test caproto against motorsim. To skip these tests, set the environment variable CAPROTO_SKIP_MOTORSIM_TESTS=1.

To build the documentation:

make -C doc html

Installation on iOS

Pythonista brings support for Python 3.6 to iOS, meaning that you can run caproto rather easily right from your iPhone or iPad.

To get started on iOS:

  1. Purchase and install Pythonista from the app store.

  2. Install StaSh in Pythonista by creating a new script and running:

import requests as r; exec(r.get('https://bit.ly/get-stash').text)
  1. Restart Pythonista and launch a StaSh shell. Install caproto with pip:

$ pip install caproto
  1. Open an example IOC and give it a try. To find the caproto examples, navigate to “Python Modules > site-packages-3 > caproto > ioc_examples > simple.py”

  2. Tap the play button to run it. From another computer on the same WiFi network, you should then be able to access the PVs served directly from your iOS device:

$ caproto-get simple:A
simple:A                   [1]
  1. Some example IOCs are available in a separate repository, including access to the accelerometer, GPS, and text-to-speech engine. See klauer/caproto_ios for more information.