Guide to subunit2sql's Python API

DB API Guide

add_run_metadata(meta_dict, run_id, session=None)

Add a metadata key value pairs for a specific run.

This method will take a dictionary and store key value pair metadata in the DB associated with the specified run.

Parameters:

• meta_dict (dict) -- A dictionary which will generate a separate key value pair row associated with the run_id
• run_id (str) -- The uuid of the run to update. (value of the id column for the row to be updated)
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of created metadata objects

Return type:

subunit2sql.models.RunMeta

add_test_metadata(meta_dict, test_id, session=None)

Add a metadata key value pairs for a specific test.

This method will take a dictionary and store key value pair metadata in the DB associated with the specified run.

Parameters:

• meta_dict (dict) -- A dictionary which will generate a separate key value pair row associated with the test_run_id
• test_id (str) -- The uuid of the test to update. (value of the id column for the row to be updated)
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of created metadata objects

Return type:

subunit2sql.models.TestMeta

add_test_run_attachments(attach_dict, test_run_id, session=None)

Add attachments a specific test run.

This method will take a dictionary and store key blob pair attachments in the DB associated with the specified test_run.

Parameters:

• attachments_dict (dict) -- A dictionary which will generate a separate key blob pair row associated with the test_run_id
• test_run_id (str) -- The uuid of the test_run to update. (value of the id column for the row to be updated)
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of created attachment objects

Return type:

subunit2sql.models.Attachments

add_test_run_metadata(meta_dict, test_run_id, session=None)

Add a metadata key value pairs for a specific run.

This method will take a dictionary and store key value pair metadata in the DB associated with the specified run.

Parameters:

• meta_dict (dict) -- A dictionary which will generate a separate key value pair row associated with the test_run_id
• test_run_id (str) -- The uuid of the test_run to update. (value of the id column for the row to be updated)
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of created metadata objects

Return type:

subunit2sql.models.TestRunMeta

create_run(skips=0, fails=0, passes=0, run_time=0, artifacts=None, id=None, session=None, run_at=None)

Create a new run record in the database

Parameters:

• skips (int) -- Total number of skipped tests defaults to 0
• fails (int) -- Total number of failed tests defaults to 0
• passes (int) -- Total number of passed tests defaults to 0
• run_time (float) -- Total run timed defaults to 0
• artifacts (str) -- A link to any artifacts from the test run defaults to None
• id (str) -- The run id for the new run, needs to be a unique value
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation
• run_at -- Optional time at which the run was started. If not specified the time that data is added to the DB will be used instead

Returns:

The run object stored in the DB

Return type:

subunit2sql.models.Run

create_test(test_id, run_count=0, success=0, failure=0, run_time=0.0, session=None)

Create a new test record in the database.

This method is used to add a new test in the database. Tests are used to track the run history of a unique test over all runs.

Parameters:

• test_id (str) -- test_id identifying the test
• run_count (int) -- Total number or runs defaults to 0
• success (int) -- Number of successful runs defaults 0
• failure (int) -- Number of failed runs defaults to 0
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

The test object stored in the DB

Return type:

subunit2sql.models.Test

Raises InvalidRunCount:  

If the run_count doesn't equal the sum of the successes and failures.

create_test_run(test_id, run_id, status, start_time=None, end_time=None, session=None)

Create a new test run record in the database

This method creates a new record in the database

Parameters:

• test_id (str) -- UUID for test that was run
• run_id (str) -- UUID for run that this was a member of
• status (str) -- Status of the test run, normally success, fail, or skip
• start_time (datetime.Datetime) -- When the test was started defaults to None
• end_time (datetime.Datetime) -- When the test was finished defaults to None
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

The test_run object stored in the DB

Return type:

subunit2sql.models.TestRun

delete_old_runs(expire_age=186, session=None)

Delete all runs and associated metadata older than the provided age

Parameters:

• expire_age (int) -- The number of days into the past to use as the expiration date for deleting the runs
• session -- Optional session object if one isn't provided a new session

delete_old_test_runs(expire_age=186, session=None)

Delete all test runs and associated metadata older than the provided age

Parameters:

• expire_age (int) -- The number of days into the past to use as the expiration date for deleting the test runs
• session -- Optional session object if one isn't provided a new session

get_all_run_metadata_keys(session=None)

Get a list of all the keys used in the run_metadata table

Parameters:session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation Return keys:A list of all keys used in the run_metadata table Return type:list

get_all_runs(session=None)

Return all runs from the DB.

Parameters:session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation Return list:The list of run objects Return type:subunit2sql.models.Run

get_all_runs_by_date(start_date=None, stop_date=None, session=None)

Return all runs from the DB.

Parameters:

• str -- Optional start_date, if provided only runs started at or after the start_date will be included in the response
• str -- Optional end_date, if provided only runs started at or before the end_date will be included in the response
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of run objects

Return type:

subunit2sql.models.Run

get_all_runs_time_series_by_key(key, start_date=None, stop_date=None, session=None)

Get a time series of run summaries grouped by a key

This method will get a time series dictionary of run summary views which are grouped by the values of the specified key

Parameters:

• key (str) -- The key to use for grouping the run summaries
• start_date (str) -- Optional start date to filter results on
• stop_date (str) -- Optional stop date to filter results on
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return runs:

A time series dictionary of runs grouped by values of the specified key

Return type:

dict

get_all_test_metadata_keys(session=None)

Get a list of all the keys used in the test_metadata table

Parameters:session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation Return keys:A list of all keys used in the test_metadata table Return type:list

get_all_test_run_metadata_keys(session=None)

Get a list of all the keys used in the test_run_metadata table

Parameters:session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation Return keys:A list of all keys used in the test_run_metadata table Return type:list

get_all_test_runs(session=None)

Return all test runs from the DB.

Parameters:session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation Return list:The list of test run objects Return type:subunit2sql.models.TestRun

get_all_tests(session=None)

Return all tests from the DB.

Parameters:session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation Return list:The list of test objects Return type:subunit2sql.models.Test

get_engine(use_slave=False)

Get a new sqlalchemy engine instance

Parameters:use_slave (bool) -- If possible, use 'slave' database for this engine Returns:The engine object for the database connection Return type:sqlalchemy.engine.Engine

get_failing_from_run(run_id, session=None)

Return the set of failing test runs for a give run.

This method will return all the test run objects that failed during the specified run.

Parameters:

• run_id (str) -- UUID for the run to find all the failing runs
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of failing test runs for the given run

Return type:

subunit2sql.models.TestRun

get_failing_test_ids_from_runs_by_key_value(key, value, session=None)

Get a list of failing test_ids from runs with run_metadata.

This method gets a distinct list of test_ids (the test_id column not the id column) from all runs that match a run metadata key value pair.

Parameters:

• key (str) -- The key to use to match runs from in run_metadata
• value (str) -- The value of the key in run_metadata to match runs against
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

A list of test_ids that failed from runs that match the provided key value run_metadata pair

Return type:

list

get_id_from_test_id(test_id, session=None)

Return the id (uuid primary key) for a test given it's test_id value

Parameters:

• test_id (str) -- The test_id's string (not UUID) to identify the test
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

The id for the specified test

Return type:

str

get_ids_for_all_tests(session=None)

Return an iterator of ids (uuid primary key) for all tests in the database

Parameters:session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation Returns:The iterator of all ids for tests in the tests table Return type:iterator

get_latest_run(session=None)

Return the most recently created run from the DB.

Parameters:session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation Returns:The latest run object Return type:subunit2sql.models.Run

get_recent_failed_runs(num_runs=10, session=None, start_date=None)

Return a list of run uuid strings for the most recent failed runs

Parameters:

• num_runs (int) -- The number of runs to return in the list
• session -- Optional session object if one isn't provided a new session
• start_date (datetime) -- An optional date to use as the starting point for getting recent runs. Only runs after this date will be returned.

Return list:

A list of run uuid strings (the id column in the runs table) for the most recent runs.

get_recent_failed_runs_by_run_metadata(key, value, num_runs=10, start_date=None, session=None)

Get a list of recent failed runs for a given run metadata pair

Parameters:

• key (str) -- The run_metadata key to get failed runs
• value (str) -- The run_metadata value to get failed runs
• num_runs (int) -- The number of results to fetch, defaults to 10
• start_date (datetime) -- The optional starting dates to get runs from. Nothing older than this date will be returned
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of recent failed Run objects

Return type:

subunit2sql.models.Run

get_recent_runs_by_key_value_metadata(key, value, num_runs=10, session=None, start_date=None)

Get a list of runs for recent runs with a key value metadata pair

Parameters:

• num_runs (int) -- The number of runs to return in the list
• session -- Optional session object if one isn't provided a new session
• start_date (datetime) -- An optional date to use as the starting point for getting recent runs. Only runs after this date will be returned.

Return list:

A list of run objects for the most recent runs.

Return type:

subunit2sql.db.models.Run

get_recent_successful_runs(num_runs=10, session=None, start_date=None)

Return a list of run uuid strings for the most recent successful runs

Parameters:

• num_runs (int) -- The number of runs to return in the list
• session -- Optional session object if one isn't provided a new session
• start_date (datetime) -- An optional date to use as the starting point for getting recent runs. Only runs after this date will be returned.

Return list:

A list of run uuid strings (the id column in the runs table) for the most recent runs.

get_recent_successful_runs_by_run_metadata(key, value, num_runs=10, start_date=None, session=None)

Get a list of recent successful runs for a given run metadata pair

Parameters:

• key (str) -- The run_metadata key to get successful runs
• value (str) -- The run_metadata value to get successful runs
• num_runs (int) -- The number of results to fetch, defaults to 10
• start_date (datetime) -- The optional starting dates to get runs from. Nothing older than this date will be returned
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of recent failed Run objects

Return type:

subunit2sql.models.Run

get_run_by_id(id, session=None)

Get an individual run by it's id.

Parameters:

• id (str) -- The id for the run
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

The specified run object

Return type:

subunit2sql.models.Run

get_run_failure_rate_by_key_value_metadata(key, value, start_date=None, stop_date=None, session=None)

Return the failure percentage of runs with a set of run metadata

Parameters:

• key (str) -- The metadata key to use for matching the runs
• value (str) -- The metadata value to use for matching the runs
• start_date -- Optional start date to filter results on
• stop_date (str) -- Optional stop date to filter results on
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return failure_rate:  

The percentage of runs that failed, will be None if no runs are found

Return type:

float

get_run_id_from_uuid(uuid, session=None)

Get the id for a run by it's uuid

Parameters:

• uuid (str) -- The uuid for the run
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

The id for the run with the provided uuid

Return type:

int

get_run_metadata(run_id, session=None)

Return all run metadata objects associated with a given run.

Parameters:

• run_id (str) -- The uuid of the run to get all the metadata
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of metadata objects

Return type:

subunit2sql.models.RunMetadata

get_run_times_all_test_runs(tests=None, start_date=None, stop_date=None, session=None)

Return the all the individual duration times for each test_run

This function will return a dictionary where each key is a test_id and the value is a list of all the durations for each run of that test

Parameters:

• tests (list) -- the list of test_ids to get results for, if none is specified all tests
• start_date (str) -- The date to use as the start date for results
• stop_date (str) -- The date to use as the cutoff date for results
• session -- optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return run_times:  

all the durations for test_runs grouped by test_id

Return type:

dict

get_run_times_grouped_by_run_metadata_key(key, start_date=None, stop_date=None, session=None, match_key=None, match_value=None)

Return the aggregate run times for all runs grouped by a metadata key

The results of the output can be limited to runs with a different matching key value run_metadata pair using the match_key and match_value parameters.

Parameters:

• key -- The run_metadata key to use for grouping runs
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation
• match_key (str) -- An optional key as part of a key value run_metadata pair to filter the runs used to. This can not be the same as the key parameter. If match_value is not also specified this does nothing
• match_value (str) -- An optional value as part of a key value run_metadata pair to filter the runs used to. If match_key is not also specified this does nothing.

Returns:

A dictionary where keys are the value of the provided metadata key and the values are a list of run_times for successful runs with that metadata value

Return type:

dict

get_run_times_time_series_grouped_by_run_metadata_key(key, start_date=None, stop_date=None, session=None, match_key=None, match_value=None)

Get a times series dict of aggregate run times grouped by a metadata key

The results of the output can be limited to runs with a different matching key value run_metadata pair using the match_key and match_value parameters.

Parameters:

• key -- The run_metadata key to use for grouping runs
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation
• match_key (str) -- An optional key as part of a key value run_metadata pair to filter the runs used to. This can not be the same as the key parameter. If match_value is not also specified this does nothing
• match_value (str) -- An optional value as part of a key value run_metadata pair to filter the runs used to. If match_key is not also specified this does nothing.

Returns:

A dictionary where keys are the time stamp and the value is a dict with the key being the value of the provided metadata key and the values are run times for the successful runs

Return type:

dict

get_runs_by_ids(ids, session=None)

Get a list of runs by their ids.

Parameters:

• id (list) -- A list of run ids for the run
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

The list of the specified run objects

Return type:

list

get_runs_by_key_value(key, value, session=None)

Return all run objects associated with a certain key/value metadata pair

Parameters:

• key -- The key to be matched
• value -- The value to be matched
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of runs

Return type:

subunit2sql.models.Run

get_runs_by_status_grouped_by_run_metadata(key, start_date=None, stop_date=None, session=None)

get_runs_count(session=None)

Get the number of runs currently in the database

Return count:The number of runs in the DB Return type:int

get_runs_counts_by_run_metadata(key, value, start_date=None, session=None)

Check runs for a given run metadata pair

Parameters:

• key (str) -- The run_metadata key to check runs
• value (str) -- The run_metadata value to check runs
• start_date (datetime) -- The optional starting dates to get runs from. Nothing older than this date will be returned
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return count:

A count for a given run metadata key-value pair

Return type:

int

get_session(autocommit=True, expire_on_commit=False)

Get a new sqlalchemy Session instance

Parameters:

• autocommit (bool) -- Enable autocommit mode for the session.
• expire_on_commit (bool) -- Expire the session on commit defaults False.

get_test_by_id(id, session=None)

Get an individual test by it's uuid.

Parameters:

• id (str) -- The uuid for the test (the id field in the DB)
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

The specified test object

Return type:

subunit2sql.models.Test

get_test_by_test_id(test_id, session=None)

Get an individual test by it's test_id.

Parameters:

• test_id (str) -- The id (aka the test name) for the test (the test_id field in the DB)
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

The specified test object

Return type:

subunit2sql.models.Test

get_test_counts_in_date_range(test_id, start_date=None, stop_date=None, session=None)

Return the number of successes, failures, and skips for a single test.

Optionally you can provide a date to filter the results to be within a certain date range

Parameters:

• test_id (str) -- The test_id's ID(big integer) to identify the test
• start_date (datetime) -- The date to use as the start for counting. A str in the datetime str format "%b %d %Y" was the previous format here and will still work but is deprecated in favor of passing in a datetime object.
• stop_date (datetime) -- The date to use as the cutoff for counting. A str in the datetime str format "%b %d %Y" was the previous format here and will still work but is deprecated in favor of passing in a datetime.
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

A dict containing the number of successes, failures, and skips

Return type:

dict

get_test_metadata(test_id, session=None)

Return all test metadata objects for associated with a given test.

Parameters:

• test_id (str) -- The uuid of the test to get all the metadata
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of created metadata objects

Return type:

subunit2sql.models.TestMetadata

get_test_prefixes(session=None)

Returns all test prefixes from the DB.

This returns a list of unique test_id prefixes from the database, defined as the first dot-separated token in the test id. Prefixes wrapped in function syntax, such as 'setUpClass (a', will have this extra syntax stripped out of the returned value, up to and including the '(' character.

As an example, given an input test with an ID 'prefix.test.Clazz.a_method', the derived prefix would be 'prefix'. Given a second test with an ID 'setUpClass (prefix.test.Clazz)', the derived prefix would also be 'prefix'. If this function were called on a database containing only these tests, a list with only one entry, 'prefix', would be returned.

Note that this implementation assumes that tests ids are semantically separated by a period. If this is not the case (and no period characters occur at any position within test ids), the full test id will be considered the prefix, and the result of this function will be all unique test ids in the database.

Parameters:session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation Return list:A list of all unique prefix strings, with any extraneous details removed, e.g. 'setUpClass ('. Return type:str

get_test_run_by_id(test_run_id, session=None)

Get an individual test run by it's id.

Parameters:

• test_run_id (str) -- The id for the test run
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

The specified test run object

Return type:

subunit2sql.models.TestRun

get_test_run_dict_by_run_meta_key_value(key, value, start_date=None, stop_date=None, session=None)

Get a list of test run dicts from runs with a run metadata key value pair

Parameters:

• key (str) -- The key to use to match runs from in run_metadata
• value (str) -- The value of the key in run_metadata to match runs against
• start_date -- Optional start date to filter results on
• stop_date -- Optional stop date to filter results on
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return test_runs:  

The dictionary of all the tests run on any run that had metadata matching the provided key value pair.

Return type:

dict

get_test_run_duration(test_run_id, session=None)

Get the run duration for a specific test_run.

Parameters:

• test_run_id (str) -- The test_run's uuid (the id column in the test_run table) to get the duration of
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

The duration of the test run in secs

Return type:

float

get_test_run_metadata(test_run_id, session=None)

Return all run metadata objects for associated with a given run.

Parameters:

• test_run_id (str) -- The uuid of the test_run to get all the metadata
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of created metadata objects

Return type:

subunit2sql.models.RunMeta

get_test_run_series(start_date=None, stop_date=None, session=None, key='build_queue', value='gate')

Returns a time series dict of total daily run counts

Parameters:

• start_date (str) -- Optional start date to filter results on
• stop_date (str) -- Optional stop date to filter results on
• session -- Optional session object if one isn't provided a new session
• key (str) -- Optional run_metadata key to filter the runs used on. Key must be specified with value for filtering to occur. This defaults to 'build_queue' for backwards compatibility with earlier versions. Note, this default will be removed in the future.
• value (str) -- Optional run_metadata value to filter the runs used on. Value must be specified with key for filtering to occur. This defaults to 'gate' for backwards compatibility with earlier versions. Note, this default will be removed in the future.

Return dict:

A dictionary with the dates as the keys and the values being the total run count for that day. (The sum of success and failures from all runs that started that day)

get_test_run_time_series(test_id, session=None)

Returns a time series dict of run_times for successes of a single test

Parameters:

• test_id (str) -- The test's uuid (the id column in the test table) which will be used to get all the test run times for.
• session -- Optional session object if one isn't provided a new session

Return dict:

A dictionary with the start times as the keys and the values being the duration of the test that started at that time in sec.

get_test_runs_by_run_id(run_id, session=None)

Get all test runs for a specific run.

Parameters:

• run_id (str) -- The run's uuid (the uuid column in the run table) which to get all test runs for
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of test run objects for the specified test

Return type:

subunit2sql.models.TestRun

get_test_runs_by_status_for_run_ids(status, run_ids, key=None, session=None, include_run_id=False)

Get a list of test run dicts by status for all the specified runs

Parameters:

• status (str) -- The test status to filter the returned test runs on
• run_ids (list) -- A list of run ids (the uuid column from the runs table) to get the test runs from
• key (str) -- An optional run_metadata key to add the values for a run to the output dict for each test_run
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation
• include_run_id (bool) -- boolean flag to enable including the run uuid in the test run dicts returned

Return test_runs:  

A list of dicts for the test_runs and associated data

Return type:

list

get_test_runs_by_test_id(test_id, session=None)

Get all test runs for a specific test.

Parameters:

• test_id (str) -- The test's uuid (the id column in the test table) which to get all test runs for
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return list:

The list of test run objects for the specified test

Return type:

subunit2sql.models.TestRun

get_test_runs_by_test_test_id(test_id, start_date=None, stop_date=None, session=None, key=None, value=None, most_recent_first=False)

Get all test runs for a specific test by the test'stest_id column

Parameters:

• test_id (str) -- The test's test_id (the test_id column in the test table) which to get all test runs for
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation
• start_date (datetime.datetime) -- The date to use as the start date for results
• stop_date (datetime.datetime) -- The date to use as the cutoff date for results
• key (str) -- An optional key for run metadata to filter the test runs on. Must be specified with a value otherwise it does nothing.
• value (str) -- An optional value for run metadata to filter the test runs on. Must be specified with a key otherwise it does nothing.
• most_recent_first (bool) -- If true order the results list by date of test_run start_time in descending order.

Return list:

The list of test run objects for the specified test

Return type:

subunit2sql.models.TestRun

get_test_status_time_series(test_id, session=None)

Returns a time series dict of test_run statuses of a single test

Parameters:

• test_id (str) -- The test's uuid (the id column in the test table) which will be used to get all the test run times for.
• session -- Optional session object if one isn't provided a new session

Return dict:

A dictionary with the start times as the keys and the values being the status of that test run.

get_tests_by_prefix(prefix, session=None, limit=100, offset=0)

Returns all tests with the given prefix in the DB.

A test prefix is the first segment of a test_id when split using a period ('.'). This function will return a list of tests whose first period-separated token ends with the specified prefix. As a side-effect, given an input 'a', this will return tests with prefixes 'a', but also prefixes wrapped in function syntax, such as 'setUpClass (a'.

Note that this implementation assumes that tests ids are semantically separated by a period. If no period character exists in a test id, its prefix will be considered the full test id, and this method may return unexpected results.

Parameters:

• prefix (str) -- The test prefix to search for
• session -- Optional session object: if one isn't provided, a new session will be acquired for the duration of this operation
• limit (int) -- The maximum number of results to return
• offset (int) -- The starting index, for pagination purposes

Return list:

The list of matching test objects, ordered by their test id

Return type:

subunit2sql.models.Test

get_tests_by_test_ids(test_ids, session=None)

Get tests that match input test_ids

Parameters:

• test_ids (list) -- A list of test_ids (aka the test name) for the test
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

A list of the specified test objects

Return type:

list

get_tests_from_run_id(run_id, session=None)

Return the all tests for a specific run.

This method returns a list of all the Test objects that were executed as part of a specified run.

Parameters:

• run_id (str) -- The run's uuid (the id column in the run table) which to get all tests for
• session -- Optional session object if one isn't provided a new session

Return list:

The list of test objects for the specified test

Return type:

subunit2sql.models.Test

get_tests_run_dicts_from_run_id(run_id, session=None)

Returns all the stored data about test runs for a specific run.

This method returns a dictionary containing all the information stored in the database regarding the test_runs. This includes the test_id from the tests table, all the stored key value pair metadata from the test_run_metadata table, and from the test_runs table the status, start_time, and stop_time.

Parameters:

• run_id (str) -- The run's uuid (the id column in the run table) which to use to select it's run ids to collect information for.
• session -- Optional session object if one isn't provided a new session

Return dict:

A dictionary with the test_id from the tests for keys that contains all the stored information about the test_runs.

get_time_series_runs_by_key_value(key, value, start_date=None, stop_date=None, session=None)

Get a time series of runs with meta for all runs with a key value pai

Parameters:

• key (str) -- The metadata key to use for matching the runs
• value (str) -- The metadata value to use for matching the runs
• start_date -- Optional start date to filter results on
• stop_date (str) -- Optional stop date to filter results on
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Return runs:

A time series dictionary (where the top level key is a timestamp) that contains all the runs which

Return type:

dict

update_run(values, run_id, session=None)

Update an individual run with new data.

This method will take a dictionary of fields to update for a specific run. If a field is omitted it will not be changed in the DB.

Parameters:

• values (dict) -- Dict of values to update the test with. The key is the column name and the value is the new value to be stored in the DB
• run_id (str) -- The uuid of the run to update. (value of the id column for the row to be updated)
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

The updated run object stored in the DB

Return type:

subunit2sql.models.Run

update_test(values, test_id, session=None)

Update an individual test with new data.

This method will take a dictionary of fields to update for a specific test. If a field is omitted it will not be changed in the DB.

Parameters:

• values (dict) -- Dict of values to update the test with. The key is the column name and the value is the new value to be stored in the DB
• test_id (str) -- The uuid of the test to update. (value of the id column for the row to be updated)
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

The updated test object stored in the DB

Return type:

subunit2sql.models.Test

update_test_run(values, test_run_id, session=None)

Update an individual test_run with new data.

This method will take a dictionary of fields to update for a specific test_run. If a field is omitted it will not be changed in the DB.

Parameters:

• values (dict) -- Dict of values to update the test with. The key is the column name and the value is the new value to be stored in the DB
• test_run_id (str) -- The uuid of the test_run to update. (value of the id column for the row to be updated)
• session -- Optional session object if one isn't provided a new session will be acquired for the duration of this operation

Returns:

The updated test_run object stored in the DB

Return type:

subunit2sql.models.TestRun

Example usage patterns

Initializing subunit2sql

The first step to using subunit2sql inside your program is to initialize the db layer client. This can be accomplished just by loading the config followed by setting the necessary values:

from subunit2sql import shell


# Load default config
shell.parse_args([])
# Set database connection
db_uri = 'mysql://subunit:subunit@localhost/subunit'
shell.CONF.set_override('connection', db_uri, group='database')

However, if your already using oslo.config in your program you should just use the options from subunit2sql instead of this step. See the oslo.config documentation on how to do this. These steps are provided to avoid using oslo.config in any consumers of subunit2sql.

Additionally you can use a separate subunit2sql config file in your program to specify these options and just pass that config file into subunit2sql:

from subunit2sql import shell

subunit2sql_conf_path = './subunit2sql.conf'
# Initialize subunit2sql config
shell.parse_args([], [subunit2sql_conf_path])

The tradeoff here is that you have to have a file available to configure subunit2sql.

Another alternative is to initialize a sqlalchemy engine to create a session with the appropriate db url. This session can then be passed to all API calls without having to deal with oslo.config:

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

# Create engine with db url for session generation
engine=create_engine('mysql://subunit:subunit@localhost/subunit')
Session = sessionmaker(bind=engine)

# Create a new session to pass to API calls
# EX: api.get_run_metadata(session=session)
session = Session()

Parsing subunit stream and storing it in a DB

If your program is generating a subunit stream or reading one from somewhere and you'd like to integrate storing it into a subunit2sql db inline this can easily be accomplished by first parsing the file object and then writing that to the db.:

from subunit2sql import shell
from subunit2sql import read_subunit


subunit_file = open('subunit_file', 'r')
# Load default config
shell.cli_opts()
shell.parse_args([])
# Set database connection
db_uri = 'mysql://subunit:subunit@localhost/subunit'
shell.CONF.set_override('connection', db_uri, group='database')
# Parse results and write to DB
stream = read_subunit.ReadSubunit(subunit_file)
shell.process_results(stream.get_results())

If you'd like to set additional metadata for the runs you are adding to the DB you can do this by overriding the conf variables. However, you'll need to load the options (which would normally be set on the cli todo this, which looks like:

from subunit2sql import shell
from subunit2sql import read_subunit


subunit_file = open('subunit_file', 'r')
# Load default config
shell.cli_opts()
shell.parse_args([])
# Set database connection
db_uri = 'mysql://subunit:subunit@localhost/subunit'
shell.CONF.set_override('connection', db_uri, group='database')
# Set run metadata and artifact path
artifacts = 'http://fake_url.com'
metadata = {
    'job_type': 'full-run',
    'job_queue': 'gate',
    'build_id': 'fun_hash'
}
shell.CONF.set_override('artifacts', artifacts)
shell.CONF.set_override('run_meta', metadata)
# Parse results and write to DB
stream = read_subunit.ReadSubunit(subunit_file)
shell.process_results(stream.get_results())

keep in mind that oslo.config uses a global object to store options so if you're considering doing this in parallel somehow that may be something to consider.