Utilities APIs

Avocado gives to you more than 40 python utility libraries (so far), that can be found under the avocado.utils. You can use these libraries to avoid having to write necessary routines for your tests. These are very general in nature and can help you speed up your test development.

The utility libraries may receive incompatible changes across minor versions, but these will be done in a staged fashion. If a given change to an utility library can cause test breakage, it will first be documented and/or deprecated, and only on the next subsequent minor version, it will actually be changed.

What this means is that upon updating to later minor versions of Avocado, you should look at the Avocado Release Notes for changes that may impact your tests.

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.

Subpackages

Submodules

avocado.utils.ar module

Module to read UNIX ar files

class avocado.utils.ar.Ar(path)

Bases: object

An UNIX ar archive.

is_valid()

Checks if a file looks like an AR archive.

Parameters

path – path to a file

Returns

bool

list()

Return the name of the members in the archive.

read_member(identifier)

Returns the data for the given member identifier.

class avocado.utils.ar.ArMember(identifier, size, offset)

Bases: object

A member of an UNIX ar archive.

avocado.utils.ar.FILE_HEADER_FMT = '16s12s6s6s8s10s2c'

The header for each file in the archive

avocado.utils.ar.MAGIC = b'!<arch>\n'

The first eight bytes of all AR archives

avocado.utils.archive module

Module to help extract and create compressed archives.

exception avocado.utils.archive.ArchiveException

Bases: 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.

Returns

the first member of the archive, a file or directory or None if the archive is empty

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.GZIP_MAGIC = b'\x1f\x8b'

The first two bytes that all gzip files start with

avocado.utils.archive.ZSTD_AVOCADO = b'(\xb5/\xfd\x04XA\x00\x00avocado\n<\xfc\x9f\xb9'

A valid zstd archive with “avocadon” as content. Created with: echo “avocado” | zstd -c

avocado.utils.archive.ZSTD_MAGIC = b'(\xb5/\xfd'

The first two bytes that all zstd files start with. See https://datatracker.ietf.org/doc/html/rfc8878#section-3.1.1-3.2

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.gzip_uncompress(path, output_path)

Uncompress a gzipped file at path, to either a file or dir at output_path

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.is_gzip_file(path)

Checks if file given by path has contents that suggests gzip file

avocado.utils.archive.is_lzma_file(path)

Checks if file given by path has contents that suggests lzma file

avocado.utils.archive.is_zstd_file(path)

Checks if file given by path has contents that suggests zstd file

avocado.utils.archive.lzma_uncompress(path, output_path=None, force=False)

Extracts a XZ compressed file to the same directory.

avocado.utils.archive.uncompress(filename, path)

Extract files from an archive.

Parameters
  • filename – archive file name.

  • path – destination path to extract to.

avocado.utils.archive.zstd_uncompress(path, output_path=None, force=False)

Extracts a zstd compressed file.

avocado.utils.asset module

Asset fetcher from multiple locations

class avocado.utils.asset.Asset(name=None, asset_hash=None, algorithm=None, locations=None, cache_dirs=None, expire=None, metadata=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. Default is ‘’.

  • asset_hash – asset hash

  • algorithm – hash algorithm

  • locations – location(s) where the asset can be fetched from

  • cache_dirs – list of cache directories

  • expire – time in seconds for the asset to expire

  • metadata – metadata which will be saved inside metadata file

property asset_name
fetch(timeout=None)

Try to fetch the current asset.

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

Parameters

timeout – timeout in seconds. Default is avocado.utils.asset.DOWNLOAD_TIMEOUT.

Raises

OSError – When it fails to fetch the asset

Returns

The path for the file on the cache directory.

Return type

str

find_asset_file(create_metadata=False)

Search for the asset file in each one of the cache locations

Parameters

create_metadata (bool) – Should this method create the metadata in case asset file found and metadata is not found? Default is False.

Returns

asset path, if it exists in the cache

Return type

str

Raises

OSError

classmethod get_all_assets(cache_dirs, sort=True)

Returns all assets stored in all cache dirs.

classmethod get_asset_by_name(name, cache_dirs, expire=None, asset_hash=None)

This method will return a cached asset based on name if exists.

You don’t have to instantiate an object of Asset class. Just use this method.

To be improved soon: cache_dirs should be not necessary.

Parameters
  • name – the asset filename used during registration.

  • cache_dirs – list of directories to use during the search.

  • expire – time in seconds for the asset to expire. Expired assets will not be returned.

  • asset_hash – asset hash.

Returns

asset path, if it exists in the cache.

Return type

str

Raises

OSError

classmethod get_assets_by_size(size_filter, cache_dirs)

Return a list of all assets in cache based on its size in MB.

Parameters
  • size_filter – a string with a filter (comparison operator + value). Ex “>20”, “<=200”. Supported operators: ==, <, >, <=, >=.

  • cache_dirs – list of directories to use during the search.

classmethod get_assets_unused_for_days(days, cache_dirs)

Return a list of all assets in cache based on the access time.

This will check if the file’s data wasn’t modified N days ago.

Parameters
  • days – how many days ago will be the threshold. Ex: “10” will return the assets files that was not accessed during the last 10 days.

  • cache_dirs – list of directories to use during the search.

get_metadata()

Returns metadata of the asset if it exists or None.

Returns

metadata

Return type

dict or None

property name_scheme

This property will return the scheme part of the name if is an URL.

Otherwise, will return None.

property name_url

This property will return the full url of the name if is an URL.

Otherwise, will return None.

static parse_name(name)

Returns a ParseResult object for the given name.

property parsed_name

Returns a ParseResult object for the currently set name.

classmethod read_hash_from_file(filename, algorithm=None)

Read the CHECKSUM file and return the hash.

This method raises a FileNotFoundError if file is missing and assumes that filename is the CHECKSUM filename.

Return type

list with algorithm and hash

property relative_dir
classmethod remove_asset_by_path(asset_path)

Remove an asset and its checksum.

To be fixed: Due the current implementation limitation, this method will not remove the metadata to avoid removing other asset metadata.

Parameters

asset_path – full path of the asset file.

classmethod remove_assets_by_overall_limit(limit, cache_dirs)

This will remove assets based on overall limit.

We are going to sort the assets based on the access time first. For instance it may be the case that a GitLab cache limit is 4 GiB, in that case we can sort by last access, and remove all that exceeds 4 GiB (that is, keep the last accessed 4 GiB worth of cached files).

Note: during the usage of this method, you should use bytes as limit.

Parameters
  • limit – a integer limit in bytes.

  • cache_dirs – list of directories to use during the search.

classmethod remove_assets_by_size(size_filter, cache_dirs)
classmethod remove_assets_by_unused_for_days(days, cache_dirs)
property urls

Complete list of locations including name if is an URL.

avocado.utils.asset.DEFAULT_HASH_ALGORITHM = 'sha1'

The default hash algorithm to use on asset cache operations

avocado.utils.asset.DOWNLOAD_TIMEOUT = 300

The default timeout for the downloading of assets

exception avocado.utils.asset.UnsupportedProtocolError

Bases: OSError

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

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.cloudinit module

cloudinit configuration support

This module can be easily used with avocado.utils.vmimage, to configure operating system images via the cloudinit tooling.

Please, keep in mind that if you would like to create/write in ISO images, you need pycdlib module installed in your environment.

see

http://cloudinit.readthedocs.io.

avocado.utils.cloudinit.AUTHORIZED_KEY_TEMPLATE = '\nssh_authorized_keys:\n  - {0}\n'

An authorized key configuration for the default user

Positional template variables are: ssh_authorized_keys

avocado.utils.cloudinit.METADATA_TEMPLATE = 'instance-id: {0}\nhostname: {1}\n'

The meta-data file template

Positional template variables are: instance-id, hostname

avocado.utils.cloudinit.PASSWORD_TEMPLATE = '\npassword: {0}\nchpasswd:\n    expire: False\n'

A username configuration as per cloudinit/config/cc_set_passwords.py

Positional template variables are: password

avocado.utils.cloudinit.PHONE_HOME_TEMPLATE = '\nphone_home:\n    url: http://{0}:{1}/$INSTANCE_ID/\n    post: [ instance_id ]\n'

A phone home configuration that will post just the instance id

Positional template variables are: address, port

class avocado.utils.cloudinit.PhoneHomeServer(address, instance_id)

Bases: HTTPServer

Implements the phone home HTTP server.

Wait the phone home from a given instance.

Initialize the server.

Parameters
  • address (tuple) – a hostname or IP address and port, in the same format given to socket and other servers

  • instance_id (str) – the identification for the instance that should be calling back, and the condition for the wait to end

classmethod set_up_and_wait_for_phone_home(address, instance_id)

Sets up a phone home server and waits for the given instance to call

This is a shorthand for setting up a server that will keep handling requests, until it has heard from the specific instance requested.

Parameters
  • address (tuple) – a hostname or IP address and port, in the same format given to socket and other servers

  • instance_id (str) – the identification for the instance that should be calling back, and the condition for the wait to end

wait_for_phone_home(new_call=False)

Waits for this instance to call.

Parameters

new_call (bool) – Default is False, so if this instance was called back already, this method will return immediately and will not wait for a new call.

class avocado.utils.cloudinit.PhoneHomeServerHandler(request, client_address, server)

Bases: BaseHTTPRequestHandler

Handles HTTP requests to the phone home server.

do_POST()

Handles an HTTP POST request.

Respond with status 200 if the instance phoned back.

log_message(format_, *args)

Logs an arbitrary message.

Note

It currently disables any message logging.

avocado.utils.cloudinit.USERDATA_HEADER = '#cloud-config'

The header expected to be found at the beginning of the user-data file

avocado.utils.cloudinit.USERNAME_TEMPLATE = '\nssh_pwauth: True\n\nsystem_info:\n   default_user:\n      name: {0}\n'

A username configuration as per cloudinit/config/cc_set_passwords.py

Positional template variables : username

avocado.utils.cloudinit.iso(output_path, instance_id, username=None, password=None, phone_home_host=None, phone_home_port=None, authorized_key=None)

Generates an ISO image with cloudinit configuration

The content always include the cloudinit metadata, and optionally the userdata content. On the userdata file, it may contain a username/password section (if both parameters are given) and/or a phone home section (if both host and port are given).

Parameters
  • output_path – the location of the resulting (to be created) ISO image containing the cloudinit configuration

  • instance_id – the ID of the cloud instance, a form of identification for the dynamically created executing instances

  • username – the username to be used when logging interactively on the instance

  • password – the password to be used along with username when authenticating with the login services on the instance

  • phone_home_host – the address of the host the instance should contact once it has finished booting

  • phone_home_port – the port acting as an HTTP phone home server that the instance should contact once it has finished booting

  • authorized_key (str) – a SSH public key to be added as an authorized key for the default user, similar to “ssh-rsa …”

Raises

RuntimeError if the system can not create ISO images. On such a case, user is expected to install supporting packages, such as pycdlib.

avocado.utils.cloudinit.wait_for_phone_home(address, instance_id)

This method is deprecated.

Please use PhoneHomeServer.set_up_and_wait_for_phone_home().

avocado.utils.cpu module

Get information from the current’s machine CPU.

exception avocado.utils.cpu.FamilyException

Bases: Exception

avocado.utils.cpu.VENDORS_MAP = {'amd': (b'AMD',), 'ibm': (b'POWER\\d', b'IBM/S390'), 'intel': (b'GenuineIntel',)}

Map vendor’s name with expected string in /proc/cpuinfo.

avocado.utils.cpu.cpu_has_flags(flags)

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

Parameters

flags (list of str) – A list of cpu flags that must exists on the current CPU.

Returns

True if all the flags were found or False if not

Return type

bool

avocado.utils.cpu.cpu_online_list(*args, **kwargs)
avocado.utils.cpu.get_arch()

Work out which CPU architecture we’re running on.

avocado.utils.cpu.get_cpu_arch(*args, **kwargs)
avocado.utils.cpu.get_cpu_vendor_name(*args, **kwargs)
avocado.utils.cpu.get_cpufreq_governor(*args, **kwargs)
avocado.utils.cpu.get_cpuidle_state(*args, **kwargs)
avocado.utils.cpu.get_family()

Get family name of the cpu like Broadwell, Haswell, power8, power9.

avocado.utils.cpu.get_freq_governor()

Get current cpu frequency governor.

avocado.utils.cpu.get_idle_state()

Get current cpu idle values.

Returns

Dict of cpuidle states values for all cpus

Return type

dict

avocado.utils.cpu.get_numa_node_has_cpus()

Get the list NUMA node numbers which has CPU’s on the system, if there is no CPU associated to NUMA node,Those NUMA node number will not be appended to list. :return: A list where NUMA node numbers only which has

CPU’s - as elements of The list.

:rtype : List

avocado.utils.cpu.get_pid_cpus(pid)

Get all the cpus being used by the process according to pid informed.

Parameters

pid (str) – process id

Returns

A list include all cpus the process is using

Return type

list

avocado.utils.cpu.get_vendor()

Get the current cpu vendor name.

Returns

a key of VENDORS_MAP (e.g. ‘intel’) depending on the current CPU architecture. Return None if it was unable to determine the vendor name.

Return type

str or None

avocado.utils.cpu.get_version()

Get cpu version.

Returns

cpu version of given machine e.g.:- ‘i5-5300U’ for Intel and ‘POWER9’ for IBM machines in case of unknown/unsupported machines, return an empty string.

Return type

str

avocado.utils.cpu.is_hotpluggable(cpu)
avocado.utils.cpu.numa_nodes_with_assigned_cpus()

Get NUMA nodes with associated CPU’s on the system. :return: A dictionary,in which “NUMA node numbers” as key

and “NUMA node associated CPU’s” as values.

:rtype : dictionary

avocado.utils.cpu.offline(cpu)

Offline given CPU.

avocado.utils.cpu.online(cpu)

Online given CPU.

avocado.utils.cpu.online_count()

Return Number of Online cpus in the system.

avocado.utils.cpu.online_cpus_count(*args, **kwargs)
avocado.utils.cpu.online_list()

Reports a list of indexes of the online cpus.

avocado.utils.cpu.set_cpufreq_governor(*args, **kwargs)
avocado.utils.cpu.set_cpuidle_state(*args, **kwargs)
avocado.utils.cpu.set_freq_governor(governor='random')

To change the given cpu frequency governor.

Parameters

governor (str) – frequency governor profile name whereas random is default option to choose random profile among available ones.

avocado.utils.cpu.set_idle_state(state_number='all', disable=True, setstate=None)

Set/Reset cpu idle states for all cpus.

Parameters
  • state_number (str) – cpuidle state number, default: all all states

  • disable (bool) – whether to disable/enable given cpu idle state, default is to disable.

  • setstate (dict) – cpuidle state value, output of get_idle_state()

avocado.utils.cpu.total_count()

Return Number of Total cpus in the system including offline cpus.

avocado.utils.cpu.total_cpus_count(*args, **kwargs)

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

Bases: object

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}
property b
property g
property k
property m
property t
property unit
property value
exception avocado.utils.data_structures.InvalidDataSize

Bases: 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.recursive_compare_dict(dict1, dict2, level='DictKey', diff_btw_dict=None)

Difference between two dictionaries are returned Dict values can be a dictionary, list and value

Return type

list or None

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.datadrainer module

data drainer

This module provides utility classes for draining data and dispatching it to different destinations. This is intended to be used concurrently with other code, usually test code producing the output to be drained/processed. A thread is started and maintained on behalf of the user.

class avocado.utils.datadrainer.BaseDrainer(source, stop_check=None, name=None)

Bases: ABC

Base drainer, doesn’t provide complete functionality to be useful.

Parameters
  • source – where to read data from, this is intentionally abstract

  • stop_check (function) – callable that should determine if the drainer should quit. If None is given, it will never stop.

  • name (str) – instance name of the drainer, used for describing the name of the thread maintained by this instance

static data_available()

Checks if source appears to have data to be drained

name = 'avocado.utils.datadrainer.BaseDrainer'
abstract read()

Abstract method supposed to read from the data source

start()

Starts a thread to do the data draining

wait()

Waits on the thread completion

abstract write(data)

Abstract method supposed to write the read data to its destination

class avocado.utils.datadrainer.BufferFDDrainer(source, stop_check=None, name=None)

Bases: FDDrainer

Drains data from a file descriptor and stores it in an internal buffer

Parameters
  • source – where to read data from, this is intentionally abstract

  • stop_check (function) – callable that should determine if the drainer should quit. If None is given, it will never stop.

  • name (str) – instance name of the drainer, used for describing the name of the thread maintained by this instance

property data

Returns the buffer data, as bytes

name = 'avocado.utils.datadrainer.BufferFDDrainer'
write(data)

Abstract method supposed to write the read data to its destination

class avocado.utils.datadrainer.FDDrainer(source, stop_check=None, name=None)

Bases: BaseDrainer

Drainer whose source is a file descriptor

This drainer uses select to efficiently wait for data to be available on a file descriptor. If the file descriptor is closed, the drainer responds by shutting itself down.

This drainer doesn’t provide a write() implementation, and is consequently not a complete implementation users can pick and use.

Parameters
  • source – where to read data from, this is intentionally abstract

  • stop_check (function) – callable that should determine if the drainer should quit. If None is given, it will never stop.

  • name (str) – instance name of the drainer, used for describing the name of the thread maintained by this instance

data_available()

Checks if source appears to have data to be drained

name = 'avocado.utils.datadrainer.FDDrainer'
read()

Abstract method supposed to read from the data source

write(data)

Abstract method supposed to write the read data to its destination

class avocado.utils.datadrainer.LineLogger(source, stop_check=None, name=None, logger=None)

Bases: FDDrainer

Parameters
  • source – where to read data from, this is intentionally abstract

  • stop_check (function) – callable that should determine if the drainer should quit. If None is given, it will never stop.

  • name (str) – instance name of the drainer, used for describing the name of the thread maintained by this instance

name = 'avocado.utils.datadrainer.LineLogger'
write(data)

Abstract method supposed to write the read data to its destination

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.diff_validator module

Diff validator: Utility for testing file changes

Some typical use of this utility would be:

>>> import diff_validator
>>> change = diff_validator.Change()
>>> change.add_validated_files(["/etc/somerc"])
>>> change.append_expected_add("/etc/somerc", "this is a new line")
>>> change.append_expected_remove("/etc/somerc", "this line is removed")
>>> diff_validator.make_temp_file_copies(change.get_target_files())

After making changes through some in-test operation:

>>> changes = diff_validator.extract_changes(change.get_target_files())
>>> change_success = diff_validator.assert_change(changes, change.files_dict)

If test fails due to invalid change on the system:

>>> if not change_success:
>>>     changes = diff_validator.assert_change_dict(changes, change.files_dict)
>>>     raise DiffValidationError("Change is different than expected:
%s" % diff_validator.create_diff_report(changes))
>>> else:
>>>     logging.info("Change made successfully")
>>> diff_validator.del_temp_file_copies(change.get_target_files())
class avocado.utils.diff_validator.Change

Bases: object

Class for tracking and validating file changes

Creates a change object.

add_validated_files(filenames)

Add file to change object.

Parameters

filenames ([str]) – files to validate

append_expected_add(filename, line)

Append expected added line to a file.

Parameters
  • filename (str) – file to append to

  • line (str) – line to append to as an expected addition

append_expected_remove(filename, line)

Append removed added line to a file.

Parameters
  • filename (str) – file to append to

  • line (str) – line to append to as an expected removal

get_all_adds()

Return a list of the added lines for all validated files.

get_all_removes()

Return a list of the removed lines for all validated files.

get_target_files()

Get added files for change.

exception avocado.utils.diff_validator.DiffValidationError

Bases: Exception

avocado.utils.diff_validator.assert_change(actual_result, expected_result)

Condition wrapper of the upper method.

Parameters
  • actual_result ({str, ([str], [str])}) – actual added and removed lines with filepath keys and a tuple of ([added_line, …], [removed_line, …])

  • expected_result ({str, ([str], [str])}) – expected added and removed lines of type as the actual result

Returns

whether changes were detected

Return type

bool

avocado.utils.diff_validator.assert_change_dict(actual_result, expected_result)

Calculates unexpected line changes.

Parameters
  • actual_result ({file_path, ([added_line, ...], [removed_line, ...])}) – actual added and removed lines

  • expected_result ({file_path, ([added_line, ...], [removed_line, ...])}) – expected added and removed lines

Returns

detected differences as groups of lines with filepath keys and a tuple of (unexpected_adds, not_present_adds, unexpected_removes, not_present_removes)

Return type

{str, (str, str, str, str)}

avocado.utils.diff_validator.create_diff_report(change_diffs)

Pretty prints the output of the change_diffs variable.

Parameters

change_diffs – detected differences as groups of lines with filepath keys and a tuple of (unexpected_adds, not_present_adds, unexpected_removes, not_present_removes)

Type

{str, (str, str, str, str)}

Returns

print string of the line differences

Return type

str

avocado.utils.diff_validator.del_temp_file_copies(file_paths)

Deletes all the provided files.

Parameters

file_paths ([str]) – deleted file paths (their temporary versions)

avocado.utils.diff_validator.extract_changes(file_paths, compared_file_paths=None)

Extracts diff information based on the new and temporarily saved old files.

Parameters
  • file_paths ([str]) – original file paths (whose temporary versions will be retrieved)

  • compared_file_paths ([str] or None) – custom file paths to use instead of the temporary versions

Returns

file paths with corresponding diff information key-value pairs

Return type

{str, ([str], [str])}

avocado.utils.diff_validator.get_temp_file_path(file_path)

Generates a temporary filename.

Parameters

file_path (str) – file path prefix

Returns

appended file path

Return type

str

avocado.utils.diff_validator.make_temp_file_copies(file_paths)

Creates temporary copies of the provided files.

Parameters

file_paths ([str]) – file paths to be copied

avocado.utils.diff_validator.parse_unified_diff_output(lines)

Parses the unified diff output of two files.

Parameters

lines ([str]) – diff lines

Returns

pair of adds and removes, where each is a list of trimmed lines

Return type

([str], [str])

avocado.utils.disk module

Disk utilities

exception avocado.utils.disk.DiskError

Bases: Exception

Generic DiskError

avocado.utils.disk.create_loop_device(size, blocksize=4096, directory='./')

Creates a loop device of size and blocksize specified.

Parameters
  • size (int) – Size of loop device, in bytes

  • blocksize (int) – block size of loop device, in bytes. Defaults to 4096

  • directory (str) – Directory where the backing file will be created. Defaults to current directory.

Returns

loop device name

Return type

str

avocado.utils.disk.delete_loop_device(device)

Deletes the specified loop device.

Parameters

device (str) – device to be deleted

Returns

True if deleted.

Return type

bool

avocado.utils.disk.freespace(path)
avocado.utils.disk.fs_exists(device)

check if filesystem exists on give disk/device

Parameters

device (str) – disk/device name

Returns

returns True if filesystem exists on the give disk else False

Return type

bool

avocado.utils.disk.get_absolute_disk_path(device)

Returns absolute device path of given disk

This will get actual disks path of given device, it can take node name, by-uuid, by-id and by-path, irrespective of any platform and device type

Parameters

device (str) – disk name or disk alias names sda or scsi-xxx

Returns

the device absolute path name

Return type

bool

avocado.utils.disk.get_all_disk_paths()

Returns all available disk names and alias on this system

This will get all the sysfs disks name entries by its device node name, by-uuid, by-id and by-path, irrespective of any platform and device type

Returns

a list of all disk path names

Return type

list of str

avocado.utils.disk.get_available_filesystems()

Return a list of all available filesystem types

Returns

a list of filesystem types

Return type

list of str

avocado.utils.disk.get_dir_mountpoint(dir_path)

get mounted disk name that is mounted on given dir_path

Parameters

dir_path (str) – absolute directory path

Returns

returns disk name which mounted on given dir_path

Return type

str

avocado.utils.disk.get_disk_blocksize(path)

Return the disk block size, in bytes

avocado.utils.disk.get_disk_mountpoint(device)

get mountpoint on which given disk is mounted

Parameters

device (str) – disk/device name

Returns

return directory name on which disk is mounted

Return type

str

avocado.utils.disk.get_disks()

Returns the physical “hard drives” available on this system

This is a simple wrapper around lsblk and will return all the top level physical (non-virtual) devices return by it.

TODO: this is currently Linux specific. Support for other platforms is desirable and may be implemented in the future.

Returns

a list of paths to the physical disks on the system

Return type

list of str

avocado.utils.disk.get_filesystem_type(mount_point='/')

Returns the type of the filesystem of mount point informed. The default mount point considered when none is informed is the root “/” mount point.

Parameters

mount_point (str) – mount point to asses the filesystem type. Default “/”

Returns

filesystem type

Return type

str

avocado.utils.disk.is_dir_mounted(dir_path)

check if given directory is mounted or not

Parameters

dir_path (str) – directory path

Returns

True if the given director is mounted else False

Return type

bool

avocado.utils.disk.is_disk_mounted(device)

check if given disk is mounted or not

Parameters

device (str) – disk/device name

Returns

True if the device/disk is mounted else False

Return type

bool

avocado.utils.disk.is_root_device(device)

check for root disk

Parameters

device – device to check

Returns

True or False, True if given device is root disk otherwise will return False.

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(session=None)

Bases: object

Probes the machine and does it best to confirm it’s the right distro. If given an avocado.utils.ssh.Session object representing another machine, Probe will attempt to detect another machine’s distro via an ssh connection.

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_for_remote_file(file_name)

Checks if provided file exists in remote machine

Parameters

file_name (str) – name of file

Returns

whether the file exists in remote machine or not

Return type

bool

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()
Parameters

session – ssh connection between another machine

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.detect(session=None)

Attempts to detect the Linux Distribution running on this machine.

If given an avocado.utils.ssh.Session object, it will attempt to detect the distro of another machine via an ssh connection.

Parameters

session (avocado.utils.ssh.Session) – ssh connection between another machine

Returns

the detected LinuxDistro or UNKNOWN_DISTRO

Return type

LinuxDistro

avocado.utils.distro.register_probe(probe_class)

Register a probe to be run during autodetection

avocado.utils.dmesg module

Module for manipulate dmesg while running test.

exception avocado.utils.dmesg.DmesgError

Bases: Exception

Base Exception Class for all dmesg utils exceptions.

exception avocado.utils.dmesg.TestFail

Bases: AssertionError, Exception

Indicates that the test failed.

This is here, just because of an impossible circular import.

status = 'FAIL'
avocado.utils.dmesg.clear_dmesg()

function clear dmesg.

The dmesg operation is a privileged user task. This function needs sudo permissions enabled on the target host

avocado.utils.dmesg.collect_dmesg(output_file=None)

Function collect dmesg and save in file.

The dmesg operation is a privileged user task. This function needs sudo permissions enabled on the target host

Parameters

output_file (str) – File use for save dmesg output if not provided it use tmp file which located in system /tmp path

Returns

file which contain dmesg

Return type

str

avocado.utils.dmesg.collect_errors_by_level(output_file=None, level_check=5, skip_errors=None)

Verify dmesg having severity level of OS issue(s).

Parameters
  • output_file (str) – The file used to save dmesg

  • level_check (int) – level of severity of issues to be checked 1 - emerg 2 - emerg,alert 3 - emerg,alert,crit 4 - emerg,alert,crit,err 5 - emerg,alert,crit,err,warn

Skip_errors

list of dmesg error messages which want skip

avocado.utils.dmesg.collect_errors_dmesg(patterns)

Check patterns in dmesg.

:param patterns : list variable to search in dmesg :returns: error log in form of list :rtype: list of str

avocado.utils.dmesg.fail_on_dmesg(level=5)

Dmesg fail method decorator

Returns a class decorator used to signal the test when DmesgError exception is raised.

Parameters

level (int) – Dmesg Level based on which the test failure should be raised

Returns

Class decorator

Return type

class

avocado.utils.dmesg.skip_dmesg_messages(dmesg_stdout, skip_messages)

Remove some messages from a dmesg buffer.

This method will remove some lines in a dmesg buffer if some strings are present. Returning the same buffer, but with less lines (in case of match).

Dmesg_stdout

dmesg messages from which filter should be applied. This must be a decoded output buffer with new lines.

Skip_messages

list of strings to be removed

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. Please, be aware that timeout here is just for blocking operations during the connection setup, since this method doesn’t read the file from the url.

Returns

file-like object.

Raises

URLError.

avocado.utils.exit_codes module

Avocado Utilities exit codes.

These codes are returned on the command-line and may be used by the Avocado command-line utilities.

avocado.utils.exit_codes.UTILITY_FAIL = 1

The utility ran, but needs to signalize a fail.

avocado.utils.exit_codes.UTILITY_GENERIC_CRASH = -1

Utility generic crash

avocado.utils.exit_codes.UTILITY_OK = 0

The utility finished successfully

avocado.utils.file_utils module

SUMMARY

Utilities for file tests.

INTERFACE

avocado.utils.file_utils.check_owner(owner, group, file_name_pattern, check_recursive=False)

Verifies that given file belongs to given owner and group.

Parameters
  • owner (str) – user that owns of the file

  • group (str) – group of the owner of the file

  • file_name_pattern (str) – can be a glob

  • check_recursive (bool) – if file_name_pattern matches a directory, recurse into that subdir or not

Raises

RuntimeError if file has wrong owner or group

avocado.utils.file_utils.check_permissions(perms, file_name_pattern)

Verify that a given file has a given numeric permission.

Parameters
  • perms (int) – best given in octal form, e.g. 0o755

  • file_name_pattern (str) – can be a glob

Raises

RuntimeError if file has wrong permissions

avocado.utils.filelock module

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

exception avocado.utils.filelock.AlreadyLocked

Bases: 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: Exception

avocado.utils.gdb module

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

class avocado.utils.gdb.GDB(path=None, *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.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

static checksum(input_message)

Calculates a remote message checksum.

More details are available at: https://sourceware.org/gdb/current/onlinedocs/gdb/Overview.html

Parameters

input_message (bytes) – the message input payload, without the start and end markers

Returns

two byte checksum

Return type

bytes

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

static decode(data)

Decodes a packet and returns its payload.

More details are available at: https://sourceware.org/gdb/current/onlinedocs/gdb/Overview.html

Parameters

command_data (bytes) – the command data payload

Returns

the encoded command, ready to be sent to a remote GDB

Return type

bytes

static encode(data)

Encodes a command.

That is, add prefix, suffix and checksum.

More details are available at: https://sourceware.org/gdb/current/onlinedocs/gdb/Overview.html

Parameters

command_data (bytes) – the command data payload

Returns

the encoded command, ready to be sent to a remote GDB

Return type

bytes

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

class avocado.utils.gdb.GDBServer(path=None, 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

avocado.utils.genio module

Avocado generic IO related functions.

exception avocado.utils.genio.GenIOError

Bases: Exception

Base Exception Class for all IO exceptions

avocado.utils.genio.append_file(filename, data)

Append data to a file.

Parameters
  • filename (str) – Path to the file.

  • line (str) – Line to be written.

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

Append one line of text to filename.

Parameters
  • filename (str) – Path to the file.

  • line (str) – Line to be written.

avocado.utils.genio.are_files_equal(filename, other)

Comparison of two files line by line :param filename: path to the first file :type filename: str :param other: path to the second file :type other: str :return: equality of file :rtype: boolean

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.is_pattern_in_file(filename, pattern)

Check if a pattern matches in a specified file. If a non regular file be informed a GenIOError will be raised.

Parameters
  • filename (str) – Path to file

  • pattern (str) – Pattern that need to match in file

Returns

True when pattern matches in file if not return False

Return type

boolean

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_line_with_matching_pattern(filename, pattern)

Return the line/lines found with a given matching pattern.

This method returns the line/lines wherever the occurrence of the pattern, that is passed as an input, is found in the file.

All the occurrences are stored in the list and the list is returned as an output.

Parameters
  • filename (str) – Path to the file to be read.

  • pattern (list) – List of all the patterns, intended to be searched

Returns

All those lines from the file, matching the pattern.

Return type

list

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

class avocado.utils.iso9660.ISO9660PyCDLib(path)

Bases: MixInMntDirMount, BaseIso9660

Represents a ISO9660 filesystem

This implementation is based on the pycdlib library

DEFAULT_CREATE_FLAGS = {'interchange_level': 3, 'joliet': 3}

Default flags used when creating a new ISO image

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

create(flags=None)

Creates a new ISO image

Parameters

flags (dict) – the flags used when creating a new image

read(path)

Abstract method to read data from path

Parameters

path – path to the file

Returns

data content from the file

Return type

str

write(path, content)

Writes a new file into the ISO image

Parameters
  • path (bytes) – the path of the new file inside the ISO image

  • content – the content of the new file

class avocado.utils.iso9660.Iso9660IsoInfo(path)

Bases: MixInMntDirMount, 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: MixInMntDirMount, 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: 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

property mnt_dir

Returns a path to the browsable content of the iso

read(path)

Read data from path

Parameters

path (str) – path to read data

Returns

data content

Return type

str

avocado.utils.iso9660.iso9660(path, capabilities=None)

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

  • capabilities (list) – list of specific capabilities that are required for the selected implementation, such as “read”, “copy” and “mnt_dir”.

Returns

an instance of any iso9660 capable tool

Return type

Iso9660IsoInfo, Iso9660IsoRead, Iso9660Mount, ISO9660PyCDLib or None

avocado.utils.kernel module

Provides utilities for the Linux kernel.

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, njobs=12)

Build kernel from source.

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

  • njobs (int or None) – number of jobs. It is mapped to the -j option from make. If njobs is None then do not limit the number of jobs (e.g. uses -j without value). The -j is omitted if a value equal or less than zero is passed. Default value is set to multiprocessing.cpu_count().

property build_dir

Return the build path if the directory exists

configure(targets='defconfig', extra_configs=None)

Configure/prepare kernel source to build.

Parameters
  • targets (list of str) – configuration targets. Default is ‘defconfig’.

  • extra_configs (list of str) – additional configurations in the form of CONFIG_NAME=VALUE.

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.

Raises

Exception in case the tarball is not downloaded

property vmlinux

Return the vmlinux path if the file exists

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 module

Linux OS utilities

avocado.utils.linux.enable_selinux_enforcing()

Enable SELinux Enforcing in system

Returns

True if SELinux enable in enforcing mode, False if not enabled

avocado.utils.linux.get_proc_sys(key)

Read values from /proc/sys

Parameters

key – A location under /proc/sys

Returns

The single-line sysctl value as a string.

avocado.utils.linux.is_selinux_enforcing()

Returns True if SELinux is in enforcing mode, False if permissive/disabled.

avocado.utils.linux.set_proc_sys(key, value)

Set values on /proc/sys

Parameters
  • key – A location under /proc/sys

  • value – If not None, a value to write into the sysctl.

Returns

The single-line sysctl value as a string.

avocado.utils.linux_modules module

Linux kernel modules APIs

class avocado.utils.linux_modules.ModuleConfig(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

BUILTIN = <object object>

Config built-in to kernel (=y)

MODULE = <object object>

Config compiled as loadable module (=m)

NOT_SET = <object object>

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

ModuleConfig

avocado.utils.linux_modules.get_loaded_modules()

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

avocado.utils.linux_modules.get_modules_dir()

Return the modules dir for the running kernel version

Returns

path of module directory

Return type

String

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 regex 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 regex 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: Exception

Base Exception Class for all exceptions

avocado.utils.lv_utils.get_device_total_space(disk)

Get the total device size.

Parameters

device (str) – name of the device/disk to find the total size

Returns

size in bytes

Return type

int

Raises

LVException on failure to find disk space

avocado.utils.lv_utils.get_devices_total_space(devices)

Get the total size of given device(s)/disk(s).

Parameters

devices (list) – list with the names of devices separated with space.

Returns

sizes in bytes

Return type

int

Raises

LVException on failure to find disk space

avocado.utils.lv_utils.get_diskspace(disk)

Get the entire disk space of a given disk.

Parameters

disk (str) – name of the disk to find the free space of

Returns

size in bytes

Return type

str

Raises

LVException on failure to find disk space

avocado.utils.lv_utils.lv_check(vg_name, lv_name)

Check whether provided logical volume exists.

Parameters
  • vg_name (str) – name of the volume group

  • lv_name (str) – name of the logical volume

Returns

whether the logical volume was found

Return type

bool

avocado.utils.lv_utils.lv_create(vg_name, lv_name, lv_size, force_flag=True, pool_name=None, pool_size='1G')

Create a (possibly thin) logical volume in a volume group. The volume group must already exist.

A thin pool will be created if pool parameters are provided and the thin pool doesn’t already exist.

The volume group must already exist.

Parameters
  • vg_name (str) – name of the volume group

  • lv_name (str) – name of the logical volume

  • lv_size (str) – size for the logical volume to be created

  • force_flag (bool) – whether to abort if volume already exists or remove and recreate it

  • pool_name (str) – name of thin pool or None for a regular volume

  • pool_size (str) – size of thin pool if it will be created

Raises

LVException if preconditions or execution fails

avocado.utils.lv_utils.lv_list(vg_name=None)

List all info about available logical volumes.

Parameters

vg_name (str) – name of the volume group or None to list all

Returns

list of available logical volumes

Return type

{str, {str, str}}

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 (str) – name of the volume group

  • lv_name (str) – name of the logical volume

  • mount_loc (str) – location to mount the logical volume to

  • create_filesystem (str) – can be one of ext2, ext3, ext4, vfat or empty if the filesystem was already created and the mkfs process is skipped

Raises

LVException if the logical volume could not be mounted

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 (str) – name of the volume group

  • lv_name (str) – name of the logical volume

  • timeout (int) – timeout between operations

Raises

LVException if the logical volume is still active

avocado.utils.lv_utils.lv_remove(vg_name, lv_name)

Remove a logical volume.

Parameters
  • vg_name (str) – name of the volume group

  • lv_name (str) – name of the logical volume

Raises

LVException if volume group or logical volume cannot be found

avocado.utils.lv_utils.lv_revert(vg_name, lv_name, lv_snapshot_name)

Revert the origin logical volume to a snapshot.

Parameters
  • vg_name (str) – name of the volume group

  • lv_name (str) – name of the logical volume

  • lv_snapshot_name (str) – name of the snapshot to be reverted

Raises

process.CmdError on failure to revert snapshot

Raises

LVException if preconditions or execution fails

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 (str) – name of the volume group

  • lv_name (str) – name of the logical volume

  • lv_snapshot_name (str) – name of the snapshot to be reverted

  • lv_snapshot_size (str) – size of the snapshot

avocado.utils.lv_utils.lv_take_snapshot(vg_name, lv_name, lv_snapshot_name, lv_snapshot_size=None, pool_name=None)

Take a (possibly thin) snapshot of a regular (or thin) logical volume.

Parameters
  • vg_name (str) – name of the volume group

  • lv_name (str) – name of the logical volume

  • lv_snapshot_name (str) – name of the snapshot be to created

  • lv_snapshot_size (str) – size of the snapshot or None for thin snapshot of an already thin volume

  • pool_name – name of thin pool or None for regular snapshot or snapshot in the same thin pool like the volume

Raises

process.CmdError on failure to create snapshot

Raises

LVException if preconditions fail

avocado.utils.lv_utils.lv_umount(vg_name, lv_name)

Unmount a Logical volume from a mount location.

Parameters
  • vg_name (str) – name of the volume group

  • lv_name (str) – name of the logical volume

Raises

LVException if the logical volume could not be unmounted

avocado.utils.lv_utils.vg_check(vg_name)

Check whether provided volume group exists.

Parameters

vg_name (str) – name of the volume group

Returns

whether the volume group was found

Return type

bool

avocado.utils.lv_utils.vg_create(vg_name, pv_list, force=False)

Create a volume group from a list of physical volumes.

Parameters
  • vg_name (str) – name of the volume group

  • pv_list (str or [str]) – list of physical volumes to use

  • force (bool) – create volume group with a force flag

Raises

LVException if volume group already exists

avocado.utils.lv_utils.vg_list(vg_name=None)

List all info about available volume groups.

Parameters

vg_name (str or None) – name of the volume group to list or or None to list all

Returns

list of available volume groups

Return type

{str, {str, str}}

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

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

Parameters
  • disk (str) – name of the disk in which volume groups are created

  • vg_name (str) – name of the volume group

  • ramdisk_vg_size (str) – size of the ramdisk virtual group (MB)

  • ramdisk_basedir (str) – base directory for the ramdisk sparse file

  • ramdisk_sparse_filename (str) – name of the ramdisk sparse file

  • use_tmpfs (bool) – whether to use RAM or slower storage

Returns

ramdisk_filename, vg_ramdisk_dir, vg_name, loop_device

Return type

(str, str, str, str)

Raises

LVException on failure at any stage

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, use_tmpfs=True)

Clean up any stage of the VG ramdisk setup in case of test error.

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

Parameters
  • ramdisk_filename (str) – name of the ramdisk sparse file

  • vg_ramdisk_dir (str) – location of the ramdisk file

  • vg_name (str) – name of the volume group

  • loop_device (str) – name of the disk or loop device

  • use_tmpfs (bool) – whether to use RAM or slower storage

Returns

ramdisk_filename, vg_ramdisk_dir, vg_name, loop_device

Return type

(str, str, str, str)

Raises

LVException on intolerable failure at any stage

avocado.utils.lv_utils.vg_reactivate(vg_name, timeout=10, export=False)

In case of unclean shutdowns some of the vgs 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 (str) – name of the volume group

  • timeout (int) – timeout between operations

Raises

LVException if the logical volume is still active

avocado.utils.lv_utils.vg_remove(vg_name)

Remove a volume group.

Parameters

vg_name (str) – name of the volume group

Raises

LVException if volume group cannot be found

avocado.utils.memory module

exception avocado.utils.memory.MemError

Bases: 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 fragment 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_supported_huge_pages_size()

Get all supported huge page sizes for this system.

Returns

list of Huge pages size (kB).

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.

exception avocado.utils.multipath.MPException

Bases: Exception

Base Exception Class for all exceptions

avocado.utils.multipath.add_mpath(mpath)

Add back the removed mpathX of multipath.

Parameters

mpath_name – mpath names. Example: mpatha, mpathb.

Returns

True or False

avocado.utils.multipath.add_path(path)

Add back the removed individual paths.

Parameters

path (str) – disk path. Example: sda, sdb.

Returns

True or False

avocado.utils.multipath.device_exists(mpath)

Checks if a given mpath exists.

Parameters

mpath – The multipath path

Returns

True if path exists, False if does not exist.

Return type

bool

avocado.utils.multipath.fail_path(path)

Fail the individual paths.

Parameters

path (str) – disk path. Example: sda, sdb.

Returns

True if succeeded, False otherwise

Return type

bool

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_from_dm(dm_id)

Get the mpath name for given device mapper id

Parameters

dev_mapper – Input device mapper dm-x

Returns

mpath name like mpathx

Return type

str

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.

Return type

str

avocado.utils.multipath.get_mpath_status(mpath)

Get the status of mpathX of multipaths.

Parameters

mpath – mpath names. Example: mpatha, mpathb.

Returns

state of mpathX eg: Active, Suspend, None

avocado.utils.multipath.get_multipath_details()

Get multipath details as a dictionary.

This is the output of the following command:

$ multipathd show maps json

Returns

Dictionary of multipath output in json format

Return type

dict

avocado.utils.multipath.get_multipath_wwid(mpath)

Get the wwid binding for given mpath name

Returns

Multipath wwid

Return type

str

avocado.utils.multipath.get_multipath_wwids()

Get list of multipath wwids.

Returns

List of multipath wwids.

Return type

list of str

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.

Return type

list of str

avocado.utils.multipath.get_policy(wwid)

Gets path_checker policy, given a multipath wwid.

Returns

path checker policy.

Return type

str

avocado.utils.multipath.get_size(wwid)

Gets size of device, given a multipath wwid.

Returns

size of multipath device.

Return type

str

avocado.utils.multipath.get_svc_name()

Gets the multipath service name based on distro.

avocado.utils.multipath.is_mpath_dev(mpath)

Check the give name is a multipath device name or not.

Returns

True if device is multipath or False

Return type

Boolean

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)

Reinstate the individual paths.

Parameters

path (str) – disk path. Example: sda, sdb.

Returns

True if succeeded, False otherwise

avocado.utils.multipath.remove_mpath(mpath)

Remove the mpathX of multipaths.

Parameters

mpath_name – mpath names. Example: mpatha, mpathb.

Returns

True or False

avocado.utils.multipath.remove_path(path)

Remove the individual paths.

Parameters

disk_path – disk path. Example: sda, sdb.

Returns

True or False

avocado.utils.multipath.resume_mpath(mpath)

Resume the suspended mpathX of multipaths.

Parameters

mpath_name – mpath names. Example: mpatha, mpathb.

Returns

True or False

avocado.utils.multipath.suspend_mpath(mpath)

Suspend the given mpathX of multipaths.

Parameters

mpath – mpath names. Example: mpatha, mpathb.

Returns

True or False

avocado.utils.nvme module

Nvme utilities

exception avocado.utils.nvme.NvmeError

Bases: Exception

nvme DiskError

avocado.utils.nvme.get_controller_id(controll_name)

Returns the nvme controller id

Parameters

controller_name – Name of the controller eg: nvme0

Return type

string

avocado.utils.nvme.get_controller_name(pci_addr)

Returns the controller/Adapter name with the help of pci_address

Parameters

pci_addr – pci_address of the adapter

Return type

string

Raises

NvmeError on failure to find pci_address in OS

avocado.utils.nvme.get_number_of_ns_supported(controller_name)

Returns the number of namespaces supported for the nvme adapter

Parameters

controller_name – Name of the controller eg: nvme0

Return type

integer

avocado.utils.nvme.get_total_capacity(controller_name)

Returns the total capacity of the nvme adapter

Parameters

controller_name – Name of the controller eg: nvme0

Return type

integer

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(timeout=60)

Bases: object

device = '/etc/mtab'
class avocado.utils.partition.Partition(device, loop_size=0, mountpoint=None, mkfs_flags='', mount_options=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.

  • mkfs_flags – Optional flags for mkfs

  • mount_options – Add mount options optionally

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='', mnt_check=True)

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.

  • mnt_check – Flag to check/avoid checking existing device/mountpoint

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: Exception

Generic PartitionError

avocado.utils.path module

Avocado path related functions.

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

Bases: 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.check_readable(path)

Verify that the given path exists and is readable

This should be used where an assertion makes sense, and is useful because it can provide a better message in the exception it raises.

Parameters

path (str) – the path to test

Raises

OSError – path does not exist or path could not be read

Return type

None

avocado.utils.path.find_command(cmd, default=None, check_exec=True)

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.

  • check_exec (bool) – if a check for permissions that render the command executable by the current user should be performed.

Raise

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

Returns

Returns an absolute path to the command or the default value if the command is not found

Return type

str

avocado.utils.path.get_max_file_name_length(path)

Returns the maximum length of a file name in the underlying file system

Parameters

path (str) – the complete filename path. if a non-absolute path is given, it’s transformed into an absolute path first.

Returns

the maximum length of a file name

Return type

int

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.get_path_mount_point(path)

Returns the mount point for a given file path

Parameters

path (str) – the complete filename path. if a non-absolute path is given, it’s transformed into an absolute path first.

Returns

the mount point for a given file path

Return type

str

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.

Check if a usable RO directory is there.

Parameters

directory – Directory

avocado.utils.path.usable_rw_dir(directory, create=True)

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

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

Parameters
  • directory – Directory

  • create – whether to create the 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.

Return type

dict

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.

Return type

list of str

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.

Return type

str

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.

Return type

str

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.

Return type

str

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.

Return type

int

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)

Return type

list of str

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_info(pci_address)

Gets PCI info of given PCI address.

Parameters

pci_address – Any segment of a PCI address (1f, 0000:00:1f, …)

Returns

Dictionary attribute name as key and attribute value as value.

Return type

Dict

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.

Return type

str

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.

Return type

dict

avocado.utils.pmem module

class avocado.utils.pmem.PMem(ndctl='ndctl', daxctl='daxctl')

Bases: object

PMem class which provides function to perform ndctl and daxctl operations

This class can be used only if ndctl binaries are provided before hand

Initialize PMem object

Parameters
  • ndctl – path to ndctl binary, defaults to ndctl

  • daxctl – path to daxctl binary, defaults to ndctl

static check_buses()

Get buses from sys subsystem to verify persistent devices exist

Returns

List of buses available

Return type

list

check_daxctl_subcmd(command)

Check if given sub command is supported by daxctl

check_ndctl_subcmd(command)

Check if given sub command is supported by ndctl

static check_subcmd(binary, command)

Check if given sub command is supported by binary

Parameters

command – sub command of ndctl to check for existence

Returns

True if sub command is available

Return type

bool

create_namespace(region='', bus='', n_type='pmem', mode='fsdax', memmap='dev', name='', size='', uuid='', sector_size='', align='', reconfig='', force=False, autolabel=False)

Creates namespace with specified options

Parameters
  • region – Region on which namespace has to be created

  • bus – Bus with which namespace has to be created

  • n_type – Type of namespace to be created [pmem/blk]

  • mode – Mode of namespace to be created, defaults to fsdax

  • memmap – Metadata mapping for created namespace

  • name – Optional name provided for namespace

  • size – Size with which namespace has to be created

  • uuid – Optional uuid provided for namespace

  • sector_size – Sector size with which namespace has to be created

  • align – Alignment with which namespace has to be created

  • reconfig – Optionally reconfigure namespace providing existing namespace/region name

  • force – Force creation of namespace

  • autolabel – Optionally autolabel the namespace

Returns

True on success

Raise

PMemException, if command fails.

destroy_namespace(namespace='all', region='', bus='', force=False)

Destroy namespaces, skipped in case of legacy namespace

Parameters
  • namespace – name of the namespace to be destroyed

  • region – Filter namespace by region

  • bus – Filter namespace by bus

  • force – Force a namespace to be destroyed

Returns

True on Success

Raise

PMemException, if command fails.

disable_namespace(namespace='all', region='', bus='', verbose=False)

Disable namespaces

Parameters
  • namespace – name of the namespace to be disabled

  • region – Filter namespace by region

  • bus – Filter namespace by bus

  • verbose – Enable True command with debug information

Returns

True on success

Raise

PMemException, if command fails.

disable_region(name='all')

Disable given region

Parameters

name – name of the region to be disabled

Returns

True on success

Raise

PMemException, if command fails.

enable_namespace(namespace='all', region='', bus='', verbose=False)

Enable namespaces

Parameters
  • namespace – name of the namespace to be enabled

  • region – Filter namespace by region

  • bus – Filter namespace by bus

  • verbose – Enable True command with debug information

return: True on success :raise: PMemException, if command fails.

enable_region(name='all')

Enable given region

Parameters

name – name of the region to be enabled

Returns

True on success

Raise

PMemException, if command fails.

get_slot_count(region)

Get max slot count in the index area for a dimm backing a region We use region0 - > nmem0

Parameters

region – Region for which slot count is found

Returns

Number of slots for given region 0 in case region is not available/command fails

Return type

int

static is_region_legacy(region)

Check whether we have label index namespace. If legacy we can’t create new namespaces.

Parameters

region – Region for which legacy check is made

Returns

True if given region is legacy, else False

read_infoblock(namespace='', inp_file='', **kwargs)

Read an infoblock from the specified medium

Parameters
  • namespace – Read the infoblock from given namespace

  • inp_file – Input file to read the infoblock from

  • kwargs

Example:

self.plib.read_infoblock(namespace=ns_name, json_form=True)

Returns

By default return list of json objects, if json_form is True Return as raw data, if json_form is False Return file path if op_file is specified

Raise

PMemException, if command fails.

reconfigure_dax_device(device, mode='devdax', region=None, no_online=False, no_movable=False)

Reconfigure devdax device into devdax or system-ram mode

Parameters
  • device – Device from which memory is to be online

  • mode – Mode with which device is to be configured, default:devdax

  • region – Optionally filter device by region

  • no_online – Optionally don’t online the memory(only system-ram)

  • no_movable – Optionally mark memory non-movable(only system-ram)

Returns

Property of configured device

Return type

str

Raise

PMemException, if command fails.

run_daxctl_list(options='')

Get the json of each provided options

Parameters

options – optional arguments to daxctl list command

Returns

By default returns entire list of json objects

Return type

list of json objects

run_ndctl_list(option='')

Get the json of each provided options

Parameters

option – optional arguments to ndctl list command

Returns

By default returns entire list of json objects

Return type

list of json objects

static run_ndctl_list_val(json_op, field)

Get the value of a field in given json

Parameters
  • json_op – Input Json object

  • field – Field to find the value from json_op object

Return type

Found value type, None if not found

set_dax_memory_offline(device, region=None)

Set memory from a given devdax device offline

Parameters
  • device – Device from which memory is to be offline

  • region – Optionally filter device by region

Returns

True if command succeeds

Return type

bool

Raise

PMemException, if command fails.

set_dax_memory_online(device, region=None, no_movable=False)

Set memory from a given devdax device online

Parameters
  • device – Device from which memory is to be online

  • region – Optionally filter device by region

  • no_movable – Optionally make the memory non-movable

Returns

True if command succeeds

Return type

bool

Raise

PMemException, if command fails.

write_infoblock(namespace='', stdout=False, output=None, **kwargs)

Write an infoblock to the specified medium.

Parameters
  • namespace – Write the infoblock to given namespace

  • stdout – Write the infoblock to stdout if True

  • output – Write the infoblock to the file path specified

  • kwargs

Example:
pmem.write_infoblock(namespace=ns_name, align=align,

size=size, mode=’devdax’)

Returns

True if command succeeds

Return type

bool

Raise

PMemException, if command fails.

exception avocado.utils.pmem.PMemException(additional_text=None)

Bases: Exception

Error raised for all PMem failures

avocado.utils.podman module

This module provides an basic API for interacting with podman.

This module it was designed to be executed in async mode. Remember this when consuming this API.

class avocado.utils.podman.Podman(podman_bin=None)

Bases: object

async copy_to_container(container_id, src, dst)

Copy artifacts from src to container:dst.

This method allows copying the contents of src to the dst. Files will be copied from the local machine to the container. The “src” argument can be a file or a directory.

Parameters
  • container_id (str) – string with the container identification.

  • src (str) – what file or directory you are trying to copy.

  • dst (str) – the destination inside the container.

Return type

tuple with returncode, stdout and stderr.

async execute(*args)

Execute a command and return the returncode, stdout and stderr.

Parameters

*args

Variable length argument list to be used as argument during execution.

Return type

tuple with returncode, stdout and stderr.

async get_container_info(container_id)

Return all information about specific container.

Parameters

container_id (str) – identifier of container

Return type

dict

async get_python_version(image)

Return the current Python version installed in an image.

Parameters

image (str) – Image name. i.e: ‘fedora:33’.

Return type

tuple with both: major, minor numbers and executable path.

async start(container_id)

Starts a container and return the returncode, stdout and stderr.

Parameters

container_id (str) – Container identification string to start.

Return type

tuple with returncode, stdout and stderr.

async stop(container_id)

Stops a container and return the returncode, stdout and stderr.

Parameters

container_id (str) – Container identification string to stop.

Return type

tuple with returncode, stdout and stderr.

exception avocado.utils.podman.PodmanException

Bases: Exception

avocado.utils.process module

Functions dedicated to find and run external commands.

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

Bases: Exception

exception avocado.utils.process.CmdInputError

Bases: Exception

Raised when the command given is invalid, such as an empty command.

class avocado.utils.process.CmdResult(command='', stdout=b'', stderr=b'', 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

The raw stderr (bytes)

property stderr_text
stdout

The raw stdout (bytes)

property 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.SubProcess(cmd, verbose=True, shell=False, env=None, sudo=False, ignore_bg_processes=False, encoding=None, logger=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.

  • 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

  • logger (logging.Logger) – User’s custom logger, which will be logging the subprocess outputs. When this parameter is not set, the avocado.utils.process logger will be used.

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

get_user_id()

Reports user id of this process

is_sudo_enabled()

Returns whether the subprocess is running with sudo enabled

kill()

Send a signal.SIGKILL to the process. Please consider using stop() instead if you want to do all that’s possible to finalize the process and wait for it to finish.

poll()

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

run(timeout=None, sig=Signals.SIGTERM)

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 it’s children using sig and get a status. When the process refuses to die within 1s we use SIGKILL and report the status (be it exit_code or zombie)

  • 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(timeout=None)

Stop background subprocess.

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

Parameters

timeout – Time (seconds) we’ll wait until the process is finished. If it’s not, we’ll try to terminate it and it’s children using sig and get a status. When the process refuses to die within 1s we use SIGKILL and report the status (be it exit_code or zombie)

terminate()

Send a signal.SIGTERM to the process. Please consider using stop() instead if you want to do all that’s possible to finalize the process and wait for it to finish.

wait(timeout=None, sig=Signals.SIGTERM)

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

Parameters
  • timeout – Time (seconds) we’ll wait until the process is finished. If it’s not, we’ll try to terminate it and it’s children using sig and get a status. When the process refuses to die within 1s we use SIGKILL and report the status (be it exit_code or zombie)

  • sig – Signal to send to the process in case it did not end after the specified timeout.

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(s, comments=False, posix=True)

This is kept for compatibility purposes, but is now deprecated and will be removed in later versions. Please use shlex.split() instead.

avocado.utils.process.get_capabilities(pid=None)

Gets a list of all capabilities for a process.

In case the getpcaps command is not available, and empty list will be returned.

It supports getpcaps’ two different formats, the current and the so called legacy/ugly.

Parameters

pid (int) – the process ID (PID), if one is not given, the current PID is used (given by os.getpid())

Returns

all capabilities

Return type

list

avocado.utils.process.get_children_pids(parent_pid, recursive=False)

Returns the children PIDs for the given process

Note

This is currently Linux specific.

Parameters

parent_pid – The PID of parent child process

Returns

The PIDs for the children processes

Return type

list of int

avocado.utils.process.get_command_output_matching(command, pattern)

Runs a command, and if the pattern is in in the output, returns it.

Parameters
  • command (str) – the command to execute

  • pattern (str) – pattern to search in the output, in a line by line basis

Returns

list of lines matching the pattern

Return type

list of str

avocado.utils.process.get_owner_id(pid)

Get the owner’s user id of a process

Parameters

pid – the process id

Returns

user id of the process owner

avocado.utils.process.get_parent_pid(pid)

Returns the parent PID for the given process

Note

This is currently Linux specific.

Parameters

pid – The PID of child process

Returns

The parent PID

Return type

int

avocado.utils.process.getoutput(cmd, timeout=None, verbose=False, ignore_status=True, shell=True, env=None, sudo=False, ignore_bg_processes=False, logger=None)

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

  • 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

  • logger (logging.Logger) – User’s custom logger, which will be logging the subprocess outputs. When this parameter is not set, the avocado.utils.process logger will be used.

Returns

Command output(stdout or stderr).

Return type

str

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

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

  • 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

  • logger (logging.Logger) – User’s custom logger, which will be logging the subprocess outputs. When this parameter is not set, the avocado.utils.process logger will be used.

Returns

Exit status and command output(stdout and stderr).

Return type

tuple

avocado.utils.process.has_capability(capability, pid=None)

Checks if a process has a given capability.

This is a simple wrapper around getpcaps, part of the libcap package. In case the getpcaps command is not available, the capability will be considered not to be available.

Parameters

capability (str) – the name of the capability, refer to capabilities(7) man page for more information.

Returns

whether the capability is available or not

Return type

bool

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=None, send_sigcont=True, timeout=0)

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, defaults to signal.SIGKILL

  • send_sigcont – Send SIGCONT to allow killing stopped processes

  • timeout – How long to wait for the pid(s) to die (negative=infinity, 0=don’t wait, positive=number_of_seconds)

Returns

list of all PIDs we sent signal to

Return type

list

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, shell=False, env=None, sudo=False, ignore_bg_processes=False, encoding=None, logger=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).

  • 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

  • logger (logging.Logger) – User’s custom logger, which will be logging the subprocess outputs. When this parameter is not set, the avocado.utils.process logger will be used.

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.system(cmd, timeout=None, verbose=True, ignore_status=False, shell=False, env=None, sudo=False, ignore_bg_processes=False, encoding=None, logger=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).

  • 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

  • logger (logging.Logger) – User’s custom logger, which will be logging the subprocess outputs. When this parameter is not set, the avocado.utils.process logger will be used.

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, shell=False, env=None, sudo=False, ignore_bg_processes=False, strip_trail_nl=True, encoding=None, logger=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).

  • 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

  • logger (logging.Logger) – User’s custom logger, which will be logging the subprocess outputs. When this parameter is not set, the avocado.utils.process logger will be used.

Returns

Command output.

Return type

bytes

Raise

CmdError, if ignore_status=False.

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

Example of use:

# 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 service manager for a specific service.

Example of use:

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

Example of use:

# 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 service manager for a specific service.

Example of use:

# 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.softwareraid module

This module provides APIs to work with software raid.

class avocado.utils.softwareraid.SoftwareRaid(name, level, disks, metadata, spare_disks=None)

Bases: object

Perform software raid related operations.

Parameters
  • name (str) – Name of the software raid to be created

  • level – Level of software raid to be created

  • disks (list) – List of disks for software raid

  • metadata (str) – Metadata level for software raid

  • spare_disks (list) – List of spare disks for software raid

add_disk(disk)

Adds disk specified to software raid.

Parameters

disk (str) – disk to be added.

Returns

True if add is successful, False otherwise.

Return type

bool

assemble()

Assembles software raid.

Returns

True if assembled, False otherwise.

Return type

bool

clear_superblock()

Zeroes superblocks in member devices of raid.

Returns

True if zeroed, False otherwise.

Return type

bool

create()

Creates software raid.

Returns

True if raid is created. False otherwise.

Return type

bool

exists()

checks if softwareraid exists or not

Mdadm

must be super-user(root) to perform this action

Returns

True if exists, False otherwise.

Return type

bool

get_detail()

Returns mdadm details.

Returns

mdadm –detail output

Return type

str

is_recovering()

Checks if raid is recovering.

Returns

True if recovering, False otherwise.

Return type

bool

remove_disk(disk)

Removes disk specified from software raid.

Parameters

disk (str) – disk to be removed.

Returns

True if remove is successful, False otherwise.

Return type

bool

stop()

Stops software raid.

Returns

True if stopped, False otherwise.

Return type

bool

avocado.utils.ssh module

Provides utilities to carry out an SSH session.

Example of use:

from avocado.utils import ssh

with ssh.Session(host, user='root', key='/path/to/file') as session:
    result = session.cmd('ls')
    if result.exit_status == 0:
        print(result.stdout_text)
exception avocado.utils.ssh.NWException

Bases: Exception

Base Exception Class for all exceptions

avocado.utils.ssh.SSH_CLIENT_BINARY = '/bin/ssh'

The SSH client binary to use, if one is found in the system

class avocado.utils.ssh.Session(host, port=None, user=None, key=None, password=None)

Bases: object

Represents an SSH session to a remote system, for the purpose of executing commands remotely.

Session is also a context manager. On entering the context it tries to establish the connection, therefore on exiting that connection is closed.

Parameters
  • host (str) – a host name or IP address

  • port (int) – port number

  • user (str) – the name of the remote user

  • key (str) – path to a key for authentication purpose

  • password (str) – password for authentication purpose

DEFAULT_OPTIONS = (('StrictHostKeyChecking', 'no'), ('UpdateHostKeys', 'no'), ('ControlPath', '~/.ssh/avocado-master-%r@%h:%p'))
MASTER_OPTIONS = (('ControlMaster', 'yes'), ('ControlPersist', 'yes'))
cleanup_master()

Removes master file if exists.

cmd(command, ignore_status=True)

Runs a command over the SSH session

Parameters
  • command (str) – the command to execute over the SSH session

  • ignore_status (bool) – Whether to check the operation failed or not. If set to False then it raises an avocado.utils.process.CmdError exception in case of either the command or ssh connection returned with exit status other than zero.

Returns

The command result object.

Return type

A avocado.utils.process.CmdResult instance.

connect()

Establishes the connection to the remote endpoint

On this implementation, it means creating the master connection, which is a process that will live while and be used for subsequent commands.

Returns

whether the connection is successfully established

Return type

bool

property control_master
copy_files(source, destination, recursive=False)

Copy Files to and from remote through scp session.

Parameters
  • source – Source file

  • destination – Destination file location

  • recursive – Scp option for copy file. if set to True copy files inside directory recursively.

Type

str

Type

str

Type

bool

Returns

True if success and an exception if not.

Return type

bool

get_raw_ssh_command(command)

Returns the raw command that will be executed locally

This should only be used if you need to interact with the ssh subprocess, and most users will NOT need to. Try to use the cmd() method instead.

Parameters

command (str) – the command to execute over the SSH session

Returns

The raw SSH command, that can be executed locally for the execution of a remote command.

Return type

str

quit()

Attempts to gracefully end the session, by finishing the master process

Returns

if closing the session was successful or not

Return type

bool

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=None)

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=None)

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.sysinfo module

class avocado.utils.sysinfo.Collectible(log_path)

Bases: ABC

Abstract class for representing sysinfo collectibles.

abstract collect()
property name
exception avocado.utils.sysinfo.CollectibleException

Bases: Exception

Base exception for all collectible errors.

class avocado.utils.sysinfo.Command(cmd, timeout=- 1, locale='C')

Bases: Collectible

Collectible command.

Parameters
  • cmd – String with the command.

  • timeout – Timeout for command execution.

  • locale – Force LANG for sysinfo collection

collect()

Execute the command as a subprocess and returns it’s output. :raise CollectibleException

class avocado.utils.sysinfo.Daemon(*args, **kwargs)

Bases: Command

Collectible daemon.

Parameters
  • cmd – String with the command.

  • timeout – Timeout for command execution.

  • locale – Force LANG for sysinfo collection

collect()

Stop daemon execution and returns it’s logs. :raise OSError

run()

Start running the daemon as a subprocess. :raise CollectibleException

class avocado.utils.sysinfo.JournalctlWatcher(log_path=None)

Bases: Collectible

Track the content of systemd journal.

Parameters

log_path – Basename of the file where output is logged (optional).

collect()

Returns the content of systemd journal :raise CollectibleException

class avocado.utils.sysinfo.LogWatcher(path, log_path=None)

Bases: Collectible

Keep track of the contents of a log file in another compressed file.

This object is normally used to track contents of the system log (/var/log/messages), and the outputs are gzipped since they can be potentially large, helping to save space.

Parameters
  • path – Path to the log file.

  • log_path – Basename of the file where output is logged (optional).

collect()

Collect all of the new data present in the log file. :raise CollectibleException

class avocado.utils.sysinfo.Logfile(path, log_path=None)

Bases: Collectible

Collectible system file.

Parameters
  • path – Path to the log file.

  • log_path – Basename of the file where output is logged (optional).

collect()

Reads the log file. :raise CollectibleException

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: ImageProviderBase

CentOS Image Provider

property file_name
get_image_url()

Probes the higher image available for the current parameters.

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

Bases: ImageProviderBase

CirrOS Image Provider

CirrOS is a Tiny OS that specializes in running on a cloud.

name = 'CirrOS'
class avocado.utils.vmimage.DebianImageProvider(version=None, build='[\\d{8}\\-\\d{3}]', arch='x86_64')

Bases: ImageProviderBase

Debian Image Provider

get_image_url()

Probes the higher image available for the current parameters.

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

Bases: FedoraImageProviderBase

Fedora Image Provider

name = 'Fedora'
class avocado.utils.vmimage.FedoraImageProviderBase(version, build, arch)

Bases: ImageProviderBase

Base Fedora Image Provider

HTML_ENCODING = 'iso-8859-1'
get_image_url()

Probes the higher image available for the current parameters.

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

Bases: FedoraImageProviderBase

Fedora Secondary Image Provider

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

Bases: ImageProviderBase

FreeBSD Image Provider

get_best_version(versions)

Return best (more recent) version

get_versions()

Return all available versions for the current parameters.

name = 'FreeBSD'
avocado.utils.vmimage.IMAGE_PROVIDERS = {<class 'avocado.utils.vmimage.JeosImageProvider'>, <class 'avocado.utils.vmimage.UbuntuImageProvider'>, <class 'avocado.utils.vmimage.FedoraSecondaryImageProvider'>, <class 'avocado.utils.vmimage.FreeBSDImageProvider'>, <class 'avocado.utils.vmimage.OpenSUSEImageProvider'>, <class 'avocado.utils.vmimage.DebianImageProvider'>, <class 'avocado.utils.vmimage.CentOSImageProvider'>, <class 'avocado.utils.vmimage.FedoraImageProvider'>, <class 'avocado.utils.vmimage.CirrOSImageProvider'>}

List of available providers classes

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

Bases: object

Creates an instance of Image class.

Parameters
  • name (str) – Name of image.

  • url (str) – The url where the image can be fetched from.

  • version (int) – Version of image.

  • arch (str) – Architecture of the system image.

  • build (str) – Build of the system image.

  • checksum (str) – Hash of the system image to match after download.

  • algorithm (str) – Hash type, used when the checksum is provided.

  • cache_dir (str or iterable) – Local system path where the base images will be held.

  • snapshot_dir (str) – Local system path where the snapshot images will be held. Defaults to cache_dir if none is given.

property base_image
download()
classmethod from_parameters(name=None, version=None, build=None, arch=None, checksum=None, algorithm=None, cache_dir=None, snapshot_dir=None)

Returns an Image, 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 base images will be held.

  • snapshot_dir – (optional) Local system path where the snapshot images will be held. Defaults to cache_dir if none is given.

Returns

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

get()
property 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.

HTML_ENCODING = 'utf-8'
property file_name
static get_best_version(versions)
get_image_parameters(image_file_name)

Computation of image parameters from image_pattern

Parameters

image_file_name (str) – pattern with parameters

Returns

dict with parameters

Return type

dict or None

get_image_url()

Probes the higher image available for the current parameters.

get_version()

Probes the higher version available for the current parameters.

get_versions()

Return all available versions for the current parameters.

property version
property version_pattern
exception avocado.utils.vmimage.ImageProviderError

Bases: Exception

Generic error class for ImageProvider

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

Bases: ImageProviderBase

JeOS Image Provider

name = 'JeOS'
class avocado.utils.vmimage.OpenSUSEImageProvider(version='[0-9]{2}.[0-9]{1}', build=None, arch='x86_64')

Bases: ImageProviderBase

OpenSUSE Image Provider

HTML_ENCODING = 'iso-8859-1'
get_best_version(versions)
get_versions()

Return all available versions for the current parameters.

name = 'OpenSUSE'
avocado.utils.vmimage.QEMU_IMG = None

The “qemu-img” binary used when creating the snapshot images. If set to None (the default), it will attempt to find a suitable binary with avocado.utils.path.find_command(), which uses the the system’s PATH environment variable

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

Bases: ImageProviderBase

Ubuntu Image Provider

get_best_version(versions)

Return best (more recent) version

get_versions()

Return all available versions for the current parameters.

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

Bases: HTMLParser

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

Initialize and reset this instance.

If convert_charrefs is True (the default), all character references are automatically converted to the corresponding Unicode characters.

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

This method is deprecated. Use Image.from_parameters().

avocado.utils.vmimage.get_best_provider(name=None, version=None, build=None, arch=None)

Wrapper to get parameters of 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.

Returns

Image Provider

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