The official Nominal Python client.

Nominal is the leading platform for operationalizing test data.

Installation

Installing the Nominal Python Client is as straightforward as installing it with pip:

$
$ pip install nominal

Version

We use semantic versioning for the Nominal Python Client. To check which version of the client you have installed, you may simply inspect the __version__ variable within the package:

1
import nominal
2
3
print(nominal.__version__)

$
$ pip install --upgrade nominal

Connect to Nominal

When using the Nominal client library, there are two primary ways of authenticating:

$
$ python -m nominal auth set-token
>
>
# Alternatively, use the globally installed CLI
>
$ nom auth set-token

1
import nominal
2
3
# Simply grab the "default" client using your stored credentials
4
client = nominal.get_default_client()
5
6
# Get details about the currently logged-in user to validate authentication
7
# Will display an object like: `User(display_name='your_email@your_company.com', ...)`
8
print(client.get_user())

1
import nominal
2
3
# Set login details for the user
4
nominal.set_token("<insert api key>")
5
6
# Get an instance of the client using provided credentials
7
client = nominal.get_default_client()
8
9
# Get details about the currently logged-in user to validate authentication
10
# Will display an object like: `User(display_name='your_email@your_company.com', ...)`
11
print(client.get_user())

Usage examples

Upload a Dataset

Download this example CSV to your local computer:

1
import polars as pl
2
3
df = pl.read_csv('hf://datasets/nominal-io/frosty-flight/frosty_flight_1k_rows.csv')
4
df.write_csv('frosty_flight_1k_rows.csv')

Then upload the CSV file to Nominal:

1
import nominal as nm
2
3
csv_dataset = nm.upload_csv(
4
    'frosty_flight_1k_rows.csv',
5
    name = 'Frosty Flight',
6
    timestamp_column = 'source_time',
7
    timestamp_type = 'iso_8601',
8
)
9
10
print('Uploaded dataset:', csv_dataset.rid)

See nm.upload_csv()

Create a Run

1
import nominal as nm
2
3
flight_simulator_run = nm.create_run(
4
    name = 'High precipitation flight',
5
    start = '2024-09-09T12:35:00Z',
6
    end = '2024-09-09T13:18:00Z',
7
)
8
9
print("Created run:", flight_simulator_run.rid)

See nm.create_run()

Add Data to a Run

(Scroll up to Upload a dataset to see how the csv_dataset was created.)

1
flight_simulator_run.add_dataset(
2
    dataset = csv_dataset,
3
    ref_name = 'high-precipitation-flight'
4
)

See Run.add_dataset()

Create a Run with Data

Create a Run and add a Dataset to it in one swoop.

nm.create_run_csv() combines upload_csv(), create_run(), and add_dataset().

1
import nominal as nm
2
3
nm.create_run_csv(
4
    'frosty_flight_1k_rows.csv',
5
    name = 'Frosty Flight',
6
    timestamp_column = 'source_time',
7
    timestamp_type = 'iso_8601'
8
)

See nm.create_run_csv()

Update Run metadata

1
import nominal as nm
2
3
run = nm.get_run('ri.scout.gov-staging.run.ce205f7e-9ef1-4a8b-92ae-11edc77441c6')
4
run.update(name = 'New Run Title')

See Run.update()

Please refer to the Function Reference and guides on the left-hand sidebar for more extensive examples.

Appendix

Tips & tricks for test engineers getting started with Python.

Python is the fastest growing language in STEM for data analytics. It’s free and functionally equivalent to MATLAB in many respects.

Python IDEs

If you’re new to scripting in Python, below are a few recommendations for Python IDEs (integrated development environments).

Jupyter

The guides on this website are styled after Jupyter notebook, a free and beginner-friendly analysis environment for Python. If you’re creating a lot of charts, or enjoy narrating your analysis code with text, you may find Jupyter productive.

VSCode

VSCode is a more minimalist, equally popular development environment for Python. If you’re creating automation scripts in Python that do not involve charts or analysis, the streamlined UX of VSCode may be appealing.