Install In a Python Environment#

The Squirro Toolbox is a collection of command line utilities that work with a Squirro cluster. This page discusses installation into a Python environment.

Introduction#

The Squirro Toolbox package for Python replaces the operating system specific versions for Windows, Mac or Linux.

The Squirro Toolbox is installed into an existing Python environment, which can then make use of all the default Python operations, such as pip install for package installation.

Download#

Download the Squirro Toolbox from the Downloads section (license required). Select the version for Python. The download file will have a name in the following form:

squirro.toolbox-VERSION.PYTHON-none-any.whl.

Set up Python#

Ensure you have a Python environment set up with Python 3.6 - 3.9.x.

Caution

Squirro does not support Python 3.10 or later.

It is recommended, but not required, to work with a virtual environment (virtualenv). Covering the details of setting up and working with virtualenv is beyond the scope of this guide.

Reference: A suggested read for setting up virtual environments is the Virtualenv documentation.

Installation#

Install the downloaded whl file using pip as follows:

$ pip install squirro.toolbox-VERSION.PYTHON-none-any.whl

Upgrade#

If you have a Squirro Toolbox installed and would like to update to a new version, use the following:

pip install --upgrade squirro.toolbox-$NEW_VERSION.PYTHON-none-any.whl

Dependencies (Troubleshooting)#

Especially on Windows, you may encounter the following error when installing:

…
    copying Levenshtein\_levenshtein.h -> build\lib.win32-2.7\Levenshtein
    running build_ext
    building 'Levenshtein._levenshtein' extension
    error: Microsoft Visual C++ 9.0 is required. Get it from http://aka.ms/vcpython27

    ----------------------------------------
Command … failed with error code 1 in …\python-levenshtein\

This is because this dependency is a binary package that must be compiled.

Christoph Golke maintains a great resource where he provides pre-compiled packages so that you do not have to go through the hassle of setting up the right Python compilation environment locally.

For any dependency that fails (python-levenshtein in the example above) follow this process:

  1. Go to Unofficial Windows Binaries for Python Extension Packages

  2. Find the package you are looking for (python-levenshtein in the example)

  3. Download the package with the correct architecture (win32 or amd64, depending on your Python installation) and python version - this will download a whl file

  4. Install the downloaded file with pip: pip install ….whl

  5. Try the Squirro Toolbox installation again (see above)

Usage#

The Squirro toolbox contains several command line applications that are used to work with a Squirro cluster.

For example, the Data Loader CLI Tool, which is used to index data in Squirro.

On the command line, you can run the following command:

squirro_data_load --version

This runs the executable squirro_data_load with the argument --version.

If the toolbox is correctly installed, this outputs the version of the toolbox.

To get an overview of the command and what it is capable of, use the --help argument:

squirro_data_load --help

This help message defines how the executable is to be used. Arguments presented in square brackets are optional, whereas arguments presented without square brackets are mandatory.

For example:

[--verbose]     :: Optional parameter
--token TOKEN   :: Mandatory parameter requiring user input

The executable will not run without all mandatory arguments supplied, displaying an error message like “squirro_data_load: error: too few arguments”.

Arguments presented with a second word in block capitals indicate that user input is required for that argument.

In the example case above, the user API token is required. An example giving that token is as follows:

squirro_data_load --token "mytoken"