buildtest.cli.buildspec

Module Contents

Classes

BuildspecCache

The initializer method for BuildspecCache class is responsible for loading and finding buildspecs into buildspec cache. First we

Functions

edit_buildspec_test(test_names, configuration, editor)

Open a list of test names in editor mode defined by EDITOR environment otherwise resort to vim.

edit_buildspec_file(buildspecs, configuration, editor)

Open buildspec in editor and validate buildspec with parser. This method is invoked by command buildtest buildspec edit-file.

show_buildspecs(test_names, configuration[, theme])

This is the entry point for buildtest buildspec show command which will print content of

show_failed_buildspecs(configuration[, test_names, ...])

This is the entry point for buildtest buildspec show-fail command which will print content of

buildspec_validate(configuration[, buildspecs, ...])

Entry point for buildtest buildspec validate. This method is responsible for discovering buildspec

summarize_buildspec_cache(pager, configuration[, color])

entry point for buildtest buildspec summary

summary_print(configuration[, color])

Prints summary of buildspec cache which is run via command buildtest buildspec summary

buildspec_maintainers(configuration[, breakdown, ...])

Entry point for buildtest buildspec maintainers command.

buildspec_find(args, configuration)

Entry point for buildtest buildspec find command

Attributes

logger

buildtest.cli.buildspec.logger
class buildtest.cli.buildspec.BuildspecCache(configuration, rebuild=False, filterfields=None, formatfields=None, roots=None, header=None, terse=None, pager=None, color=None, count=None, row_count=None)[source]

The initializer method for BuildspecCache class is responsible for loading and finding buildspecs into buildspec cache. First we resolve paths to directory where buildspecs will be searched. This can be specified via --roots option on command line or one can specify directory paths in the configuration file. Next we build the cache that contains metadata for each buildspec that will be written to file. If any filter or format options are specified we check if they are valid and finally display a content of the cache depending on the argument.

This method is called when using buildtest buildspec find command.

Parameters:
  • configuration (buildtest.config.SiteConfiguration) – Instance of SiteConfiguration class that is loaded buildtest configuration.

  • rebuild (bool, optional) – rebuild the buildspec cache by validating all buildspecs when using buildtest buildspec find --rebuild. Defaults to False if --rebuild is not specified

  • filterfields (str, optional) – The filter options specified via buildtest buildspec find --filter that contains list of key value pairs for filtering buildspecs

  • formatfields (str, optional) – The format options used for formating table. The format option is a comma separated list of format fields specified via buildtest buildspec find --format

  • roots (list, optional) – List of directories to search for buildspecs. This argument contains value of buildtest buildspec find --roots

  • headers (bool, optional) – Option to control whether header are printed in terse output. This argument contains value of buildtest buildspec find --no-header

  • terse (bool, optional) – Enable terse mode when printing output. In this mode we don’t print output in table format instead output is printed in parseable format. This option can be specified via buildtest buildspec find --terse

  • color (str, optional) – An instance of a string class that selects the color to use when printing table output

  • count (int, optional) – Number of entries to display in output. This argument contains value of buildtest buildspec find --count

  • row_count (bool, optional) – Print total number of records from the table

table
filter_fields = ['type', 'executor', 'tags', 'buildspec']
default_format_fields = ['name', 'type', 'executor', 'tags', 'description']
format_fields
get_cache()[source]

Returns cache file as loaded dictionary

load_paths()[source]

Add all paths to search for buildspecs. We read configuration file and check whether we need to load buildspecs from list of directories. We check if directories exist, if any fail we don’t add them to path. If no root directories are specified we load the default buildspec roots which are tutorials and general_tests directory.

build()[source]

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

_discover_buildspecs()[source]

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

_write_buildspec_cache()[source]

This method is responsible for writing buildspec cache to file

_validate_buildspecs(buildspecs)[source]

Given a list of buildspec files, validate each buildspec using buildtest.buildsystem.parser.BuildspecParser class and return a list of valid buildspecs. Any invalid buildspecs are added to separate list

Parameters:

buildspecs – A list of buildspec to validate

get_names()[source]

Return a list of test names found in buildspec cache. We only return test names for valid buildspecs

get_random_tests(num_items=1)[source]

Returns a list of random test names from the list of available test. The test are picked using random.sample

Parameters:

num_items (int, optional) – Number of test items to retrieve

lookup_buildspec_by_name(name)[source]

Given an input test name, return corresponding buildspec file found in the cache.

Parameters:

name (str) – Name of test to query in cache

Returns:

Return path to buildspec that contains name of test

build_cache()[source]

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

_check_filter_fields()[source]

This method checks filter fields are valid. The filter fields are specified as buildtest buildspec find --filter <KEY1>=<VAL1>,<KEY2>=<VAL2>,...

Raises:

BuildTestError – If there is an invalid filter field

_check_format_fields()[source]

This method will check if all format fields are valid. Format fields are passed as comma separated fields: --format field1,field2,field3,...

Raises:

BuildTestError – If there is an invalid format field

_filter_buildspecs(executor, tags, schema_type)[source]

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) – executor property in buildspec

  • tags (list) – List of tagnames specified via `tags` property in buildspec

  • schema_type (str) – type property in buildspec

Returns:

Return True if there is no match otherwise returns False

Return type:

bool

find_buildspecs()[source]

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.

Raises:

BuildTestError – Raises exception if input buildspec for buildtest buildspec find --filter buildspec is invalid path or directory or buildspec not found in cache.

get_valid_buildspecs()[source]

Return a list of valid buildspecs

get_invalid_buildspecs()[source]

Return a list of invalid buildspecs

get_unique_tags()[source]

Return a list of unique tags.

get_unique_executors()[source]

Return a list of unique executors.

get_maintainers()[source]

Return a list of maintainers.

get_paths()[source]

Return a list of search paths

tag_breakdown()[source]

This method will return a breakdown of tags by test names.

executor_breakdown()[source]

This method will return a dictionary with breakdown of executors by test names.

test_breakdown_by_buildspec()[source]

This method will return a dictionary with breakdown of buildspecs by test names.

print_buildspecfiles(terse=None, header=None, row_count=None, count=None)[source]

This method implements buildtest buildspec find --buildspec which reports all buildspec files in cache.

Parameters:
  • terse (bool, optional) – This argument will print output in terse format if --terse option is specified otherwise will print output in table format

  • header (bool, optional) – This argument controls whether header will be printed in terse format. If --terse option is not specified this argument has no effect. This argument holds the value of --no-header option

  • row_count (bool, optional) – Print total number of records from the table

  • count (int, optional) – Number of entries to display in output. This argument contains value of buildtest buildspec find --count

print_tags(row_count=None, count=None, terse=None, header=None)[source]

This method implements buildtest buildspec find --tags which reports a list of unique tags from all buildspecs in cache file.

Parameters:
  • row_count (bool, optional) – Print total number of records from the table

  • count (int, optional) – Number of entries to display in output. This argument contains value of buildtest buildspec find --count

  • terse (bool, optional) – This argument will print output in terse format if --terse option is specified otherwise will print output in table format

  • header (bool, optional) – This argument controls whether header will be printed in terse format. If --terse option is not specified this argument has no effect. This argument holds the value of --no-header option

print_executors(row_count=None, count=None, terse=None, header=None)[source]

This method implements buildtest buildspec find --executors which reports all executors from cache.

Parameters:
  • row_count (bool, optional) – Print total number of records from the table

  • count (int, optional) – Number of entries to display in output. This argument contains value of buildtest buildspec find --count

  • terse (bool, optional) – This argument will print output in terse format if --terse option is specified otherwise will print output in table format

  • header (bool, optional) – This argument controls whether header will be printed in terse format. If --terse option is not specified this argument has no effect. This argument holds the value of --no-header option

print_by_executors(row_count=None, count=None, terse=None, header=None)[source]

This method prints executors by tests and implements buildtest buildspec find --group-by-executor command

Parameters:
  • row_count (bool, optional) – Print total number of records from the table

  • count (int, optional) – Number of entries to display in output. This argument contains value of buildtest buildspec find --count

  • terse (bool, optional) – This argument will print output in terse format if --terse option is specified otherwise will print output in table format

  • header (bool, optional) – This argument controls whether header will be printed in terse format. If --terse option is not specified this argument has no effect. This argument holds the value of --no-header option

print_by_tags(count=None, row_count=None, terse=None, header=None)[source]

This method prints tags by tests and implements buildtest buildspec find --group-by-tags command :param count: Number of entries to display in output. This argument contains value of buildtest buildspec find --count :type count: int, optional :param row_count: Print total number of records from the table :type row_count: bool, optional :param terse: This argument will print output in terse format if --terse option is specified otherwise will print output in table format :type terse: bool, optional :param header: This argument controls whether header will be printed in terse format. If --terse option is not specified this argument has no effect. This argument holds the value of --no-header option :type header: bool, optional

_print_terse_format(tdata)[source]

This method will print the output of buildtest buildspec find in terse format.

Parameters:

tdata (list) – Table data to print in terse format

Returns:

print_buildspecs(terse=None, header=None, quiet=None, row_count=None, count=None)[source]

Print buildspec table. This method is typically called when running buildtest buildspec find or options with --filter and --format.

Parameters:
  • terse (bool, optional) – This argument will print output in terse format if --terse option is specified otherwise will print output in table format

  • header (bool, optional) – This argument controls whether header will be printed in terse format. If --terse option is not specified this argument has no effect. This argument holds the value of --no-header option

  • quiet (bool, optional) – If this option is set we return immediately and don’t anything. This is specified via buildtest buildspec find --quiet which can be useful when rebuilding cache without displaying output

  • row_count (bool, optional) – Print total number of records from the table

  • count (int, optional) – Number of entries to display in output. This argument contains value of buildtest buildspec find --count

list_maintainers()[source]

Return a list of maintainers

print_maintainer()[source]

This method prints maintainers from buildspec cache file which implements buildtest buildspec maintainers command.

print_maintainers_find(name)[source]

Display a list of buildspec files associated to a given maintainer. This command is used when running buildtest buildspec maintainers find

Parameters:

name (str) – Name of maintainer specified via buildtest buildspec maintainers find <name>

print_maintainers_by_buildspecs()[source]

This method prints maintainers breakdown by buildspecs. This method implements buildtest buildspec maintainers --breakdown.

print_invalid_buildspecs(error=None, terse=None, header=None, row_count=None)[source]

Print invalid buildspecs from cache file. This method implements command buildtest buildspec find invalid

Parameters:
  • error (bool, optional) – Display error messages for invalid buildspecs. Default is False where we only print list of invalid buildspecs

  • terse (bool, optional) – Display output in machine readable format.

  • header (bool, optional) – Determine whether to print header column in machine readable format.

  • row_count (bool, optional) – Display row count of invalid buildspces table

print_filter_fields()[source]

This method prints filter fields available for buildspec cache. This method implements command buildtest buildspec find --helpfilter

print_format_fields()[source]

This method prints format fields available for buildspec cache. This method implements command buildtest buildspec find --helpformat

print_raw_filter_fields()[source]

This method prints the raw filter fields available for buildspec cache. This method implements command buildtest buildspec find --filterfields

print_raw_format_fields()[source]

This method prints the raw format fields available for buildspec cache. This method implements command buildtest buildspec find --formatfields

print_paths()[source]

This method print buildspec paths, this implements command buildtest buildspec find --paths

buildtest.cli.buildspec.edit_buildspec_test(test_names, configuration, editor)[source]

Open a list of test names in editor mode defined by EDITOR environment otherwise resort to vim. This method will search for buildspec cache and find path to buildspec file corresponding to test name and open file in editor. If multiple test are specified via buildtest buildspec edit-test then each file will be open and upon closing file, the next file will be open for edit until all files are written.

Parameters:
  • test_names (list) – A list of test names to open in editor

  • configuration (buildtest.config.SiteConfiguration) – An instance of SiteConfiguration class

  • editor (str) – Path to editor to use when opening file

buildtest.cli.buildspec.edit_buildspec_file(buildspecs, configuration, editor)[source]

Open buildspec in editor and validate buildspec with parser. This method is invoked by command buildtest buildspec edit-file.

Parameters:
  • buildspec (str) – Path to buildspec file to edit

  • configuration (buildtest.config.SiteConfiguration) – An instance of SiteConfiguration class

  • editor (str) – Path to editor to use when opening file

buildtest.cli.buildspec.show_buildspecs(test_names, configuration, theme=None)[source]

This is the entry point for buildtest buildspec show command which will print content of buildspec based on name of test.

Parameters:
buildtest.cli.buildspec.show_failed_buildspecs(configuration, test_names=None, report_file=None, theme=None)[source]

This is the entry point for buildtest buildspec show-fail command which will print content of buildspec on name of all failed tests if a list of test names are not speficied

Parameters:
buildtest.cli.buildspec.buildspec_validate(configuration, buildspecs=None, excluded_buildspecs=None, tags=None, executors=None)[source]

Entry point for buildtest buildspec validate. This method is responsible for discovering buildspec with same options used for building buildspecs that includes --buildspec, --exclude, --tag, and --executor. Upon discovery we pass each buildspec to BuildspecParser class to validate buildspec and report any errors during validation which is raised as exceptions.

Parameters:
  • configuration (buildtest.config.SiteConfiguration) – An instance of SiteConfiguration class which is the loaded buildtest configuration used for validating the buildspecs.

  • buildspecs (list, optional) – List of paths to buildspec file which can be a file or directory. This option is specified via buildtest buildspec validate --buildspec

  • excluded_buildspecs (list, optional) – List of excluded buildspecs which can be a file or directory. This option is specified via buildtest buildspec validate --exclude

  • tags (list, optional) – List of tag names to search for buildspec to validate. This option is specified via buildtest buildspec validate --tag

  • executors (list, optional) – List of executor names to search for buildspecs to validate. This option is specified via buildtest buildspec validate --executor

buildtest.cli.buildspec.summarize_buildspec_cache(pager, configuration, color=None)[source]

entry point for buildtest buildspec summary

Parameters:
  • configuration (buildtest.config.SiteConfiguration) – instance of type SiteConfiguration

  • pager (bool) – Boolean control output of summary with paging

  • color (str, optional) – An instance of str, color that the summary should be printed in

buildtest.cli.buildspec.summary_print(configuration, color=None)[source]

Prints summary of buildspec cache which is run via command buildtest buildspec summary

Parameters:
buildtest.cli.buildspec.buildspec_maintainers(configuration, breakdown=None, terse=None, header=None, color=None, name=None, row_count=None)[source]

Entry point for buildtest buildspec maintainers command.

Parameters:
  • configuration (buildtest.config.SiteConfiguration) – instance of type SiteConfiguration

  • terse (bool, optional) – Print in terse mode

  • header (bool, optional) – If True disable printing of headers

  • color (bool, optional) – Print output of table with selected color

  • name (str, optional) – List all buildspecs corresponding to maintainer name. This command is specified via buildtest buildspec maintainers find <name>

  • row_count (bool, opotional) – Print row count of the maintainer table. This command is specified via buildtest --row-count buildspec maintainers -l

buildtest.cli.buildspec.buildspec_find(args, configuration)[source]

Entry point for buildtest buildspec find command

Parameters: