buildtest ¶

class buildtest.cli.build.BuildTest(configuration=None, buildspecs=None, exclude_buildspecs=None, tags=None, executors=None, testdir=None, stage=None, filter_tags=None, rebuild=None, buildtest_system=None, report_file=None, max_pend_time=None, poll_interval=None, keep_stage_dir=None)¶

This class is an interface to building tests via “buildtest build” command.

_print_build_phase(self, invalid_builders, table)¶

_print_jobs_after_poll(self, valid_builders)¶: Print table of all tests after polling

_print_test_summary(self)¶: Print a summary of total pass and fail test with percentage breakdown.

_update_build_history(self)¶: Write a build history file that is stored in $BUILDTEST_ROOT/var/.history directory summarizing output of build. The history file is a json file named build.json which contains a copy of the build log for troubleshooting. buildtest will create a sub-directory that is incremented such as 0, 1, 2 in $BUILDTEST_ROOT/var/.history which is used to differentiate builds.

build(self)¶: This method is responsible for discovering buildspecs based on input argument. Then we parse the buildspecs and retrieve builder objects for each test. Each builder object will invoke build which will build the test script, and then we run the test and update report.

build_phase(self)¶: This method will build all tests by invoking class method build for each builder that generates testscript in the test directory.

parse_buildspecs(self)¶

Parse all buildspecs by passing buildspec file to BuildspecParser class. If buildspec fails validation we skip the buildspec and print all skipped buildspecs. If buildspec passes validation we get all builders by invoking Builder class that is responsible for creating builder objects for each test.

Returns: A list of builder objects which are instances of BuilderBase class
Return type: list

poll_jobs(self, poll_queue, valid_builders)¶

This method will poll jobs by processing all jobs in poll_queue. If job is cancelled by scheduler, we remove this from valid_builders list. This method will return a list of valid_builders after polling. If there are no valid_builders after polling, the method will return None

Parameters

poll_queue (list, required) – a list of jobs that need to be polled. The jobs will poll using poll method from executor
valid_builders (list, required) – list of valid builders

resolve_testdirectory(self, cli_testdir=None)¶

This method resolves which test directory to select. For example, one can specify test directory via command line buildtest build --testdir <path> or path in configuration file. The default is $HOME/.buildtest/var/tests

Parameters: cli_testdir (str) – test directory from command line buildtest build --testdir
Returns: Path to test directory to use
Return type: str

run_phase(self)¶

This method will run all builders with the appropriate executor. The executor argument is an instance of BuildExecutor that is responsible for orchestrating builder execution to the appropriate executor class. The executor contains a list of executors picked up from buildtest configuration. For tests running locally, we get the test metadata and count PASS/FAIL test state which is printed at end in Test Summary. For tests that need to run via scheduler, the first stage of run will dispatch job, and state will be N/A. We first dispatch all jobs and later poll jobs until they are complete. The poll section is skipped if all tests are run locally. In poll section we regenerate table with all valid_builders and updated test state and returncode and recalculate total pass/fail tests. Finally we return a list of valid_builders which are tests that ran through one of the executors. Any test that failed to run or be dispatched will be skipped during run stage and not added in valid_builders. The valid_builders contains the test meta-data that is used for updating test report in next stage.

Returns: A list of valid builders
Return type: list

buildtest.cli.build.discover_buildspecs(buildspecs=None, exclude_buildspecs=None, executors=None, tags=None)¶

This method discovers all buildspecs based on –buildspecs, –tags, –executor and excluding buildspecs (–exclude).

Parameters

buildspecs (list) – List of input buildspecs passed by argument buildtest build –buildspec
exclude_buildspecs (list) – List of excluded buildspecs by argument buildtest build –exclude
tags (list) – List of input tags for discovering buildspecs by argument buildtest build –tags
executors (list) – List of input executors for discovering buildspecs by argument buildtest build –executor

buildtest.cli.build.discover_buildspecs_by_executor(executors)¶

This method discovers buildspecs by executor name, using buildtest build --executor command. This method will read BUILDSPEC_CACHE_FILE and search for executor key in buildspec recipe and match with input executor name. The return is a list of matching buildspec with executor name to process.

Parameters: executors (list) – List of input executor name from command line argument buildtest build --executor <name>
Returns: a list of buildspec files that match tag name
Return type: list

buildtest.cli.build.discover_buildspecs_by_tags(tagnames)¶

This method discovers buildspecs by tags, using --tags option from buildtest build command. This method will read BUILDSPEC_CACHE_FILE and search for tags key in buildspec recipe and match with input tag. Since tags field is a list, we check if input tag is in list and if so we add the entire buildspec into a list. The return is a list of buildspec files to process.

Parameters: input_tag (list) – List of input tags from command line argument buildtest build --tags <tags>
Returns: a list of buildspec files that match tag name
Return type: list

buildtest.cli.build.discover_by_buildspecs(buildspec)¶

Given a buildspec file specified by the user with buildtest build --buildspec, discover one or more files and return a list for buildtest to process. This method is called once per argument of --buildspec or --exclude option. If its a directory path we recursively find all buildspecs with option. If its a directory path we recursively find all buildspecs with .yml extension. If filepath doesn’t exist or file extension is not .yml we return None and capture error in log.

# file path buildtest build –buildspec tutorials/hello.sh.yml

# directory path buildtest build –buildspec tutorials

Parameters: buildspec (str) – Input argument from buildtest build --buildspec
Returns: A list of discovered buildspec with resolved path, if its invalid we return None
Return type: list or None

buildtest.cli.build.logger¶

buildtest.cli.build.print_discovered_buildspecs(buildspec_dict)¶: This method will print the discovered buildspecs in the table format

buildtest.cli.build.update_report(valid_builders, report_file=BUILD_REPORT)¶

This method will update BUILD_REPORT after every test run performed by buildtest build. If BUILD_REPORT is not created, we will create file and update json file by extracting contents from builder.metadata

Parameters

valid_builders (instance of BuilderBase (subclass)) – builder object that were successful during build and able to execute test
report_file (str) – specify location to report file

buildtest.cli.buildspec¶

Module Contents¶

Classes¶

BuildspecCache

Functions¶

buildspec_find(args, configuration)

Entry point for buildtest buildspec find command

Attributes¶

class buildtest.cli.buildspec.BuildspecCache(configuration, rebuild=False, filterfields=None, formatfields=None, roots=None)¶

default_format_fields = ['name', 'type', 'executor', 'tags', 'description']¶

filter_fields = ['type', 'executor', 'tags']¶

format_fields¶

table¶

_discover_buildspecs(self)¶: This method retrieves buildspecs based on self.paths which is a list of directory paths to search. If --root is specified we process each argument and recursively find all .yml files

_filter_buildspecs(self, executor, tags, schema_type)¶

This method will return a boolean True/False that determines if buildspec test entry is skipped as part of filter process. The filter are done based on executor, tags, type field. True indicates test needs to be skipped.

Parameters

executor (str, required) – ‘executor; field from buildspec recipe
tags (str or list, required) – ‘tags’ field from buildspec recipe
schema_type (str, required) – ‘type’ field from buildspec recipe

Returns

boolean to determine if we need to skip buildspec

Return type

bool

_validate_buildspecs(self, buildspecs)¶: Given a list of buildspec files, validate each buildspec using BuildspecParser and return a list of valid buildspecs. Any invalid buildspecs are added to separate list

_write_buildspec_cache(self)¶: This method is responsible for writing buildspec cache to file

build(self)¶: This method will build buildspec cache file. If user requests to rebuild cache we remove the file and recreate cache. If cache file exists, we simply load from cache

build_cache(self)¶

This method will rebuild the buildspec cache file by recursively searching all .yml files specified by input argument paths which is a list of directory roots. The buildspecs are validated and cache file is updated”

Parameters: paths (list) – A list of directory roots to process buildspecs files.
Returns: Rebuild cache file

check_filter_fields(self)¶: This method checks filter fields are valid. The filter fields are specified as ``buildtest buildspec find –filter <KEY1>=<VAL1>,<KEY2>=<VAL2>,…

check_format_fields(self)¶: This method will check if all format fields are valid. Format fields are passed comma separated as –format field1,field2,field3,…

find_buildspecs(self)¶: This method will find buildspecs based on cache content. We skip any tests based on executor filter, tag filter or type filter and build a table of tests that will be printed using print_buildspecs method.

get_buildspecfiles(self)¶: This method implements buildtest buildspec find --buildspec-files which reports all buildspec files in cache.

get_cache(self)¶: Returns cache file as loaded dictionary

get_executors(self)¶: This method implements buildtest buildspec find --executors which reports all executors from cache.

get_tags(self)¶: This method implements buildtest buildspec find --tags which reports a list of unique tags from all buildspecs in cache file.

load_paths(self)¶: Add all paths to search for buildspecs. We must read configuration file and check property buildspec_roots for list of directories to search. We check all directories exist, if any fail we don’t add them to path. In addition, we add the default buildspec path where we find tutorials and general tests.

print_buildspecs(self)¶: Print buildspec table

print_by_executors(self)¶: This method prints executors by tests and implements buildtest buildspec find --group-by-executor command

print_by_tags(self)¶: This method prints tags by tests and implements buildtest buildspec find --group-by-tags command

static print_filter_fields()¶: This method prints filter fields available for buildspec cache. This method implements command buildtest buildspec find --helpfilter

static print_format_fields()¶: This method prints format fields available for buildspec cache. This method implements command buildtest buildspec find --helpformat

print_maintainer(self)¶: This method prints maintainers from buildspec cache file which implements buildtest buildspec find --maintainers command.

print_maintainers_by_buildspecs(self)¶: This method prints maintainers breakdown by buildspecs. This method implements buildtest buildspec find --maintainers-by-buildspecs

print_paths(self)¶: This method print buildspec paths, this implements command buildtest buildspec find --paths

buildtest.cli.buildspec.buildspec_find(args, configuration)¶: Entry point for buildtest buildspec find command

buildtest.cli.buildspec.logger¶

buildtest.cli.cdash¶

Module Contents¶

Functions¶

`cdash_cmd`(args, default_configuration=None, open_browser=True)	This method is entry point for `buildtest cdash` command which implements uploading
`upload_test_cdash`(build_name, configuration, site=None, report_file=None)	This method is responsible for reading report file and pushing results to CDASH

buildtest.cli.cdash.cdash_cmd(args, default_configuration=None, open_browser=True)¶

This method is entry point for buildtest cdash command which implements uploading results to CDASH server and command line interface to open CDASH project.

Parameters

args (ArgumentParser) – Instance of ArgumentParser that contains arguments for buildtest cdash command
default_configuration (SiteConfiguration, optional) – The loaded default configuration which is an instance of SiteConfiguration
open_browser (optional) – boolean to control if we open page in web browser using webbrowser.open. This is enabled by default, but can be turned off especially when running regression test where we don’t want to see the page

buildtest.cli.cdash.upload_test_cdash(build_name, configuration, site=None, report_file=None)¶

This method is responsible for reading report file and pushing results to CDASH server. User can specify cdash settings in configuration file or pass them in command line. The command buildtest cdash upload will upload results to CDASH.

Parameters

build_name – build name that shows up in CDASH
configuration (SiteConfiguration) – Instance of SiteConfiguration class that contains the configuration file
site (str, optional) – site name that shows up in CDASH
report_file (str, optional) – Path to report file when uploading results. This is specified via buildtest cdash upload -r command

Returns

buildtest.cli.compilers¶

Module Contents¶

Classes¶

BuildtestCompilers

Functions¶

`compiler_cmd`(args, configuration)
`compiler_find`(args, configuration)	This method implements `buildtest config compilers find` which detects

class buildtest.cli.compilers.BuildtestCompilers(configuration, settings_file=None, debug=False)¶

compiler_table¶

_update_compiler_section(self)¶

This method will update the compiler section by adding new compilers if found

Returns: Updated compiler section for buildtest configuration
Return type: dict

_validate_modules(self, module_dict)¶: This method will validate modules by running module load test for all discovered modules specified in parameter discovered_modules. This method returns a list of modules that were valid, if all tests pass we return the same list. A module test pass if we get a returncode 0.

find_compilers(self)¶

This method returns compiler modules discovered depending on your module system. If you have Lmod system we use spider utility to detect modules, this is leveraging Lmodule API. If you have environment-modules we parse output of module av -t.

Returns: return a list of compiler modules detected based on module key name.
Return type: dict

list(self)¶: Return all compilers defined in buildtest configuration

print_compilers(self)¶: This method implements buildtest config compilers which prints all compilers from buildtest configuration

print_json(self)¶: Prints compiler section in JSON, this implements buildtest config compilers --json

print_yaml(self)¶: Prints compiler section in YAML, this implements buildtest config compilers --yaml

buildtest.cli.compilers.compiler_cmd(args, configuration)¶

buildtest.cli.compilers.compiler_find(args, configuration)¶: This method implements buildtest config compilers find which detects new compilers based on module names defined in configuration. If system has Lmod we use Lmodule API to detect the compilers. For environment-modules we search for all modules in current $MODULEPATH.

buildtest.cli.config¶

Module Contents¶

Functions¶

`config_cmd`(args, configuration)
`validate_config`(configuration)	This method implements `buildtest config validate` which attempts to
`view_configuration`(configuration)	View buildtest configuration file. This implements `buildtest config view`
`view_executors`(configuration, buildexecutor, json_format=False, yaml_format=False)	Display executors from buildtest configuration. This implements `buildtest config executors` command.
`view_summary`(configuration, buildtestsystem=None)	This method implements `buildtest config summary` option. In this method
`view_system`(configuration)	This method implements command `buildtest config systems` which displays

buildtest.cli.config.config_cmd(args, configuration)¶

buildtest.cli.config.validate_config(configuration)¶: This method implements buildtest config validate which attempts to validate buildtest settings with schema. If it’s not validate an exception is raised which could be ValidationError or ConfigurationError.

buildtest.cli.config.view_configuration(configuration)¶: View buildtest configuration file. This implements buildtest config view

buildtest.cli.config.view_executors(configuration, buildexecutor, json_format=False, yaml_format=False)¶: Display executors from buildtest configuration. This implements buildtest config executors command. If no option is specified we display output in JSON format

buildtest.cli.config.view_summary(configuration, buildtestsystem=None)¶

This method implements buildtest config summary option. In this method we will display a summary of System Details, Buildtest settings, Schemas, Repository details, Buildspecs files and test names.

Parse buildtestsystem: instance of class BuildTestSystem, optional

buildtest.cli.config.view_system(configuration)¶: This method implements command buildtest config systems which displays system details from configuration file in table format.

buildtest.cli.history¶

Module Contents¶

Functions¶

`build_history`(args)	This is the entry point for command `buildtest build history` command which reports
`list_builds`()
`query_builds`(build_id, log_option)	This method is called when user runs buildtest history query which will

buildtest.cli.history.build_history(args)¶: This is the entry point for command buildtest build history command which reports

buildtest.cli.history.list_builds()¶

buildtest.cli.history.query_builds(build_id, log_option)¶

This method is called when user runs buildtest history query which will report the build.json and logfile.

Parameters

build_id (int, required) – Input argument buildtest history query <id>
log_option (bool, required) – Input argument buildtest history query <id> –log

buildtest.cli.inspect¶

This module implements methods for buildtest inspect command that can be used to retrieve test record from report file in JSON format.

Module Contents¶

Functions¶

`get_all_ids`(report)	Return all unique test ids from report cache
`inspect_by_id`(test_ids, report, args)
`inspect_by_name`(report, names)	Implements command `buildtest inspect name` which will print all test records
`inspect_cmd`(args)	Entry point for `buildtest inspect` command
`inspect_list`(test_ids)	Implements method `buildtest inspect list`

buildtest.cli.inspect.get_all_ids(report)¶

Return all unique test ids from report cache

Parameters: report (dict) – loaded report file in JSON format
Returns: a dictionary returning a list of unique test IDs
Return type: dict

buildtest.cli.inspect.inspect_by_id(test_ids, report, args)¶

buildtest.cli.inspect.inspect_by_name(report, names)¶: Implements command buildtest inspect name which will print all test records by given name in JSON format.

buildtest.cli.inspect.inspect_cmd(args)¶: Entry point for buildtest inspect command

buildtest.cli.inspect.inspect_list(test_ids)¶: Implements method buildtest inspect list

buildtest.cli.report¶

Module Contents¶

Classes¶

Report

Functions¶

`is_int`(val)
`report_cmd`(args)

class buildtest.cli.report.Report(filter_args, format_args, latest, oldest, report_file=BUILD_REPORT)¶

display_table¶

filter_fields = ['buildspec', 'name', 'executor', 'state', 'tags', 'returncode']¶

format_fields = ['buildspec', 'command', 'compiler', 'endtime', 'errfile', 'executor', 'full_id', 'hostname',...¶

_check_filter_fields(self)¶

_check_format_fields(self)¶: Check all format arguments (–format) are valid, the arguments are specified in format (–format key1=val1,key2=val2). We make sure each key is valid format field.

_filter_test_by_executor(self, test)¶

_filter_test_by_names(self, name)¶

_filter_test_by_returncode(self, test)¶

_filter_test_by_state(self, test)¶

_filter_test_by_tags(self, test)¶

filter_buildspecs_from_report(self)¶

get_report_file(self)¶

load(self)¶: This method is responsible for loading report file. If file not found or report is empty dictionary we raise an error. The report file is loaded using json.loads and return value is a dictionary containing entire report of all tests.

print_display_table(self)¶

print_filter_fields(self)¶: Implements command buildtest report --helpfilter

print_format_fields(self)¶: Implements command buildtest report --helpformat

process_report(self)¶

buildtest.cli.report.is_int(val)¶

buildtest.cli.report.report_cmd(args)¶

buildtest.cli.schema¶

Module Contents¶

Functions¶

schema_cmd(args)

This method implements command buildtest schema which shows a list

buildtest.cli.schema.schema_cmd(args)¶

This method implements command buildtest schema which shows a list of schemas, their json content and list of schema examples. The input args is an instance of argparse class that contains user selection via command line. This method can do the following

buildtest schema - Show all schema names buildtest schema --name <NAME> -j ``. View json content of a specified schema ``buildtest schema --name <NAME> -e. Show schema examples Parameters:

Parameters: args (<class 'argparse.Namespace'>) – instance of argparse class
Result: output of json schema on console

Package Contents¶

Functions¶

`build_menu`(subparsers)	This method implements command line menu for `buildtest build` command.
`buildspec_menu`(subparsers)	This method implements `buildtest buildspec` command
`cdash_menu`(subparsers)	This method builds arguments for buildtest cdash command.
`config_menu`(subparsers)	This method adds argparse argument for `buildtest config`
`get_parser`()
`handle_kv_string`(val)	This method is used as type field in –filter argument in `buildtest buildspec find`.
`history_menu`(subparsers)	This method builds the command line menu for `buildtest history` command
`inspect_menu`(subparsers)	This method builds argument for buildtest inspect command
`positive_number`(value)	Checks if input value is positive value and within range of 1-50. This method
`report_menu`(subparsers)	This method implements the `buildtest report` command options
`schema_menu`(subparsers)	This method builds menu for `buildtest schema`

Attributes¶

`BUILDTEST_COPYRIGHT`
`BUILDTEST_VERSION`
`BUILD_REPORT`
`schema_table`

buildtest.cli.BUILDTEST_COPYRIGHT = Copyright (c) 2021, The Regents of the University of California, through Lawrence Berkeley...¶

buildtest.cli.BUILDTEST_VERSION = 0.9.6¶

buildtest.cli.BUILD_REPORT¶

buildtest.cli.build_menu(subparsers)¶: This method implements command line menu for buildtest build command.

buildtest.cli.buildspec_menu(subparsers)¶: This method implements buildtest buildspec command

buildtest.cli.cdash_menu(subparsers)¶: This method builds arguments for buildtest cdash command.

buildtest.cli.config_menu(subparsers)¶: This method adds argparse argument for buildtest config

buildtest.cli.get_parser()¶

buildtest.cli.handle_kv_string(val)¶

This method is used as type field in –filter argument in buildtest buildspec find. This method returns a dict of key,value pair where input is in format key1=val1,key2=val2,key3=val3

Parameters: val (str) – input value
Returns: dictionary of key/value pairs
Return type: dict

buildtest.cli.history_menu(subparsers)¶: This method builds the command line menu for buildtest history command

buildtest.cli.inspect_menu(subparsers)¶: This method builds argument for buildtest inspect command

buildtest.cli.positive_number(value)¶: Checks if input value is positive value and within range of 1-50. This method is used for –rebuild option

buildtest.cli.report_menu(subparsers)¶: This method implements the buildtest report command options

buildtest.cli.schema_menu(subparsers)¶: This method builds menu for buildtest schema

buildtest.cli.schema_table¶

`buildtest.executors`¶

Submodules¶

buildtest.executors.base¶

BuildExecutor: manager for test executors

Module Contents¶

Classes¶

BaseExecutor

The BaseExecutor is an abstract base class for all executors.

class buildtest.executors.base.BaseExecutor(name, settings, site_configs)¶

The BaseExecutor is an abstract base class for all executors.

type = base¶

__repr__(self)¶: Return repr(self).

__str__(self)¶: Return str(self).

_check_regex(self, builder)¶

This method conducts a regular expression check using re.search with regular expression defined in Buildspec. User must specify an output stream (stdout, stderr) to select when performing regex. In buildtest, this would read the .out or .err file based on stream and run the regular expression to see if there is a match. This method will return a boolean True indicates there is a match otherwise False if regex object not defined or re.search doesn’t find a match.

Parameters: builder (BuilderBase (subclass)) – instance of BuilderBase class
Returns: A boolean return True/False based on if re.search is successful or not
Return type: bool

_check_runtime(self, builder)¶: This method will return a boolean (True/False) based on runtime specified in buildspec and check with test runtime. User can specify both min and max, or just specify min or max.

_returncode_check(self, builder)¶

Check status check of returncode field if specified in status property.

Parameters: builder (BuilderBase (subclass)) – instance of BuilderBase class

check_test_state(self, builder)¶

This method is responsible for detecting state of test (PASS/FAIL) based on returncode or regular expression.

Parameters: builder (BuilderBase (subclass)) – instance of BuilderBase class

load(self)¶: Load a particular configuration based on the name. This method should set defaults for the executor, and will vary based on the class.

run(self)¶: The run step basically runs the build. This is run after setup so we are sure that the builder is defined. This is also where we set the result to return.

buildtest.executors.cobalt¶

This method implements CobaltExecutor class which is defines how cobalt executor submit job to Cobalt scheduler.

Module Contents¶

Classes¶

`CobaltExecutor`	The CobaltExecutor class is responsible for submitting jobs to Cobalt Scheduler.
`CobaltJob`	The `CobaltJob` class performs operation on cobalt job upon job submission such

Attributes¶

class buildtest.executors.cobalt.CobaltExecutor(name, settings, site_configs, max_pend_time=None)¶

The CobaltExecutor class is responsible for submitting jobs to Cobalt Scheduler. The class implements the following methods:

load: load Cobalt executors from configuration file
dispatch: submit Cobalt job to scheduler
poll: poll Cobalt job via qstat and retrieve job state
gather: gather job record including output, error, exit code

type = cobalt¶

dispatch(self, builder)¶

This method is responsible for dispatching job to Cobalt Scheduler by invoking builder.run() which runs the build script. If job is submitted to scheduler, we get the JobID and pass this to CobaltJob class. At job submission, cobalt will report the output and error file which can be retrieved using qstat. We retrieve the cobalt job record using builder.job.gather().

Parameters: builder (BuilderBase, required) – builder object

gather(self, builder)¶

This method is responsible for moving output and error file in the run directory. We need to read <JOBID>.cobaltlog file which contains output of exit code by performing a regular expression (exit code of.)(\d+)(\;). The cobalt log file will contain a line: task completed normally with an exit code of 0; initiating job cleanup and removal

Parameters: builder (BuilderBase, required) – builder object

launcher_command(self)¶

load(self)¶: Load the a Cobalt executor configuration from buildtest settings.

poll(self, builder)¶

This method is responsible for polling Cobalt job by invoking the builder method builder.job.poll(). We check the job state and existence of output file. If file exists or job is complete, we gather the results and return from function. If job is pending we check if job time exceeds max_pend_time time limit and cancel job.

Parameters: builder (BuilderBase, required) – builder object

class buildtest.executors.cobalt.CobaltJob(jobID)¶

The CobaltJob class performs operation on cobalt job upon job submission such as polling job, gather job record, cancel job. We also retrieve job state and determine if job is pending, running, complete, suspended.

cancel(self)¶: Cancel job by running qdel <jobid>. This method is called if job timer exceeds max_pend_time if job is pending.

cobalt_log(self)¶: Return job cobalt.log file

error_file(self)¶: Return job error file

exitcode(self)¶: Return job exit code

gather(self)¶

Gather Job state by running qstat -lf <jobid> which retrieves all fields.

The output is in text format which is parsed into key/value pair and stored in a dictionary. This method will return a dict containing the job record

$ qstat -lf 347106
   JobID: 347106
       JobName           : hold_job
       User              : shahzebsiddiqui
       WallTime          : 00:10:00
       QueuedTime        : 00:13:14
       RunTime           : N/A
       TimeRemaining     : N/A

`

is_cancelled(self)¶: Return True if job is cancelled otherwise returns False. Job state is cancelled which is set by class cancel method

is_complete(self)¶: Return True if job is complete otherwise returns False. Cobalt job state for completed job job is marked as exiting

is_pending(self)¶: Return True if job is pending otherwise returns False. When cobalt recieves job it is in starting followed by queued state. We check if job is in either state.

is_running(self)¶: Return True if job is running otherwise returns False. Cobalt job state for running job is is marked as running

is_suspended(self)¶: Return True if job is suspended otherwise returns False. Cobalt job state for suspended is marked as user_hold

output_file(self)¶: Return job output file

poll(self)¶: Poll job by running qstat -l --header State <jobid> which retrieves job state.

buildtest.executors.cobalt.logger¶

buildtest.executors.job¶

Module Contents¶

Classes¶

Job

This is a base class for holding job level data and common methods for used

class buildtest.executors.job.Job(jobID)¶

This is a base class for holding job level data and common methods for used for batch job submission.

abstract cancel(self)¶: Cancel job

get(self)¶: Return Job ID

abstract is_pending(self)¶: Check if job is in pending state

abstract is_running(self)¶: Check if job is in running state

abstract is_suspended(self)¶: Check if job is in suspended state

abstract poll(self)¶: Poll job and update job state.

state(self)¶

buildtest.executors.local¶

This module implements the LocalExecutor class responsible for submitting jobs to localhost. This class is called in class BuildExecutor when initializing the executors.

Module Contents¶

Classes¶

LocalExecutor

The LocalExecutor class is responsible for running tests locally for

class buildtest.executors.local.LocalExecutor(name, settings, site_configs)¶

The LocalExecutor class is responsible for running tests locally for bash, sh and python shell. The LocalExecutor runs the tests and gathers the output and error results and writes to file. This class implements load, check and run method.

type = local¶

check(self)¶: Check if shell binary is available

load(self)¶: Load a particular configuration based on the name. This method should set defaults for the executor, and will vary based on the class.

run(self, builder)¶

This method is responsible for running test for LocalExecutor which runs test locally. We keep track of metadata in builder.metadata that keeps track of run result. The output and error file are written to filesystem.

Parameters: builder (BuilderBase, required) – builder object

write_testresults(self, builder)¶

Upon execution of tests we write stdout and stderr to output and error file.

Parameters: builder (BuilderBase, required) – builder object

buildtest.executors.lsf¶

This module implements the LSFExecutor class responsible for submitting jobs to LSF Scheduler. This class is called in class BuildExecutor when initializing the executors.

Module Contents¶

Classes¶

`LSFExecutor`	The LSFExecutor class is responsible for submitting jobs to LSF Scheduler.
`LSFJob`	This is a base class for holding job level data and common methods for used

Attributes¶

class buildtest.executors.lsf.LSFExecutor(name, settings, site_configs, max_pend_time=None)¶

The LSFExecutor class is responsible for submitting jobs to LSF Scheduler. The LSFExecutor performs the following steps

load: load lsf configuration from buildtest configuration file
dispatch: dispatch job to scheduler and acquire job ID
poll: wait for LSF jobs to finish
gather: Once job is complete, gather job data

type = lsf¶

dispatch(self, builder)¶

This method is responsible for dispatching job to scheduler and extracting job ID by applying a re.search against output at onset of job submission. If job id is not retrieved due to job failure or unable to match regular expression we mark job incomplete by invoking builder.incomplete() method and return from method.

If we have a valid job ID we invoke LSFJob class given the job id to poll job and store this into builder.job attribute.

Parameters: builder (BuilderBase, required) – builder object

gather(self, builder)¶

Gather Job detail after completion of job by invoking the builder method builder.job.gather(). We retrieve exit code, output file, error file and update builder metadata.

Parameters: builder (BuilderBase, required) – builder object

launcher_command(self)¶: This command returns the launcher command and any options specified in configuration file. This is useful when generating the build script in the BuilderBase class

load(self)¶: Load the a LSF executor configuration from buildtest settings.

poll(self, builder)¶

Given a builder object we poll the job by invoking builder method builder.job.poll() return state of job. If job is suspended or pending we stop timer and check if timer exceeds max_pend_time value which could be defined in configuration file or passed via command line --max-pend-time

Parameters: builder (BuilderBase, required) – builder object

class buildtest.executors.lsf.LSFJob(jobID)¶

This is a base class for holding job level data and common methods for used for batch job submission.

cancel(self)¶: Cancel LSF Job by running bkill <jobid>. This is called if job has exceeded max_pend_time limit during poll stage.

error_file(self)¶: Return job error file

exitcode(self)¶: Return job exit code

gather(self)¶

Gather Job record at onset of job completion by running bjobs -o '<format1> <format2>' <jobid> -json. The format fields extracted from job are the following:

“job_name”

“stat”

“user”

“user_group”

“queue”

“proj_name”

“pids”

“exit_code”

“from_host”

“exec_host”

“submit_time”

“start_time”

“finish_time”

“nthreads”

“exec_home”

“exec_cwd”

“output_file”

“error_file”

Shown below is the output format and we retrieve the job records defined in RECORDS property

$ bjobs -o 'job_name stat user user_group queue proj_name pids exit_code from_host exec_host submit_time start_time finish_time nthreads exec_home exec_cwd output_file error_file' 58652 -json
{
  "COMMAND":"bjobs",
  "JOBS":1,
  "RECORDS":[
    {
      "JOB_NAME":"hold_job",
      "STAT":"PSUSP",
      "USER":"shahzebsiddiqui",
      "USER_GROUP":"GEN014ECPCI",
      "QUEUE":"batch",
      "PROJ_NAME":"GEN014ECPCI",
      "PIDS":"",
      "EXIT_CODE":"",
      "FROM_HOST":"login1",
      "EXEC_HOST":"",
      "SUBMIT_TIME":"May 28 12:45",
      "START_TIME":"",
      "FINISH_TIME":"",
      "NTHREADS":"",
      "EXEC_HOME":"",
      "EXEC_CWD":"",
      "OUTPUT_FILE":"hold_job.out",
      "ERROR_FILE":"hold_job.err"
    }
  ]
}

is_complete(self)¶: Check if Job is complete which is in DONE state. Return True if there is a match otherwise return False

is_failed(self)¶: Check if Job failed. We return True if job is in EXIT state otherwise return False

is_pending(self)¶: Check if Job is pending which is reported by LSF as PEND. Return True if there is a match otherwise returns False

is_running(self)¶: Check if Job is running which is reported by LSF as RUN. Return True if there is a match otherwise returns False

is_suspended(self)¶: Check if Job is in suspended state which could be in any of the following states: [PSUSP, USUSP, SSUSP]. We return True if job is in one of the states otherwise return False

output_file(self)¶: Return job output file

poll(self)¶

Given a job id we poll the LSF Job by retrieving its job state, output file, error file and exit code. We run the following commands to retrieve following states

Job State: bjobs -noheader -o 'stat' <JOBID>
Output File: bjobs -noheader -o 'output_file' <JOBID>'
Error File: bjobs -noheader -o 'error_file' <JOBID>'
Exit Code File: bjobs -noheader -o 'EXIT_CODE' <JOBID>'

buildtest.executors.lsf.logger¶

buildtest.executors.pbs¶

This module implements PBSExecutor class that defines how executors submit job to PBS Scheduler

Module Contents¶

Classes¶

`PBSExecutor`	The PBSExecutor class is responsible for submitting jobs to PBS Scheduler.
`PBSJob`	See https://www.altair.com/pdfs/pbsworks/PBSReferenceGuide2021.1.pdf section 8.1 for Job State Codes

Attributes¶

class buildtest.executors.pbs.PBSExecutor(name, settings, site_configs, max_pend_time=None)¶

The PBSExecutor class is responsible for submitting jobs to PBS Scheduler. The class implements the following methods:

load: load PBS executors from configuration file dispatch: submit PBS job to scheduler poll: poll PBS job via qstat and retrieve job state gather: gather job result cancel: cancel job if it exceeds max pending time

poll_cmd = qstat¶

type = pbs¶

dispatch(self, builder)¶

This method is responsible for dispatching PBS job, get JobID and start record metadata in builder object. If job failed to submit we check returncode and exit with failure. After we submit job, we start timer and record when job was submitted and poll job once to get job details and store them in builder object.

Parameters: builder (BuilderBase, required) – builder object

gather(self, builder)¶

This method is responsible for getting output of job using qstat -x -f -F json <jobID> and storing the result in builder object. We retrieve specific fields such as exit status, start time, end time, runtime and store them in builder object. We read output and error file and store the content in builder object.

Parameters: builder (BuilderBase, required) – builder object

launcher_command(self)¶

load(self)¶: Load the a Cobalt executor configuration from buildtest settings.

poll(self, builder)¶

This method is responsible for polling Cobalt job, we check the job state and existence of output file. If file exists or job is in ‘exiting’ stage we set job to ‘done’ stage and gather results. If job is in ‘pending’ stage we check if job exceeds ‘max_pend_time’ time limit by checking with builder timer attribute using start and stop method. If job exceeds the time limit job is cancelled.

Parameters: builder (BuilderBase, required) – builder object

class buildtest.executors.pbs.PBSJob(jobID)¶

See https://www.altair.com/pdfs/pbsworks/PBSReferenceGuide2021.1.pdf section 8.1 for Job State Codes

cancel(self)¶: Cancel job

error_file(self)¶

exitcode(self)¶

fail(self)¶

gather(self)¶

is_complete(self)¶

is_pending(self)¶: Check if job is in pending state

is_running(self)¶: Check if job is in running state

is_suspended(self)¶: Check if job is in suspended state

output_file(self)¶

poll(self)¶: Poll job and update job state.

success(self)¶: This method determines if job was completed successfully. According to https://www.altair.com/pdfs/pbsworks/PBSAdminGuide2021.1.pdf section 14.9 Job Exit Status Codes we have the following:

Exit Code: X < 0 - Job could not be executed Exit Code: 0 <= X < 128 - Exit value of Shell or top-level process Exit Code: X >= 128 - Job was killed by signal

Exit Code 0 is a success

buildtest.executors.pbs.logger¶

buildtest.executors.setup¶

This module is responsible for setup of executors defined in buildtest configuration. The BuildExecutor class initializes the executors and chooses the executor class (LocalExecutor, LSFExecutor, SlurmExecutor, CobaltExecutor) to call depending on executor name.

Module Contents¶

Classes¶

BuildExecutor

A BuildExecutor is responsible for initialing executors from buildtest configuration

Attributes¶

class buildtest.executors.setup.BuildExecutor(site_config, max_pend_time=None)¶

A BuildExecutor is responsible for initialing executors from buildtest configuration file which provides a list of executors. This class keeps track of all executors and provides the following methods:

setup: This method will write executor’s before_script.sh that is sourced in each test upon calling executor. run: Responsible for invoking executor’s run method based on builder object which is of type BuilderBase. poll: This is responsible for invoking poll method for corresponding executor from the builder object by checking job state

__repr__(self)¶: Return repr(self).

__str__(self)¶: Return str(self).

_choose_executor(self, builder)¶

Choose executor is called at the onset of a run and poll stage. Given a builder object we retrieve the executor property builder.executor of the builder and check if there is an executor object and of type BaseExecutor.

Parameters: builder (BuilderBase (subclass), required.) – the builder with the loaded Buildspec.

get(self, name)¶: Given the name of an executor return the executor object which is of subclass of BaseExecutor

is_cobalt(self, executor_type)¶

is_local(self, executor_type)¶

is_lsf(self, executor_type)¶

is_pbs(self, executor_type)¶

is_slurm(self, executor_type)¶

list_executors(self)¶

poll(self, builders)¶

The poll stage is called after the run stage for builders that require job submission through a batch executor. Given a set of builders object which are instance of BuilderBase, we select the executor object and invoke the poll method for the executor.

If job is pending, running, suspended we poll job
If job is complete we gather job results and mark job complete
Otherwise we mark job incomplete and it will be ignored by buildtest in reporting

Poll all jobs for batch executors (LSF, Slurm, Cobalt, PBS). For slurm we poll until job is in PENDING or RUNNING state. If Slurm job is in FAILED or COMPLETED state we assume job is finished and we gather results. If its in any other state we ignore job and return out of method.

For LSF jobs we poll job if it’s in PEND or RUN state, if its in DONE state we gather results, otherwise we assume job is incomplete and return with ignore_job set to True. This informs buildtest to ignore job when showing report.

For Cobalt jobs, we poll if its in starting, queued, or running state. For Cobalt jobs we cannot query job after its complete since JobID is no longer present in queuing system. Therefore, for when job is complete which is done or exiting state, we mark job is complete.

For PBS jobs we poll job if its in queued or running stage which corresponds to Q and R in job stage. If job is finished (F) we gather results. If job is in H stage we automatically cancel job otherwise we ignore job and mark job complete.

Parameters: builder (list , required) – a list of builder objects for polling. Each element is an instance of BuilderBase (subclass)
Returns: Return a list of builders
Return type: list

run(self, builder)¶

This method implements the executor run implementation. Given a builder object we first detect the correct executor object to use and invoke its run method. The executor object is a sub-class of BaseExecutor (i.e LocalExecutor, SlurmExecutor, LSFExecutor,…).

Parameters: builder (BuilderBase (subclass), required.) – the builder with the loaded test configuration.

setup(self)¶: This method creates directory var/executors/<executor-name> for every executor defined in buildtest configuration and write scripts before_script.sh if the field before_script is specified in executor section. This method is called after executors are initialized in the class __init__ method.

buildtest.executors.setup.logger¶

buildtest.executors.slurm¶

This module implements the SlurmExecutor class responsible for submitting jobs to Slurm Scheduler. This class is called in class BuildExecutor when initializing the executors.

Module Contents¶

Classes¶

`SlurmExecutor`	The SlurmExecutor class is responsible for submitting jobs to Slurm Scheduler.
`SlurmJob`	This is a base class for holding job level data and common methods for used

Attributes¶

class buildtest.executors.slurm.SlurmExecutor(name, settings, site_configs, max_pend_time=None)¶

The SlurmExecutor class is responsible for submitting jobs to Slurm Scheduler. The SlurmExecutor performs the following steps:

load: load slurm configuration from buildtest configuration file

dispatch: dispatch job to scheduler and acquire job ID

poll: wait for Slurm jobs to finish, if job is pending and exceeds max_pend_time then cancel job

gather: Once job is complete, gather job data

type = slurm¶

dispatch(self, builder)¶

This method is responsible for dispatching job to slurm scheduler and extracting job id. If job id is valid we pass the job to SlurmJob class and store object in builder.job.

Parameters: builder (BuilderBase, required) – builder object

gather(self, builder)¶

Gather Slurm job data after job completion. In this step we call builder.job.gather(), and update builder metadata such as returncode, output and error file.

Parameters: builder (BuilderBase (subclass), required) – instance of BuilderBase

launcher_command(self)¶: Return sbatch launcher command with options used to submit job

load(self)¶: Load the a slurm executor configuration from buildtest settings.

poll(self, builder)¶

This method is called during poll stage where we invoke builder.job.poll() to get updated job state. If job is pending or suspended we stop timer and check if job needs to be cancelled if time exceeds max_pend_time value.

Parameters: builder (BuilderBase, required) – builder object

class buildtest.executors.slurm.SlurmJob(jobID, cluster=None)¶

This is a base class for holding job level data and common methods for used for batch job submission.

cancel(self)¶: Cancel job by running scancel <jobid>. If job is specified to a slurm cluster we cancel job using scancel <jobid> --clusters=<cluster>. This method is called if job exceeds max_pend_time.

complete(self)¶: This method is used for gathering job result we assume job is complete if it’s in any of the following state: COMPLETED, FAILED, OUT_OF_MEMORY, TIMEOUT

exitcode(self)¶: Return job exit code

gather(self)¶

Gather job record which is called after job completion. We use sacct to gather job record and return the job record as a dictionary. The command we run is sacct -j <jobid> -X -n -P -o <field1>,<field2>,...,<fieldN>. We retrieve the following format fields from job record:

“Account”

“AllocNodes”

“AllocTRES”

“ConsumedEnergyRaw”

“CPUTimeRaw”

“Elapsed”

“End”

“ExitCode”

“JobID”

“JobName”

“NCPUS”

“NNodes”

“QOS”

“ReqGRES”

“ReqMem”

“ReqNodes”

“ReqTRES”

“Start”

“State”

“Submit”

“UID”

“User”

“WorkDir”

The output of sacct is parseable using the pipe symbol (|) and stored into a dict

$ sacct -j 42909266 -X -n -P -o Account,AllocNodes,AllocTRES,ConsumedEnergyRaw,CPUTimeRaw,Elapsed,End,ExitCode,JobID,JobName,NCPUS,NNodes,QOS,ReqGRES,ReqMem,ReqNodes,ReqTRES,Start,State,Submit,UID,User,WorkDir --clusters=cori
nstaff|1|billing=272,cpu=272,energy=262,mem=87G,node=1|262|2176|00:00:08|2021-05-27T18:47:49|0:0|42909266|slurm_metadata|272|1|debug_knl|PER_NODE:craynetwork:1|87Gn|1|billing=1,cpu=1,node=1|2021-05-27T18:47:41|COMPLETED|2021-05-27T18:44:07|92503|siddiq90|/global/u1/s/siddiq90/.buildtest/tests/cori.slurm.knl_debug/metadata/slurm_metadata/0/stage

is_cancelled(self)¶: If job is cancelled return True otherwise return False. Slurm will report CANCELLED for job state.

is_complete(self)¶: If job is complete return True otherwise return False. Slurm will report COMPLETED for job state.

is_failed(self)¶: If job failed return True otherwise return False. Slurm will report FAILED for job state.

is_out_of_memory(self)¶: If job is out of memory return True otherwise return False. Slurm will report OUT_OF_MEMORY for job state.

is_pending(self)¶: If job is pending return True otherwise return False. Slurm Job state for pending is PENDING.

is_running(self)¶: If job is running return True otherwise return False. Slurm will report RUNNING for job state.

is_suspended(self)¶: If job is suspended return True otherwise return False. Slurm will report SUSPENDED for job state.

is_timeout(self)¶: If job timed out return True otherwise return False. Slurm will report TIMEOUT for job state.

poll(self)¶

Poll job to extract job state and exit code. We also retrieve job work directory. We run the following commands to retrieve the following properties.

Job State: sacct -j <jobid> -o State -n -X -P

ExitCode and Workdir: sacct -j <jobid> -X -n -P -o ExitCode,Workdir

state(self)¶: Return job state

workdir(self)¶: Return job work directory

buildtest.executors.slurm.logger¶

`buildtest.schemas`¶

Submodules¶

buildtest.schemas.defaults¶

Module Contents¶

Functions¶

custom_validator(recipe, schema)

This is a custom validator for validating JSON documents. We implement a

Attributes¶

`here`
`resolver`
`schema_store`
`schema_table`

buildtest.schemas.defaults.custom_validator(recipe, schema)¶

This is a custom validator for validating JSON documents. We implement a custom resolver for finding json schemas locally by implementing a schema store. The input arguments recipe and schema is your input JSON recipe and schema content for validating the recipe. This method uses Draft7Validator for validating schemas.

Parameters

recipe (dict) – Input recipe as JSON document
schema (dict) – Input JSON Schema content to validate JSON document

buildtest.schemas.defaults.here¶

buildtest.schemas.defaults.resolver¶

buildtest.schemas.defaults.schema_store¶

buildtest.schemas.defaults.schema_table¶

buildtest.schemas.utils¶

Utility and helper functions for schemas.

Module Contents¶

Functions¶

`load_recipe`(path)	Load a yaml recipe file. The file must be in .yml extension
`load_schema`(path)	Load a json schema file, the file extension must be ‘.schema.json’

Attributes¶

here

buildtest.schemas.utils.here¶

buildtest.schemas.utils.load_recipe(path)¶

Load a yaml recipe file. The file must be in .yml extension for buildtest to load.

Parameters: path (str) – the path to the recipe file.

buildtest.schemas.utils.load_schema(path)¶

Load a json schema file, the file extension must be ‘.schema.json’

Parameters: path (str) – the path to the schema file.

`buildtest.utils`¶

Submodules¶

buildtest.utils.command¶

Module Contents¶

Classes¶

`BuildTestCommand`	Class method to invoke shell commands and retrieve output and error.
`Capturing`	capture output from stdout and stderr into capture object.

class buildtest.utils.command.BuildTestCommand(cmd=None)¶

Class method to invoke shell commands and retrieve output and error. This class is inspired and derived from utils functions in https://github.com/vsoch/scif

decode(self, line)¶: Given a line of output (error or regular) decode using the system default, if appropriate

execute(self)¶: Execute a system command and return output and error. :param cmd: shell command to execute :type cmd: str, required :return: Output and Error from shell command :rtype: two str objects

get_command(self)¶: Returns the executed command :rtype: str

get_error(self)¶: Returns the error from shell command :rtype: str

get_output(self)¶: Returns the output from shell command :rtype: str

returncode(self)¶: Returns the return code from shell command :rtype: int

set_command(self, cmd)¶: parse is called when a new command is provided to ensure we have a list. We don’t check that the executable is on the path, as the initialization might not occur in the runtime environment.

class buildtest.utils.command.Capturing¶

capture output from stdout and stderr into capture object. This is based off of github.com/vsoch/gridtest but modified to write files. The stderr and stdout are set to temporary files at the init of the capture, and then they are closed when we exit. This means expected usage looks like:

with Capturing() as capture:: process = subprocess.Popen(…)

And then the output and error are retrieved from reading the files: and exposed as properties to the client:

capture.out capture.err

And cleanup means deleting these files, if they exist.

__enter__(self)¶

__exit__(self, *args)¶

cleanup(self)¶

property err(self)¶: Return error stream. Returns empty string if empty or doesn’t exist. Returns (str) : error stream written to file

property out(self)¶: Return output stream. Returns empty string if empty or doesn’t exist. Returns (str) : output stream written to file

set_stderr(self)¶

set_stdout(self)¶

buildtest.utils.file¶

This module provides some generic file and directory level operation that include the following: 1. Check if path is a File or Directory via is_file(), is_dir() 2. Create a directory via create_dir() 3. Walk a directory tree based on single extension using walk_tree() 4. Resolve path including shell and user expansion along with getting realpath to file using resolve_path() 5. Read and write a file via read_file(), write_file()

Module Contents¶

Functions¶

`create_dir`(dirname)	Create a directory if it doesn’t exist. If directory contains variable
`is_dir`(dirname)	This method will check if a directory exist. If directory found we return
`is_file`(fname)	This method will check if file exist, if so returns True otherwise returns False
`load_json`(fname)	Given a filename, resolves full path to file and loads json file. This method will
`read_file`(filepath)	This method is used to read a file specified by argument `filepath`.
`remove_file`(fpath)	This method is responsible for removing a file. The input path is an absolute path
`resolve_path`(path, exist=True)	This method will resolve a file path to account for shell expansion and resolve paths in
`walk_tree`(root_dir, ext=None)	This method will traverse a directory tree and return list of files
`write_file`(filepath, content)	This method is used to write an input `content` to a file specified by

buildtest.utils.file.create_dir(dirname)¶

Create a directory if it doesn’t exist. If directory contains variable expansion ($HOME), user expansion (~) we resolve this before creating directory. If there is an error creating directory we raise an exception

Parameters: dirname (str, required) – directory path to create
Returns: creates the directory or print an exception message upon failure
Return type: Catches exception of type OSError

buildtest.utils.file.is_dir(dirname)¶

This method will check if a directory exist. If directory found we return True otherwise False.

Parameters: dir (str, required) – directory path
Returns: returns a boolean True/False depending on if input is a valid directory.
Return type: bool

buildtest.utils.file.is_file(fname)¶

This method will check if file exist, if so returns True otherwise returns False

Parameters: file (str, required) – file path
Returns: returns a boolean True/False depending on if input is a valid file.
Return type: bool

buildtest.utils.file.load_json(fname)¶: Given a filename, resolves full path to file and loads json file. This method will catch exception json.JSONDecodeError and raise an exception with useful message. If there is no error we return content of json file

buildtest.utils.file.read_file(filepath)¶

This method is used to read a file specified by argument filepath. If filepath is not a string we raise an error. We also run resolve_path to get realpath to file and account for shell or user expansion. The return from resolve_path will be a valid file or None so we check if input is an invalid file. Finally we read the file and return the content of the file as a string.

Parameters: filepath (str, required) – file name to read
Raises: BuildTestError: If filepath is not a string BuildTestError: If filepath is not valid file
Returns: return content of file as a string
Return type: str

buildtest.utils.file.remove_file(fpath)¶

This method is responsible for removing a file. The input path is an absolute path to file. We check for exceptions first, and return immediately before removing file.

Parameters: fpath (str, required) – full path to file

buildtest.utils.file.resolve_path(path, exist=True)¶

This method will resolve a file path to account for shell expansion and resolve paths in when a symlink is provided in the file. This method assumes file already exists.

Parameters: path (str, required) – file path to resolve
Returns: return realpath to file if found otherwise return None
Return type: str or None

buildtest.utils.file.walk_tree(root_dir, ext=None)¶

This method will traverse a directory tree and return list of files based on extension type. This method invokes is_dir() to check if directory exists before traversal.

Parameters:

Parameters

root_dir (str, required) – directory path to traverse
ext (str, optional) – file extensions to search in traversal

Returns

returns a list of file paths

Return type

list

buildtest.utils.file.write_file(filepath, content)¶

This method is used to write an input content to a file specified by filepath. Both filepath and content must be a str. An error is raised if filepath is not a string or a directory. If ``content is not a str, we return None since we can’t process the content for writing. Finally, we write the content to file and return. A successful write will return nothing otherwise an exception will occur during the write process.

Parameters

filepath (str, required) – file name to write
content (str, required) – content to write to file

Raises

BuildTestError: System error if filepath is not string BuildTestError: System error if filepath is a directory

Returns

Return nothing if write is successful. A system error if filepath is not str or directory. If argument content is not str we return None

buildtest.utils.shell¶

Module Contents¶

Classes¶

Shell

class buildtest.utils.shell.Shell(shell='bash')¶

valid_shells = ['bash', 'sh', 'zsh', 'csh', 'tcsh', '/bin/bash', '/bin/csh', '/bin/sh', '/bin/tcsh',...¶

__repr__(self)¶: Return repr(self).

__str__(self)¶: Return str(self).

get(self)¶: Return shell attributes as a dictionary

property opts(self)¶: retrieve the shell opts that are set on init, and updated with setter

property path(self)¶

This method returns the full path to shell program using shutil.which() If shell program is not found we raise an exception. The shebang is is updated assuming path is valid which is just adding character ‘#!’ in front of path. The return is full path to shell program. This method automatically updates the shell path when there is a change in attribute self.name

>>> shell = Shell("bash")
>>> shell.path
'/usr/bin/bash'
>>> shell.name="sh"
>>> shell.path
'/usr/bin/sh'

buildtest.utils.timer¶

Module Contents¶

Classes¶

Timer

class buildtest.utils.timer.Timer¶

start(self)¶: Start a new timer

stop(self)¶: Stop the timer, and report the elapsed time

exception buildtest.utils.timer.TimerError¶

Bases: Exception

A custom exception used to report errors in use of Timer class

buildtest.utils.tools¶

Module Contents¶

Classes¶

Hasher

dict() -> new empty dictionary

Functions¶

deep_get(dictionary, *keys)

class buildtest.utils.tools.Hasher¶

Bases: dict

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:: d = {} for k, v in iterable:

d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs: in the keyword argument list. For example: dict(one=1, two=2)

__missing__(self, key)¶

__str__(self)¶: Return str(self).

get(self, path, sep='.', default=None)¶: D.get(k[,d]) -> D[k] if k in D, else d. d defaults to None.

buildtest.utils.tools.deep_get(dictionary, *keys)¶

Submodules¶

`buildtest.config`¶

Module Contents¶

Classes¶

SiteConfiguration

This class is an interface to buildtest configuration

Attributes¶