utah
Generic functionality to execute callbacks on exit.
Cleanup allocated resources on exit.
Warning
This is private class not expected to be instanciated please use utah.cleanup.cleanup singleton object to call any of the methods documented below.
Register a command to be run on cleanup.
| Parameters: | cmd (iterable) – A command as would be passed subprocess.Popen. |
|---|
Register a function to be run on cleanup.
The function will be run through utah.timeout.timeout().
| Parameters: |
|
|---|
Register a path to be cleaned later.
| Parameters: | path (str) – A link, file, or directory to be cleaned later. |
|---|
Singleton object used to cleanup everything
Provide stringification for commands used by timeout and retry.
Provide a user-oriented command display.
i.e. commandstr(command, arg1, arg2, kw1=1, kw2=2) should return ‘command(arg1, arg2, kw1=1, kw2=2)’
Provide config variables via utah.config.
When run directly as part of the package build, output machine-independent defaults as json for writing a config file.
Provide exceptions for UTAH.
Provide a foundation class for UTAH exceptions.
Support retry and external arguments, but default to False.
Provide unix group checking functionality.
Return whether the user is a member of the given group.
Print error message to stderr to be used by scripts.
All commands use bsdtar and accept a logmethod to use for logging.
Provide a simplified method of interfacing with images.
Log download information (i.e., as a urllib callback).
| Parameters: |
|
|---|
Download an ISO given series, type, and arch.
| Parameters: |
|
|---|---|
| Returns: | Local path of downloaded image |
| Return type: | str |
Extract file contents from an ISO.
| Parameters: | filename (str) – Name of the file to be extracted |
|---|---|
| Returns: | Contents of the file |
| Return type: | str |
See also
Extract file from an ISO.
| Parameters: |
|
|---|---|
| Returns: | Path to the extracted file |
| Return type: | str |
See also
Unpack the image’s info file to get the arch.
| Returns: | Image architecture |
|---|---|
| Return type: | str |
Unpack the image’s info file to get the build number.
| Returns: | Build number of the image. |
|---|---|
| Return type: | str |
Inspect the image’s files to get the image type.
If .disk/mini-info exists, it’s mini. If the casper directory exists, it’s desktop. If ubuntu-server.seed exists in the preseeds directory, it’s server. :returns: Image type :rtype: str
Return the MD5 checksum of a file.
Default file is this image. :param path: Path of file to checksum :type path: str :returns: MD5 checksum of file :rtype: str
Return a command to safely extract a file from an ISO.
Based on unbsdtar-safelink from ubuntu ISO testing.
| Params filename: | |
|---|---|
| Path to the file in the ISO to be extracted | |
| Returns: | Command that can be passed to a subprocess method |
| Return type: | list |
Unpack the image’s info file to get the series.
| Returns: | Image series |
|---|---|
| Return type: | str |
Command line parser for the utah server script.
Argument passed through the command line which is a valid directory.
| Parameters: | directory (string) – A path to a directory passed through the command line. |
|---|---|
| Returns: | The same directory passed if it’s valid. |
| Return type: | string |
| Raises argparse.ArgumentTypeError: | |
| If path doesn’t point to a directory. | |
The expected way to use it is by passing a file-like object or an iterable that yields one line of the preseed at a time:
>>> from utah.preseed import Preseed
>>> from StringIO import StringIO
>>> preseed_text = StringIO(
... '# Comment\n'
... '\n'
... 'd-i passwd/username string utah\n')
>>> preseed = Preseed(preseed_text)
After that, any of the configuration sections can be accessed by the question name:
>>> section = preseed['passwd/username']
>>> section
<ConfigurationSection: 'd-i passwd/username string utah\n'>
and values can be updated by setting them directly in the section objects:
>>> section.value = 'ubuntu'
>>> section
<ConfigurationSection: 'd-i passwd/username string ubuntu\n'>
In addition to this, if a new section is needed, it can be appended/prepended to the preseed by calling directly the Preseed methods or the ConfigurationSection methods to use the section as a reference, that is, append/prepend after/before the given section.
>>> section.append('d-i passwd/user-password password\n')
>>> section.append('d-i passwd/user-password-again password\n')
Once the desired changes have been applied, the Preseed.dump() method can be used to write the output to a new file:
>>> print preseed.dump()
# Comment
d-i passwd/username string ubuntu
d-i passwd/user-password-again password
d-i passwd/user-password password
Read/Write preseed files easily.
| Parameters: | lines (iterable) – File-like object or iterable that yields one line from the preseed at a time. |
|---|
Parse preseed configuration lines.
| Parameters: | lines (iterable) – Any iterable that yields preseed file configuration lines |
|---|---|
| Returns: | Preseed file object with information parsed |
| Return type: | Preseed |
| Raises ParsingError: | |
| If there’s a problem parsing some configuration lines, this exception will be raised with the line number where the problem was detected in the message. | |
| Example : | |
>>> from StringIO import StringIO
>>> preseed_text = StringIO(
... '# Comment\n'
... '\n'
... 'd-i passwd/username string utah\n')
>>> preseed = Preseed()
>>> preseed.load(preseed_text)
>>> print preseed.dump()
# Comment
d-i passwd/username string utah
Note
This method is automatically called at initialization time if the lines parameter is passed to the constructor, so it’s not really expected to be used directly.
See also
Dump preseed configuration statements.
This method returns the contents of the preseed after the changes applied. The string returned is normally used to write the changes back to a file that can be used as the new preseed to provision a system.
| Returns: | Formatted preseed configuration lines |
|---|---|
| Return type: | string |
| Example : |
>>> preseed = Preseed('# Comment\n'.splitlines())
>>> preseed.dump()
'# Comment\n'
See also
Prepend a new section to the preseed.
| Parameters: |
|
|---|---|
| Example : |
>>> preseed = Preseed('d-i passwd/username string utah\n'.splitlines())
>>> preseed.prepend('# Comment')
>>> print preseed.dump()
# Comment
d-i passwd/username string utah
See also
Append a new section to the preseed.
| Parameters: |
|
|---|---|
| Example : |
>>> preseed = Preseed('# Comment\n'.splitlines())
>>> preseed.append('d-i passwd/username string utah\n')
>>> print preseed.dump()
# Comment
d-i passwd/username string utah
See also
Update question names index.
This is a callback called every time a section property is updated and used to maintain question names index integrity
| Parameters: |
|
|---|---|
| Raises DuplicatedQuestionName: | |
If the updated property is qname and the new text is already taken by other section which would break the access to a section by the question name. |
|
Any kind of preseed section (blank, comment or configuration).
Create new section subclass based on the lines in the preseed.
This method is used by the Preseed.load() method to create new sections while parsing a preseed file.
| Parameters: | lines (list) – Lines to be parsed for this particular section |
|---|---|
| Returns: | Section object the properly represents the lines passed |
| Return type: | subclass of Section |
| Example : |
>>> from utah.preseed import Section
>>> Section.new('\n'.splitlines())
<BlankSection: '\n'>
>>> Section.new('# Comment\n'.splitlines())
<CommentSection: '# Comment\n'>
>>> Section.new('d-i passwd/username string utah\n'.splitlines())
<ConfigurationSection: 'd-i passwd/username string utah\n'>
See also
A pressed section that represents a group of consecutive blank lines.
| Parameters: | lines_count (int) – Number of blank lines represented by this section |
|---|---|
| Variables: | lines_count – The number of lines as passed to the constructor |
| Example : |
>>> from utah.preseed import BlankSection
>>> section = BlankSection(3)
>>> section.lines_count
3
Add two blank sections.
| Parameters: | other (BlankSection) – The section to add |
|---|---|
| Returns: | A new blank section that contains the amount of lines lines from the two sections being added. |
| Return type: | BlankSection |
| Example : |
>>> blank1 = BlankSection(1)
>>> blank2 = BlankSection(2)
>>> blank3 = blank1 + blank2
>>> blank3.lines_count
3
See also
Add two blank sections in place.
| Parameters: | other (BlankSection) – The section to add |
|---|---|
| Returns: | The section on the left updated to contain the amount of lines lines from the two sections being added. |
| Return type: | BlankSection |
| Example : |
>>> blank1 = BlankSection(1)
>>> blank2 = BlankSection(2)
>>> blank3 = blank1 + blank2
>>> blank3.lines_count
3
See also
A preseed section that represents a group consecutive comment lines.
| Parameters: | lines (iterable) – An iterable that yields one line at a time |
|---|---|
| Variables: | lines – The comment lines that were passed to the constructor |
| Example : |
>>> from utah.preseed import CommentSection
>>> comment_str = '# Comment\n'
>>> section = CommentSection(comment_str.splitlines())
>>> section.lines
['# Comment']
Add two comment sections.
| Parameters: | other (CommentSection) – The section to add |
|---|---|
| Returns: | A new comment section that contains the comment lines from the two sections being added. |
| Return type: | CommentSection |
| Example : |
>>> comment1 = CommentSection('# Comment 1\n'.splitlines())
>>> comment2 = CommentSection('# Comment 2\n'.splitlines())
>>> comment3 = comment1 + comment2
>>> comment3.lines
['# Comment 1', '# Comment 2']
See also
Add two comment sections in place.
| Parameters: | other (CommentSection) – The section to add |
|---|---|
| Returns: | The section on the left updated to contain the comment lines from the two sections being added. |
| Return type: | CommentSection |
| Example : |
>>> comment1 = CommentSection('# Comment 1\n'.splitlines())
>>> comment2 = CommentSection('# Comment 2\n'.splitlines())
>>> comment1 += comment2
>>> comment1.lines
['# Comment 1', '# Comment 2']
See also
A text property used in ConfigurationSection objects.
See also
A text value used in TextProperty objects.
The value being stored is just a text string, so there’s currently no type even if the configuration sections in a preseed use types for values.
Prepend a string to the stored value.
| Parameters: | other_text (basestring) – The text to be prepended |
|---|---|
| Returns: | The updated value |
| Return type: | TextPropertyValue |
| Example : |
>>> late_command_str = 'd-i preseed/late_command string some_command\n'
>>> section = Section.new(late_command_str.splitlines())
>>> section.value
<TextPropertyValue: 'some_command'>
>>> section.value.prepend('another_command; ')
<TextPropertyValue: 'another_command; some_command'>
Note
The change happens in place, so there’s no need to assign any result back to the TextProperty object:
Append a string to the stored value.
| Parameters: | other_text (basestring) – The text to be appended |
|---|---|
| Returns: | The updated value |
| Return type: | TextPropertyValue |
| Example : |
>>> late_command_str = 'd-i preseed/late_command string some_command\n'
>>> section = Section.new(late_command_str.splitlines())
>>> section.value
<TextPropertyValue: 'some_command'>
>>> section.value.append('; another_command')
<TextPropertyValue: 'some_command; another_command'>
Note
The change happens in place, so there’s no need to assign any result back to the TextProperty object:
A preseed configuration statement made of one or multiple lines.
The expected format of a configuration section is as follows:
<owner> <qname> <qtype> <value>
where the whole section might be made of multiple lines. A line is considered not to finish the statement if there’s a backslash character just before the newline character.
If the parsing succeeds, every field is accessible using the same name as above.
| Parameters: | raw_lines (iterable) – An iterable that yields one line at a time |
|---|---|
| Raises ParsingError: | |
| If the configuration lines don’t follow the expected format above, this exception will be raised. | |
| Example : | |
>>> from utah.preseed import ConfigurationSection
>>> configuration_str = 'd-i passwd/username string utah\n'
>>> section = ConfigurationSection(configuration_str.splitlines())
>>> section.owner
<TextPropertyValue: 'd-i'>
>>> section.qname
<TextPropertyValue: 'passwd/username'>
>>> section.qtype
<TextPropertyValue: 'string'>
>>> section.value
<TextPropertyValue: 'utah'>
Prepend a new section to this one.
This is a wrapper method that actually calls the Preseed.prepend() method in the preseed using this section as a reference section to set the insertion position.
| Parameters: | new_section (Section | basestring) – The new section to be prepended. Note If a string is passed instead, a new section will be created from the string with Section.new(). |
|---|---|
| Returns: | None |
| Return type: | None |
| Example : |
>>> preseed = Preseed()
>>> section = Section.new('d-i passwd/username string utah\n'
... .splitlines())
>>> preseed.append(section)
>>> section.prepend('d-i passwd/user-password password\n')
>>> print preseed.dump()
d-i passwd/user-password password
d-i passwd/username string utah
See also
Append a new section to this one.
This is a wrapper method that actually calls the Preseed.append() method in the preseed using this section as a reference section to set the insertion position.
| Parameters: | new_section (Section | basestring) – The new section to be appended. Note If a string is passed instead, a new section will be created from the string with Section.new(). |
|---|---|
| Returns: | None |
| Return type: | None |
| Example : |
>>> preseed = Preseed()
>>> section = Section.new('d-i passwd/username string utah\n'
... .splitlines())
>>> preseed.append(section)
>>> section.append('d-i passwd/user-password password\n')
>>> print preseed.dump()
d-i passwd/username string utah
d-i passwd/user-password password
See also
Propagate property updates to preseed parent.
If a parent preseed is set, for every updated received from a property value, the same update is propagated to the parent preseed object.
| Parameters: |
|
|---|
An error happened when parsing a preseed section.
This exception is raised when a preseed is being parsed and a new section object is being created to store some contents.
| Example : |
|---|
>>> preseed_str = ('not valid\n')
>>> preseed = Preseed(preseed_str.splitlines())
Traceback (most recent call last):
...
ParsingError: Line 1: Unable to parse configuration lines: not valid
See also
Duplicated question name found in preseed.
This exception is raised when a question name is found more than once in a preseed. This is part of the process used in the Preseed class to guarantee that questions can be accessed based on their name.
| Example : |
|---|
>>> preseed_str = ('d-i passwd/username string utah\n'
... 'd-i passwd/username string ubuntu\n')
>>> preseed = Preseed(preseed_str.splitlines())
Traceback (most recent call last):
...
DuplicatedQuestionName: passwd/username
Process related utilities.
Check all running process looking for a given pattern.
Run a command in a subprocess and log output properly.
| Parameters: | arglist (list) – Argument list as would be passsed to subprocess.Popen |
|---|---|
| Attribute output: | |
| Command output (both stdout and stderr) | |
| Attribute returncode: | |
| Command return code | |
Note
Process is launched when object is instantiated, there isn’t any separate run method.
Test if the given pid is running.
If arg_patterns is provided then the pid’s command line will be compared to make sure it matches an expected value.
| Returns: | proc object if the pid is active and optionally matches one of the arg_patterns, otherwise None |
|---|---|
| Return type: | psutil.Process |
Run a command using fork/exec.
subprocess.* methods, don’t provide a good way to do the UNIX classic fork/exec/select to get stdout/stderr while a process is executing. This provides a version for UTAH.
| Returns: | rc, timed_out, stdout, stderr |
|---|---|
| Return type: | tuple(int, bool, string, string) |
Provide a retry loop that exits on success or an unretryable exception.
Retry a command as long as a retriable exception is captured.
A retriable exception is considered to be a UTAHException that has the attribute retry set to True.
| Parameters: |
|
|---|---|
| Returns: | The value returned by the callable. |
See also
Provide routines used to process command line arguments and run tests.
Provide standard return codes for run_ scripts.
Add offset to client error to avoid overlapping.
This is useful to be able to know when a failure happened in the server or in the client at the shell level.
| Parameters: | returncode (int) – The code returned by the client |
|---|---|
| Returns: | The code to be returned by the server |
| Return type: | int |
Configure logging.
Configure root logger using three different handlers with a different log level: - Console: Set according to consoleloglevel from configuration - Log file: Set according to fileloglevel from configuration - Debug log file: Always set to debug
Other loggers are expected to propagate their messages up to the logging hierarchy.
Download files from machine.
| Returns: | list of download files |
|---|---|
| Return type: | list(str) |
Capture SIGTERM signal to avoid abrupt process termination.
This function registers a handler that raises an exception when SIGTERM is received to ensure that machine object cleanup methods are called. Otherwise, cleanup methods aren’t called when the process is abruptly terminated.
Use utah-done.py to check if the run is finished.
| Parameters: |
|
|---|---|
| Returns: | The exit status of utah-done.py if it’s not UNKNOWN. |
| Raises UTAHException: | |
When the utah client process isn’t finished yet. |
|
Get master runlist and validate it against its schema.
This function calls utah.url.url_argument() to download the runlist file if needed and then uses the schema defined in utah.client.runner.Runner to validate it.
This functions is expected to be passed as the type argument of an argparse.ArgumentParser object to make sure the master runlist is reachable and valid before provisioning the system under test.
| Parameters: | url (basestring) – URL as passed to parser object. |
|---|---|
| Returns: | URL or path to the local file |
| Return type: | basestring |
See also
| Example : |
|---|
>>> from utah.run import master_runlist_argument
>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('url',
... type=master_runlist_argument)
_StoreAction(... dest='url', ...)
>>> runlist = 'lp:utah/utah/client/examples/pass.run'
>>> parser.parse_args([runlist])
Namespace(url='/tmp/utah_...')
Run a runlist and retrieve results.
| Returns: | exitstatus and list of logs returned |
|---|---|
| Return type: | tuple(int, list(str)) |
Provide functionality to execute command with timeouts.
Provide a special exception to indicate an operation timed out.
Find process children so they can be killed when the timeout expires.
| Parameters: | pid (int) – Process ID for the parent process |
|---|---|
| Returns: | The pid for each children process |
| Return type: | list(int) |
Run command through subprocess.Popen for up to timeout seconds.
Command termination is checked using subprocess.Popen.poll.
| Parameters: |
|
|---|---|
| Returns: | The subprocess object |
| Return type: | subprocess.Popen |
| Raises UTAHTimeout: | |
If command execution hasn’t finished before timeout seconds. |
|
Run a command for up to timeout seconds.
| Parameters: |
|
|---|---|
| Returns: | The value returned by the callable. |
| Raises UTAHTimeout: | |
If command execution hasn’t finished before timeout seconds. |
|
See also
Provide easy accessors to the Jinja2 template library
This module provides the classes/functions needed to:
A request that sends HEAD method instead of GET.
See also
An opener to checks a URL is valid and readable.
To use it, create an object instance and call the open method passing the url to be checked as argument.
Check if http URL exists and is readable.
The check is performed by sending an HTTP HEAD request, waiting for the response and checking that the code is 200 OK.
If a redirect response is received, the URL will still be reported as working fine, but the underlying implementation will use an HTTP GET method instead, so it won’t be as efficient as in the standard case.
| Parameters: | url (basestring) – The HTTP URL to be checked |
|---|---|
| Returns: | The url passed as argument when it’s valid and readable. |
| Return type: | basestring |
| Raises URLNotFound: | |
| When there’s a problem opening the URL or isn’t found. | |
| Example : | |
>>> from utah.url import URLChecker
>>> opener = URLChecker()
>>> opener.open('http://www.ubuntu.com')
'http://www.ubuntu.com'
Note
This method is called by the open method when the URL protocol is http, so it’s not expected to be called directly.
See also
Check if local file exists.
| Parameters: | url (basestring) – The file URL to be checked |
|---|---|
| Returns: | The path to the file if it was found and readable. Note The returned value is a path, not a URL, so it can be used to open the file the same way as any other files. |
| Return type: | basestring |
| Raises: |
|
| Example : |
>>> import tempfile
>>> with tempfile.NamedTemporaryFile() as f:
... opener = URLChecker()
... opener.open(f.name)
'/tmp/tmp...'
Note
This method is called by the open method when the URL protocol is file, so it’s not expected to be called directly.
See also
URL argument to be used in an argparse.ArgumentParser object.
| Parameters: | url (basestring) – URL as passed to the parser object. Note The URL passed as argument can be a launchpad URL. In that case, the file pointed by the URL will be downloaded as when using bzr export and the returned value is the path to the downloaded file. |
|---|---|
| Returns: | URL or path to local file |
| Return type: | basestring |
| Raises argparse.ArgumentTypeError: | |
| when the URL is invalid or unreadable. In any case, the error message will provide information to be displayed by the argparse.ArgumentParser object in the command line. | |
| Example : | |
>>> from utah.url import url_argument
>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('url', type=url_argument)
_StoreAction(... dest='url', ...)
>>> parser.parse_args(['http://www.ubuntu.com'])
Namespace(url='http://www.ubuntu.com')
>>> parser.parse_args(['lp:utah/setup.py'])
Namespace(url='/tmp/utah_...')
See also
Exception raised when a URL isn’t found.
| Example : |
|---|
>>> opener = URLChecker()
>>> opener.open('http://localhost/invalid_url')
Traceback (most recent call last):
...
URLNotFound: http://localhost/invalid_url
>>> opener.open('file:///tmp/invalid_url')
Traceback (most recent call last):
...
URLNotFound: /tmp/invalid_url
See also
Exception raised when a URL isn’t readable.
| Example : |
|---|
>>> import os
>>> with tempfile.NamedTemporaryFile() as f:
... os.chmod(f.name, 0000)
... opener = URLChecker()
... opener.open(f.name)
Traceback (most recent call last):
...
URLNotReadable: /tmp/tmp...
See also
utah.client
UTAH client common classes and functions.
Provide consistent return codes for UTAH client.
PASS: All test cases were executed and passed FAIL: All test cases were executed, but at least one of them failed ERROR: At least one error was detected that prevented a test case from being executed. Examples of situations that are considered an error are: - Fetch command failure - Setup command failure REBOOT: The system under test rebooted as required by a test case. To get final result the state file has to be checked. UNKNOWN: Unable to retrieve state file to check if client finished properly. INVALID_USER: The client was launched with a user other than root. EXCEPTION_ERROR: An exception error was encountered. CMD_PARSING_ERROR: Command line arguments parsing error.
Print debugging information according to CONFIG['DEBUG'] value.
Data will be printed with the DEBUG: string prepended to it.
| Parameters: |
|
|---|---|
| Returns: | Whether something was printed or not |
| Return type: | bool |
Get the host’s architecture.
| Returns: | The human readable architecture or 'unknown' |
|---|---|
| Return type: | str |
Get build number.
| Returns: | Build number as according to media-info or '?' if not found |
|---|---|
| Return type: | str |
See also
Get host info, useful for debugging.
| Returns: | Host uname, media-info and product_uuid together |
|---|---|
| Return type: | dict |
See also
Get the contents of the install-type file if available.
| Returns: | The contents of the install-type file or 'unknown' if not available. |
|---|---|
| Return type: | str |
Note
This is only a best-effort approach.
See also
Get the contents of the media-info file if available.
| Returns: | The contents of the media-info file or 'unknown' if not available. |
|---|---|
| Return type: | str |
Note
This is only a best-effort approach.
Get the product_uuid of the machine under test.
| Returns: | The contents of the product_uuid file or None if not available. |
|---|
Note
This is only a best-effort approach.
Get the host’s release name.
| Returns: | Release name (i.e. quantal, raring, etc.) |
|---|---|
| Return type: | str |
Make a result data structure.
Note
Battery information will only be included if some value is passed as argument.
| Parameters: |
|
|---|---|
| Returns: | Result data |
| Return type: | dict |
Create a directory only if needed with proper error handling.
Parse a control file and check against a jsonschema.
| Parameters: |
|
|---|---|
| Returns: | Parsed data |
| Return type: | object |
| Raises jsonschema.ValidationError: | |
If file contents doesn’t follow the schema definitions |
|
See also
parse_yaml_file(), DefaultValidator
Parse yaml file.
| Parameters: | filename (str) – Path to the file that should be read |
|---|---|
| Returns: | Parsed data |
| Return type: | object |
| Raises YAMLParsingError: | |
| If there’s a problem while parsing the file with the information about where in the file the problem was detected. | |
See also
Run command and return result using the client’s format.
| Parameters: |
|
|---|---|
| Returns: | Command execution result |
| Return type: | dict |
See also
Provide UTAH client exceptions.
Directory error.
Raised when some test directory isn’t found or an error happens when trying to change to it
Raised when master runlist isn’t in the expected format.
Raised when yaml file with metadata about tests cannot be found.
Base class of all exceptions in the client.
Used to provide additional information when schema validation fails.
Raised when a file that was supposed to contain yaml data is empty.
Provide more detailed yaml.load exception handling.
Used to provide the filename and the location in which the parsing error happened when calling yaml.load
Get package information in the system under test.
Calculate delta between to set of installed packages.
| Parameters: |
|
|---|---|
| Variables: |
|
Query apt cache for installed packages and their version.
Provide functionality for test result handling.
Result collection class.
| Params filename: | |
|---|---|
| Filename where the report should be written to or None to print it to sys.stdout | |
| Parameters: | append_to_file (bool) – Whether results should be appended to the results from a previous execution or not. If that’s the case, then filename is read to get the old results. |
Add a result to the object.
Note: ‘result’ is expected to be a dictionary like this:
{
'command': '',
'returncode': 0,
'stdout': '',
'stderr': '',
'start_time': '',
'time_delta': '',
}
Return results in a JSON format.
Return results in a YAML format.
Provide code to actually run the tests.
Provide The main runner class.
Parses a master runlist, builds a list of TestSuites, and runs them.
Parse a master runlist and build a list of suites from the data.
| Parameters: |
|
|---|
Add stats to results and process them.
| Returns: | A return code based on the test status. |
|---|---|
| Return type: | int |
Run the test suites we’ve parsed.
| Returns: | The result of process_results, which is a return code. |
|---|---|
| Return type: | int |
See also
Provide functionality for saving and restoring run state.
State saving base class.
Accepts a dictionary of state info and prints it to the state file.
YAML based state saver.
Testcase specific code.
Base class describing a test case.
status is one of ‘NOTRUN’, ‘BUILD’, ‘SETUP’, ‘RUN’, ‘CLEANUP’, or ‘DONE’
Determine if the case is done.
This might mean that something has failed. Used by suite to determine if the suite needs to be re-run on resume.
| Returns: | Whether the test case is finished (done or cleaned up) |
|---|---|
| Return type: | bool |
Restore state from the supplied dictionary.
Requires that ‘state’ has the same fieldnames as the TestCase class.
Set override values from a TestSuite runlist for this test case.
Run the complete test case.
This includes any build, setup, and cleanup commands.
| Returns: | Whether to keep running tests (True) or reboot (False) |
|---|---|
| Return type: | bool |
Placeholder for save_state_callbacks.
Testsuite specific code.
A dynamic test suite.
This class contructs itself based on a tslist.auto file that builds the list of test cases it should execute at runtime.
Base class describing a test suite.
Determine if the suite is done.
This might mean that something has failed. Used by Runner to determine if the suite needs to be re-run on resume.
| Returns: | Whether the test suite is finished (done or cleaned up) |
|---|---|
| Return type: | bool |
Restore our state from the supplied dictionary.
Requires that the fieldnames in the dictionary match the class properties.
Run the complete test suite.
This includes any build, setup, and cleanup commands, as well as all test cases (including build, setup, and cleanup.)
| Returns: | Whether to keep running tests (True) or reboot (False) |
|---|---|
| Return type: | bool |
Placeholder for save_state_callbacks.
utah.provisioning
Provide exceptions specific to provisioning.
Provide a foundation class for UTAH provisioning exceptions.
Provide basic inventory routines.
Provide a generic class for an arbitrary inventory of machines.
Raise exceptions for most methods, since they should be defined by subclasses. Except for special read-only cases, subclasses should provide request(). Subclasses will generally also need to provide delete() for cleanup purposes. All other methods (i.e. release, destroy) are optional.
Delete this inventory and remove the lockfile.
Subclasses can call this via super to delete the lockfile, or implement lockfile deletion in their delete() method.
Mark a machine as destroyed and unusable for future tests.
Current implementations do not call machine.destroy(), requiring that do be done separately.
| Returns: | False since this is unimplemented but not exception-worthy |
|---|---|
| Return type: | bool |
Provide basic SQLite database access with a cursor.
Execute SQL statement and return cursor.
This method is expected to be used as a wrapper around all connection.execute calls so that all the SQL statements are logged in case this information is needed to troubleshoot problems.
| Parameters: |
|
|---|---|
| Returns: | Cursor used to execute statement |
| Return type: | object |
Provide a class for UTAH provisioning inventory exceptions.
Provide common functions for provisioning and interacting with machines. Functions here should apply to multiple machine types (VM, bare metal, etc.)
Provide routines for automating an install from an image.
Provide a generic class to provision an arbitrary machine.
Raise exceptions for most methods, since subclasses should provide them. run, uploadfiles, and downloadfiles are the most important methods for interacting with a machine.
Some method of satisfying activecheck is generally required to run commands on a machine (i.e., implementing _start or reimplementing activecheck.)
Some method of satisfying provisioncheck is generally required to install on a machine (i.e., implementing some combination of _create, _load, and _provision, or reimplementing provisioncheck.) Installation may be separated from the Machine classes in the future.
Ensure the machine is active and capable of accepting commands.
Check if the machine is running and able to accept commands, start it if necessary, and raise an exception if it cannot be started.
Register a command to be run on cleanup.
| Parameters: | cmd (iterable) – A command as would be passed subprocess.Popen. |
|---|
See also
Register a path to be cleaned later.
| Parameters: | path (str) – A link, file, or directory to be cleaned later. |
|---|
See also
Register a function to be run on cleanup.
| Parameters: |
|
|---|
See also
Free up the machine and associated resources.
Release resources consumed by the machine, set provisioned to False, and return True on success. For a VM, this should destroy the VM files on the disk, and remove it from libvirt if it is registered there. For a physical machine, this should free it up to be used by another process in the future, and destroy sensitive data if any exists. Destroying the install on a physical machine is optional, but the machine must be left in a state where a new install can start.
Log download information (i.e., as a urllib callback).
| Parameters: |
|
|---|
Download a list of files from the machine to a local target.
Support for files as a string specifying a single file is recommended but not required. target should be a valid target path for cp, i.e. a filename for a single file, a directory name for multiple files. Recursive directory download is not currently supported by all implementations.
Install the required packages on the machine.
Install the python-jsonschema, utah-common, and utah-client packages.
| Raises UTAHProvisioningException: | |
|---|---|
| When packages won’t install | |
Check network connectivity using ping.
| Raises UTAHProvisioningException: | |
|---|---|
| When ping fails. | |
See also
Run pingcheck over and over until timeout expires.
| Parameters: |
|
|---|
Ensure the machine is provisioned and installed.
Check if the machine is provisioned, provision it if necessary, run an install if needed, and raise an exception if it cannot be provisioned, or if it exceeds the timeout value set in config for installation.
| Raises UTAHProvisioningException: | |
|---|---|
| When the machine fails to install within the timeout value. | |
Use the default rsyslog method if no override is in place.
| Returns: | rsyslog method for this machine |
|---|---|
| Return type: | object |
Run a command on the machine.
| Parameters: |
|
|---|---|
| Returns: | A tuple of the form (returncode, stdout, stder) |
| Return type: | tuple |
rsyslog processing and monitoring.
Listen to rsyslog messages and process them.
| Parameters: |
|
|---|
Monitor rsyslog during boot up.
Works the same as the wait_for_install() method but takes in steps that determine a system has booted after the install has completed.
| Parameters: | uuid (string) – The UUID generated by provisioning code. |
|---|
Monitor rsyslog messages during the installation.
Works through each step in the steps array to find messages in the syslog indicating what part of the install we are in.
| Parameters: | booted_callback (callable | None) – function to be called once the system has been booted |
|---|
SSH based machine class for a provisioned system and SSHMixin for every machine class that needs SSH support.
A machine that is provisioned and can be accessed through ssh.
Provide methods for machines accessed via ssh.
Copy a file or list of files from the machine to a local target.
| Parameters: |
|
|---|
Recursively copy files to the target directory on the machine.
| Parameters: |
|
|---|
SSH mixin initialization.
Use this method when it isn’t appropriate to follow the MRO as in __init__
Run a command through SSH.
| Parameters: |
|
|---|
Provide functions for virtual machine provisioning.
Install a VM from an image using libvirt direct kernel booting.
Provide a class to utilize VMs using libvirt.
Capable of utilizing existing VMs Creation currently handled by sublcasses
Provide basic SQLite inventory for VMs.
Only implements request, release, and destroy. No authentication or conflict checking currently exists. Only suitable for VMs at present.
Provide a foundation class for UTAH VM provisioning exceptions.
Return a Machine object for a VM with the passed in arguments.
| Parameters: | kw (dict) – All parameters are passed to the Machine constructor |
|---|---|
| Returns: | Appropriately constructed Machine object |
| Return type: | object |
utah.provisioning.baremetal
Provide inventory functions specific to bare metal deployments.
Keep an inventory of manually entered machines.
All columns other than machineid, name, and state are assumed to be arguments for system creation (i.e., with cobbler).
Release a machine so it can be used by other processes.
| Parameters: |
|
|---|
Return a Machine object meeting the given criteria.
| Parameters: |
|
|---|---|
| Type : | str or None |
All other parameters are passed to Machine constructor.
| Returns: | Machine object |
|---|---|
| Return type: | obj |
Support bare metal provisioning through cobbler.
Provision and manage a machine via cobbler.
Support provisioning of bamboo-feeder-based systems.
Provision and manage an ARM board in a bamboo-feeder setup.
Provide exceptions specific to bare metal provisioning.