Skip to content

Usage

This package's primary use is as a command-line interface (CLI). It's meant to efficiently extract, transform, and load data from their Heurist database into local CSV, JSON, and DuckDB files.

Secondarily, you can also exploit certain modules, such as the API client, for your own Python development. For this secondary use, read the documentation here.

Installation

Requirements

  • Python version 3.10 or greater
  • A way to manage your virtual Python environment, i.e. pyenv.

Steps

  1. If you don't have Python installed on your machine, download version 3.10 or greater.
    • Need help installing Python? Check out the Real Python blog's tutorial.
  2. Create a new virtual environment for the package. Then activate it.
    • What's the simplest way? Check out Real Python's thorough blog post.
    • I recommend naming the environment heurist-api.
  3. Use pip install to install the heurist-api Python package.
$ pip install heurist-api

Configure the CLI

All of the heurist subcommands require connecting to your Heurist database.

Option 1: Manually declare login credentials

After the heurist command, provide the Heurist database name (--database, -d) as well as the username (--login, -l) and password (--password, -p) for a user with access to the Heurist database.

heurist -d YOUR_DATABASE -l "your.username" -p "your-password"

Option 2: Set environment variables

From wherever you're running the command in the terminal, create a .env file.

touch .env

Then, using some kind of simple text editor (and replacing the defaults with your login credentials), add the following 3 lines to the .env file:

DB_NAME=your_database
DB_LOGIN=your.username
DB_PASSWORD=your-password

With the .env file, you can run any heurist subcommand without needing to provide any other information.

$ heurist --help
Usage: heurist [OPTIONS] COMMAND [ARGS]...

  Group CLI command for connecting to the Heurist DB

Options:
  --version            Show the version and exit.
  -d, --database TEXT  Name of the Heurist database
  -l, --login TEXT     Login name for the database user
  -p, --password TEXT  Password for the database user
  --debugging          Whether to run in debug mode, default false.
  --help               Show this message and exit.

Commands:
  download  Export data of records of 1 or more record group types.
  record    Get a JSON export of a certain record type.
  schema    Generate documentation about the database schema.

CLI commands

Download groups of records

For full documentation on this command, see the basic usage of download.

heurist download -f NEW_DATABASE.db

Export a record type from Heurist's API

For full documentation on this command, see Export from API.

heurist record -t RECORD_TYPE_ID_NUMBER

Generate documentation about Heurist's schema

For full documentation on this command, see Generate schema.

heurist schema -t CSV|JSON