Getting Started in Python

Python client and command line tool for Blackfynn.


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.


We currently only support and test on Python v2.7. This will be expanded in the near future.

Basic Usage

Import and Initialize

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)
print ds1.items

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()