subunit2sql/doc/source/api.rst

Guide to subunit2sql's Python API

DB API Guide

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.