A Python library for interacting with the Crux platform.
The aim of this module is to be a Pythonic way to use the Crux API reliably. It covers client functionality including scanning subscriptions, getting delivery status, and downloading files.
Python 3.6+ is supported.
See crux-python.cruxinformatics.com for detailed documentation.
Install a recent version of Python, and a Python dependency and virtual environment manager like pipenv. On macOS run:
brew install python
brew install pipenv
Install crux
from PyPI in a virtual environment, and get a shell in that environment:
mkdir -p crux_example
cd crux_example
pipenv install "crux==1.3"
pipenv shell
Create a file, like example.py, and use the crux
module:
from crux import Crux
conn = Crux()
identity = conn.whoami()
print("I am", identity.email)
Run the script:
HISTCONTROL=ignoreboth
export CRUX_API_KEY='YOUR_API_KEY'
python3 example.py
See the installation and authentication documentation for details.
Python 3.7 is required for development, which can be installed with brew install python
. For heavy development work, every supported version of Python must be installed, see the pyenv documentation below.
Pipenv should be used to manage dependancies during development.
- Install Pipenv, on macOS run
brew install pipenv
git clone https://github.com/cruxinformatics/crux-python.git
cd crux-python
pipenv install --dev
to install the dependanciespipenv shell
to get a shell in the virtual environment
To be able to run tests against all supported Python versions, you must have all supported Python versions installed. The test runner will look for binaries called python2.7
, python3.5
, python3.6
, etc. There are multiple ways to install Python versions, we'll document using pyenv.
-
brew install pyenv
to install -
Put
eval "$(pyenv init -)"
towards the end of the shell configuration file (~/.bashrc or ~/.bash_profile), because it manipulates$PATH
, for example:echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n eval "$(pyenv init -)"\nfi' >> ~/.bashrc
-
Open a new Terminal to get an updated shell
-
Install required/missing Python versions (this assumes you have Python 2.7 already installed, otherwise install it too):
pyenv install 3.5.6 pyenv install 3.6.6 pyenv install 3.7.0
-
pyenv global system 3.5.6 3.6.6 3.7.0
to make all the Python versions available -
If you already have pipenv virtual environment, remove it with
pipenv --rm
so it detects the Python versions -
pipenv install --dev
to install all the dependancies -
pipenv shell
to get a shell in the virtual environment
We use Nox to automate running tests, and use make
to automate running some commands. These commands should be run within a shell created with pipenv shell
.
# Run all tests: lint, unit, format_check
make test
# Or
nox
# Run only lint checks
make lint
# Or
nox -s lint
# Run unit tests against all available Python versions
make unit
# Or
nox -s unit
# Run integration tests agains all available Python versions
export CRUX_API_KEY="12345"
export CRUX_API_HOST="https://api.example.com"
make integration
# Or
export CRUX_API_KEY="12345"
export CRUX_API_HOST="https://api.example.com"
nox --s integration
# Check formatting
make format_check
# Or
nox -s format_check
# List all commands available
make
# Or
nox -l
# Run unit test only against Python 3.7
nox -s unit-3.7
# Reformat code
make format
# Generate Sphinx HTML documentation
make docs
Manual testing scripts could be found at tests/regression
.
In order to run one, i.e. client.py
, follow the steps:
- copy corresponding
.env.dist
file as.env
file (if you plan to runclient.py
, copyclient.env.dist
asclient.env
) - fill variables within
.env
file - launch the script (while being in the
tests/regression
folder, executepython client.py
)