Matthew Treinish 41b585e829 Reorganize the python api documentation

This commit reorganizes the structure of the documentation to group
all the documentation about the python api into the same page and then
link to that from the index.

Change-Id: I5f3903fbd3992fe8179afe7431ad2a9f2ec10a4f

2014-11-20 03:42:45 +00:00

3.3 KiB

Raw Blame History

Guide to subunit2sql's Python API

DB API Guide

Example usage patterns

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

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.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
aritfacts = '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.

3.3 KiB Raw Blame History