Utilities APIs

This is a set of utility APIs that Avocado provides as added value to test writers.

It’s suppose to be generic, without any knowledge of Avocado and reusable in different projects.

Note

In the current version there is a hidden knowledge of avocado logging streams. More about this issue can be found here https://trello.com/c/4QyUgWsW/720-get-rid-of-avocado-test-loggers-from-avocado-utils

Submodules

avocado.utils.archive module

Module to help extract and create compressed archives.

exception avocado.utils.archive.ArchiveException

Bases: exceptions.Exception

Base exception for all archive errors.

class avocado.utils.archive.ArchiveFile(filename, mode='r')

Bases: object

Class that represents an Archive file.

Archives are ZIP files or Tarballs.

Creates an instance of ArchiveFile.

Parameters:
  • filename – the archive file name.
  • mode – file mode, r read, w write.
add(filename, arcname=None)

Add file to the archive.

Parameters:
  • filename – file to archive.
  • arcname – alternative name for the file in the archive.
close()

Close archive.

extract(path='.')

Extract all files from the archive.

Parameters:path – destination path.
list()

List files to the standard output.

classmethod open(filename, mode='r')

Creates an instance of ArchiveFile.

Parameters:
  • filename – the archive file name.
  • mode – file mode, r read, w write.
avocado.utils.archive.compress(filename, path)

Compress files in an archive.

Parameters:
  • filename – archive file name.
  • path – origin directory path to files to compress. No individual files allowed.
avocado.utils.archive.create(filename, path)

Compress files in an archive.

Parameters:
  • filename – archive file name.
  • path – origin directory path to files to compress. No individual files allowed.
avocado.utils.archive.extract(filename, path)

Extract files from an archive.

Parameters:
  • filename – archive file name.
  • path – destination path to extract to.
avocado.utils.archive.is_archive(filename)

Test if a given file is an archive.

Parameters:filename – file to test.
Returns:True if it is an archive.
avocado.utils.archive.uncompress(filename, path)

Extract files from an archive.

Parameters:
  • filename – archive file name.
  • path – destination path to extract to.

avocado.utils.asset module

Asset fetcher from multiple locations

class avocado.utils.asset.Asset(name, asset_hash, algorithm, locations, cache_dirs, expire=None)

Bases: object

Try to fetch/verify an asset file from multiple locations.

Initialize the Asset() class.

Parameters:
  • name – the asset filename. url is also supported
  • asset_hash – asset hash
  • algorithm – hash algorithm
  • locations – list of locations fetch asset from
  • cache_dirs – list of cache directories
  • expire – time in seconds for the asset to expire
fetch()

Fetches the asset. First tries to find the asset on the provided cache_dirs list. Then tries to download the asset from the locations list provided.

Raises:EnvironmentError – When it fails to fetch the asset
Returns:The path for the file on the cache directory.
avocado.utils.asset.DEFAULT_HASH_ALGORITHM = 'sha1'

The default hash algorithm to use on asset cache operations

exception avocado.utils.asset.UnsupportedProtocolError

Bases: exceptions.EnvironmentError

Signals that the protocol of the asset URL is not supported

avocado.utils.astring module

Operations with strings (conversion and sanitation).

The unusual name aims to avoid causing name clashes with the stdlib module string. Even with the dot notation, people may try to do things like

import string … from avocado.utils import string

And not notice until their code starts failing.

avocado.utils.astring.ENCODING = 'UTF-8'

On import evaluated value representing the system encoding based on system locales using locale.getpreferredencoding(). Use this value wisely as some files are dumped in different encoding.

avocado.utils.astring.FS_UNSAFE_CHARS = '<>:"/\\|?*;'

String containing all fs-unfriendly chars (Windows-fat/Linux-ext3)

avocado.utils.astring.bitlist_to_string(data)

Transform from bit list to ASCII string.

Parameters:data – Bit list to be transformed
avocado.utils.astring.is_bytes(data)

Checks if the data given is a sequence of bytes

And not a “text” type, that can be of multi-byte characters. Also, this does NOT mean a bytearray type.

Parameters:data – the instance to be checked if it falls under the definition of an array of bytes.
avocado.utils.astring.is_text(data)

Checks if the data given is a suitable for holding text

That is, if it can hold text that requires more than one byte for each character.

avocado.utils.astring.iter_tabular_output(matrix, header=None, strip=False)

Generator for a pretty, aligned string representation of a nxm matrix.

This representation can be used to print any tabular data, such as database results. It works by scanning the lengths of each element in each column, and determining the format string dynamically.

Parameters:
  • matrix – Matrix representation (list with n rows of m elements).
  • header – Optional tuple or list with header elements to be displayed.
  • strip – Optionally remove trailing whitespace from each row.
avocado.utils.astring.shell_escape(command)

Escape special characters from a command so that it can be passed as a double quoted (” “) string in a (ba)sh command.

Parameters:command – the command string to escape.
Returns:The escaped command string. The required englobing double quotes are NOT added and so should be added at some point by the caller.

See also: http://www.tldp.org/LDP/abs/html/escapingsection.html

avocado.utils.astring.string_safe_encode(input_str)

People tend to mix unicode streams with encoded strings. This function tries to replace any input with a valid utf-8 encoded ascii stream.

On Python 3, it’s a terrible idea to try to mess with encoding, so this function is limited to converting other types into strings, such as numeric values that are often the members of a matrix.

Parameters:input_str – possibly unsafe string or other object that can be turned into a string
Returns:a utf-8 encoded ascii stream
avocado.utils.astring.string_to_bitlist(data)

Transform from ASCII string to bit list.

Parameters:data – String to be transformed
avocado.utils.astring.string_to_safe_path(input_str)

Convert string to a valid file/dir name.

This takes a string that may contain characters that are not allowed on FAT (Windows) filesystems and/or ext3 (Linux) filesystems, and replaces them for safe (boring) underlines.

It limits the size of the path to be under 255 chars, and make hidden paths (starting with “.”) non-hidden by making them start with “_”.

Parameters:input_str – String to be converted
Returns:String which is safe to pass as a file/dir name (on recent fs)
avocado.utils.astring.strip_console_codes(output, custom_codes=None)

Remove the Linux console escape and control sequences from the console output. Make the output readable and can be used for result check. Now only remove some basic console codes using during boot up.

Parameters:
  • output (string) – The output from Linux console
  • custom_codes – The codes added to the console codes which is not covered in the default codes
Returns:

the string without any special codes

Return type:

string

avocado.utils.astring.tabular_output(matrix, header=None, strip=False)

Pretty, aligned string representation of a nxm matrix.

This representation can be used to print any tabular data, such as database results. It works by scanning the lengths of each element in each column, and determining the format string dynamically.

Parameters:
  • matrix – Matrix representation (list with n rows of m elements).
  • header – Optional tuple or list with header elements to be displayed.
  • strip – Optionally remove trailing whitespace from each row.
Returns:

String with the tabular output, lines separated by unix line feeds.

Return type:

str

avocado.utils.astring.to_text(data, encoding='UTF-8', errors='strict')

Convert anything to text decoded text

When the data is bytes, it’s decoded. When it’s not of string types it’s re-formatted into text and returned. Otherwise (it’s string) it’s returned unchanged.

Parameters:

avocado.utils.aurl module

URL related functions.

The strange name is to avoid accidental naming collisions in code.

avocado.utils.aurl.is_url(path)

Return True if path looks like an URL.

Parameters:path – path to check.
Return type:Boolean.

avocado.utils.build module

avocado.utils.build.configure(path, configure=None)

Configures the source tree for a subsequent build

Most source directories coming from official released tarballs will have a “configure” script, but source code snapshots may have “autogen.sh” instead (which usually creates and runs a “configure” script itself). This function will attempt to run the first one found (if a configure script name not given explicitly).

Parameters:configure (str or None) – the name of the configure script (None for trying to find one automatically)
Returns:the configure script exit status, or None if no script was found and executed
avocado.utils.build.make(path, make='make', env=None, extra_args='', ignore_status=None, allow_output_check=None, process_kwargs=None)

Run make, adding MAKEOPTS to the list of options.

Parameters:
  • make – what make command name to use.
  • env – dictionary with environment variables to be set before calling make (e.g.: CFLAGS).
  • extra – extra command line arguments to pass to make.
  • allow_output_check (str) – Whether to log the command stream outputs (stdout and stderr) of the make process in the test stream files. Valid values: ‘stdout’, for allowing only standard output, ‘stderr’, to allow only standard error, ‘all’, to allow both standard output and error, and ‘none’, to allow none to be recorded (default). The default here is ‘none’, because usually we don’t want to use the compilation output as a reference in tests.
Returns:

exit status of the make process

avocado.utils.build.run_make(path, make='make', extra_args='', process_kwargs=None)

Run make, adding MAKEOPTS to the list of options.

Parameters:
  • path – directory from where to run make
  • make – what make command name to use.
  • extra_args – extra command line arguments to pass to make.
  • process_kwargs – Additional key word arguments to the underlying process running the make.
Returns:

the make command result object

avocado.utils.cpu module

Get information from the current’s machine CPU.

avocado.utils.cpu.cpu_has_flags(flags)

Check if a list of flags are available on current CPU info

Parameters:flags (list) – A list of cpu flags that must exists on the current CPU.
Returns:bool True if all the flags were found or False if not
Return type:list
avocado.utils.cpu.cpu_online_list()

Reports a list of indexes of the online cpus

avocado.utils.cpu.get_cpu_arch()

Work out which CPU architecture we’re running on

avocado.utils.cpu.get_cpu_vendor_name()

Get the current cpu vendor name

Returns:string ‘intel’ or ‘amd’ or ‘power7’ depending on the current CPU architecture.
Return type:string
avocado.utils.cpu.get_cpufreq_governor()

Get current cpu frequency governor

avocado.utils.cpu.get_cpuidle_state()

Get current cpu idle values

Returns:Dict of cpuidle states values for all cpus
Return type:Dict of dicts
avocado.utils.cpu.offline(cpu)

Offline given CPU

avocado.utils.cpu.online(cpu)

Online given CPU

avocado.utils.cpu.online_cpus_count()

Return Number of Online cpus in the system

avocado.utils.cpu.set_cpufreq_governor(governor='random')

To change the given cpu frequency governor

Parameters:governor – frequency governor profile name whereas random is default option to choose random profile among available ones.
avocado.utils.cpu.set_cpuidle_state(state_number='all', disable=True, setstate=None)

Set/Reset cpu idle states for all cpus

Parameters:
  • state_number – cpuidle state number, default: all all states
  • disable – whether to disable/enable given cpu idle state, default is to disable (True)
  • setstate – cpuidle state value, output of get_cpuidle_state()
avocado.utils.cpu.total_cpus_count()

Return Number of Total cpus in the system including offline cpus

avocado.utils.crypto module

avocado.utils.crypto.hash_file(filename, size=None, algorithm='md5')

Calculate the hash value of filename.

If size is not None, limit to first size bytes. Throw exception if something is wrong with filename. Can be also implemented with bash one-liner (assuming size%1024==0):

dd if=filename bs=1024 count=size/1024 | sha1sum -
Parameters:
  • filename – Path of the file that will have its hash calculated.
  • algorithm – Method used to calculate the hash (default is md5).
  • size – If provided, hash only the first size bytes of the file.
Returns:

Hash of the file, if something goes wrong, return None.

avocado.utils.data_factory module

Generate data useful for the avocado framework and tests themselves.

avocado.utils.data_factory.generate_random_string(length, ignore='!"#$%&\'()*+, -./:;<=>?@[\\]^_`{|}~', convert='')

Generate a random string using alphanumeric characters.

Parameters:
  • length (int) – Length of the string that will be generated.
  • ignore (str) – Characters that will not include in generated string.
  • convert (str) – Characters that need to be escaped (prepend “”).
Returns:

The generated random string.

avocado.utils.data_factory.make_dir_and_populate(basedir='/tmp')

Create a directory in basedir and populate with a number of files.

The files just have random text contents.

Parameters:basedir (str) – Base directory where directory should be generated.
Returns:Path of the dir created and populated.
Return type:str

avocado.utils.data_structures module

This module contains handy classes that can be used inside avocado core code or plugins.

class avocado.utils.data_structures.Borg

Multiple instances of this class will share the same state.

This is considered a better design pattern in Python than more popular patterns, such as the Singleton. Inspired by Alex Martelli’s article mentioned below:

See:http://www.aleax.it/5ep.html
class avocado.utils.data_structures.CallbackRegister(name, log)

Bases: object

Registers pickable functions to be executed later.

Parameters:name – Human readable identifier of this register
register(func, args, kwargs, once=False)

Register function/args to be called on self.destroy() :param func: Pickable function :param args: Pickable positional arguments :param kwargs: Pickable keyword arguments :param once: Add unique (func,args,kwargs) combination only once

run()

Call all registered function

unregister(func, args, kwargs)

Unregister (func,args,kwargs) combination :param func: Pickable function :param args: Pickable positional arguments :param kwargs: Pickable keyword arguments

class avocado.utils.data_structures.DataSize(data)

Bases: object

Data Size object with builtin unit-converted attributes.

Parameters:data (str) – Data size plus optional unit string. i.e. ‘10m’. No unit string means the data size is in bytes.
MULTIPLIERS = {'b': 1, 'g': 1073741824, 'k': 1024, 'm': 1048576, 't': 1099511627776}
b
g
k
m
t
unit
value
exception avocado.utils.data_structures.InvalidDataSize

Bases: exceptions.ValueError

Signals that the value given to DataSize is not valid.

class avocado.utils.data_structures.LazyProperty(f_get)

Bases: object

Lazily instantiated property.

Use this decorator when you want to set a property that will only be evaluated the first time it’s accessed. Inspired by the discussion in the Stack Overflow thread below:

See:http://stackoverflow.com/questions/15226721/
avocado.utils.data_structures.comma_separated_ranges_to_list(string)

Provides a list from comma separated ranges

Parameters:string – string of comma separated range
Return list:list of integer values in comma separated range
avocado.utils.data_structures.compare_matrices(matrix1, matrix2, threshold=0.05)

Compare 2 matrices nxm and return a matrix nxm with comparison data and stats. When the first columns match, they are considered as header and included in the results intact.

Parameters:
  • matrix1 – Reference Matrix of floats; first column could be header.
  • matrix2 – Matrix that will be compared; first column could be header
  • threshold – Any difference greater than this percent threshold will be reported.
Returns:

Matrix with the difference in comparison, number of improvements, number of regressions, total number of comparisons.

avocado.utils.data_structures.geometric_mean(values)

Evaluates the geometric mean for a list of numeric values. This implementation is slower but allows unlimited number of values. :param values: List with values. :return: Single value representing the geometric mean for the list values. :see: http://en.wikipedia.org/wiki/Geometric_mean

avocado.utils.data_structures.ordered_list_unique(object_list)

Returns an unique list of objects, with their original order preserved

avocado.utils.data_structures.time_to_seconds(time)

Convert time in minutes, hours and days to seconds. :param time: Time, optionally including the unit (i.e. ‘10d’)

avocado.utils.debug module

This file contains tools for (not only) Avocado developers.

avocado.utils.debug.log_calls(length=None, cls_name=None)

Use this as decorator to log the function call altogether with arguments. :param length: Max message length :param cls_name: Optional class name prefix

avocado.utils.debug.log_calls_class(length=None)

Use this as decorator to log the function methods’ calls. :param length: Max message length

avocado.utils.debug.measure_duration(func)

Use this as decorator to measure duration of the function execution. The output is “Function $name: ($current_duration, $accumulated_duration)”

avocado.utils.disk module

Disk utilities

avocado.utils.disk.freespace(path)

avocado.utils.distro module

This module provides the client facilities to detect the Linux Distribution it’s running under.

class avocado.utils.distro.LinuxDistro(name, version, release, arch)

Bases: object

Simple collection of information for a Linux Distribution

Initializes a new Linux Distro

Parameters:
  • name (str) – a short name that precisely distinguishes this Linux Distribution among all others.
  • version (str) – the major version of the distribution. Usually this is a single number that denotes a large development cycle and support file.
  • release (str) – the release or minor version of the distribution. Usually this is also a single number, that is often omitted or starts with a 0 when the major version is initially release. It’s often associated with a shorter development cycle that contains incremental a collection of improvements and fixes.
  • arch (str) – the main target for this Linux Distribution. It’s common for some architectures to ship with packages for previous and still compatible architectures, such as it’s the case with Intel/AMD 64 bit architecture that support 32 bit code. In cases like this, this should be set to the 64 bit architecture name.
class avocado.utils.distro.Probe

Bases: object

Probes the machine and does it best to confirm it’s the right distro

CHECK_FILE = None

Points to a file that can determine if this machine is running a given Linux Distribution. This servers a first check that enables the extra checks to carry on.

CHECK_FILE_CONTAINS = None

Sets the content that should be checked on the file pointed to by CHECK_FILE_EXISTS. Leave it set to None (its default) to check only if the file exists, and not check its contents

CHECK_FILE_DISTRO_NAME = None

The name of the Linux Distribution to be returned if the file defined by CHECK_FILE_EXISTS exist.

CHECK_VERSION_REGEX = None

A regular expression that will be run on the file pointed to by CHECK_FILE_EXISTS

check_name_for_file()

Checks if this class will look for a file and return a distro

The conditions that must be true include the file that identifies the distro file being set (CHECK_FILE) and the name of the distro to be returned (CHECK_FILE_DISTRO_NAME)

check_name_for_file_contains()

Checks if this class will look for text on a file and return a distro

The conditions that must be true include the file that identifies the distro file being set (CHECK_FILE), the text to look for inside the distro file (CHECK_FILE_CONTAINS) and the name of the distro to be returned (CHECK_FILE_DISTRO_NAME)

check_release()

Checks if this has the conditions met to look for the release number

check_version()

Checks if this class will look for a regex in file and return a distro

get_distro()

Returns the LinuxDistro this probe detected

name_for_file()

Get the distro name if the CHECK_FILE is set and exists

name_for_file_contains()

Get the distro if the CHECK_FILE is set and has content

release()

Returns the release of the distro

version()

Returns the version of the distro

avocado.utils.distro.register_probe(probe_class)

Register a probe to be run during autodetection

avocado.utils.distro.detect()

Attempts to detect the Linux Distribution running on this machine

Returns:the detected LinuxDistro or UNKNOWN_DISTRO
Return type:LinuxDistro

avocado.utils.download module

Methods to download URLs and regular files.

avocado.utils.download.get_file(src, dst, permissions=None, hash_expected=None, hash_algorithm='md5', download_retries=1)

Gets a file from a source location, optionally using caching.

If no hash_expected is provided, simply download the file. Else, keep trying to download the file until download_failures exceeds download_retries or the hashes match.

If the hashes match, return dst. If download_failures exceeds download_retries, raise an EnvironmentError.

Parameters:
  • src – source path or URL. May be local or a remote file.
  • dst – destination path.
  • permissions – (optional) set access permissions.
  • hash_expected – Hash string that we expect the file downloaded to have.
  • hash_algorithm – Algorithm used to calculate the hash string (md5, sha1).
  • download_retries – Number of times we are going to retry a failed download.
Raise:

EnvironmentError.

Returns:

destination path.

avocado.utils.download.url_download(url, filename, data=None, timeout=300)

Retrieve a file from given url.

Parameters:
  • url – source URL.
  • filename – destination path.
  • data – (optional) data to post.
  • timeout – (optional) default timeout in seconds.
Returns:

None.

avocado.utils.download.url_download_interactive(url, output_file, title='', chunk_size=102400)

Interactively downloads a given file url to a given output file.

Parameters:
  • url (string) – URL for the file to be download
  • output_file (string) – file name or absolute path on which to save the file to
  • title (string) – optional title to go along the progress bar
  • chunk_size (integer) – amount of data to read at a time
avocado.utils.download.url_open(url, data=None, timeout=5)

Wrapper to urllib2.urlopen() with timeout addition.

Parameters:
  • url – URL to open.
  • data – (optional) data to post.
  • timeout – (optional) default timeout in seconds.
Returns:

file-like object.

Raises:

URLError.

avocado.utils.filelock module

Utility for individual file access control implemented via PID lock files.

exception avocado.utils.filelock.AlreadyLocked

Bases: exceptions.Exception

class avocado.utils.filelock.FileLock(filename, timeout=0)

Bases: object

Creates an exclusive advisory lock for a file. All processes should use and honor the advisory locking scheme, but uncooperative processes are free to ignore the lock and access the file in any way they choose.

exception avocado.utils.filelock.LockFailed

Bases: exceptions.Exception

avocado.utils.gdb module

Module that provides communication with GDB via its GDB/MI interpreter

class avocado.utils.gdb.GDB(path='/usr/bin/gdb', *extra_args)

Bases: object

Wraps a GDB subprocess for easier manipulation

DEFAULT_BREAK = 'main'
REQUIRED_ARGS = ['--interpreter=mi', '--quiet']
cli_cmd(command)

Sends a cli command encoded as an MI command

Parameters:command (str) – a regular GDB cli command
Returns:a CommandResult instance
Return type:CommandResult
cmd(command)

Sends a command and parses all lines until prompt is received

Parameters:command (str) – the GDB command, hopefully in MI language
Returns:a CommandResult instance
Return type:CommandResult
cmd_exists(command)

Checks if a given command exists

Parameters:command (str) – a GDB MI command, including the dash (-) prefix
Returns:either True or False
Return type:bool
connect(port)

Connects to a remote debugger (a gdbserver) at the given TCP port

This uses the “extended-remote” target type only

Parameters:port (int) – the TCP port number
Returns:a CommandResult instance
Return type:CommandResult
del_break(number)

Deletes a breakpoint by its number

Parameters:number (int) – the breakpoint number
Returns:a CommandResult instance
Return type:CommandResult
disconnect()

Disconnects from a remote debugger

Returns:a CommandResult instance
Return type:CommandResult
exit()

Exits the GDB application gracefully

Returns:the result of subprocess.POpen.wait(), that is, a subprocess.POpen.returncode
Return type:int or None
read_gdb_response(timeout=0.01, max_tries=100)

Read raw responses from GDB

Parameters:
  • timeout (float) – the amount of time to way between read attempts
  • max_tries (int) – the maximum number of cycles to try to read until a response is obtained
Returns:

a string containing a raw response from GDB

Return type:

str

read_until_break(max_lines=100)

Read lines from GDB until a break condition is reached

Parameters:max_lines (int) – the maximum number of lines to read
Returns:a list of messages read
Return type:list of str
run(args=None)

Runs the application inside the debugger

Parameters:args (builtin.list) – the arguments to be passed to the binary as command line arguments
Returns:a CommandResult instance
Return type:CommandResult
send_gdb_command(command)

Send a raw command to the GNU debugger input

Parameters:command (str) – the GDB command, hopefully in MI language
Returns:None
set_break(location, ignore_error=False)

Sets a new breakpoint on the binary currently being debugged

Parameters:location (str) – a breakpoint location expression as accepted by GDB
Returns:a CommandResult instance
Return type:CommandResult
set_file(path)

Sets the file that will be executed

Parameters:path (str) – the path of the binary that will be executed
Returns:a CommandResult instance
Return type:CommandResult
class avocado.utils.gdb.GDBServer(path='/usr/bin/gdbserver', port=None, wait_until_running=True, *extra_args)

Bases: object

Wraps a gdbserver instance

Initializes a new gdbserver instance

Parameters:
  • path (str) – location of the gdbserver binary
  • port (int) – tcp port number to listen on for incoming connections
  • wait_until_running (bool) – wait until the gdbserver is running and accepting connections. It may take a little after the process is started and it is actually bound to the allocated port
  • extra_args – optional extra arguments to be passed to gdbserver
INIT_TIMEOUT = 5.0

The time to optionally wait for the server to initialize itself and be ready to accept new connections

PORT_RANGE = (20000, 20999)

The range from which a port to GDB server will try to be allocated from

REQUIRED_ARGS = ['--multi']

The default arguments used when starting the GDB server process

exit(force=True)

Quits the gdb_server process

Most correct way of quitting the GDB server is by sending it a command. If no GDB client is connected, then we can try to connect to it and send a quit command. If this is not possible, we send it a signal and wait for it to finish.

Parameters:force (bool) – if a forced exit (sending SIGTERM) should be attempted
Returns:None
class avocado.utils.gdb.GDBRemote(host, port, no_ack_mode=True, extended_mode=True)

Bases: object

Initializes a new GDBRemote object.

A GDBRemote acts like a client that speaks the GDB remote protocol, documented at:

https://sourceware.org/gdb/current/onlinedocs/gdb/Remote-Protocol.html

Caveat: we currently do not support communicating with devices, only with TCP sockets. This limitation is basically due to the lack of use cases that justify an implementation, but not due to any technical shortcoming.

Parameters:
  • host (str) – the IP address or host name
  • port (int) – the port number where the the remote GDB is listening on
  • no_ack_mode (bool) – if the packet transmission confirmation mode should be disabled
  • extended_mode – if the remote extended mode should be enabled
cmd(command_data, expected_response=None)

Sends a command data to a remote gdb server

Limitations: the current version does not deal with retransmissions.

Parameters:
  • command_data (str) – the remote command to send the the remote stub
  • expected_response (str) – the (optional) response that is expected as a response for the command sent
Raises:

RetransmissionRequestedError, UnexpectedResponseError

Returns:

raw data read from from the remote server

Return type:

str

connect()

Connects to the remote target and initializes the chosen modes

set_extended_mode()

Enable extended mode. In extended mode, the remote server is made persistent. The ‘R’ packet is used to restart the program being debugged. Original documentation at:

https://sourceware.org/gdb/current/onlinedocs/gdb/Packets.html#extended-mode

start_no_ack_mode()

Request that the remote stub disable the normal +/- protocol acknowledgments. Original documentation at:

https://sourceware.org/gdb/current/onlinedocs/gdb/General-Query-Packets.html#QStartNoAckMode

avocado.utils.genio module

Avocado generic IO related functions.

exception avocado.utils.genio.GenIOError

Bases: exceptions.Exception

Base Exception Class for all IO exceptions

avocado.utils.genio.ask(question, auto=False)

Prompt the user with a (y/n) question.

Parameters:
  • question (str) – Question to be asked
  • auto (bool) – Whether to return “y” instead of asking the question
Returns:

User answer

Return type:

str

avocado.utils.genio.close_log_file(filename)
avocado.utils.genio.log_line(filename, line)

Write a line to a file.

Parameters:
  • filename – Path of file to write to, either absolute or relative to the dir set by set_log_file_dir().
  • line – Line to write.
avocado.utils.genio.read_all_lines(filename)

Return all lines of a given file

This utility method returns an empty list in any error scenario, that is, it doesn’t attempt to identify error paths and raise appropriate exceptions. It does exactly the opposite to that.

This should be used when it’s fine or desirable to have an empty set of lines if a file is missing or is unreadable.

Parameters:filename (str) – Path to the file.
Returns:all lines of the file as list
Return type:builtin.list
avocado.utils.genio.read_file(filename)

Read the entire contents of file.

Parameters:filename (str) – Path to the file.
Returns:File contents
Return type:str
avocado.utils.genio.read_one_line(filename)

Read the first line of filename.

Parameters:filename (str) – Path to the file.
Returns:First line contents
Return type:str
avocado.utils.genio.set_log_file_dir(directory)

Set the base directory for log files created by log_line().

Parameters:dir – Directory for log files.
avocado.utils.genio.write_file(filename, data)

Write data to a file.

Parameters:
  • filename (str) – Path to the file.
  • line (str) – Line to be written.
avocado.utils.genio.write_file_or_fail(filename, data)

Write to a file and raise exception on write failure

Parameters:
  • filename (str) – Path to file
  • data (str) – Data to be written to file
Raises:

GenIOError – On write Failure

avocado.utils.genio.write_one_line(filename, line)

Write one line of text to filename.

Parameters:
  • filename (str) – Path to the file.
  • line (str) – Line to be written.

avocado.utils.git module

APIs to download/update git repositories from inside python scripts.

class avocado.utils.git.GitRepoHelper(uri, branch='master', lbranch=None, commit=None, destination_dir=None, base_uri=None)

Bases: object

Helps to deal with git repos, mostly fetching content from a repo

Instantiates a new GitRepoHelper

Parameters:
  • uri (string) – git repository url
  • branch (string) – git remote branch
  • lbranch (string) – git local branch name, if different from remote
  • commit (string) – specific commit to download
  • destination_dir (string) – path of a dir where to save downloaded code
  • base_uri (string) – a closer, usually local, git repository url from where to fetch content first from
checkout(branch=None, commit=None)

Performs a git checkout for a given branch and start point (commit)

Parameters:
  • branch – Remote branch name.
  • commit – Specific commit hash.
execute()

Performs all steps necessary to initialize and download a git repo.

This includes the init, fetch and checkout steps in one single utility method.

fetch(uri)

Performs a git fetch from the remote repo

get_top_commit()

Returns the topmost commit id for the current branch.

Returns:Commit id.
get_top_tag()

Returns the topmost tag for the current branch.

Returns:Tag.
git_cmd(cmd, ignore_status=False)

Wraps git commands.

Parameters:
  • cmd – Command to be executed.
  • ignore_status – Whether we should suppress error.CmdError exceptions if the command did return exit code !=0 (True), or not suppress them (False).
init()

Initializes a directory for receiving a verbatim copy of git repo

This creates a directory if necessary, and either resets or inits the repo

avocado.utils.git.get_repo(uri, branch='master', lbranch=None, commit=None, destination_dir=None, base_uri=None)

Utility function that retrieves a given git code repository.

Parameters:
  • uri (string) – git repository url
  • branch (string) – git remote branch
  • lbranch (string) – git local branch name, if different from remote
  • commit (string) – specific commit to download
  • destination_dir (string) – path of a dir where to save downloaded code
  • base_uri (string) – a closer, usually local, git repository url from where to fetch content first from

avocado.utils.iso9660 module

Basic ISO9660 file-system support.

This code does not attempt (so far) to implement code that knows about ISO9660 internal structure. Instead, it uses commonly available support either in userspace tools or on the Linux kernel itself (via mount).

avocado.utils.iso9660.iso9660(path)

Checks the available tools on a system and chooses class accordingly

This is a convenience function, that will pick the first available iso9660 capable tool.

Parameters:path (str) – path to an iso9660 image file
Returns:an instance of any iso9660 capable tool
Return type:Iso9660IsoInfo, Iso9660IsoRead, Iso9660Mount or None
class avocado.utils.iso9660.Iso9660IsoInfo(path)

Bases: avocado.utils.iso9660.MixInMntDirMount, avocado.utils.iso9660.BaseIso9660

Represents a ISO9660 filesystem

This implementation is based on the cdrkit’s isoinfo tool

read(path)

Abstract method to read data from path

Parameters:path – path to the file
Returns:data content from the file
Return type:str
class avocado.utils.iso9660.Iso9660IsoRead(path)

Bases: avocado.utils.iso9660.MixInMntDirMount, avocado.utils.iso9660.BaseIso9660

Represents a ISO9660 filesystem

This implementation is based on the libcdio’s iso-read tool

close()

Cleanups and frees any resources being used

copy(src, dst)

Simplistic version of copy that relies on read()

Parameters:
  • src (str) – source path
  • dst (str) – destination path
Return type:

None

read(path)

Abstract method to read data from path

Parameters:path – path to the file
Returns:data content from the file
Return type:str
class avocado.utils.iso9660.Iso9660Mount(path)

Bases: avocado.utils.iso9660.BaseIso9660

Represents a mounted ISO9660 filesystem.

initializes a mounted ISO9660 filesystem

Parameters:path (str) – path to the ISO9660 file
close()

Perform umount operation on the temporary dir

Return type:None
copy(src, dst)
Parameters:
  • src (str) – source
  • dst (str) – destination
Return type:

None

mnt_dir
read(path)

Read data from path

Parameters:path (str) – path to read data
Returns:data content
Return type:str

avocado.utils.kernel module

class avocado.utils.kernel.KernelBuild(version, config_path=None, work_dir=None, data_dirs=None)

Bases: object

Build the Linux Kernel from official tarballs.

Creates an instance of KernelBuild.

Parameters:
  • version – kernel version (“3.19.8”).
  • config_path – path to config file.
  • work_dir – work directory.
  • data_dirs – list of directories to keep the downloaded kernel
Returns:

None.

SOURCE = 'linux-{version}.tar.gz'
URL = 'https://www.kernel.org/pub/linux/kernel/v{major}.x/'
build(binary_package=False)

Build kernel from source.

Parameters:binary_package – when True, the appropriate platform package is built for install() to use
configure()

Configure/prepare kernel source to build.

download(url=None)

Download kernel source.

Parameters:url (str or None) – override the url from where to fetch the kernel source tarball
install()

Install built kernel.

uncompress()

Uncompress kernel source.

avocado.utils.kernel.check_version(version)

This utility function compares the current kernel version with the version parameter and gives assertion error if the version parameter is greater.

Parameters:version (string) – version to be compared with current kernel version

avocado.utils.linux_modules module

Linux kernel modules APIs

avocado.utils.linux_modules.BUILTIN = 2

Config built-in to kernel (=y)

avocado.utils.linux_modules.MODULE = 1

Config compiled as loadable module (=m)

avocado.utils.linux_modules.NOT_SET = 0

Config commented out or not set

avocado.utils.linux_modules.check_kernel_config(config_name)

Reports the configuration of $config_name of the current kernel

Parameters:config_name (str) – Name of kernel config to search
Returns:Config status in running kernel (NOT_SET, BUILTIN, MODULE)
Return type:int
avocado.utils.linux_modules.get_loaded_modules()

Gets list of loaded modules. :return: List of loaded modules.

avocado.utils.linux_modules.get_submodules(module_name)

Get all submodules of the module.

Parameters:module_name (str) – Name of module to search for
Returns:List of the submodules
Return type:builtin.list
avocado.utils.linux_modules.load_module(module_name)

Checks if a module has already been loaded. :param module_name: Name of module to check :return: True if module is loaded, False otherwise :rtype: Bool

avocado.utils.linux_modules.loaded_module_info(module_name)

Get loaded module details: Size and Submodules.

Parameters:module_name (str) – Name of module to search for
Returns:Dictionary of module name, size, submodules if present, filename, version, number of modules using it, list of modules it is dependent on, list of dictionary of param name and type
Return type:dict
avocado.utils.linux_modules.module_is_loaded(module_name)

Is module loaded

Parameters:module_name (str) – Name of module to search for
Returns:True if module is loaded
Return type:bool
avocado.utils.linux_modules.parse_lsmod_for_module(l_raw, module_name, escape=True)

Use a regexp to parse raw lsmod output and get module information :param l_raw: raw output of lsmod :type l_raw: str :param module_name: Name of module to search for :type module_name: str :param escape: Escape regexp tokens in module_name, default True :type escape: bool :return: Dictionary of module info, name, size, submodules if present :rtype: dict

avocado.utils.linux_modules.unload_module(module_name)

Removes a module. Handles dependencies. If even then it’s not possible to remove one of the modules, it will throw an error.CmdError exception.

Parameters:module_name (str) – Name of the module we want to remove.

avocado.utils.lv_utils module

exception avocado.utils.lv_utils.LVException

Bases: exceptions.Exception

Base Exception Class for all exceptions

avocado.utils.lv_utils.get_diskspace(disk)

Get the entire disk space of a given disk

Parameters:disk – Name of the disk to find free space
Returns:size in bytes
avocado.utils.lv_utils.lv_check(vg_name, lv_name)

Check whether provided Logical volume exists.

Parameters:
  • vg_name – Name of the volume group
  • lv_name – Name of the logical volume
avocado.utils.lv_utils.lv_create(vg_name, lv_name, lv_size, force_flag=True)

Create a Logical volume in a volume group. The volume group must already exist.

Parameters:
  • vg_name – Name of the volume group
  • lv_name – Name of the logical volume
  • lv_size – Size for the logical volume to be created
avocado.utils.lv_utils.lv_list()

List available group volumes.

:return list available logical volumes

avocado.utils.lv_utils.lv_mount(vg_name, lv_name, mount_loc, create_filesystem='')

Mount a Logical volume to a mount location.

Parameters:
  • vg_name – Name of volume group
  • lv_name – Name of the logical volume
  • create_filesystem – Can be one of ext2, ext3, ext4, vfat or empty if the filesystem was already created and the mkfs process is skipped
Mount_loc:

Location to mount the logical volume

avocado.utils.lv_utils.lv_reactivate(vg_name, lv_name, timeout=10)

In case of unclean shutdowns some of the lvs is still active and merging is postponed. Use this function to attempt to deactivate and reactivate all of them to cause the merge to happen.

Parameters:
  • vg_name – Name of volume group
  • lv_name – Name of the logical volume
  • timeout – Timeout between operations
avocado.utils.lv_utils.lv_remove(vg_name, lv_name)

Remove a logical volume.

Parameters:
  • vg_name – Name of the volume group
  • lv_name – Name of the logical volume
avocado.utils.lv_utils.lv_revert(vg_name, lv_name, lv_snapshot_name)

Revert the origin to a snapshot.

Parameters:
  • vg_name – An existing volume group
  • lv_name – An existing logical volume
  • lv_snapshot_name – Name of the snapshot be to reverted
avocado.utils.lv_utils.lv_revert_with_snapshot(vg_name, lv_name, lv_snapshot_name, lv_snapshot_size)

Perform Logical volume merge with snapshot and take a new snapshot.

Parameters:
  • vg_name – Name of volume group in which lv has to be reverted
  • lv_name – Name of the logical volume to be reverted
  • lv_snapshot_name – Name of the snapshot be to reverted
  • lv_snapshot_size – Size of the snapshot
avocado.utils.lv_utils.lv_take_snapshot(vg_name, lv_name, lv_snapshot_name, lv_snapshot_size)

Take a snapshot of the original Logical volume.

Parameters:
  • vg_name – An existing volume group
  • lv_name – An existing logical volume
  • lv_snapshot_name – Name of the snapshot be to created
  • lv_snapshot_size – Size of the snapshot
avocado.utils.lv_utils.lv_umount(vg_name, lv_name)

Unmount a Logical volume from a mount location.

Parameters:
  • vg_name – Name of volume group
  • lv_name – Name of the logical volume
avocado.utils.lv_utils.thin_lv_create(vg_name, thinpool_name='lvthinpool', thinpool_size='1.5G', thinlv_name='lvthin', thinlv_size='1G')

Create a thin volume from given volume group.

Parameters:
  • vg_name – An exist volume group
  • thinpool_name – The name of thin pool
  • thinpool_size – The size of thin pool to be created
  • thinlv_name – The name of thin volume
  • thinlv_size – The size of thin volume
avocado.utils.lv_utils.vg_check(vg_name)

Check whether provided volume group exists.

Parameters:vg_name – Name of the volume group.
avocado.utils.lv_utils.vg_create(vg_name, pv_list, force=False)

Create a volume group by using the block special devices

Parameters:
  • vg_name – Name of the volume group
  • pv_list – List of physical volumes
  • force – Create volume group forcefully
avocado.utils.lv_utils.vg_list()

List available volume groups.

:return List of volume groups.

avocado.utils.lv_utils.vg_ramdisk(disk, vg_name, ramdisk_vg_size, ramdisk_basedir, ramdisk_sparse_filename)

Create vg on top of ram memory to speed up lv performance. When disk is specified size of the physical volume is taken from existing disk space.

Parameters:
  • disk – Name of the disk in which volume groups are created.
  • vg_name – Name of the volume group.
  • ramdisk_vg_size – Size of the ramdisk virtual group (MB).
  • ramdisk_basedir – Base directory for the ramdisk sparse file.
  • ramdisk_sparse_filename – Name of the ramdisk sparse file.
Returns:

ramdisk_filename, vg_ramdisk_dir, vg_name, loop_device

Raises:

LVException – On failure

Sample ramdisk params: - ramdisk_vg_size = “40000” - ramdisk_basedir = “/tmp” - ramdisk_sparse_filename = “virtual_hdd”

Sample general params: - vg_name=’autotest_vg’, - lv_name=’autotest_lv’, - lv_size=‘1G’, - lv_snapshot_name=’autotest_sn’, - lv_snapshot_size=‘1G’ The ramdisk volume group size is in MB.

avocado.utils.lv_utils.vg_ramdisk_cleanup(ramdisk_filename=None, vg_ramdisk_dir=None, vg_name=None, loop_device=None)

Inline cleanup function in case of test error.

It detects whether the components were initialized and if so it tries to remove them. In case of failure it raises summary exception.

Parameters:
  • ramdisk_filename – Name of the ramdisk sparse file.
  • vg_ramdisk_dir – Location of the ramdisk file
Vg_name:

Name of the volume group

Loop_device:

Name of the disk or loop device

Raises:

LVException – In case it fail to clean things detected in system

avocado.utils.lv_utils.vg_remove(vg_name)

Remove a volume group.

Parameters:vg_name – Name of the volume group

avocado.utils.memory module

exception avocado.utils.memory.MemError

Bases: exceptions.Exception

called when memory operations fails

class avocado.utils.memory.MemInfo

Bases: object

Representation of /proc/meminfo

avocado.utils.memory.check_hotplug()

Check kernel support for memory hotplug

Returns:True if hotplug supported, else False
Return type:‘bool’
avocado.utils.memory.drop_caches()

Writes back all dirty pages to disk and clears all the caches.

avocado.utils.memory.freememtotal()

Read MemFree from meminfo.

avocado.utils.memory.get_blk_string(block)

Format the given block id to string

Parameters:block – memory block id or block string.
Returns:returns string memory198 if id 198 is given
Return type:string
avocado.utils.memory.get_buddy_info(chunk_sizes, nodes='all', zones='all')

Get the fragement status of the host.

It uses the same method to get the page size in buddyinfo. The expression to evaluate it is:

2^chunk_size * page_size

The chunk_sizes can be string make up by all orders that you want to check split with blank or a mathematical expression with >, < or =.

For example:
  • The input of chunk_size could be: 0 2 4, and the return will be {'0': 3, '2': 286, '4': 687}
  • If you are using expression: >=9 the return will be {'9': 63, '10': 225}
Parameters:
  • chunk_size (string) – The order number shows in buddyinfo. This is not the real page size.
  • nodes (string) – The numa node that you want to check. Default value is all
  • zones (string) – The memory zone that you want to check. Default value is all
Returns:

A dict using the chunk_size as the keys

Return type:

dict

avocado.utils.memory.get_huge_page_size()

Get size of the huge pages for this system.

Returns:Huge pages size (KB).
avocado.utils.memory.get_num_huge_pages()

Get number of huge pages for this system.

Returns:Number of huge pages.
avocado.utils.memory.get_page_size()

Get linux page size for this system.

:return Kernel page size (Bytes).

avocado.utils.memory.get_thp_value(feature)

Gets the value of the thp feature arg passed

Param feature:Thp feature to get value
avocado.utils.memory.hotplug(block)

Online the memory for the given block id.

Parameters:block – memory block id or or memory198
avocado.utils.memory.hotunplug(block)

Offline the memory for the given block id.

Parameters:block – memory block id.
avocado.utils.memory.is_hot_pluggable(block)

Check if the given memory block is hotpluggable

Parameters:block – memory block id.
Returns:True if hotpluggable, else False
Return type:‘bool’
avocado.utils.memory.memtotal()

Read Memtotal from meminfo.

avocado.utils.memory.memtotal_sys()

Reports actual memory size according to online-memory blocks available via “/sys”

Returns:system memory in Kb as float
avocado.utils.memory.node_size()

Return node size.

Returns:Node size.
avocado.utils.memory.numa_nodes()

Get a list of NUMA nodes present on the system.

Returns:List with nodes.
avocado.utils.memory.numa_nodes_with_memory()

Get a list of NUMA nodes present with memory on the system.

Returns:List with nodes which has memory.
avocado.utils.memory.read_from_meminfo(key)

Retrieve key from meminfo.

Parameters:key – Key name, such as MemTotal.
avocado.utils.memory.read_from_numa_maps(pid, key)

Get the process numa related info from numa_maps. This function only use to get the numbers like anon=1.

Parameters:
  • pid (String) – Process id
  • key (String) – The item you want to check from numa_maps
Returns:

A dict using the address as the keys

Return type:

dict

avocado.utils.memory.read_from_smaps(pid, key)

Get specific item value from the smaps of a process include all sections.

Parameters:
  • pid (String) – Process id
  • key (String) – The item you want to check from smaps
Returns:

The value of the item in kb

Return type:

int

avocado.utils.memory.read_from_vmstat(key)

Get specific item value from vmstat

Parameters:key (String) – The item you want to check from vmstat
Returns:The value of the item
Return type:int
avocado.utils.memory.rounded_memtotal()

Get memtotal, properly rounded.

Returns:Total memory, KB.
avocado.utils.memory.set_num_huge_pages(num)

Set number of huge pages.

Parameters:num – Target number of huge pages.
avocado.utils.memory.set_thp_value(feature, value)

Sets THP feature to a given value

Parameters:
  • feature (str) – Thp feature to set
  • value (str) – Value to be set to feature

avocado.utils.multipath module

Module with multipath related utility functions. It needs root access.

avocado.utils.multipath.device_exists(path)

Checks if a given path exists.

Returns:True if path exists, False if does not exist.
avocado.utils.multipath.fail_path(path)

failing the individual paths :param disk_path: disk path. Example: sda, sdb. :return: True or False

avocado.utils.multipath.flush_path(path_name)

Flushes the given multipath.

Returns:Returns False if command fails, True otherwise.
avocado.utils.multipath.form_conf_mpath_file(blacklist='', defaults_extra='')

Form a multipath configuration file, and restart multipath service.

Parameters:
  • blacklist – Entry in conf file to indicate blacklist section.
  • defaults_extra – Extra entry in conf file in defaults section.
avocado.utils.multipath.get_mpath_name(wwid)

Get multipath name for a given wwid.

Parameters:wwid – wwid of multipath device.
Returns:Name of multipath device.
avocado.utils.multipath.get_multipath_details()

Get multipath details as a dictionary, as given by the command: multipathd show maps json

Returns:Dictionary of multipath output in json format.
avocado.utils.multipath.get_multipath_wwids()

Get list of multipath wwids.

Returns:List of multipath wwids.
avocado.utils.multipath.get_path_status(disk_path)

Return the status of a path in multipath.

Parameters:disk_path – disk path. Example: sda, sdb.
Returns:Tuple in the format of (dm status, dev status, checker status)
avocado.utils.multipath.get_paths(wwid)

Get list of paths, given a multipath wwid.

Returns:List of paths.
avocado.utils.multipath.get_policy(wwid)

Gets path_checker policy, given a multipath wwid.

Returns:path checker policy.
avocado.utils.multipath.get_size(wwid)

Gets size of device, given a multipath wwid.

Returns:size of multipath device.
avocado.utils.multipath.get_svc_name()

Gets the multipath service name based on distro.

avocado.utils.multipath.is_path_a_multipath(disk_path)

Check if given disk path is part of a multipath.

Parameters:disk_path – disk path. Example: sda, sdb.
Returns:True if part of multipath, else False.
avocado.utils.multipath.reinstate_path(path)

reinstating the individual paths :param disk_path: disk path. Example: sda, sdb. :return: True or False

avocado.utils.network module

Module with network related utility functions

class avocado.utils.network.PortTracker

Bases: avocado.utils.data_structures.Borg

Tracks ports used in the host machine.

find_free_port(start_port=None)
register_port(port)
release_port(port)
avocado.utils.network.find_free_port(start_port, end_port, address='localhost', sequent=True)

Return a host free port in the range [start_port, end_port].

Parameters:
  • start_port – header of candidate port range
  • end_port – ender of candidate port range
  • sequent – Find port sequentially, random order if it’s False
  • address – Socket address to bind or connect
avocado.utils.network.find_free_ports(start_port, end_port, count, address='localhost', sequent=True)

Return count of host free ports in the range [start_port, end_port].

Parameters:
  • start_port – header of candidate port range
  • end_port – ender of candidate port range
  • count – Initial number of ports known to be free in the range.
  • address – Socket address to bind or connect
  • sequent – Find port sequentially, random order if it’s False
avocado.utils.network.is_port_free(port, address)

Return True if the given port is available for use.

Parameters:
  • port – Port number
  • address – Socket address to bind or connect

avocado.utils.output module

Utility functions for user friendly display of information.

class avocado.utils.output.ProgressBar(minimum=0, maximum=100, width=75, title='')

Bases: object

Displays interactively the progress of a given task

Inspired/adapted from https://gist.github.com/t0xicCode/3306295

Initializes a new progress bar

Parameters:
  • minimum (integer) – minimum (initial) value on the progress bar
  • maximum (integer) – maximum (final) value on the progress bar
  • with – number of columns, that is screen width
append_amount(amount)

Increments the current amount value.

draw()

Prints the updated text to the screen.

update_amount(amount)

Performs sanity checks and update the current amount.

update_percentage(percentage)

Updates the progress bar to the new percentage.

avocado.utils.output.display_data_size(size)

Display data size in human readable units (SI).

Parameters:size (int) – Data size, in Bytes.
Returns:Human readable string with data size, using SI prefixes.

avocado.utils.partition module

Utility for handling partitions.

class avocado.utils.partition.MtabLock

Bases: object

mtab = None
class avocado.utils.partition.Partition(device, loop_size=0, mountpoint=None)

Bases: object

Class for handling partitions and filesystems

Parameters:
  • device – The device in question (e.g.”/dev/hda2”). If device is a file it will be mounted as loopback.
  • loop_size – Size of loopback device (in MB). Defaults to 0.
  • mountpoint – Where the partition to be mounted to.
get_mountpoint(filename=None)

Find the mount point of this partition object.

Parameters:filename – where to look for the mounted partitions information (default None which means it will search /proc/mounts and/or /etc/mtab)
Returns:a string with the mount point of the partition or None if not mounted
static list_mount_devices()

Lists mounted file systems and swap on devices.

static list_mount_points()

Lists the mount points.

mkfs(fstype=None, args='')

Format a partition to filesystem type

Parameters:
  • fstype – the filesystem type, such as “ext3”, “ext2”. Defaults to previously set type or “ext2” if none has set.
  • args – arguments to be passed to mkfs command.
mount(mountpoint=None, fstype=None, args='')

Mount this partition to a mount point

Parameters:
  • mountpoint – If you have not provided a mountpoint to partition object or want to use a different one, you may specify it here.
  • fstype – Filesystem type. If not provided partition object value will be used.
  • args – Arguments to be passed to “mount” command.
unmount(force=True)

Umount this partition.

It’s easier said than done to umount a partition. We need to lock the mtab file to make sure we don’t have any locking problems if we are umounting in parallel.

When the unmount fails and force==True we unmount the partition ungracefully.

Returns:1 on success, 2 on force umount success
Raises:PartitionError – On failure
exception avocado.utils.partition.PartitionError(partition, reason, details=None)

Bases: exceptions.Exception

Generic PartitionError

avocado.utils.path module

Avocado path related functions.

exception avocado.utils.path.CmdNotFoundError(cmd, paths)

Bases: exceptions.Exception

Indicates that the command was not found in the system after a search.

Parameters:
  • cmd – String with the command.
  • paths – List of paths where we looked after.
class avocado.utils.path.PathInspector(path)

Bases: object

get_first_line()
has_exec_permission()
is_empty()
is_python()
is_script(language=None)
avocado.utils.path.find_command(cmd, default=None)

Try to find a command in the PATH, paranoid version.

Parameters:
  • cmd – Command to be found.
  • default – Command path to use as a fallback if not found in the standard directories.
Raise:

avocado.utils.path.CmdNotFoundError in case the command was not found and no default was given.

avocado.utils.path.get_path(base_path, user_path)

Translate a user specified path to a real path. If user_path is relative, append it to base_path. If user_path is absolute, return it as is.

Parameters:
  • base_path – The base path of relative user specified paths.
  • user_path – The user specified path.
avocado.utils.path.init_dir(*args)

Wrapper around os.path.join that creates dirs based on the final path.

Parameters:args – List of dir arguments that will be os.path.joined.
Returns:directory.
Return type:str
avocado.utils.path.usable_ro_dir(directory)

Verify whether dir exists and we can access its contents.

If a usable RO is there, use it no questions asked. If not, let’s at least try to create one.

Parameters:directory – Directory
avocado.utils.path.usable_rw_dir(directory)

Verify whether we can use this dir (read/write).

Checks for appropriate permissions, and creates missing dirs as needed.

Parameters:directory – Directory

avocado.utils.pci module

Module for all PCI devices related functions.

avocado.utils.pci.get_cfg(dom_pci_address)

Gets the hardware configuration data of the given PCI address.

Note:Specific for ppc64 processor.
Parameters:dom_pci_address – Partial PCI address including domain addr and at least bus addr (0003:00, 0003:00:1f.2, …)
Returns:dictionary of configuration data of a PCI address.
avocado.utils.pci.get_disks_in_pci_address(pci_address)

Gets disks in a PCI address.

Parameters:pci_address – Any segment of a PCI address (1f, 0000:00:1f, …)
Returns:list of disks in a PCI address.
avocado.utils.pci.get_domains()

Gets all PCI domains. Example, it returns [‘0000’, ‘0001’, …]

Returns:List of PCI domains.
avocado.utils.pci.get_driver(pci_address)

Gets the kernel driver in use of given PCI address. (first match only)

Parameters:pci_address – Any segment of a PCI address (1f, 0000:00:1f, …)
Returns:driver of a PCI address.
avocado.utils.pci.get_interfaces_in_pci_address(pci_address, pci_class)

Gets interface in a PCI address.

e.g: host = pci.get_interfaces_in_pci_address(“0001:01:00.0”, “net”)
[‘enP1p1s0f0’] host = pci.get_interfaces_in_pci_address(“0004:01:00.0”, “fc_host”) [‘host6’]
Parameters:
  • pci_address – Any segment of a PCI address (1f, 0000:00:1f, …)
  • class – Adapter type (FC(fc_host), FCoE(net), NIC(net), SCSI(scsi)..)
Returns:

list of generic interfaces in a PCI address.

avocado.utils.pci.get_mask(pci_address)

Gets the mask of PCI address. (first match only)

Note:There may be multiple memory entries for a PCI address.
Note:This mask is calculated only with the first such entry.
Parameters:pci_address – Any segment of a PCI address (1f, 0000:00:1f, …)
Returns:mask of a PCI address.
avocado.utils.pci.get_memory_address(pci_address)

Gets the memory address of a PCI address. (first match only)

Note:There may be multiple memory address for a PCI address.
Note:This function returns only the first such address.
Parameters:pci_address – Any segment of a PCI address (1f, 0000:00:1f, …)
Returns:memory address of a pci_address.
avocado.utils.pci.get_nics_in_pci_address(pci_address)

Gets network interface(nic) in a PCI address.

Parameters:pci_address – Any segment of a PCI address (1f, 0000:00:1f, …)
Returns:list of network interfaces in a PCI address.
avocado.utils.pci.get_num_interfaces_in_pci(dom_pci_address)

Gets number of interfaces of a given partial PCI address starting with full domain address.

Parameters:dom_pci_address – Partial PCI address including domain address (0000, 0000:00:1f, 0000:00:1f.2, etc)
Returns:number of devices in a PCI domain.
avocado.utils.pci.get_pci_addresses()

Gets list of PCI addresses in the system. Does not return the PCI Bridges/Switches.

Returns:list of full PCI addresses including domain (0000:00:14.0)
avocado.utils.pci.get_pci_class_name(pci_address)

Gets pci class name for given pci bus address

e.g: >>> pci.get_pci_class_name(“0000:01:00.0”)
‘scsi_host’
Parameters:pci_address – Any segment of a PCI address(1f, 0000:00:if, …)
Returns:class name for corresponding pci bus address
avocado.utils.pci.get_pci_fun_list(pci_address)

Gets list of functions in the given PCI address. Example: in address 0000:03:00, functions are 0000:03:00.0 and 0000:03:00.1

Parameters:pci_address – Any segment of a PCI address (1f, 0000:00:1f, …)
Returns:list of functions in a PCI address.
avocado.utils.pci.get_pci_id(pci_address)

Gets PCI id of given address. (first match only)

Parameters:pci_address – Any segment of a PCI address (1f, 0000:00:1f, …)
Returns:PCI ID of a PCI address.
avocado.utils.pci.get_pci_id_from_sysfs(full_pci_address)

Gets the PCI ID from sysfs of given PCI address.

Parameters:full_pci_address – Full PCI address including domain (0000:03:00.0)
Returns:PCI ID of a PCI address from sysfs.
avocado.utils.pci.get_pci_prop(pci_address, prop)

Gets specific PCI ID of given PCI address. (first match only)

Parameters:
  • pci_address – Any segment of a PCI address (1f, 0000:00:1f, …)
  • part – prop of PCI ID.
Returns:

specific PCI ID of a PCI address.

avocado.utils.pci.get_slot_from_sysfs(full_pci_address)

Gets the PCI slot of given address.

Note:Specific for ppc64 processor.
Parameters:full_pci_address – Full PCI address including domain (0000:03:00.0)
Returns:Removed port related details using re, only returns till physical slot of the adapter.
avocado.utils.pci.get_slot_list()

Gets list of PCI slots in the system.

Note:Specific for ppc64 processor.
Returns:list of slots in the system.
avocado.utils.pci.get_vpd(dom_pci_address)

Gets the VPD (Virtual Product Data) of the given PCI address.

Note:Specific for ppc64 processor.
Parameters:dom_pci_address – Partial PCI address including domain addr and at least bus addr (0003:00, 0003:00:1f.2, …)
Returns:dictionary of VPD of a PCI address.

avocado.utils.process module

Functions dedicated to find and run external commands.

avocado.utils.process.CURRENT_WRAPPER = None

The active wrapper utility script.

exception avocado.utils.process.CmdError(command=None, result=None, additional_text=None)

Bases: exceptions.Exception

class avocado.utils.process.CmdResult(command='', stdout='', stderr='', exit_status=None, duration=0, pid=None, encoding=None)

Bases: object

Command execution result.

Parameters:
  • command (str) – the command line itself
  • exit_status (int) – exit code of the process
  • stdout (bytes) – content of the process stdout
  • stderr (bytes) – content of the process stderr
  • duration (float) – elapsed wall clock time running the process
  • pid (int) – ID of the process
  • encoding (str) – the encoding to use for the text version of stdout and stderr, by default avocado.utils.astring.ENCODING
stderr = None

The raw stderr (bytes)

stderr_text
stdout = None

The raw stdout (bytes)

stdout_text
class avocado.utils.process.FDDrainer(fd, result, name=None, logger=None, logger_prefix='%s', stream_logger=None, ignore_bg_processes=False, verbose=False)

Bases: object

Reads data from a file descriptor in a thread, storing locally in a file-like data object.

Parameters:
  • fd (int) – a file descriptor that will be read (drained) from
  • result (a CmdResult instance) – a CmdResult instance associated with the process used to detect if the process is still running and if there’s still data to be read.
  • name (str) – a descriptive name that will be passed to the Thread name
  • logger (logging.Logger) – the logger that will be used to (interactively) write the content from the file descriptor
  • logger_prefix (str with one %-style string formatter) – the prefix used when logging the data
  • ignore_bg_processes (boolean) – When True the process does not wait for child processes which keep opened stdout/stderr streams after the main process finishes (eg. forked daemon which did not closed the stdout/stderr). Note this might result in missing output produced by those daemons after the main thread finishes and also it allows those daemons to be running after the process finishes.
  • verbose (boolean) – whether to log in both the logger and stream_logger
flush()
start()
class avocado.utils.process.GDBSubProcess(cmd, verbose=True, allow_output_check=None, shell=False, env=None, sudo=False, ignore_bg_processes=False, encoding=None)

Bases: object

Runs a subprocess inside the GNU Debugger

Creates the subprocess object, stdout/err, reader threads and locks.

Parameters:
  • cmd (str) – Command line to run.
  • allow_output_check – Currently ignored in GDBSubProcess
  • shell – Currently ignored in GDBSubProcess
  • env – Currently ignored in GDBSubProcess
  • sudo – Currently ignored in GDBSubProcess
  • ignore_bg_processes – Currently ignored in GDBSubProcess
  • encoding (str) – the encoding to use for the text representation of the command result stdout and stderr, by default avocado.utils.astring.ENCODING
Params verbose:

Currently ignored in GDBSubProcess

create_and_wait_on_resume_fifo(path)

Creates a FIFO file and waits until it’s written to

Parameters:path (str) – the path that the file will be created
Returns:first character that was written to the fifo
Return type:str
generate_core()
generate_gdb_connect_cmds()
generate_gdb_connect_sh()
handle_break_hit(response)
handle_fatal_signal(response)
run(timeout=None)
wait_for_exit()

Waits until debugger receives a message about the binary exit

avocado.utils.process.OUTPUT_CHECK_RECORD_MODE = None

The current output record mode. It’s not possible to record both the ‘stdout’ and ‘stderr’ streams, and at the same time in the right order, the combined ‘output’ stream. So this setting defines the mode.

class avocado.utils.process.SubProcess(cmd, verbose=True, allow_output_check=None, shell=False, env=None, sudo=False, ignore_bg_processes=False, encoding=None)

Bases: object

Run a subprocess in the background, collecting stdout/stderr streams.

Creates the subprocess object, stdout/err, reader threads and locks.

Parameters:
  • cmd (str) – Command line to run.
  • verbose (bool) – Whether to log the command run and stdout/stderr.
  • allow_output_check (str) – Whether to record the output from this process (from stdout and stderr) in the test’s output record files. Valid values: ‘stdout’, for standard output only, ‘stderr’ for standard error only, ‘both’ for both standard output and error in separate files, ‘combined’ for standard output and error in a single file, and ‘none’ to disable all recording. ‘all’ is also a valid, but deprecated, option that is a synonym of ‘both’. If an explicit value is not given to this parameter, that is, if None is given, it defaults to using the module level configuration, as set by OUTPUT_CHECK_RECORD_MODE. If the module level configuration itself is not set, it defaults to ‘none’.
  • shell (bool) – Whether to run the subprocess in a subshell.
  • env (dict) – Use extra environment variables.
  • sudo (bool) – Whether the command requires admin privileges to run, so that sudo will be prepended to the command. The assumption here is that the user running the command has a sudo configuration such that a password won’t be prompted. If that’s not the case, the command will straight out fail.
  • ignore_bg_processes – When True the process does not wait for child processes which keep opened stdout/stderr streams after the main process finishes (eg. forked daemon which did not closed the stdout/stderr). Note this might result in missing output produced by those daemons after the main thread finishes and also it allows those daemons to be running after the process finishes.
  • encoding (str) – the encoding to use for the text representation of the command result stdout and stderr, by default avocado.utils.astring.ENCODING
Raises:

ValueError if incorrect values are given to parameters

get_pid()

Reports PID of this process

get_stderr()

Get the full stderr of the subprocess so far.

Returns:Standard error of the process.
Return type:str
get_stdout()

Get the full stdout of the subprocess so far.

Returns:Standard output of the process.
Return type:str
kill()

Send a signal.SIGKILL to the process.

poll()

Call the subprocess poll() method, fill results if rc is not None.

run(timeout=None, sig=15)

Start a process and wait for it to end, returning the result attr.

If the process was already started using .start(), this will simply wait for it to end.

Parameters:
  • timeout (float) – Time (seconds) we’ll wait until the process is finished. If it’s not, we’ll try to terminate it and get a status.
  • sig (int) – Signal to send to the process in case it did not end after the specified timeout.
Returns:

The command result object.

Return type:

A CmdResult instance.

send_signal(sig)

Send the specified signal to the process.

Parameters:sig – Signal to send.
start()

Start running the subprocess.

This method is particularly useful for background processes, since you can start the subprocess and not block your test flow.

Returns:Subprocess PID.
Return type:int
stop()

Stop background subprocess.

Call this method to terminate the background subprocess and wait for it results.

terminate()

Send a signal.SIGTERM to the process.

wait()

Call the subprocess poll() method, fill results if rc is not None.

avocado.utils.process.UNDEFINED_BEHAVIOR_EXCEPTION = None

Exception to be raised when users of this API need to know that the execution of a given process resulted in undefined behavior. One concrete example when a user, in an interactive session, let the inferior process exit before before avocado resumed the debugger session. Since the information is unknown, and the behavior is undefined, this situation will be flagged by an exception.

avocado.utils.process.WRAP_PROCESS = None

The global wrapper. If set, run every process under this wrapper.

avocado.utils.process.WRAP_PROCESS_NAMES_EXPR = []

Set wrapper per program names. A list of wrappers and program names. Format: [ (‘/path/to/wrapper.sh’, ‘progname’), … ]

class avocado.utils.process.WrapSubProcess(cmd, verbose=True, allow_output_check=None, shell=False, env=None, wrapper=None, sudo=False, ignore_bg_processes=False, encoding=None)

Bases: avocado.utils.process.SubProcess

Wrap subprocess inside an utility program.

avocado.utils.process.binary_from_shell_cmd(cmd)

Tries to find the first binary path from a simple shell-like command.

Note:It’s a naive implementation, but for commands like: VAR=VAL binary -args || true gives the right result (binary)
Parameters:cmd (unicode string) – simple shell-like binary
Returns:first found binary from the cmd
avocado.utils.process.can_sudo(cmd=None)

Check whether sudo is available (or running as root)

Parameters:cmd – unicode string with the commands
avocado.utils.process.cmd_split(cmd)

Splits a command line into individual components

This is a simple wrapper around shlex.split(), which has the requirement of having text (not bytes) as its argument on Python 3, but bytes on Python 2.

Parameters:cmd – text (a multi byte string) encoded as ‘utf-8’
avocado.utils.process.get_children_pids(ppid, recursive=False)

Get all PIDs of children/threads of parent ppid param ppid: parent PID param recursive: True to return all levels of sub-processes return: list of PIDs of all children/threads of ppid

avocado.utils.process.get_sub_process_klass(cmd)

Which sub process implementation should be used

Either the regular one, or the GNU Debugger version

Parameters:cmd – the command arguments, from where we extract the binary name
avocado.utils.process.getoutput(cmd, timeout=None, verbose=False, ignore_status=True, allow_output_check='combined', shell=True, env=None, sudo=False, ignore_bg_processes=False)

Because commands module is removed in Python3 and it redirect stderr to stdout, we port commands.getoutput to make code compatible Return output (stdout or stderr) of executing cmd in a shell.

Parameters:
  • cmd (str) – Command line to run.
  • timeout (float) – Time limit in seconds before attempting to kill the running process. This function will take a few seconds longer than ‘timeout’ to complete if it has to kill the process.
  • verbose (bool) – Whether to log the command run and stdout/stderr.
  • ignore_status – Whether to raise an exception when command returns =! 0 (False), or not (True).
  • allow_output_check (str) – Whether to record the output from this process (from stdout and stderr) in the test’s output record files. Valid values: ‘stdout’, for standard output only, ‘stderr’ for standard error only, ‘both’ for both standard output and error in separate files, ‘combined’ for standard output and error in a single file, and ‘none’ to disable all recording. ‘all’ is also a valid, but deprecated, option that is a synonym of ‘both’. If an explicit value is not given to this parameter, that is, if None is given, it defaults to using the module level configuration, as set by OUTPUT_CHECK_RECORD_MODE. If the module level configuration itself is not set, it defaults to ‘none’.
  • shell (bool) – Whether to run the command on a subshell
  • env (dict) – Use extra environment variables
  • sudo (bool) – Whether the command requires admin privileges to run, so that sudo will be prepended to the command. The assumption here is that the user running the command has a sudo configuration such that a password won’t be prompted. If that’s not the case, the command will straight out fail.
  • ignore_bg_processes (bool) – Whether to ignore background processes
Returns:

Command output(stdout or stderr).

Return type:

str

avocado.utils.process.getstatusoutput(cmd, timeout=None, verbose=False, ignore_status=True, allow_output_check='combined', shell=True, env=None, sudo=False, ignore_bg_processes=False)

Because commands module is removed in Python3 and it redirect stderr to stdout, we port commands.getstatusoutput to make code compatible Return (status, output) of executing cmd in a shell.

Parameters:
  • cmd (str) – Command line to run.
  • timeout (float) – Time limit in seconds before attempting to kill the running process. This function will take a few seconds longer than ‘timeout’ to complete if it has to kill the process.
  • verbose (bool) – Whether to log the command run and stdout/stderr.
  • ignore_status – Whether to raise an exception when command returns =! 0 (False), or not (True).
  • allow_output_check (str) – Whether to record the output from this process (from stdout and stderr) in the test’s output record files. Valid values: ‘stdout’, for standard output only, ‘stderr’ for standard error only, ‘both’ for both standard output and error in separate files, ‘combined’ for standard output and error in a single file, and ‘none’ to disable all recording. ‘all’ is also a valid, but deprecated, option that is a synonym of ‘both’. If an explicit value is not given to this parameter, that is, if None is given, it defaults to using the module level configuration, as set by OUTPUT_CHECK_RECORD_MODE. If the module level configuration itself is not set, it defaults to ‘none’.
  • shell (bool) – Whether to run the command on a subshell
  • env (dict) – Use extra environment variables
  • sudo (bool) – Whether the command requires admin privileges to run, so that sudo will be prepended to the command. The assumption here is that the user running the command has a sudo configuration such that a password won’t be prompted. If that’s not the case, the command will straight out fail.
  • ignore_bg_processes (bool) – Whether to ignore background processes
Returns:

Exit status and command output(stdout and stderr).

Return type:

tuple

avocado.utils.process.kill_process_by_pattern(pattern)

Send SIGTERM signal to a process with matched pattern.

Parameters:pattern – normally only matched against the process name
avocado.utils.process.kill_process_tree(pid, sig=9, send_sigcont=True)

Signal a process and all of its children.

If the process does not exist – return.

Parameters:
  • pid – The pid of the process to signal.
  • sig – The signal to send to the processes.
avocado.utils.process.pid_exists(pid)

Return True if a given PID exists.

Parameters:pid – Process ID number.
avocado.utils.process.process_in_ptree_is_defunct(ppid)

Verify if any processes deriving from PPID are in the defunct state.

Attempt to verify if parent process and any children from PPID is defunct (zombie) or not.

Parameters:ppid – The parent PID of the process to verify.
avocado.utils.process.run(cmd, timeout=None, verbose=True, ignore_status=False, allow_output_check=None, shell=False, env=None, sudo=False, ignore_bg_processes=False, encoding=None)

Run a subprocess, returning a CmdResult object.

Parameters:
  • cmd (str) – Command line to run.
  • timeout (float) – Time limit in seconds before attempting to kill the running process. This function will take a few seconds longer than ‘timeout’ to complete if it has to kill the process.
  • verbose (bool) – Whether to log the command run and stdout/stderr.
  • ignore_status (bool) – Whether to raise an exception when command returns =! 0 (False), or not (True).
  • allow_output_check (str) – Whether to record the output from this process (from stdout and stderr) in the test’s output record files. Valid values: ‘stdout’, for standard output only, ‘stderr’ for standard error only, ‘both’ for both standard output and error in separate files, ‘combined’ for standard output and error in a single file, and ‘none’ to disable all recording. ‘all’ is also a valid, but deprecated, option that is a synonym of ‘both’. If an explicit value is not given to this parameter, that is, if None is given, it defaults to using the module level configuration, as set by OUTPUT_CHECK_RECORD_MODE. If the module level configuration itself is not set, it defaults to ‘none’.
  • shell (bool) – Whether to run the command on a subshell
  • env (dict) – Use extra environment variables
  • sudo – Whether the command requires admin privileges to run, so that sudo will be prepended to the command. The assumption here is that the user running the command has a sudo configuration such that a password won’t be prompted. If that’s not the case, the command will straight out fail.
  • encoding (str) – the encoding to use for the text representation of the command result stdout and stderr, by default avocado.utils.astring.ENCODING
Returns:

An CmdResult object.

Raise:

CmdError, if ignore_status=False.

avocado.utils.process.safe_kill(pid, signal)

Attempt to send a signal to a given process that may or may not exist.

Parameters:signal – Signal number.
avocado.utils.process.should_run_inside_gdb(cmd)

Whether the given command should be run inside the GNU debugger

Parameters:cmd – the command arguments, from where we extract the binary name
avocado.utils.process.should_run_inside_wrapper(cmd)

Whether the given command should be run inside the wrapper utility.

Parameters:cmd – the command arguments, from where we extract the binary name
avocado.utils.process.split_gdb_expr(expr)

Splits a GDB expr into (binary_name, breakpoint_location)

Returns avocado.gdb.GDB.DEFAULT_BREAK as the default breakpoint if one is not given.

Parameters:expr (str) – an expression of the form <binary_name>[:<breakpoint>]
Returns:a (binary_name, breakpoint_location) tuple
Return type:tuple
avocado.utils.process.system(cmd, timeout=None, verbose=True, ignore_status=False, allow_output_check=None, shell=False, env=None, sudo=False, ignore_bg_processes=False, encoding=None)

Run a subprocess, returning its exit code.

Parameters:
  • cmd (str) – Command line to run.
  • timeout (float) – Time limit in seconds before attempting to kill the running process. This function will take a few seconds longer than ‘timeout’ to complete if it has to kill the process.
  • verbose (bool) – Whether to log the command run and stdout/stderr.
  • ignore_status (bool) – Whether to raise an exception when command returns =! 0 (False), or not (True).
  • allow_output_check (str) – Whether to record the output from this process (from stdout and stderr) in the test’s output record files. Valid values: ‘stdout’, for standard output only, ‘stderr’ for standard error only, ‘both’ for both standard output and error in separate files, ‘combined’ for standard output and error in a single file, and ‘none’ to disable all recording. ‘all’ is also a valid, but deprecated, option that is a synonym of ‘both’. If an explicit value is not given to this parameter, that is, if None is given, it defaults to using the module level configuration, as set by OUTPUT_CHECK_RECORD_MODE. If the module level configuration itself is not set, it defaults to ‘none’.
  • shell (bool) – Whether to run the command on a subshell
  • env (dict) – Use extra environment variables.
  • sudo – Whether the command requires admin privileges to run, so that sudo will be prepended to the command. The assumption here is that the user running the command has a sudo configuration such that a password won’t be prompted. If that’s not the case, the command will straight out fail.
  • encoding (str) – the encoding to use for the text representation of the command result stdout and stderr, by default avocado.utils.astring.ENCODING
Returns:

Exit code.

Return type:

int

Raise:

CmdError, if ignore_status=False.

avocado.utils.process.system_output(cmd, timeout=None, verbose=True, ignore_status=False, allow_output_check=None, shell=False, env=None, sudo=False, ignore_bg_processes=False, strip_trail_nl=True, encoding=None)

Run a subprocess, returning its output.

Parameters:
  • cmd (str) – Command line to run.
  • timeout (float) – Time limit in seconds before attempting to kill the running process. This function will take a few seconds longer than ‘timeout’ to complete if it has to kill the process.
  • verbose (bool) – Whether to log the command run and stdout/stderr.
  • ignore_status – Whether to raise an exception when command returns =! 0 (False), or not (True).
  • allow_output_check (str) – Whether to record the output from this process (from stdout and stderr) in the test’s output record files. Valid values: ‘stdout’, for standard output only, ‘stderr’ for standard error only, ‘both’ for both standard output and error in separate files, ‘combined’ for standard output and error in a single file, and ‘none’ to disable all recording. ‘all’ is also a valid, but deprecated, option that is a synonym of ‘both’. If an explicit value is not given to this parameter, that is, if None is given, it defaults to using the module level configuration, as set by OUTPUT_CHECK_RECORD_MODE. If the module level configuration itself is not set, it defaults to ‘none’.
  • shell (bool) – Whether to run the command on a subshell
  • env (dict) – Use extra environment variables
  • sudo (bool) – Whether the command requires admin privileges to run, so that sudo will be prepended to the command. The assumption here is that the user running the command has a sudo configuration such that a password won’t be prompted. If that’s not the case, the command will straight out fail.
  • ignore_bg_processes (bool) – Whether to ignore background processes
  • strip_trail_nl (bool) – Whether to strip the trailing newline
  • encoding (str) – the encoding to use for the text representation of the command result stdout and stderr, by default avocado.utils.astring.ENCODING
Returns:

Command output.

Return type:

bytes

Raise:

CmdError, if ignore_status=False.

avocado.utils.runtime module

Module that contains runtime configuration

avocado.utils.runtime.CURRENT_JOB = None

Sometimes it’s useful for the framework and API to know about the job that is currently running, if one exists

avocado.utils.runtime.CURRENT_TEST = None

Sometimes it’s useful for the framework and API to know about the test that is currently running, if one exists

avocado.utils.script module

Module to handle scripts creation.

avocado.utils.script.DEFAULT_MODE = 509

What is commonly known as “0775” or “u=rwx,g=rwx,o=rx”

avocado.utils.script.READ_ONLY_MODE = 292

What is commonly known as “0444” or “u=r,g=r,o=r”

class avocado.utils.script.Script(path, content, mode=509, open_mode='w')

Bases: object

Class that represents a script.

Creates an instance of Script.

Note that when the instance inside a with statement, it will automatically call save() and then remove() for you.

Parameters:
  • path – the script file name.
  • content – the script content.
  • mode – set file mode, defaults what is commonly known as 0775.
remove()

Remove script from the file system.

Returns:True if script has been removed, otherwise False.
save()

Store script to file system.

Returns:True if script has been stored, otherwise False.
class avocado.utils.script.TemporaryScript(name, content, prefix='avocado_script', mode=509, open_mode='w')

Bases: avocado.utils.script.Script

Class that represents a temporary script.

Creates an instance of TemporaryScript.

Note that when the instance inside a with statement, it will automatically call save() and then remove() for you.

When the instance object is garbage collected, it will automatically call remove() for you.

Parameters:
  • name – the script file name.
  • content – the script content.
  • prefix – prefix for the temporary directory name.
  • mode – set file mode, default to 0775.
remove()

Remove script from the file system.

Returns:True if script has been removed, otherwise False.
avocado.utils.script.make_script(path, content, mode=509)

Creates a new script stored in the file system.

Parameters:
  • path – the script file name.
  • content – the script content.
  • mode – set file mode, default to 0775.
Returns:

the script path.

avocado.utils.script.make_temp_script(name, content, prefix='avocado_script', mode=509)

Creates a new temporary script stored in the file system.

Parameters:
  • path – the script file name.
  • content – the script content.
  • prefix – the directory prefix Default to ‘avocado_script’.
  • mode – set file mode, default to 0775.
Returns:

the script path.

avocado.utils.service module

avocado.utils.service.ServiceManager(run=<function run>)

Detect which init program is being used, init or systemd and return a class has methods to start/stop services.

# Get the system service manager >> service_manager = ServiceManager()

# Stating service/unit “sshd” >> service_manager.start(“sshd”)

# Getting a list of available units >> units = service_manager.list()

# Disabling and stopping a list of services >> services_to_disable = [‘ntpd’, ‘httpd’]

>> for s in services_to_disable: >> service_manager.disable(s) >> service_manager.stop(s)

Returns:SysVInitServiceManager or SystemdServiceManager
Return type:_GenericServiceManager
avocado.utils.service.SpecificServiceManager(service_name, run=<function run>)

# Get the specific service manager for sshd >>> sshd = SpecificServiceManager(“sshd”) >>> sshd.start() >>> sshd.stop() >>> sshd.reload() >>> sshd.restart() >>> sshd.condrestart() >>> sshd.status() >>> sshd.enable() >>> sshd.disable() >>> sshd.is_enabled()

Parameters:service_name (str) – systemd unit or init.d service to manager
Returns:SpecificServiceManager that has start/stop methods
Return type:_SpecificServiceManager
avocado.utils.service.convert_systemd_target_to_runlevel(target)

Convert systemd target to runlevel.

Parameters:target (str) – systemd target
Returns:sys_v runlevel
Return type:str
Raises:ValueError – when systemd target is unknown
avocado.utils.service.convert_sysv_runlevel(level)

Convert runlevel to systemd target.

Parameters:level (str or int) – sys_v runlevel
Returns:systemd target
Return type:str
Raises:ValueError – when runlevel is unknown
avocado.utils.service.get_name_of_init(run=<function run>)

Internal function to determine what executable is PID 1

It does that by checking /proc/1/exe. Fall back to checking /proc/1/cmdline (local execution).

Returns:executable name for PID 1, aka init
Return type:str
avocado.utils.service.service_manager(run=<function run>)

Detect which init program is being used, init or systemd and return a class has methods to start/stop services.

# Get the system service manager >> service_manager = ServiceManager()

# Stating service/unit “sshd” >> service_manager.start(“sshd”)

# Getting a list of available units >> units = service_manager.list()

# Disabling and stopping a list of services >> services_to_disable = [‘ntpd’, ‘httpd’]

>> for s in services_to_disable: >> service_manager.disable(s) >> service_manager.stop(s)

Returns:SysVInitServiceManager or SystemdServiceManager
Return type:_GenericServiceManager
avocado.utils.service.specific_service_manager(service_name, run=<function run>)

# Get the specific service manager for sshd >>> sshd = SpecificServiceManager(“sshd”) >>> sshd.start() >>> sshd.stop() >>> sshd.reload() >>> sshd.restart() >>> sshd.condrestart() >>> sshd.status() >>> sshd.enable() >>> sshd.disable() >>> sshd.is_enabled()

Parameters:service_name (str) – systemd unit or init.d service to manager
Returns:SpecificServiceManager that has start/stop methods
Return type:_SpecificServiceManager
avocado.utils.service.sys_v_init_command_generator(command)

Generate lists of command arguments for sys_v style inits.

Parameters:command (str) – start,stop,restart, etc.
Returns:list of commands to pass to process.run or similar function
Return type:builtin.list
avocado.utils.service.sys_v_init_result_parser(command)

Parse results from sys_v style commands.

command status: return true if service is running. command is_enabled: return true if service is enabled. command list: return a dict from service name to status. command others: return true if operate success.

Parameters:command (str.) – command.
Returns:different from the command.
avocado.utils.service.systemd_command_generator(command)

Generate list of command line argument strings for systemctl.

One argument per string for compatibility Popen

WARNING: If systemctl detects that it is running on a tty it will use color, pipe to $PAGER, change column sizes and not truncate unit names. Use –no-pager to suppress pager output, or set PAGER=cat in the environment. You may need to take other steps to suppress color output. See https://bugzilla.redhat.com/show_bug.cgi?id=713567

Parameters:command (str) – start,stop,restart, etc.
Returns:List of command and arguments to pass to process.run or similar functions
Return type:builtin.list
avocado.utils.service.systemd_result_parser(command)

Parse results from systemd style commands.

command status: return true if service is running. command is_enabled: return true if service is enabled. command list: return a dict from service name to status. command others: return true if operate success.

Parameters:command (str.) – command.
Returns:different from the command.

avocado.utils.software_manager module

Software package management library.

This is an abstraction layer on top of the existing distributions high level package managers. It supports package operations useful for testing purposes, and multiple high level package managers (here called backends). If you want to make this lib to support your particular package manager/distro, please implement the given backend class.

author:Higor Vieira Alves <halves@br.ibm.com>
author:Lucas Meneghel Rodrigues <lmr@redhat.com>
author:Ramon de Carvalho Valle <rcvalle@br.ibm.com>
copyright:IBM 2008-2009
copyright:Red Hat 2009-2014
class avocado.utils.software_manager.AptBackend

Bases: avocado.utils.software_manager.DpkgBackend

Implements the apt backend for software manager.

Set of operations for the apt package manager, commonly found on Debian and Debian based distributions, such as Ubuntu Linux.

Initializes the base command and the debian package repository.

add_repo(repo)

Add an apt repository.

Parameters:repo – Repository string. Example: ‘deb http://archive.ubuntu.com/ubuntu/ maverick universe’
build_dep(name)

Installed build-dependencies of a given package [name].

Parameters:name – parameter package to install build-dependencies for.
Return True:If packages are installed properly
get_source(name, path)

Download source for provided package. Returns the path with source placed.

Parameters:name – parameter wildcard package to get the source for
Return path:path of ready-to-build source
install(name)

Installs package [name].

Parameters:name – Package name.
provides(path)

Return a list of packages that provide [path].

Parameters:path – File path.
remove(name)

Remove package [name].

Parameters:name – Package name.
remove_repo(repo)

Remove an apt repository.

Parameters:repo – Repository string. Example: ‘deb http://archive.ubuntu.com/ubuntu/ maverick universe’
upgrade(name=None)

Upgrade all packages of the system with eventual new versions.

Optionally, upgrade individual packages.

Parameters:name (str) – optional parameter wildcard spec to upgrade
class avocado.utils.software_manager.BaseBackend

Bases: object

This class implements all common methods among backends.

install_what_provides(path)

Installs package that provides [path].

Parameters:path – Path to file.
class avocado.utils.software_manager.DnfBackend

Bases: avocado.utils.software_manager.YumBackend

Implements the dnf backend for software manager.

DNF is the successor to yum in recent Fedora.

Initializes the base command and the DNF package repository.

class avocado.utils.software_manager.DpkgBackend

Bases: avocado.utils.software_manager.BaseBackend

This class implements operations executed with the dpkg package manager.

dpkg is a lower level package manager, used by higher level managers such as apt and aptitude.

INSTALLED_OUTPUT = 'install ok installed'
PACKAGE_TYPE = 'deb'
check_installed(name)
list_all()

List all packages available in the system.

list_files(package)

List files installed by package [package].

Parameters:package – Package name.
Returns:List of paths installed by package.
class avocado.utils.software_manager.RpmBackend

Bases: avocado.utils.software_manager.BaseBackend

This class implements operations executed with the rpm package manager.

rpm is a lower level package manager, used by higher level managers such as yum and zypper.

PACKAGE_TYPE = 'rpm'
SOFTWARE_COMPONENT_QRY = 'rpm %{NAME} %{VERSION} %{RELEASE} %{SIGMD5} %{ARCH}'
check_installed(name, version=None, arch=None)

Check if package [name] is installed.

Parameters:
  • name – Package name.
  • version – Package version.
  • arch – Package architecture.
list_all(software_components=True)

List all installed packages.

Parameters:software_components – log in a format suitable for the SoftwareComponent schema
list_files(name)

List files installed on the system by package [name].

Parameters:name – Package name.
prepare_source(spec_file, dest_path=None)

Rpmbuild the spec path and return build dir

Parameters:spec_path – spec path to install
Return path:build directory
rpm_install(file_path)

Install the rpm file [file_path] provided.

Parameters:file_path – Rpm file path.
Return True:if file is installed properly
class avocado.utils.software_manager.SoftwareManager

Bases: object

Package management abstraction layer.

It supports a set of common package operations for testing purposes, and it uses the concept of a backend, a helper class that implements the set of operations of a given package management tool.

Lazily instantiate the object

class avocado.utils.software_manager.SystemInspector

Bases: object

System inspector class.

This may grow up to include more complete reports of operating system and machine properties.

Probe system, and save information for future reference.

get_package_management()

Determine the supported package management systems present on the system. If more than one package management system installed, try to find the best supported system.

class avocado.utils.software_manager.YumBackend(cmd='yum')

Bases: avocado.utils.software_manager.RpmBackend

Implements the yum backend for software manager.

Set of operations for the yum package manager, commonly found on Yellow Dog Linux and Red Hat based distributions, such as Fedora and Red Hat Enterprise Linux.

Initializes the base command and the yum package repository.

add_repo(url)

Adds package repository located on [url].

Parameters:url – Universal Resource Locator of the repository.
build_dep(name)

Install build-dependencies for package [name]

Parameters:name – name of the package
Return True:If build dependencies are installed properly
get_source(name, dest_path)

Downloads the source package and prepares it in the given dest_path to be ready to build.

Parameters:
  • name – name of the package
  • dest_path – destination_path
Return final_dir:
 

path of ready-to-build directory

install(name)

Installs package [name]. Handles local installs.

provides(name)

Returns a list of packages that provides a given capability.

Parameters:name – Capability name (eg, ‘foo’).
remove(name)

Removes package [name].

Parameters:name – Package name (eg. ‘ipython’).
remove_repo(url)

Removes package repository located on [url].

Parameters:url – Universal Resource Locator of the repository.
upgrade(name=None)

Upgrade all available packages.

Optionally, upgrade individual packages.

Parameters:name (str) – optional parameter wildcard spec to upgrade
class avocado.utils.software_manager.ZypperBackend

Bases: avocado.utils.software_manager.RpmBackend

Implements the zypper backend for software manager.

Set of operations for the zypper package manager, found on SUSE Linux.

Initializes the base command and the yum package repository.

add_repo(url)

Adds repository [url].

Parameters:url – URL for the package repository.
get_source(name, dest_path)

Downloads the source package and prepares it in the given dest_path to be ready to build

Parameters:
  • name – name of the package
  • dest_path – destination_path
Return final_dir:
 

path of ready-to-build directory

install(name)

Installs package [name]. Handles local installs.

Parameters:name – Package Name.
provides(name)

Searches for what provides a given file.

Parameters:name – File path.
remove(name)

Removes package [name].

remove_repo(url)

Removes repository [url].

Parameters:url – URL for the package repository.
upgrade(name=None)

Upgrades all packages of the system.

Optionally, upgrade individual packages.

Parameters:name (str) – Optional parameter wildcard spec to upgrade
avocado.utils.software_manager.install_distro_packages(distro_pkg_map, interactive=False)

Installs packages for the currently running distribution

This utility function checks if the currently running distro is a key in the distro_pkg_map dictionary, and if there is a list of packages set as its value.

If these conditions match, the packages will be installed using the software manager interface, thus the native packaging system if the currently running distro.

Parameters:distro_pkg_map (dict) – mapping of distro name, as returned by utils.get_os_vendor(), to a list of package names
Returns:True if any packages were actually installed, False otherwise
avocado.utils.software_manager.main()

avocado.utils.stacktrace module

Traceback standard module plus some additional APIs.

avocado.utils.stacktrace.analyze_unpickable_item(path_prefix, obj)

Recursive method to obtain unpickable objects along with location

Parameters:
  • path_prefix – Path to this object
  • obj – The sub-object under introspection
Returns:

[($path_to_the_object, $value), …]

avocado.utils.stacktrace.log_exc_info(exc_info, logger='')

Log exception info to logger_name.

Parameters:
  • exc_info – Exception info produced by sys.exc_info()
  • logger – Name or logger instance (defaults to ‘’)
avocado.utils.stacktrace.log_message(message, logger='')

Log message to logger.

Parameters:
  • message – Message
  • logger – Name or logger instance (defaults to ‘’)
avocado.utils.stacktrace.prepare_exc_info(exc_info)

Prepare traceback info.

Parameters:exc_info – Exception info produced by sys.exc_info()
avocado.utils.stacktrace.str_unpickable_object(obj)

Return human readable string identifying the unpickable objects

Parameters:obj – The object for analysis
Raises:ValueError – In case the object is pickable
avocado.utils.stacktrace.tb_info(exc_info)

Prepare traceback info.

Parameters:exc_info – Exception info produced by sys.exc_info()

avocado.utils.vmimage module

Provides VM images acquired from official repositories

class avocado.utils.vmimage.CentOSImageProvider(version='[0-9]+', build='[0-9]{4}', arch='x86_64')

Bases: avocado.utils.vmimage.ImageProviderBase

CentOS Image Provider

name = 'CentOS'
class avocado.utils.vmimage.DebianImageProvider(version='[0-9]+.[0-9]+.[0-9]+-.*', build=None, arch='x86_64')

Bases: avocado.utils.vmimage.ImageProviderBase

Debian Image Provider

name = 'Debian'
class avocado.utils.vmimage.FedoraImageProvider(version='[0-9]+', build='[0-9]+.[0-9]+', arch='x86_64')

Bases: avocado.utils.vmimage.ImageProviderBase

Fedora Image Provider

get_image_url()

Probes the higher image available for the current parameters.

name = 'Fedora'
class avocado.utils.vmimage.FedoraSecondaryImageProvider(version='[0-9]+', build='[0-9]+.[0-9]+', arch='x86_64')

Bases: avocado.utils.vmimage.ImageProviderBase

Fedora Secondary Image Provider

get_image_url()

Probes the higher image available for the current parameters.

name = 'FedoraSecondary'
avocado.utils.vmimage.IMAGE_PROVIDERS = set([<class 'avocado.utils.vmimage.JeosImageProvider'>, <class 'avocado.utils.vmimage.UbuntuImageProvider'>, <class 'avocado.utils.vmimage.DebianImageProvider'>, <class 'avocado.utils.vmimage.CentOSImageProvider'>, <class 'avocado.utils.vmimage.FedoraSecondaryImageProvider'>, <class 'avocado.utils.vmimage.FedoraImageProvider'>])

List of available providers classes

class avocado.utils.vmimage.Image(name, url, version, arch, checksum, algorithm, cache_dir)

Bases: object

base_image
get()
path
class avocado.utils.vmimage.ImageProviderBase(version, build, arch)

Bases: object

Base class to define the common methods and attributes of an image. Intended to be sub-classed by the specific image providers.

get_image_url()

Probes the higher image available for the current parameters.

get_version()

Probes the higher version available for the current parameters.

version
exception avocado.utils.vmimage.ImageProviderError

Bases: exceptions.Exception

Generic error class for ImageProvider

class avocado.utils.vmimage.JeosImageProvider(version='[0-9]+', build=None, arch='x86_64')

Bases: avocado.utils.vmimage.ImageProviderBase

JeOS Image Provider

name = 'JeOS'
class avocado.utils.vmimage.UbuntuImageProvider(version='[0-9]+.[0-9]+', build=None, arch='x86_64')

Bases: avocado.utils.vmimage.ImageProviderBase

Ubuntu Image Provider

name = 'Ubuntu'
class avocado.utils.vmimage.VMImageHtmlParser(pattern)

Bases: HTMLParser.HTMLParser

Custom HTML parser to extract the href items that match a given pattern

handle_starttag(tag, attrs)
avocado.utils.vmimage.get(name=None, version=None, build=None, arch=None, checksum=None, algorithm=None, cache_dir=None)

Wrapper to get the best Image Provider, according to the parameters provided.

Parameters:
  • name – (optional) Name of the Image Provider, usually matches the distro name.
  • version – (optional) Version of the system image.
  • build – (optional) Build number of the system image.
  • arch – (optional) Architecture of the system image.
  • checksum – (optional) Hash of the system image to match after download.
  • algorithm – (optional) Hash type, used when the checksum is provided.
  • cache_dir – (optional) Local system path where the images and the snapshots will be held.
Returns:

Image Provider instance that can provide the image according to the parameters.

avocado.utils.vmimage.list_providers()

List the available Image Providers

avocado.utils.wait module

avocado.utils.wait.wait_for(func, timeout, first=0.0, step=1.0, text=None, args=None, kwargs=None)

Wait until func() evaluates to True.

If func() evaluates to True before timeout expires, return the value of func(). Otherwise return None.

Parameters:
  • timeout – Timeout in seconds
  • first – Time to sleep before first attempt
  • step – Time to sleep between attempts in seconds
  • text – Text to print while waiting, for debug purposes
  • args – Positional arguments to func
  • kwargs – Keyword arguments to func

Module contents