Getting Started in Python

Python client and command line tool for Blackfynn.


The Python client is compatible with Python 2.7 and 3.4-3.7.

pip install -U blackfynn


In order to connect to Blackfynn using the any client, first you must Generate API token & secret and enable in client.

Basic Usage

Import and Initialize


If you are using Python 2.7 it is highly recommended that you add from __future__ import print_function to the top of your scripts. This will allow you to easily use Python 3 in the future.

from blackfynn import Blackfynn

bf = Blackfynn()

This will use your default profile to establish a connection. Alternatively, you may want to specify a profile explicitly:

bf = Blackfynn('my_profile')

Where my_profile is an existing profile.


See Create connection profile for creating and managing connection profiles.

Basic Operations

Get your datasets:

# print your available datasets
for ds in bf.datasets():
    print(" Found a dataset: ",

# grab some dataset by name
ds1 = bf.get_dataset('my dataset 1')

# list items inside dataset (first level)

Upload some files into your dataset:


Get a data package:

# use ID to get a package
pkg = bf.get('N:package:1234-1234-1234-1235')

Rename it & add some properties: = "My new package name"
pkg.set_property('Temperature', 83.0)

Uploading files


You must upload files into a Dataset or Collection.

You can upload using the .upload() methods provided on Dataset and Collection objects:

# upload a file into a dataset (ds)

Retrieving data

Let’s say you grab a TimeSeries package:

ts = bf.get('N:package:your-timeseries-id')

You can get first minute of data in 1-second chunks:

for chunk in ts.get_data_iter(chunk_size='1s', length='1m'):
    # do something with data (pandas Dataframe)
    print("Mean values =", chunk.mean())

You can do the same thing for a single channel:

channel = ts.channels[0]
for chunk in channel.get_data_iter(chunk_size='5s', length='10m'):
    # do something with data (pandas Series)
    print("Max value =", chunk.max())