## Guide to subunit2sql’s Python API

this page last updated: 2019-07-16 22:32:18

# 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

> `delete_run_by_uuid`(run_uuid, session=None)

>   Delete a single test run based on its uuid.

>   Parameters:

>   - uuid (str) – The uuid of the run that will be deleted.
>   - session – Optional session object. if one isn’t provided, a new session will be created.

> `delete_test_runs_by_run_uuid`(run_uuid, session=None)

>   Delete all test runs included in a given run

>   Parameters:

>   - uuid (str) – The uuid of the run that will be deleted.
>   - session – Optional session object. if one isn’t provided, a new session will be created.

> `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.

this page last updated: 2019-07-16 22:32:18

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug questions?