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
- avocado.utils.external package
- Submodules
- avocado.utils.external.gdbmi_parser module
- avocado.utils.external.spark module
GenericASTBuilder
GenericASTMatcher
GenericASTTraversal
GenericASTTraversalPruningException
GenericParser
GenericParser.add()
GenericParser.addRule()
GenericParser.ambiguity()
GenericParser.augment()
GenericParser.buildTree()
GenericParser.causal()
GenericParser.collectRules()
GenericParser.computeNull()
GenericParser.deriveEpsilon()
GenericParser.error()
GenericParser.finalState()
GenericParser.goto()
GenericParser.gotoST()
GenericParser.gotoT()
GenericParser.isnullable()
GenericParser.makeNewRules()
GenericParser.makeSet()
GenericParser.makeSet_fast()
GenericParser.makeState()
GenericParser.makeState0()
GenericParser.parse()
GenericParser.predecessor()
GenericParser.preprocess()
GenericParser.resolve()
GenericParser.skip()
GenericParser.typestring()
GenericScanner
- Module contents
- avocado.utils.network package
- Submodules
- avocado.utils.network.common module
- avocado.utils.network.exceptions module
- avocado.utils.network.hosts module
- avocado.utils.network.interfaces module
NetworkInterface
NetworkInterface.add_ipaddr()
NetworkInterface.add_vlan_tag()
NetworkInterface.are_packets_lost()
NetworkInterface.bring_down()
NetworkInterface.bring_up()
NetworkInterface.config_file_path
NetworkInterface.config_filename
NetworkInterface.flush_ipaddr()
NetworkInterface.get_device_IPI_name()
NetworkInterface.get_hwaddr()
NetworkInterface.get_ipaddrs()
NetworkInterface.get_mtu()
NetworkInterface.is_admin_link_up()
NetworkInterface.is_available()
NetworkInterface.is_bond()
NetworkInterface.is_link_up()
NetworkInterface.is_operational_link_up()
NetworkInterface.is_sriov()
NetworkInterface.is_veth()
NetworkInterface.is_vnic()
NetworkInterface.netmask_to_cidr()
NetworkInterface.nm_flush_ipaddr()
NetworkInterface.ping_check()
NetworkInterface.ping_flood()
NetworkInterface.remove_all_vlans()
NetworkInterface.remove_cfg_file()
NetworkInterface.remove_ipaddr()
NetworkInterface.remove_link()
NetworkInterface.remove_vlan_by_tag()
NetworkInterface.restore_from_backup()
NetworkInterface.restore_slave_cfg_file()
NetworkInterface.save()
NetworkInterface.set_hwaddr()
NetworkInterface.set_mtu()
NetworkInterface.slave_config_filename
NetworkInterface.validate_ipv4_format()
NetworkInterface.validate_ipv4_netmask_format()
NetworkInterface.vlans
- avocado.utils.network.ports module
- Module contents
- avocado.utils.software_manager package
- Subpackages
- avocado.utils.software_manager.backends package
- Submodules
- avocado.utils.software_manager.backends.apt module
- avocado.utils.software_manager.backends.base module
- avocado.utils.software_manager.backends.dnf module
- avocado.utils.software_manager.backends.dpkg module
- avocado.utils.software_manager.backends.rpm module
- avocado.utils.software_manager.backends.yum module
- avocado.utils.software_manager.backends.zypper module
- Module contents
- avocado.utils.software_manager.backends package
- Submodules
- avocado.utils.software_manager.distro_packages module
- avocado.utils.software_manager.inspector module
- avocado.utils.software_manager.main module
- avocado.utils.software_manager.manager module
- Module contents
- 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.probe_zstd_cmd()
Attempts to find a suitable zstd tool that behaves as expected
- Return type:
str or None
- Returns:
path to a suitable zstd executable or None if not found
- 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:
- find_asset_file(create_metadata=False)
Search for the asset file in each one of the cache locations
- 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:
- 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
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:
- 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:
data (either bytes or other data that will be returned unchanged) – data to be transformed into text
encoding – encoding of the data (only used when decoding is necessary)
errors – how to handle encode/decode errors, see: https://docs.python.org/3/library/codecs.html#error-handlers
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.
- 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:
- 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.
- 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.
- 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.
- 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:
- avocado.utils.cpu.get_model()
Get model of cpu
- 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.
- Returns:
A list where NUMA node numbers only which has CPU’s - as elements of The list.
- Return type:
- avocado.utils.cpu.get_pid_cpus(pid)
Get all the cpus being used by the process according to pid informed.
- avocado.utils.cpu.get_revision()
Get revision from /proc/cpuinfo
- Returns:
revision entry from /proc/cpuinfo file e.g.:- ‘0080’ for IBM POWER10 machine
- Return type:
- avocado.utils.cpu.get_va_bits()
Check for VA address bit size in /proc/cpuinfo
- Returns:
VA address bit size
- Return type:
- 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:
- avocado.utils.cpu.get_x86_amd_zen(family=None, model=None)
- avocado.utils.cpu.is_hotpluggable(cpu)
- avocado.utils.cpu.lscpu()
Get Cores per socket, Physical sockets and Physical chips by executing ‘lscpu’ command.
- Return type:
dict_obj with the following details
- Cores per socket:
- Physical sockets:
- Physical chips:
- Chips:
physical sockets * physical chips
- avocado.utils.cpu.numa_nodes_with_assigned_cpus()
Get NUMA nodes with associated CPU’s on the system.
- Returns:
A dictionary,in which “NUMA node numbers” as key and “NUMA node associated CPU’s” as values.
- Return type:
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.
- 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.
- 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.
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:
- 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:
- 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.
- append_expected_remove(filename, line)
Append removed added line to a file.
- 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.
- avocado.utils.diff_validator.assert_change(actual_result, expected_result)
Condition wrapper of the upper method.
- Parameters:
- Returns:
whether changes were detected
- Return type:
- 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:
- avocado.utils.diff_validator.create_diff_report(change_diffs)
Pretty prints the output of the change_diffs variable.
- 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:
- Returns:
file paths with corresponding diff information key-value pairs
- Return type:
- avocado.utils.diff_validator.get_temp_file_path(file_path)
Generates a temporary filename.
avocado.utils.disk module
Disk utilities
- avocado.utils.disk.clean_disk(disk_name)
Cleans partitions table of a disk
- Parameters:
disk_name (str) – disk name
- avocado.utils.disk.create_linux_raw_partition(disk_name, size=None, num_of_par=1)
Creates partitions using sfdisk command
- Parameters:
Returns list of created partitions
- avocado.utils.disk.create_loop_device(size, blocksize=4096, directory='./')
Creates a loop device of size and blocksize specified.
- avocado.utils.disk.delete_loop_device(device)
Deletes the specified loop device.
- avocado.utils.disk.delete_partition(partition_name)
Deletes mentioned partition from disk
- Parameters:
partition_name (str) – partition absolute path
- avocado.utils.disk.freespace(path)
- avocado.utils.disk.fs_exists(device)
check if filesystem exists on give disk/device
- 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
- 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
- avocado.utils.disk.get_available_filesystems()
Return a list of all available filesystem types
- avocado.utils.disk.get_dir_mountpoint(dir_path)
get mounted disk name that is mounted on given dir_path
- 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
- avocado.utils.disk.get_disk_partitions(disk)
Returns partitions of a disk excluding extended partition
- Parameters:
disk (str) – disk name
Returns array with all partitions of disk
- 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.
- 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.
- avocado.utils.disk.get_io_scheduler(device_name)
Return io scheduler name which is set currently for device :param device_name: Device name example like sda :return: IO scheduler :rtype : str
- avocado.utils.disk.get_io_scheduler_list(device_name)
Returns io scheduler available for the IO Device :param device_name: Device name example like sda :return: list of IO scheduler
- avocado.utils.disk.get_size_of_disk(disk)
Returns size of disk in bytes
- Parameters:
disk (str) – disk/device name
Return Type: int
- avocado.utils.disk.is_dir_mounted(dir_path)
check if given directory is mounted or not
- avocado.utils.disk.is_disk_mounted(device)
check if given disk is mounted or not
- 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.disk.set_io_scheduler(device_name, name)
Set io scheduler to a device :param device_name: Device name example like sda :param name: io scheduler name
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
- 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
orUNKNOWN_DISTRO
- Return type:
- 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
- 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).
- 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:
- 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:
- Raises:
RuntimeError
if file has wrong permissions
avocado.utils.filelock module
Utility for individual file access control implemented via PID lock files.
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
- 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, asubprocess.POpen.returncode
- Return type:
int or None
- read_gdb_response(timeout=0.01, max_tries=100)
Read raw responses from GDB
- read_until_break(max_lines=100)
Read lines from GDB until a break condition is reached
- 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
- 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:
- static checksum(input_message)
Calculates a remote message checksum.
More details are available at: https://sourceware.org/gdb/current/onlinedocs/gdb/Overview.html
- 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:
- Raises:
RetransmissionRequestedError, UnexpectedResponseError
- Returns:
raw data read from from the remote server
- Return type:
- 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
- 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
- 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.
- avocado.utils.genio.append_one_line(filename, line)
Append one line of text to filename.
- 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.
- 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.
- 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.
- 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.
- avocado.utils.genio.read_one_line(filename)
Read the first line of filename.
- avocado.utils.genio.write_file(filename, data)
Write data to a file.
- avocado.utils.genio.write_file_or_fail(filename, data)
Write to a file and raise exception on write failure
- Parameters:
- Raises:
GenIOError – On write Failure
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, submodule=False)
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
submodule (Boolean) – to download submodules recursively
- 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
- submodule_checkout()
Performs a git checkout of submodules recursively
- avocado.utils.git.get_repo(uri, branch='master', lbranch=None, commit=None, destination_dir=None, base_uri=None, submodule=False)
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
submodule (Boolean) – to download submodules recursively
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()
- 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:
- class avocado.utils.iso9660.Iso9660IsoInfo(path)
Bases:
MixInMntDirMount
,BaseIso9660
Represents a ISO9660 filesystem
This implementation is based on the cdrkit’s isoinfo tool
- 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()
- 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
- property mnt_dir
Returns a path to the browsable content of the iso
- 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:
- 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=2)
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.
- 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
- exception avocado.utils.linux.UnsupportedMachineError
Bases:
Exception
Exception class for unsupported hardware
- 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_os_secureboot_enabled()
Check whether the secure-boot is enabled at os level. Check for “00000002” in “/proc/device-tree/ibm,secure-boot” file If found, then secure-boot is enabled.
- Returns:
True if secureboot is enabled, False if otherwise
- 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:
- 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.
- avocado.utils.linux_modules.module_is_loaded(module_name)
Is module loaded
- 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.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:
- 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:
- 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:
- Raises:
LVException
on failure to find disk space
- avocado.utils.lv_utils.lv_check(vg_name, lv_name)
Check whether provided logical volume exists.
- 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:
- 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:
- Raises:
LVException
if the logical volume is still active
- avocado.utils.lv_utils.lv_remove(vg_name, lv_name)
Remove a logical volume.
- Parameters:
- 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:
- 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.
- 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:
- Raises:
LVException
if the logical volume could not be unmounted
- avocado.utils.lv_utils.vg_check(vg_name)
Check whether provided volume group exists.
- avocado.utils.lv_utils.vg_create(vg_name, pv_list, force=False)
Create a volume group from a list of physical volumes.
- Parameters:
- 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:
- 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:
- Returns:
ramdisk_filename, vg_ramdisk_dir, vg_name, loop_device
- Return type:
- 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:
- 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
- class avocado.utils.memory.MemInfo
Bases:
object
Representation of /proc/meminfo
There will not be memory information on systems that do not have a /proc/meminfo file accessible.
- 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:
- 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:
- 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:
- 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:
- 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.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:
- avocado.utils.multipath.fail_path(path)
Fail the individual paths.
- 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:
- 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:
- avocado.utils.multipath.get_mpath_paths_status(wwid)
Return the status of all paths of mpath device.
- Parameters:
wwid – wwid or user friendly name of mpath. Example: mpatha or 360050768108001b3a800000000000296
- Returns:
Dict in the format of {path: (dm status, dev status, checker status)}
- 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:
- avocado.utils.multipath.get_multipath_wwid(mpath)
Get the wwid binding for given mpath name
- Returns:
Multipath wwid
- Return type:
- avocado.utils.multipath.get_multipath_wwids()
Get list of multipath wwids.
- avocado.utils.multipath.get_path_status(disk_path)
Return the status of a path in multipath.
- Parameters:
disk_path – disk path. Example: sda, sdb.
- Returns:
Tuple in the format of (dm status, dev status, checker status)
- avocado.utils.multipath.get_paths(wwid)
Get list of paths, given a multipath wwid.
- avocado.utils.multipath.get_policy(wwid)
Gets path_checker policy, given a multipath wwid.
- Returns:
path checker policy.
- Return type:
- avocado.utils.multipath.get_size(wwid)
Gets size of device, given a multipath wwid.
- Returns:
size of multipath device.
- Return type:
- 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.NvmeException
Bases:
Exception
Base Exception Class for all exceptions
- avocado.utils.nvme.attach_ns(ns_id, controller_name, cont_id)
attach the namespace_id to specified controller
- Parameters:
ns_id – namespace ID
controller_name – controller name
cont_id – controller_ID
- avocado.utils.nvme.create_full_capacity_ns(controller_name)
Creates one namespace with full capacity
- Parameters:
controller_name – name of the controller like nvme0/nvme1 etc..
- avocado.utils.nvme.create_max_ns(controller_name, force)
Creates maximum number of namespaces, with equal capacity
- Parameters:
controller_name – name of the controller like nvme0/nvme1 etc..
force – if wants to create the namespace force, then pass force=True
- avocado.utils.nvme.create_namespaces(controller_name, ns_count)
creates equal n number of namespaces on the specified controller
- Parameters:
controller_name – name of the controller like nvme0
ns_count – number of namespaces to be created
- avocado.utils.nvme.create_one_ns(ns_id, controller_name, ns_size)
creates a single namespaces with given size and controller_id
- Parameters:
ns_id – Namespace ID
controller_name – name of the controller like nvme0/nvme1 etc..
ns_size – Size of the namespace that is going to be created
- avocado.utils.nvme.delete_all_ns(controller_name)
Deletes all the name spaces available on the given nvme controller
- Parameters:
controller_name – Nvme controller name eg : nvme0, nvme1 etc..
- avocado.utils.nvme.delete_ns(controller_name, ns_id)
Deletes the specified namespace on the controller
- Parameters:
controller_name – Nvme controller name to which namespace belongs
ns_id – namespace id to be deleted
- avocado.utils.nvme.detach_ns(controller_name, ns_id, cont_id)
detach the namespace_id to specified controller
- Parameters:
ns_id – namespace ID
controller_name – controller name
cont_id – controller_ID
- avocado.utils.nvme.get_block_size(controller_name)
Returns the block size of the namespace. If not found, return defaults to 4k.
- Parameters:
namespace – Name of the namespace like /dev/nvme0n1 etc..
- Return type:
Integer
- 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:
NvmeException
on failure to find pci_address in OS
- avocado.utils.nvme.get_current_ns_ids(controller_name)
Returns the list of namespaces in the nvme controller
- Parameters:
controller_name – Name of the nvme controller like nvme0, nvme1
- Return type:
- avocado.utils.nvme.get_current_ns_list(controller_name)
Returns the list of namespaces in the nvme controller
- Parameters:
controller_name – Name of the nvme controller like nvme0, nvme1
- Return type:
- avocado.utils.nvme.get_equal_ns_size(controller_name, ns_count)
It calculate and return the size of a namespace when want to create more than one namespace with equal sizes
- Parameters:
controller_name – name of the controller like nvme0/nvme1 etc…
ns_count – Number of namespaces you want to create with equal sizes it should be less than or equal to max ns supported on the controller
- Return type:
integer
- avocado.utils.nvme.get_free_space(controller_name)
Returns the total capacity of the nvme adapter
- Parameters:
controller_name – Name of the controller eg: nvme0
- Return type:
integer
- avocado.utils.nvme.get_lba(namespace)
Returns LBA of the namespace. If not found, return defaults to 0.
- Parameters:
namespace – nvme namespace like /dev/nvme0n1, /dev/nvme0n2 etc..
- Return type:
Integer
- avocado.utils.nvme.get_max_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_ns_status(controller_name, ns_id)
Returns the status of namespaces on the specified controller
- Parameters:
controller_name – name of the controller like nvme0
ns_id – ID of namespace for which we need the status
- Return type:
- avocado.utils.nvme.get_nslist_with_pci(pci_address)
Fetches and returns list of namespaces for specified pci_address
- Parameters:
pci_address – pci_address of any nvme adapter
- Return type:
- 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.nvme.is_ns_exists(controller_name, ns_id)
Returns if that particular namespace exists on the controller or not
- Parameters:
controller_name – name of the controller on which we want to check ns existence
- Returns:
True if exists else False
- Return type:
boolean
- avocado.utils.nvme.ns_rescan(controller_name)
re-scans all the names spaces on the given controller
- Parameters:
controller_name – controller name on which re-scan is applied
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.partition module
Utility for handling partitions.
- 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
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.
- 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:
- avocado.utils.path.get_max_file_name_length(path)
Returns the maximum length of a file name in the underlying file system
- 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
- 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:
- 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.bind(driver, full_pci_address)
Bind the pci device(full_pci_address) to driver
- Parameters:
driver – driver of the PCI address (full_pci_address)
full_pci_address – Full PCI address including domain (0000:03:00.0)
- Returns:
None
- avocado.utils.pci.change_domain(dom, def_dom, full_pci_address)
Change the domain of pci device(full_pci_address) to dom
- Parameters:
dom – domain type
def_dom – default domain of pci device(full_pci_address)
full_pci_address – Full PCI address including domain (0000:03:00.0)
- Returns:
None
- avocado.utils.pci.change_domain_check(dom, full_pci_address, def_dom)
Check if the domain changed successfully to “dom” for “full_pci_address”
- Parameters:
dom – domain type
def_dom – default domain of pci device(full_pci_address)
full_pci_address – Full PCI address including domain (0000:03:00.0)
- Returns:
whether domain changed successfully to “dom”
- Return type:
- 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:
- 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’, …]
- 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:
- 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_iommu_group(full_pci_address)
Return the iommu group of full_pci_address
- Parameters:
full_pci_address – Full PCI address including domain (0000:03:00.0)
- Returns:
iommu group of full_pci_address
- Return type:
string
- 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:
- 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:
- 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:
- avocado.utils.pci.get_pci_addresses()
Gets list of PCI addresses in the system. Does not return the PCI Bridges/Switches.
- 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:
- 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_vendor_id(full_pci_address)
Get vendor id of a PCI address
- Parameters:
full_pci_address – Full PCI address including domain (0000:03:00.0)
- Returns:
vendor id of PCI address
- Return type:
- 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:
- avocado.utils.pci.rescan(full_pci_address)
Rescan the system and check for full_pci_address
- Parameters:
full_pci_address – Full PCI address including domain (0000:03:00.0)
- Returns:
None
- avocado.utils.pci.rescan_check(full_pci_address)
Check if rescan for full_pci_address is successful
- Parameters:
full_pci_address – Full PCI address including domain (0000:03:00.0)
- Returns:
whether rescan for full_pci_address is successful
- Return type:
- avocado.utils.pci.reset(full_pci_address)
Remove the full_pci_address
- Parameters:
full_pci_address – Full PCI address including domain (0000:03:00.0)
- Returns:
None
- avocado.utils.pci.reset_check(full_pci_address)
Check if reset for “full_pci_address” is successful
- Parameters:
full_pci_address – Full PCI address including domain (0000:03:00.0)
- Returns:
whether reset for “full_pci_address” is successful
- Return type:
- avocado.utils.pci.unbind(driver, full_pci_address)
Unbind the pci device(full_pci_address) from driver
- Parameters:
driver – driver of the PCI address (full_pci_address)
full_pci_address – Full PCI address including domain (0000:03:00.0)
- Returns:
None
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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- Raise:
PMemException
, if command fails.
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.AsyncPodman(podman_bin=None)
Bases:
_Podman
- 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.
- 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.
- 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.
- class avocado.utils.podman.Podman(podman_bin=None)
Bases:
_Podman
- 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.
- 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.
- get_container_info(container_id)
Return all information about specific container.
- 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.
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) – aCmdResult
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 descriptorlogger_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:
- get_stdout()
Get the full stdout of the subprocess so far.
- Returns:
Standard output of the process.
- Return type:
- 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 usingstop()
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:
- 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 usingstop()
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:
- avocado.utils.process.get_children_pids(parent_pid, recursive=False)
Returns the children PIDs for the given process
- avocado.utils.process.get_command_output_matching(command, pattern)
Runs a command, and if the pattern is in in the output, returns it.
- 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:
- 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:
- 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:
- 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.
- 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:
- 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.
This relies on the GNU version of “ps” and is not guaranteed to work in MacOS.
- 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
, ifignore_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:
- Raise:
CmdError
, ifignore_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:
- Raise:
CmdError
, ifignore_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:
- Raises:
ValueError – when systemd target is unknown
- avocado.utils.service.convert_sysv_runlevel(level)
Convert runlevel to systemd target.
- Parameters:
- Returns:
systemd target
- Return type:
- 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:
- 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:
- add_disk(disk)
Adds disk specified to software raid.
- clear_superblock()
Zeroes superblocks in member devices of raid.
- Returns:
True if zeroed, False otherwise.
- Return type:
- create()
Creates software raid.
- Returns:
True if raid is created. False otherwise.
- Return type:
- 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:
- is_recovering()
Checks if raid is recovering.
- Returns:
True if recovering, False otherwise.
- Return type:
- remove_disk(disk)
Removes disk specified from software raid.
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)
- 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:
- 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, timeout=None)
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.timeout (float) – Limit the command execution time, if you want the command to end within a few seconds, you can set a specific time.
- 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:
- property control_master
- copy_files(source, destination, recursive=False)
Copy Files to and from remote through scp session.
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.CentOSImageProvider'>, <class 'avocado.utils.vmimage.CirrOSImageProvider'>, <class 'avocado.utils.vmimage.DebianImageProvider'>, <class 'avocado.utils.vmimage.FedoraImageProvider'>, <class 'avocado.utils.vmimage.FedoraSecondaryImageProvider'>, <class 'avocado.utils.vmimage.FreeBSDImageProvider'>, <class 'avocado.utils.vmimage.JeosImageProvider'>, <class 'avocado.utils.vmimage.OpenSUSEImageProvider'>, <class 'avocado.utils.vmimage.UbuntuImageProvider'>}
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
- 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