Utilities APIs 

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.

It handles both normal asset names and direct file paths.

Returns:: metadata
Return type:: dict or None

property name_scheme

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

Otherwise, will return None.

property name_url

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

Otherwise, will return None.

static parse_name(name): Returns a ParseResult object for the given name.

property parsed_name: Returns a ParseResult object for the currently set name.

classmethod read_hash_from_file(filename, algorithm=None)

Read the CHECKSUM file and return the hash.

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

Return type:: list with algorithm and hash

property relative_dir

classmethod remove_asset_by_path(asset_path)

Remove an asset and its checksum.

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

Parameters:: asset_path – full path of the asset file.

classmethod remove_assets_by_overall_limit(limit, cache_dirs)

This will remove assets based on overall limit.

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

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

Parameters:

limit – a integer limit in bytes.
cache_dirs – list of directories to use during the search.

classmethod remove_assets_by_size(size_filter, cache_dirs)

classmethod remove_assets_by_unused_for_days(days, cache_dirs)

property urls: Complete list of locations including name if is an URL.

avocado.utils.asset.DEFAULT_HASH_ALGORITHM = 'sha1': The default hash algorithm to use on asset cache operations

avocado.utils.asset.DOWNLOAD_TIMEOUT = 300: The default timeout for the downloading of assets

exception avocado.utils.asset.UnsupportedProtocolError

Bases: OSError

Signals that the protocol of the asset URL is not supported

avocado.utils.astring module

Operations with strings (conversion and sanitation).

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

import string … from avocado.utils import string

And not notice until their code starts failing.

avocado.utils.astring.ENCODING = 'UTF-8': On import evaluated value representing the system encoding based on system locales using locale.getpreferredencoding(). Use this value wisely as some files are dumped in different encoding.

avocado.utils.astring.FS_UNSAFE_CHARS = '<>:"/\\|?*;': String containing all fs-unfriendly chars (Windows-fat/Linux-ext3)

avocado.utils.astring.bitlist_to_string(data)

Transform from bit list to ASCII string.

Converts a list of bits to an ASCII string representation. Only complete bytes (8 bits) are processed; partial bytes are ignored.

Parameters:: data (list[int]) – List of integers representing bits to be transformed
Returns:: ASCII string representation of the bit list
Return type:: str
Raises:: UnicodeDecodeError – If the resulting byte values are not valid ASCII

Note

Only processes complete bytes. If the bit list length is not a multiple of 8, the remaining bits are ignored.

Example

>>> bitlist_to_string([0, 1, 0, 0, 0, 0, 0, 1])  # 'A' = 65
'A'
>>> bitlist_to_string([1, 0, 0, 0])  # Incomplete byte
''

avocado.utils.astring.is_bytes(data)

Check if the given data is a bytes object.

Determines whether the input is specifically a bytes type, as opposed to a text string or other sequence type. This is useful for encoding/decoding operations and type-specific processing.

Parameters:: data (Any) – The data instance to check
Returns:: True if data is a bytes object, False otherwise
Return type:: bool

Note

This function specifically checks for the bytes type, not bytearray or other byte-like sequences.

Example

>>> is_bytes(b'hello')
True
>>> is_bytes('hello')
False
>>> is_bytes(bytearray(b'hello'))
False

avocado.utils.astring.is_text(data)

Check if the given data is a text string.

Determines whether the input is a string type capable of holding Unicode text with multi-byte characters, as opposed to a bytes sequence or other data type.

Parameters:: data (Any) – The data instance to check
Returns:: True if data is a text string, False otherwise
Return type:: bool

Note

In Python 3, this checks for the str type, which is Unicode-capable.

Example

>>> is_text('hello')
True
>>> is_text(b'hello')
False
>>> is_text(42)
False

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 (list) – Matrix representation (list with n rows of m elements).
header (tuple or list or None) – Optional tuple or list with header elements to be displayed.
strip (bool) – Optionally remove trailing whitespace from each row.

Returns:

Generator yielding each formatted row of the tabular output

Return type:

generator of str

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.

Escapes backslashes, dollar signs, double quotes, and backticks that have special meaning in bash when inside double quotes.

Parameters:: command (str) – The command string to escape
Returns:: The escaped command string safe for shell execution
Return type:: str

avocado.utils.astring.string_safe_encode(input_str)

Safely convert any input to a string representation.

Handles mixed unicode and encoded strings by ensuring all input is converted to a proper string type. In Python 3, this primarily serves to convert non-string types (numbers, objects) to strings.

Parameters:: input_str (Any) – Input value that needs to be converted to string. Can be string, numeric, or any object with __str__.
Returns:: String representation of the input
Return type:: str

Note

On Python 3, encoding/decoding is handled automatically by the language, so this function focuses on type conversion rather than encoding management.

Supported Input Types

Strings: returned as-is
Numbers: converted using str()
Objects: converted using their __str__ method
None: converted to 'None'

Example

>>> string_safe_encode('hello')
'hello'
>>> string_safe_encode(42)
'42'
>>> string_safe_encode([1, 2, 3])
'[1, 2, 3]'

avocado.utils.astring.string_to_bitlist(data)

Transform from ASCII string to bit list.

Converts each character in the string to its 8-bit binary representation and returns a flat list of all bits.

Parameters:: data (str) – ASCII string to be transformed to bit list
Returns:: List of integers representing the bits of each character
Return type:: list[int]

Note

Each character produces exactly 8 bits, with the most significant bit first.

Example

>>> string_to_bitlist('A')  # 'A' = 65 = 01000001
[0, 1, 0, 0, 0, 0, 0, 1]
>>> string_to_bitlist('AB')
[0, 1, 0, 0, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 1, 0]

avocado.utils.astring.string_to_safe_path(input_str)

Convert string to a filesystem-safe filename or directory name.

Sanitizes strings for use as filenames by replacing characters that are not allowed on common filesystems (FAT, NTFS, ext3/4) with underscores. Also handles length limits and hidden file conventions.

Parameters:: input_str (str) – String to be converted to a safe filename
Returns:: Filesystem-safe string suitable for use as filename or directory name
Return type:: str

Transformations Applied

Replaces unsafe characters with underscores: < > : " / \ | ? * ;
Limits length to filesystem maximum (typically 255 characters)
Converts hidden files (starting with .) to start with _
Handles Unicode characters that may cause encoding issues

Cross-Platform Compatibility

The function ensures compatibility with:

Windows: FAT32, NTFS filesystems
Linux: ext3, ext4 filesystems
macOS: HFS+, APFS filesystems

Example

>>> string_to_safe_path('my file: <test>.txt')
'my file_ _test_.txt'
>>> string_to_safe_path('.hidden_file')
'_hidden_file'
>>> string_to_safe_path('very_long_filename' * 20)  # Too long
'very_long_filename...'  # Truncated to max length

avocado.utils.aurl module

URL related functions.

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

avocado.utils.aurl.COMMON_SCHEMES = ('http', 'https', 'ftp', 'git'): The most common schemes (protocols) used in URLs

avocado.utils.aurl.is_url(path)

Return True if path looks like an URL of common protocols.

Refer to COMMON_SCHEMES for the list of common protocols.

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

avocado.utils.build module

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

Configures the source tree for a subsequent build

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

Parameters:: configure (str or None) – the name of the configure script (None for trying to find one automatically)
Returns:: the configure script exit status, or None if no script was found and executed

avocado.utils.build.make(path, make='make', env=None, extra_args='', ignore_status=None, process_kwargs=None)

Run make, adding MAKEOPTS to the list of options.

Parameters:

make – what make command name to use.
env – dictionary with environment variables to be set before calling make (e.g.: CFLAGS).
extra – extra command line arguments to pass to make.

Returns:

exit status of the make process

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

Run make, adding MAKEOPTS to the list of options.

Parameters:

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

Returns:

the make command result object

avocado.utils.cloudinit module

cloudinit configuration support

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

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

see:: http://cloudinit.readthedocs.io.

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

An authorized key configuration for the default user

Positional template variables are: ssh_authorized_keys

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

The meta-data file template

Positional template variables are: instance-id, hostname

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

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

Positional template variables are: password

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

A phone home configuration that will post just the instance id

Positional template variables are: address, port

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

Bases: HTTPServer

Implements the phone home HTTP server.

Wait the phone home from a given instance.

Initialize the server.

Parameters:

address (tuple) – a hostname or IP address and port, in the same format given to socket and other servers
instance_id (str) – the identification for the instance that should be calling back, and the condition for the wait to end

classmethod set_up_and_wait_for_phone_home(address, instance_id)

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

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

Parameters:

address (tuple) – a hostname or IP address and port, in the same format given to socket and other servers
instance_id (str) – the identification for the instance that should be calling back, and the condition for the wait to end

wait_for_phone_home(new_call=False)

Waits for this instance to call.

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

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

Bases: BaseHTTPRequestHandler

Handles HTTP requests to the phone home server.

do_POST()

Handles an HTTP POST request.

Respond with status 200 if the instance phoned back.

log_message(format_, *args)

Logs an arbitrary message.

Note:: It currently disables any message logging.

avocado.utils.cloudinit.USERDATA_HEADER = '#cloud-config': The header expected to be found at the beginning of the user-data file

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

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

Positional template variables : username

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

Generates an ISO image with cloudinit configuration

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

Parameters:

output_path (str) – the location of the resulting (to be created) ISO image containing the cloudinit configuration
instance_id (str) – the ID of the cloud instance, a form of identification for the dynamically created executing instances
username (str) – the username to be used when logging interactively on the instance
password (str) – the password to be used along with username when authenticating with the login services on the instance
phone_home_host (str) – the address of the host the instance should contact once it has finished booting
phone_home_port (str) – 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

Utilities for querying and managing CPU information on the current machine.

This module provides functions to read CPU details from /proc/cpuinfo and sysfs, including architecture, vendor, version, online/offline status, NUMA topology, and frequency governor settings. It supports x86_64, i386, powerpc, s390, aarch64, and other architectures.

exception avocado.utils.cpu.FamilyException

Bases: Exception

Raised when CPU family cannot be determined for the current architecture.

avocado.utils.cpu.VENDORS_MAP = {'amd': (b'AMD',), 'ibm': (b'POWER\\d', b'IBM/S390', b'Power\\d'), 'intel': (b'GenuineIntel',)}: Map vendor’s name with expected string in /proc/cpuinfo.

avocado.utils.cpu.cpu_has_flags(flags)

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

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

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

Wrapper that emits deprecation warning and delegates to newfunc.

Parameters:

args – Positional arguments passed through to newfunc.
kwargs – Keyword arguments passed through to newfunc.

Returns:

Result of newfunc(*args, **kwargs).

Return type:

any

avocado.utils.cpu.get_arch()

Detect the CPU architecture of the current machine.

Returns:: Architecture string (e.g. ‘x86_64’, ‘powerpc’, ‘s390’, ‘aarch64’).
Return type:: str

avocado.utils.cpu.get_cpu_arch(*args, **kwargs)

Wrapper that emits deprecation warning and delegates to newfunc.

Parameters:

args – Positional arguments passed through to newfunc.
kwargs – Keyword arguments passed through to newfunc.

Returns:

Result of newfunc(*args, **kwargs).

Return type:

any

avocado.utils.cpu.get_cpu_vendor_name(*args, **kwargs)

Wrapper that emits deprecation warning and delegates to newfunc.

Parameters:

args – Positional arguments passed through to newfunc.
kwargs – Keyword arguments passed through to newfunc.

Returns:

Result of newfunc(*args, **kwargs).

Return type:

any

avocado.utils.cpu.get_cpufreq_governor(*args, **kwargs)

Wrapper that emits deprecation warning and delegates to newfunc.

Parameters:

args – Positional arguments passed through to newfunc.
kwargs – Keyword arguments passed through to newfunc.

Returns:

Result of newfunc(*args, **kwargs).

Return type:

any

avocado.utils.cpu.get_cpuidle_state(*args, **kwargs)

Wrapper that emits deprecation warning and delegates to newfunc.

Parameters:

args – Positional arguments passed through to newfunc.
kwargs – Keyword arguments passed through to newfunc.

Returns:

Result of newfunc(*args, **kwargs).

Return type:

any

avocado.utils.cpu.get_family()

Get CPU family or microarchitecture name.

Returns:

Family string (e.g. ‘broadwell’, ‘haswell’, ‘power8’, ‘power9’, ‘z15’) depending on architecture.

Return type:

Raises:

FamilyException – When family cannot be determined.
NotImplementedError – On unsupported architectures.

avocado.utils.cpu.get_freq_governor()

Get the current CPU frequency governor.

Returns:: Governor name (e.g. ‘performance’), or empty string on error.
Return type:: str

avocado.utils.cpu.get_idle_state()

Get current CPU idle state values.

Returns:: Dict of cpuidle state values for all CPUs
Return type:: dict

avocado.utils.cpu.get_model()

Get CPU model number (x86 only).

Returns:: Model integer from /proc/cpuinfo, or None if not found.
Return type:: int or None
Raises:: NotImplementedError – On non-x86 architectures.

avocado.utils.cpu.get_numa_node_has_cpus()

Get NUMA node numbers that have CPUs assigned.

Returns:: List of NUMA node identifiers that have CPUs.
Return type:: list of str

avocado.utils.cpu.get_pid_cpus(pid)

Get CPU indices used by a process (from /proc/<pid>/task/*/stat).

Parameters:: pid (int or str) – Process ID.
Returns:: List of CPU index strings the process threads are running on.
Return type:: list of str

avocado.utils.cpu.get_revision()

Get revision from /proc/cpuinfo.

Returns:: Revision entry from /proc/cpuinfo (e.g. ‘0080’ for IBM POWER10), or None if no revision line is found.
Return type:: str or None

avocado.utils.cpu.get_va_bits()

Get virtual address bit size from /proc/cpuinfo (x86).

Returns:: VA address bit size as string (e.g. ‘48’), or empty string if not found or on non-x86 architectures.
Return type:: str

avocado.utils.cpu.get_vendor()

Get the current cpu vendor name.

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

avocado.utils.cpu.get_version()

Get cpu version.

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

avocado.utils.cpu.get_x86_amd_zen(family=None, model=None)

Get the AMD Zen architecture version for x86 AMD CPUs.

Parameters:

family (int or None) – AMD CPU family (default: from get_family()).
model (int or None) – AMD CPU model (default: from get_model()).

Returns:

Zen generation (1-6), or None if not an AMD Zen CPU.

Return type:

int or None

avocado.utils.cpu.is_hotpluggable(cpu)

Check whether a CPU can be hot-plugged (offlined/onlined).

Parameters:: cpu (int) – CPU index to check.
Returns:: True if the CPU has an ‘online’ sysfs interface.
Return type:: bool

avocado.utils.cpu.lscpu()

Get CPU topology by executing the ‘lscpu’ command.

Returns:: Dict with keys such as ‘cores_per_chip’, ‘physical_sockets’, ‘physical_chips’, ‘threads_per_core’, ‘sockets’, ‘chips’, ‘physical_cores’ (depending on lscpu output).
Return type:: dict

avocado.utils.cpu.numa_nodes_with_assigned_cpus()

Get NUMA nodes with their associated CPU indices.

Returns:: Dict mapping NUMA node ID to sorted list of CPU indices.
Return type:: dict

avocado.utils.cpu.offline(cpu)

Take a CPU offline.

Parameters:: cpu (int) – CPU index to take offline.
Returns:: 0 on success, 1 on failure (requires root).
Return type:: int

avocado.utils.cpu.online(cpu)

Bring a CPU online.

Parameters:: cpu (int) – CPU index to bring online.
Returns:: 1 on success, 0 on failure (requires root).
Return type:: int

avocado.utils.cpu.online_count()

Return number of online CPUs in the system.

Returns:: Online CPU count.
Return type:: int

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

Wrapper that emits deprecation warning and delegates to newfunc.

Parameters:

args – Positional arguments passed through to newfunc.
kwargs – Keyword arguments passed through to newfunc.

Returns:

Result of newfunc(*args, **kwargs).

Return type:

any

avocado.utils.cpu.online_list()

Report a list of indexes of the online CPUs.

Returns:: List of online CPU indices.
Return type:: list of int

avocado.utils.cpu.set_cpufreq_governor(*args, **kwargs)

Wrapper that emits deprecation warning and delegates to newfunc.

Parameters:

args – Positional arguments passed through to newfunc.
kwargs – Keyword arguments passed through to newfunc.

Returns:

Result of newfunc(*args, **kwargs).

Return type:

any

avocado.utils.cpu.set_cpuidle_state(*args, **kwargs)

Wrapper that emits deprecation warning and delegates to newfunc.

Parameters:

args – Positional arguments passed through to newfunc.
kwargs – Keyword arguments passed through to newfunc.

Returns:

Result of newfunc(*args, **kwargs).

Return type:

any

avocado.utils.cpu.set_freq_governor(governor='random')

Change the CPU frequency governor for all CPUs.

Parameters:: governor (str) – Governor name (e.g. ‘performance’, ‘powersave’), or ‘random’ to pick one randomly from available governors.
Returns:: True on success, False on failure.
Return type:: bool

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

Set or reset CPU idle states for all CPUs.

Parameters:

state_number (str) – cpuidle state number, default: all all states
disable (bool) – whether to disable/enable given cpu idle state, default is to disable.
setstate (dict) – cpuidle state value, output of get_idle_state()

avocado.utils.cpu.total_count()

Return number of total CPUs in the system including offline CPUs.

Returns:: Total CPU count.
Return type:: int

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

Wrapper that emits deprecation warning and delegates to newfunc.

Parameters:

args – Positional arguments passed through to newfunc.
kwargs – Keyword arguments passed through to newfunc.

Returns:

Result of newfunc(*args, **kwargs).

Return type:

any

avocado.utils.crypto module

Cryptographic hash utilities for file verification.

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

Calculate the hash value of a file.

Computes a cryptographic hash of the specified file using the given algorithm. Optionally limits hashing to the first N bytes of the file, which is useful for verifying partial downloads or large files.

Parameters:

filename (str) – Path of the file that will have its hash calculated.
size (int or None) – If provided, hash only the first size bytes of the file. If None or 0, the entire file is hashed. If size exceeds the file size, the entire file is hashed.
algorithm (str) – Hash algorithm to use. Supported algorithms include md5, sha1, sha256, sha512, blake2b, and others available in hashlib.

Returns:

Hexadecimal digest string of the computed hash. Returns None if an invalid algorithm is specified.

Return type:

str or None

Raises:

FileNotFoundError – When the specified file does not exist.
PermissionError – When the file cannot be read due to permissions.

Example:

>>> hash_file('/path/to/file')
'abc123...'
>>> hash_file('/path/to/file', algorithm='sha256')
'e3b0c44298fc1c149afbf4c8996fb924...'
>>> hash_file('/path/to/large_file', size=1024)
'abc123...'

avocado.utils.data_factory module

Generate data useful for the avocado framework and tests themselves.

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

Generate a random string using alphanumeric characters.

Parameters:

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

Returns:

The generated random string.

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

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

The files just have random text contents.

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

avocado.utils.data_structures module

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

class avocado.utils.data_structures.Borg

Bases: object

Multiple instances of this class will share the same state.

This is considered a better design pattern in Python than more popular patterns, such as the Singleton. The Borg pattern allows multiple instances to exist but they all share the same state, making them effectively equivalent. Inspired by Alex Martelli’s article mentioned below.

All instances of this class will have the same __dict__, so any changes to instance variables will be reflected across all instances.

See:: http://www.aleax.it/5ep.html

Example:

>>> b1 = Borg()
>>> b2 = Borg()
>>> b1.value = 42
>>> b2.value  # Will be 42, state is shared
42

Initialize a new Borg instance with shared state.

Sets the instance’s __dict__ to the shared state dictionary, ensuring all instances share the same state.

class avocado.utils.data_structures.CallbackRegister(name, log)

Bases: object

Registers pickable functions to be executed later.

This class maintains a registry of functions with their arguments that can be called at a later time, typically for cleanup operations. All registered functions must be pickable (serializable).

Initialize the callback register.

Parameters:

name (str) – Human readable identifier of this register
log (logging.Logger) – Logger instance for error reporting

register(func, args, kwargs, once=False)

Register function/args to be called on self.run().

Parameters:

func (callable) – Pickable function to be called later
args (tuple) – Pickable positional arguments for the function
kwargs (dict) – Pickable keyword arguments for the function
once (bool) – Add unique (func,args,kwargs) combination only once

run()

Call all registered functions.

Executes all registered functions with their associated arguments. If any function raises an exception, it is logged and execution continues with the remaining functions. Functions are called in LIFO order (last registered, first executed).

unregister(func, args, kwargs)

Unregister (func,args,kwargs) combination.

Parameters:

func (callable) – Pickable function to unregister
args (tuple) – Pickable positional arguments
kwargs (dict) – Pickable keyword arguments

class avocado.utils.data_structures.DataSize(data)

Bases: object

Data Size object with builtin unit-converted attributes.

Represents a data size with automatic unit conversion capabilities. Supports bytes (b), kibibytes (k), mebibytes (m), gibibytes (g), and tebibytes (t). All conversions use binary multipliers (1024-based).

Parameters:: data (str, int, or float) – Data size plus optional unit string. i.e. ‘10m’. No unit string means the data size is in bytes.
Raises:: InvalidDataSize – If the data format is invalid

Example:

>>> size = DataSize('10m')
>>> size.b  # bytes
10485760
>>> size.k  # kibibytes
10240
>>> size.g  # gibibytes
0

Initialize a DataSize object.

Parameters:: data (str, int, or float) – Data size with optional binary unit (e.g., ‘10M’, ‘2.5G’, ‘100’)
Raises:: InvalidDataSize – If the data format is invalid

MULTIPLIERS = {'b': 1, 'g': 1073741824, 'k': 1024, 'm': 1048576, 't': 1099511627776}

property b

Data size in bytes.

Returns:: Size converted to bytes
Return type:: float

property g

Data size in gibibytes.

Returns:: Size converted to gibibytes (truncated to integer)
Return type:: int

property k

Data size in kibibytes.

Returns:: Size converted to kibibytes (truncated to integer)
Return type:: int

property m

Data size in mebibytes.

Returns:: Size converted to mebibytes (truncated to integer)
Return type:: int

property t

Data size in tebibytes.

Returns:: Size converted to tebibytes (truncated to integer)
Return type:: int

property unit

The unit of the data size.

Returns:: Single character representing the unit (‘b’, ‘k’, ‘m’, ‘g’, ‘t’)
Return type:: str

property value

The numeric value of the data size.

Returns:: The original numeric value without unit conversion
Return type:: float

exception avocado.utils.data_structures.InvalidDataSize

Bases: ValueError

Signals that the value given to DataSize is not valid.

This exception is raised when an invalid data size string is provided to the DataSize class constructor.

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. This is useful for expensive computations that should be deferred until actually needed.

Once computed, the value is stored as a regular attribute on the instance, avoiding repeated computation. Inspired by the discussion in the Stack Overflow thread below.

See:: http://stackoverflow.com/questions/15226721/

Initialize the lazy property with a getter function.

Parameters:: f_get (callable) – Function that computes the property value

avocado.utils.data_structures.comma_separated_ranges_to_list(string)

Provides a list from comma separated ranges.

Converts a string containing comma-separated ranges into a list of integers. Ranges can be specified as single numbers or as ranges using hyphens.

Parameters:: string (str) – String of comma separated range (e.g., “1,3-5,7”)
Returns:: List of integer values in comma separated range
Return type:: list of int
Raises:: ValueError – If the string contains invalid range format

Example:

>>> comma_separated_ranges_to_list("1,3-5,7")
[1, 3, 4, 5, 7]
>>> comma_separated_ranges_to_list("10-12")
[10, 11, 12]

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. This function is useful for comparing performance data between different test runs.

Parameters:

matrix1 (list of lists) – Reference Matrix of floats; first column could be header
matrix2 (list of lists) – Matrix that will be compared; first column could be header
threshold (float) – Any difference greater than this percent threshold will be reported (default: 0.05 = 5%)

Returns:

Tuple containing: - Matrix with the difference in comparison - Number of improvements - Number of regressions - Total number of comparisons

Return type:

tuple(list, int, int, int)

Example:

>>> matrix1 = [['test1', 10.0, 20.0]]
>>> matrix2 = [['test1', 12.0, 18.0]]
>>> result = compare_matrices(matrix1, matrix2)
>>> # Returns comparison matrix and statistics

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. The geometric mean is calculated as the nth root of the product of n numbers.

Parameters:: values (list) – List with numeric values
Returns:: Single value representing the geometric mean for the list values, or None if the list is empty
Return type:: float or None
Raises:: ValueError – If any value in the list cannot be converted to int
See:: http://en.wikipedia.org/wiki/Geometric_mean

Example:

>>> geometric_mean([1, 2, 4, 8])
2.8284271247461903

avocado.utils.data_structures.ordered_list_unique(object_list)

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

This function removes duplicates from a list while maintaining the original order of the first occurrence of each element.

Parameters:: object_list (list) – List of objects that may contain duplicates
Returns:: List with duplicates removed, order preserved
Return type:: list

Example:

>>> ordered_list_unique([1, 2, 2, 3, 1, 4])
[1, 2, 3, 4]

avocado.utils.data_structures.recursive_compare_dict(dict1, dict2, level='DictKey', diff_btw_dict=None)

Finds difference between two dictionaries.

Recursively compares two dictionaries and returns a list of differences. The function handles nested structures and provides detailed difference information.

Parameters:

dict1 (dict, list, or any) – First dictionary to compare
dict2 (dict, list, or any) – Second dictionary to compare
level (str) – Current level identifier for nested comparison
diff_btw_dict (list or None) – List to store differences (used internally for recursion)

Returns:

List of differences between the two dictionaries, or None for recursive calls

Return type:

list or None

Example:

>>> dict1 = {'a': 1, 'b': {'c': 2}}
>>> dict2 = {'a': 2, 'b': {'c': 2}}
>>> differences = recursive_compare_dict(dict1, dict2)
>>> # Returns list of differences

avocado.utils.data_structures.time_to_seconds(time)

Convert time in minutes, hours and days to seconds.

Converts a time string with optional unit suffix to seconds. Supported units are ‘s’ (seconds), ‘m’ (minutes), ‘h’ (hours), and ‘d’ (days). If no unit is specified, the value is assumed to be in seconds.

Parameters:: time (str, int, or None) – Time, optionally including the unit (i.e. ‘10d’, ‘5m’, ‘30’)
Returns:: Time converted to seconds
Return type:: int
Raises:: ValueError – If the time format is invalid

Example:

>>> time_to_seconds('10m')
600
>>> time_to_seconds('2h')
7200
>>> time_to_seconds('30')
30
>>> time_to_seconds(None)
0

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.deprecation module

class avocado.utils.deprecation.LogDeprecation

Bases: object

A class that ensures a message is logged only once.

flush()

warning(utility_name, msg=None): Logs a warning message only once.

avocado.utils.diff_validator module

Diff validator: Utility for testing file changes

Some typical use of this utility would be:

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

After making changes through some in-test operation:

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

If test fails due to invalid change on the system:

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

class avocado.utils.diff_validator.Change

Bases: object

Class for tracking and validating file changes

Creates a change object.

add_validated_files(filenames)

Add file to change object.

Parameters:: filenames ([str]) – files to validate

append_expected_add(filename, line)

Append expected added line to a file.

Parameters:

filename (str) – file to append to
line (str) – line to append to as an expected addition

append_expected_remove(filename, line)

Append removed added line to a file.

Parameters:

filename (str) – file to append to
line (str) – line to append to as an expected removal

get_all_adds(): Return a list of the added lines for all validated files.

get_all_removes(): Return a list of the removed lines for all validated files.

get_target_files(): Get added files for change.

exception avocado.utils.diff_validator.DiffValidationError: Bases: Exception

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

Condition wrapper of the upper method.

Parameters:

actual_result ({str, ([str], [str])}) – actual added and removed lines with filepath keys and a tuple of ([added_line, …], [removed_line, …])
expected_result ({str, ([str], [str])}) – expected added and removed lines of type as the actual result

Returns:

whether changes were detected

Return type:

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

Calculates unexpected line changes.

Parameters:

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

Returns:

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

Return type:

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

avocado.utils.diff_validator.create_diff_report(change_diffs)

Pretty prints the output of the change_diffs variable.

Parameters:: change_diffs – detected differences as groups of lines with filepath keys and a tuple of (unexpected_adds, not_present_adds, unexpected_removes, not_present_removes)
Type:: {str, (str, str, str, str)}
Returns:: print string of the line differences
Return type:: str

avocado.utils.diff_validator.del_temp_file_copies(file_paths)

Deletes all the provided files.

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

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

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

Parameters:

file_paths ([str]) – original file paths (whose temporary versions will be retrieved)
compared_file_paths ([str] or None) – custom file paths to use instead of the temporary versions

Returns:

file paths with corresponding diff information key-value pairs

Return type:

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

avocado.utils.diff_validator.get_temp_file_path(file_path)

Generates a temporary filename.

Parameters:: file_path (str) – file path prefix
Returns:: appended file path
Return type:: str

avocado.utils.diff_validator.make_temp_file_copies(file_paths)

Creates temporary copies of the provided files.

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

avocado.utils.diff_validator.parse_unified_diff_output(lines)

Parses the unified diff output of two files.

Parameters:: lines ([str]) – diff lines
Returns:: pair of adds and removes, where each is a list of trimmed lines
Return type:: ([str], [str])

avocado.utils.disk module

Disk utilities

exception avocado.utils.disk.DiskError

Bases: Exception

Generic DiskError

avocado.utils.disk.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:

disk_name (str) – disk/device name
size (str) – size of partition
num_of_par (int) – Number of partitions to be created

Returns list of created partitions

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

Creates a loop device of size and blocksize specified.

Parameters:

size (int) – Size of loop device, in bytes
blocksize (int) – block size of loop device, in bytes. Defaults to 4096
directory (str) – Directory where the backing file will be created. Defaults to current directory.

Returns:

loop device name

Return type:

avocado.utils.disk.delete_loop_device(device)

Deletes the specified loop device.

Parameters:: device (str) – device to be deleted
Returns:: True if deleted.
Return type:: bool

avocado.utils.disk.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

Parameters:: device (str) – disk/device name
Returns:: returns True if filesystem exists on the give disk else False
Return type:: bool

avocado.utils.disk.get_absolute_disk_path(device)

Returns absolute device path of given disk

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

Parameters:: device (str) – disk name or disk alias names sda or scsi-xxx
Returns:: the device absolute path name
Return type:: bool

avocado.utils.disk.get_all_disk_paths()

Returns all available disk names and alias on this system

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

Returns:: a list of all disk path names
Return type:: list of str

avocado.utils.disk.get_available_filesystems()

Return a list of all available filesystem types

Returns:: a list of filesystem types
Return type:: list of str

avocado.utils.disk.get_dir_mountpoint(dir_path)

get mounted disk name that is mounted on given dir_path

Parameters:: dir_path (str) – absolute directory path
Returns:: returns disk name which mounted on given dir_path
Return type:: str

avocado.utils.disk.get_disk_blocksize(path): Return the disk block size, in bytes

avocado.utils.disk.get_disk_mountpoint(device)

get mountpoint on which given disk is mounted

Parameters:: device (str) – disk/device name
Returns:: return directory name on which disk is mounted
Return type:: str

avocado.utils.disk.get_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.

Returns:: a list of paths to the physical disks on the system
Return type:: list of str

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

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

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

avocado.utils.disk.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

Parameters:: dir_path (str) – directory path
Returns:: True if the given director is mounted else False
Return type:: bool

avocado.utils.disk.is_disk_mounted(device)

check if given disk is mounted or not

Parameters:: device (str) – disk/device name
Returns:: True if the device/disk is mounted else False
Return type:: bool

avocado.utils.disk.is_root_device(device)

check for root disk

Parameters:: device – device to check
Returns:: True or False, True if given device is root disk otherwise will return False.

avocado.utils.disk.rescan_disk(disk_name)

Re-scans disk

Parameters:: disk_name (str) – disk name

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

Parameters:: file_name (str) – name of file
Returns:: whether the file exists in remote machine or not
Return type:: bool

check_name_for_file()

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

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

check_name_for_file_contains()

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

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

check_release(): Checks if this has the conditions met to look for the release number

check_version(): Checks if this class will look for a regex in file and return a distro

get_distro()

Parameters:: session – ssh connection between another machine

Returns the LinuxDistro this probe detected

name_for_file(): Get the distro name if the CHECK_FILE is set and exists

name_for_file_contains(): Get the distro if the CHECK_FILE is set and has content

release(): Returns the release of the distro

version(): Returns the version of the distro

avocado.utils.distro.detect(session=None)

Attempts to detect the Linux Distribution running on this machine.

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

Parameters:: session (avocado.utils.ssh.Session) – ssh connection between another machine
Returns:: the detected LinuxDistro or UNKNOWN_DISTRO
Return type:: LinuxDistro

avocado.utils.distro.register_probe(probe_class): Register a probe to be run during autodetection

avocado.utils.dmesg module

Module for manipulate dmesg while running test.

exception avocado.utils.dmesg.DmesgError

Bases: Exception

Base Exception Class for all dmesg utils exceptions.

exception avocado.utils.dmesg.TestFail

Bases: AssertionError, Exception

Indicates that the test failed.

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

status = 'FAIL'

avocado.utils.dmesg.check_kernel_cmdline_param(param: str) → bool

Check if a given kernel cmdline parameter is present in /proc/cmdline.

Parameters:: param – Kernel cmdline parameter string to search for (e.g. “fred=on”)
Returns:: True if the parameter is found, False otherwise

avocado.utils.dmesg.check_kernel_logs(pattern)

Check if “pattern” is present in kernel logs.

Parameters:: pattern – string to check in kernel logs
Returns:: True if pattern found, False otherwise

avocado.utils.dmesg.clear_dmesg()

function clear dmesg.

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

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

Function collect dmesg and save in file.

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

Parameters:: output_file (str) – File use for save dmesg output if not provided it use tmp file which located in system /tmp path
Returns:: file which contain dmesg
Return type:: str

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

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

Parameters:

output_file (str) – The file used to save dmesg
level_check (int) – level of severity of issues to be checked 1 - emerg 2 - emerg,alert 3 - emerg,alert,crit 4 - emerg,alert,crit,err 5 - emerg,alert,crit,err,warn

Skip_errors:

list of dmesg error messages which want skip

avocado.utils.dmesg.collect_errors_dmesg(patterns)

Check patterns in dmesg.

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

avocado.utils.dmesg.collect_journalctl_logs(pattern: str) → list

Collect kernel logs from journalctl that match a given pattern.

Parameters:: pattern – String to search for in journalctl logs
Returns:: List of matching log lines

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

Dmesg fail method decorator

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

Parameters:: level (int) – Dmesg Level based on which the test failure should be raised
Returns:: Class decorator
Return type:: class

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

Remove some messages from a dmesg buffer.

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

Dmesg_stdout:: dmesg messages from which filter should be applied. This must be a decoded output buffer with new lines.
Skip_messages:: list of strings to be removed

avocado.utils.download module

Methods to download URLs and regular files.

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

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

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

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

Parameters:

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

Raise:

EnvironmentError.

Returns:

destination path.

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

Retrieve a file from given url.

Parameters:

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

Returns:

None.

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

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

Parameters:

url (string) – URL for the file to be download
output_file (string) – file name or absolute path on which to save the file to
title (string) – optional title to go along the progress bar
chunk_size (integer) – amount of data to read at a time

avocado.utils.download.url_open(url, data=None, timeout=5)

Wrapper to urllib2.urlopen() with timeout addition.

Parameters:

url – URL to open.
data – (optional) data to post.
timeout – (optional) default timeout in seconds. Please, be aware that timeout here is just for blocking operations during the connection setup, since this method doesn’t read the file from the url.

Returns:

file-like object.

Raises:

URLError.

avocado.utils.exit_codes module

Avocado Utilities exit codes.

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

avocado.utils.exit_codes.UTILITY_FAIL = 1: The utility ran, but needs to signalize a fail.

avocado.utils.exit_codes.UTILITY_GENERIC_CRASH = -1: Utility generic crash

avocado.utils.exit_codes.UTILITY_OK = 0: The utility finished successfully

avocado.utils.file_utils module

SUMMARY

Utilities for file tests.

INTERFACE

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

Verifies that given file belongs to given owner and group.

Parameters:

owner (str) – user that owns of the file
group (str) – group of the owner of the file
file_name_pattern (str) – can be a glob
check_recursive (bool) – if file_name_pattern matches a directory, recurse into that subdir or not

Raises:

RuntimeError if file has wrong owner or group

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

Verify that a given file has a given numeric permission.

Parameters:

perms (int) – best given in octal form, e.g. 0o755
file_name_pattern (str) – can be a glob

Raises:

RuntimeError if file has wrong permissions

avocado.utils.filelock module

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

exception avocado.utils.filelock.AlreadyLocked: Bases: Exception

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

Bases: object

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

exception avocado.utils.filelock.LockFailed: Bases: Exception

avocado.utils.gdb module

GDB Communication and Debugging Utilities

This module provides comprehensive functionality for interacting with the GNU Debugger (GDB) through multiple interfaces and protocols. It supports both local debugging sessions and remote debugging scenarios.

Key Features:

GDB/MI (Machine Interface) communication for programmatic control
GDB Server management for remote debugging sessions
GDB Remote Protocol client implementation
Command execution with structured result parsing
Breakpoint management and program flow control
Support for both CLI and MI command interfaces

Main Classes:

GDB: Wraps a local GDB subprocess with MI interface communication GDBServer: Manages a gdbserver instance for remote debugging GDBRemote: Implements GDB remote protocol client for direct communication CommandResult: Encapsulates command execution results and metadata

Common Usage Patterns:

Automated debugging workflows in test environments
Remote debugging of embedded or containerized applications
Programmatic analysis of application crashes and core dumps
Integration with continuous integration and testing frameworks

The module handles low-level protocol details, message parsing, and connection management, providing a high-level Python interface for GDB operations.

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
Raises:: gdbmi_parser.GdbMiError – if there are many result responses to a single cmd

cmd_exists(command)

Checks if a given command exists

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

connect(port)

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

This uses the “extended-remote” target type only

Parameters:: port (int) – the TCP port number
Returns:: a CommandResult instance
Return type:: CommandResult
Raises:: UnexpectedResponseError – if response is unexpected

del_break(number)

Deletes a breakpoint by its number

Parameters:: number (int) – the breakpoint number
Returns:: a CommandResult instance
Return type:: CommandResult
Raises:: UnexpectedResponseError – if response is unexpected

disconnect()

Disconnects from a remote debugger

Returns:: a CommandResult instance
Return type:: CommandResult
Raises:: UnexpectedResponseError – if response is unexpected

exit()

Exits the GDB application gracefully

Returns:: the result of subprocess.POpen.wait(), that is, a subprocess.POpen.returncode
Return type:: int or None

read_gdb_response(timeout=0.01, max_tries=100)

Read raw responses from GDB

Parameters:

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

Returns:

a string containing a raw response from GDB

Return type:

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

Raises:

ValueError – if can’t read GDB response

read_until_break(max_lines=100)

Read lines from GDB until a break condition is reached

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

run(args=None)

Runs the application inside the debugger

Parameters:: args (builtin.list) – the arguments to be passed to the binary as command line arguments
Returns:: a CommandResult instance
Return type:: CommandResult
Raises:: UnexpectedResponseError – if response is unexpected

send_gdb_command(command)

Send a raw command to the GNU debugger input

Parameters:: command (str) – the GDB command, hopefully in MI language

set_break(location, ignore_error=False)

Sets a new breakpoint on the binary currently being debugged

Parameters:

location (str) – a breakpoint location expression as accepted by GDB
ignore_error (bool) – if set, won’t raise exceptions

Returns:

a CommandResult instance

Return type:

CommandResult

Raises:

UnexpectedResponseError – if response is unexpected

set_file(path)

Sets the file that will be executed

Parameters:: path (str) – the path of the binary that will be executed
Returns:: a CommandResult instance
Return type:: CommandResult
Raises:: UnexpectedResponseError – if response is unexpected

class avocado.utils.gdb.GDBRemote(host, port, no_ack_mode=True, extended_mode=True)

Bases: object

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

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.

Initializes a new GDBRemote object.

Parameters:

host (str) – the IP address or host name
port (int) – the port number where the the remote GDB is listening on
no_ack_mode (bool) – if the packet transmission confirmation mode should be disabled
extended_mode – if the remote extended mode should be enabled

static checksum(input_message)

Calculates a remote message checksum.

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

Parameters:: input_message (bytes) – the message input payload, without the start and end markers
Returns:: two byte checksum
Return type:: bytes

cmd(command_data, expected_response=None)

Sends a command data to a remote gdb server

Limitations: the current version does not deal with retransmissions.

Parameters:

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

Returns:

raw data read from from the remote server

Return type:

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

Raises:

NotConnectedError – if the socket is not initialized
RetransmissionRequestedError – if there was a failure while reading the result of the command
UnexpectedResponseError – if response is unexpected

connect(): Connects to the remote target and initializes the chosen modes

static decode(data)

Decodes a packet and returns its payload.

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

Parameters:: data (bytes) – the command data payload
Returns:: the encoded command, ready to be sent to a remote GDB
Return type:: bytes
Raises:: InvalidPacketError – if the packet is not well constructed, like in checksum mismatches

static encode(data)

Encodes a command.

That is, add prefix, suffix and checksum.

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

Parameters:: data (bytes) – the command data payload
Returns:: the encoded command, ready to be sent to a remote GDB
Return type:: bytes

set_extended_mode()

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

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

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.

If the file does not exist, it will be created.

Parameters:

filename (str) – Path to the file.
data (str) – Data to be appended to the file.

Raises:

FileNotFoundError – When the parent directory does not exist.
PermissionError – When the file cannot be written due to permissions.

Example:

>>> append_file("/tmp/log.txt", "New log entry\n")  

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

Append one line of text to a file.

A newline character is automatically appended. Any existing trailing newline in the input line is stripped before adding the newline. If the file does not exist, it will be created.

Parameters:

filename (str) – Path to the file.
line (str) – Line to be appended.

Raises:

FileNotFoundError – When the parent directory does not exist.
PermissionError – When the file cannot be written due to permissions.

Example:

>>> append_one_line("/tmp/log.txt", "Log entry 1")  
>>> append_one_line("/tmp/log.txt", "Log entry 2")  

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

Compare two files for equality using cryptographic hashing.

This function computes the hash of both files and compares them, which is efficient for large files. Files are considered equal if they have identical content.

Parameters:

filename (str) – Path to the first file.
other (str) – Path to the second file.

Returns:

True if files have identical content, False otherwise.

Return type:

Example:

>>> are_files_equal("/tmp/file1.txt", "/tmp/file2.txt")  
True

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

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

Parameters:

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

Returns:

User answer.

Return type:

Example:

>>> ask("Do you want to continue?", auto=True)
'y'

avocado.utils.genio.is_pattern_in_file(filename, pattern)

Check if a regex pattern matches anywhere in a file.

The pattern is matched using Python’s re.search with MULTILINE mode, allowing patterns like ^ and $ to match at line boundaries.

Parameters:

filename (str) – Path to the file.
pattern (str) – Regular expression pattern to search for.

Returns:

True if pattern matches anywhere in the file, False otherwise.

Return type:

Raises:

GenIOError – When filename is not a regular file (e.g., directory).

Example:

>>> is_pattern_in_file("/etc/passwd", r"^root:")  
True
>>> is_pattern_in_file("/etc/passwd", r"nonexistent")  
False

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 a list with newlines stripped.
Return type:: list

Example:

>>> read_all_lines("/etc/hosts")  
['127.0.0.1 localhost', '::1 localhost']
>>> read_all_lines("/nonexistent/file.txt")
[]

avocado.utils.genio.read_file(filename)

Read the entire contents of a file.

Parameters:

filename (str) – Path to the file.

Returns:

File contents.

Return type:

Raises:

FileNotFoundError – When the file does not exist.
PermissionError – When the file cannot be read due to permissions.

Example:

>>> read_file("/etc/hostname")  
'myhost\n'

avocado.utils.genio.read_line_with_matching_pattern(filename, pattern)

Return lines from a file that contain a given pattern.

This method returns all lines where the pattern substring is found. The search uses simple substring matching (not regex).

Parameters:

filename (str) – Path to the file to be read.
pattern (str) – Pattern substring to search for in each line.

Returns:

All lines from the file that contain the pattern, with newlines stripped.

Return type:

list

Raises:

FileNotFoundError – When the file does not exist.
PermissionError – When the file cannot be read due to permissions.

Example:

>>> read_line_with_matching_pattern("/etc/passwd", "root")  
['root:x:0:0:root:/root:/bin/bash']

avocado.utils.genio.read_one_line(filename)

Read the first line of a file.

The returned line has the trailing newline character stripped.

Parameters:

filename (str) – Path to the file.

Returns:

First line contents with newline stripped.

Return type:

Raises:

FileNotFoundError – When the file does not exist.
PermissionError – When the file cannot be read due to permissions.

Example:

>>> read_one_line("/etc/hostname")  
'myhost'

avocado.utils.genio.write_file(filename, data)

Write data to a file.

This will overwrite any existing content in the file. If the file does not exist, it will be created.

Parameters:

filename (str) – Path to the file.
data (str) – Data to be written to the file.

Raises:

FileNotFoundError – When the parent directory does not exist.
PermissionError – When the file cannot be written due to permissions.

Example:

>>> write_file("/tmp/test.txt", "Hello World")  

avocado.utils.genio.write_file_or_fail(filename, data)

Write to a file and raise GenIOError on write failure.

Unlike write_file(), this function catches OSError exceptions and re-raises them as GenIOError with a descriptive message.

Parameters:

filename (str) – Path to the file.
data (str) – Data to be written to the file.

Raises:

GenIOError – When the write operation fails for any reason.

Example:

>>> write_file_or_fail("/tmp/test.txt", "Hello World")  

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

Write one line of text to a file.

A newline character is automatically appended. Any existing trailing newline in the input line is stripped before adding the newline.

Parameters:

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

Raises:

FileNotFoundError – When the parent directory does not exist.
PermissionError – When the file cannot be written due to permissions.

Example:

>>> write_one_line("/tmp/test.txt", "Hello World")  

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

Parameters:

src (str) – source path
dst (str) – destination path

Return type:

None

create(flags=None)

Creates a new ISO image

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

read(path)

Abstract method to read data from path

Parameters:: path – path to the file
Returns:: data content from the file
Return type:: str

write(path, content)

Writes a new file into the ISO image

Parameters:

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

class avocado.utils.iso9660.Iso9660IsoInfo(path)

Bases: MixInMntDirMount, BaseIso9660

Represents a ISO9660 filesystem

This implementation is based on the cdrkit’s isoinfo tool

read(path)

Abstract method to read data from path

Parameters:: path – path to the file
Returns:: data content from the file
Return type:: str

class avocado.utils.iso9660.Iso9660IsoRead(path)

Bases: MixInMntDirMount, BaseIso9660

Represents a ISO9660 filesystem

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

close(): Cleanups and frees any resources being used

copy(src, dst)

Simplistic version of copy that relies on read()

Parameters:

src (str) – source path
dst (str) – destination path

Return type:

None

read(path)

Abstract method to read data from path

Parameters:: path – path to the file
Returns:: data content from the file
Return type:: str

class avocado.utils.iso9660.Iso9660Mount(path)

Bases: BaseIso9660

Represents a mounted ISO9660 filesystem.

initializes a mounted ISO9660 filesystem

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

close()

Perform umount operation on the temporary dir

Return type:: None

copy(src, dst)

Parameters:

src (str) – source
dst (str) – destination

Return type:

None

property mnt_dir: Returns a path to the browsable content of the iso

read(path)

Read data from path

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

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

Checks the available tools on a system and chooses class accordingly

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

Parameters:

path (str) – path to an iso9660 image file
capabilities (list) – list of specific capabilities that are required for the selected implementation, such as “read”, “copy” and “mnt_dir”.

Returns:

an instance of any iso9660 capable tool

Return type:

Iso9660IsoInfo, Iso9660IsoRead, Iso9660Mount, ISO9660PyCDLib or None

avocado.utils.kernel module

Provides utilities for the Linux kernel.

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

Bases: object

Build the Linux Kernel from official tarballs.

Creates an instance of KernelBuild.

Parameters:

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

Returns:

None.

SOURCE = 'linux-{version}.tar.gz'

URL = 'https://www.kernel.org/pub/linux/kernel/v{major}.x/'

build(binary_package=False, njobs=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.

Parameters:

targets (list of str) – configuration targets. Default is ‘defconfig’.
extra_configs (list of str) – additional configurations in the form of CONFIG_NAME=VALUE.

download(url=None)

Download kernel source.

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

install(): Install built kernel.

uncompress()

Uncompress kernel source.

Raises:: Exception in case the tarball is not downloaded

property vmlinux: Return the vmlinux path if the file exists

exception avocado.utils.kernel.KernelBuildError

Bases: Exception

Exception raised when there is an error building the kernel.

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_sched_schedstats()

Enable SELinux Enforcing in system

Returns:: True if sched_schedstats enabled , False if not enabled

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_sched_schedstats_enabled(): Returns True if sched_schedstats is in enabled mode, False if no.

avocado.utils.linux.is_selinux_enforcing(): Returns True if SELinux is in enforcing mode, False if permissive/disabled.

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

Set values on /proc/sys

Parameters:

key – A location under /proc/sys
value – If not None, a value to write into the sysctl.

Returns:

The single-line sysctl value as a string.

avocado.utils.linux_modules module

Linux kernel modules APIs

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

Bases: Enum

BUILTIN = <object object>: Config built-in to kernel (=y)

MODULE = <object object>: Config compiled as loadable module (=m)

NOT_SET = <object object>: Config commented out or not set

avocado.utils.linux_modules.check_kernel_config(config_name)

Reports the configuration of $config_name of the current kernel

Parameters:: config_name (str) – Name of kernel config to search
Returns:: Config status in running kernel (NOT_SET, BUILTIN, MODULE)
Return type:: ModuleConfig

avocado.utils.linux_modules.configure_module(module, config)

Check if ‘config’ is not set, builtin or module. Load ‘module’ if ‘config’ is set as module.

Parameters:

module – kernel module to configure
config – kernel config to check and validate

Returns:

True if module is builtin or loaded successfully. Else False.

Return type:

boolean

avocado.utils.linux_modules.get_loaded_modules(): Gets list of loaded modules. :return: List of loaded modules.

avocado.utils.linux_modules.get_modules_dir()

Return the modules dir for the running kernel version

Returns:: path of module directory
Return type:: String

avocado.utils.linux_modules.get_submodules(module_name)

Get all submodules of the module.

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

avocado.utils.linux_modules.load_module(module_name): Checks if a module has already been loaded. :param module_name: Name of module to check :return: True if module is loaded, False otherwise :rtype: Bool

avocado.utils.linux_modules.loaded_module_info(module_name)

Get loaded module details: Size and Submodules.

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

avocado.utils.linux_modules.module_is_loaded(module_name)

Is module loaded

Parameters:: module_name (str) – Name of module to search for
Returns:: True if module is loaded
Return type:: bool

avocado.utils.linux_modules.parse_lsmod_for_module(l_raw, module_name, escape=True): Use a regex to parse raw lsmod output and get module information :param l_raw: raw output of lsmod :type l_raw: str :param module_name: Name of module to search for :type module_name: str :param escape: Escape regex tokens in module_name, default True :type escape: bool :return: Dictionary of module info, name, size, submodules if present :rtype: dict

avocado.utils.linux_modules.unload_module(module_name)

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

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

avocado.utils.lv_utils module

exception avocado.utils.lv_utils.LVException

Bases: Exception

Base Exception Class for all exceptions

avocado.utils.lv_utils.get_device_total_space(disk)

Get the total device size.

Parameters:: device (str) – name of the device/disk to find the total size
Returns:: size in bytes
Return type:: int
Raises:: LVException on failure to find disk space

avocado.utils.lv_utils.get_devices_total_space(devices)

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

Parameters:: devices (list) – list with the names of devices separated with space.
Returns:: sizes in bytes
Return type:: int
Raises:: LVException on failure to find disk space

avocado.utils.lv_utils.get_diskspace(disk)

Get the entire disk space of a given disk.

Parameters:: disk (str) – name of the disk to find the free space of
Returns:: size in bytes
Return type:: str
Raises:: LVException on failure to find disk space

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

Check whether provided logical volume exists.

Parameters:

vg_name (str) – name of the volume group
lv_name (str) – name of the logical volume

Returns:

whether the logical volume was found

Return type:

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

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

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

The volume group must already exist.

Parameters:

vg_name (str) – name of the volume group
lv_name (str) – name of the logical volume
lv_size (str) – size for the logical volume to be created
force_flag (bool) – whether to abort if volume already exists or remove and recreate it
pool_name (str) – name of thin pool or None for a regular volume
pool_size (str) – size of thin pool if it will be created

Raises:

LVException if preconditions or execution fails

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

List all info about available logical volumes.

Parameters:: vg_name (str) – name of the volume group or None to list all
Returns:: list of available logical volumes
Return type:: {str, {str, str}}

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

Mount a logical volume to a mount location.

Parameters:

vg_name (str) – name of the volume group
lv_name (str) – name of the logical volume
mount_loc (str) – location to mount the logical volume to
create_filesystem (str) – can be one of ext2, ext3, ext4, vfat or empty if the filesystem was already created and the mkfs process is skipped

Raises:

LVException if the logical volume could not be mounted

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

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

Parameters:

vg_name (str) – name of the volume group
lv_name (str) – name of the logical volume
timeout (int) – timeout between operations

Raises:

LVException if the logical volume is still active

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

Remove a logical volume.

Parameters:

vg_name (str) – name of the volume group
lv_name (str) – name of the logical volume

Raises:

LVException if volume group or logical volume cannot be found

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

Revert the origin logical volume to a snapshot.

Parameters:

vg_name (str) – name of the volume group
lv_name (str) – name of the logical volume
lv_snapshot_name (str) – name of the snapshot to be reverted

Raises:

process.CmdError on failure to revert snapshot

Raises:

LVException if preconditions or execution fails

avocado.utils.lv_utils.lv_revert_with_snapshot(vg_name, lv_name, lv_snapshot_name, lv_snapshot_size)

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

Parameters:

vg_name (str) – name of the volume group
lv_name (str) – name of the logical volume
lv_snapshot_name (str) – name of the snapshot to be reverted
lv_snapshot_size (str) – size of the snapshot

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

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

Parameters:

vg_name (str) – name of the volume group
lv_name (str) – name of the logical volume
lv_snapshot_name (str) – name of the snapshot be to created
lv_snapshot_size (str) – size of the snapshot or None for thin snapshot of an already thin volume
pool_name – name of thin pool or None for regular snapshot or snapshot in the same thin pool like the volume

Raises:

process.CmdError on failure to create snapshot

Raises:

LVException if preconditions fail

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

Unmount a Logical volume from a mount location.

Parameters:

vg_name (str) – name of the volume group
lv_name (str) – name of the logical volume

Raises:

LVException if the logical volume could not be unmounted

avocado.utils.lv_utils.vg_check(vg_name)

Check whether provided volume group exists.

Parameters:: vg_name (str) – name of the volume group
Returns:: whether the volume group was found
Return type:: bool

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

Create a volume group from a list of physical volumes.

Parameters:

vg_name (str) – name of the volume group
pv_list (str or [str]) – list of physical volumes to use
force (bool) – create volume group with a force flag

Raises:

LVException if volume group already exists

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

List all info about available volume groups.

Parameters:: vg_name (str or None) – name of the volume group to list or or None to list all
Returns:: list of available volume groups
Return type:: {str, {str, str}}

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

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

Parameters:

disk (str) – name of the disk in which volume groups are created
vg_name (str) – name of the volume group
ramdisk_vg_size (str) – size of the ramdisk virtual group (MB)
ramdisk_basedir (str) – base directory for the ramdisk sparse file
ramdisk_sparse_filename (str) – name of the ramdisk sparse file
use_tmpfs (bool) – whether to use RAM or slower storage

Returns:

ramdisk_filename, vg_ramdisk_dir, vg_name, loop_device

Return type:

(str, str, str, str)

Raises:

LVException on failure at any stage

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

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

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

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

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

Parameters:

ramdisk_filename (str) – name of the ramdisk sparse file
vg_ramdisk_dir (str) – location of the ramdisk file
vg_name (str) – name of the volume group
loop_device (str) – name of the disk or loop device
use_tmpfs (bool) – whether to use RAM or slower storage

Returns:

ramdisk_filename, vg_ramdisk_dir, vg_name, loop_device

Return type:

(str, str, str, str)

Raises:

LVException on intolerable failure at any stage

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

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

Parameters:

vg_name (str) – name of the volume group
timeout (int) – timeout between operations

Raises:

LVException if the logical volume is still active

avocado.utils.lv_utils.vg_remove(vg_name)

Remove a volume group.

Parameters:: vg_name (str) – name of the volume group
Raises:: LVException if volume group cannot be found

avocado.utils.memory module

exception avocado.utils.memory.MemError

Bases: Exception

called when memory operations fails

class avocado.utils.memory.MemInfo

Bases: object

Representation of /proc/meminfo

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:

dict

avocado.utils.memory.get_huge_page_size()

Get size of the huge pages for this system.

Returns:: Huge pages size (KB).

avocado.utils.memory.get_num_huge_pages()

Get number of huge pages for this system.

Returns:: Number of huge pages.

avocado.utils.memory.get_num_huge_pages_meminfo()

Get number of huge pages for this system from /proc/meminfo file.

Returns:: Number of huge pages.

avocado.utils.memory.get_page_size()

Get linux page size for this system.

:return Kernel page size (Bytes).

avocado.utils.memory.get_supported_huge_pages_size()

Get all supported huge page sizes for this system.

Returns:: list of Huge pages size (kB).

avocado.utils.memory.get_thp_value(feature)

Gets the value of the thp feature arg passed

Param feature:: Thp feature to get value

avocado.utils.memory.hotplug(block)

Online the memory for the given block id.

Parameters:: block – memory block id or or memory198

avocado.utils.memory.hotunplug(block)

Offline the memory for the given block id.

Parameters:: block – memory block id.

avocado.utils.memory.is_hot_pluggable(block)

Check if the given memory block is hotpluggable

Parameters:: block – memory block id.
Returns:: True if hotpluggable, else False
Return type:: ‘bool’

avocado.utils.memory.memtotal(): Read Memtotal from meminfo.

avocado.utils.memory.memtotal_sys()

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

Returns:: system memory in Kb as float

avocado.utils.memory.node_size()

Return node size.

Returns:: Node size.

avocado.utils.memory.numa_nodes()

Get a list of NUMA nodes present on the system.

Returns:: List with nodes.

avocado.utils.memory.numa_nodes_with_memory()

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

Returns:: List with nodes which has memory.

avocado.utils.memory.read_from_meminfo(key)

Retrieve key from meminfo.

Parameters:: key – Key name, such as MemTotal.

avocado.utils.memory.read_from_numa_maps(pid, key)

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

Parameters:

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

Returns:

A dict using the address as the keys

Return type:

dict

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

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

Parameters:

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

Returns:

The value of the item in kb

Return type:

int

avocado.utils.memory.read_from_vmstat(key)

Get specific item value from vmstat

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

avocado.utils.memory.rounded_memtotal()

Get memtotal, properly rounded.

Returns:: Total memory, KB.

avocado.utils.memory.set_num_huge_pages(num)

Set number of huge pages.

Parameters:: num – Target number of huge pages.

avocado.utils.memory.set_thp_value(feature, value)

Sets THP feature to a given value

Parameters:

feature (str) – Thp feature to set
value (str) – Value to be set to feature

avocado.utils.multipath module

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

exception avocado.utils.multipath.MPException

Bases: Exception

Base Exception Class for all exceptions

avocado.utils.multipath.add_mpath(mpath)

Add back the removed mpathX of multipath.

Parameters:: mpath_name – mpath names. Example: mpatha, mpathb.
Returns:: True or False

avocado.utils.multipath.add_path(path)

Add back the removed individual paths.

Parameters:: path (str) – disk path. Example: sda, sdb.
Returns:: True or False

avocado.utils.multipath.device_exists(mpath)

Checks if a given mpath exists.

Parameters:: mpath – The multipath path
Returns:: True if path exists, False if does not exist.
Return type:: bool

avocado.utils.multipath.fail_path(path)

Fail the individual paths.

Parameters:: path (str) – disk path. Example: sda, sdb.
Returns:: True if succeeded, False otherwise
Return type:: bool

avocado.utils.multipath.flush_path(path_name)

Flushes the given multipath.

Returns:: Returns False if command fails, True otherwise.

avocado.utils.multipath.form_conf_mpath_file(blacklist='', defaults_extra='')

Form a multipath configuration file, and restart multipath service.

Parameters:

blacklist – Entry in conf file to indicate blacklist section.
defaults_extra – Extra entry in conf file in defaults section.

avocado.utils.multipath.get_mpath_from_dm(dm_id)

Get the mpath name for given device mapper id

Parameters:: dev_mapper – Input device mapper dm-x
Returns:: mpath name like mpathx
Return type:: str

avocado.utils.multipath.get_mpath_name(wwid)

Get multipath name for a given wwid.

Parameters:: wwid – wwid of multipath device.
Returns:: Name of multipath device.
Return type:: str

avocado.utils.multipath.get_mpath_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:: dict

avocado.utils.multipath.get_multipath_wwid(mpath)

Get the wwid binding for given mpath name

Returns:: Multipath wwid
Return type:: str

avocado.utils.multipath.get_multipath_wwids()

Get list of multipath wwids.

Returns:: List of multipath wwids.
Return type:: list of str

avocado.utils.multipath.get_path_status(disk_path)

Return the status of a path in multipath.

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

avocado.utils.multipath.get_paths(wwid)

Get list of paths, given a multipath wwid.

Returns:: List of paths.
Return type:: list of str

avocado.utils.multipath.get_policy(wwid)

Gets path_checker policy, given a multipath wwid.

Returns:: path checker policy.
Return type:: str

avocado.utils.multipath.get_size(wwid)

Gets size of device, given a multipath wwid.

Returns:: size of multipath device.
Return type:: str

avocado.utils.multipath.get_svc_name(): Gets the multipath service name based on distro.

avocado.utils.multipath.is_mpath_dev(mpath)

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

Returns:: True if device is multipath or False
Return type:: Boolean

avocado.utils.multipath.is_path_a_multipath(disk_path)

Check if given disk path is part of a multipath.

Parameters:: disk_path – disk path. Example: sda, sdb.
Returns:: True if part of multipath, else False.

avocado.utils.multipath.reinstate_path(path)

Reinstate the individual paths.

Parameters:: path (str) – disk path. Example: sda, sdb.
Returns:: True if succeeded, False otherwise

avocado.utils.multipath.remove_mpath(mpath)

Remove the mpathX of multipaths.

Parameters:: mpath_name – mpath names. Example: mpatha, mpathb.
Returns:: True or False

avocado.utils.multipath.remove_path(path)

Remove the individual paths.

Parameters:: disk_path – disk path. Example: sda, sdb.
Returns:: True or False

avocado.utils.multipath.resume_mpath(mpath)

Resume the suspended mpathX of multipaths.

Parameters:: mpath_name – mpath names. Example: mpatha, mpathb.
Returns:: True or False

avocado.utils.multipath.suspend_mpath(mpath)

Suspend the given mpathX of multipaths.

Parameters:: mpath – mpath names. Example: mpatha, mpathb.
Returns:: True or False

avocado.utils.nvme module

Nvme utilities

exception avocado.utils.nvme.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, shared_ns=False)

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, shared_ns=False)

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, shared_ns=False)

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, shared_ns=False)

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, shared_ns=False)

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, shared_ns=False)

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_alternate_controller_name(ctrl)

Fetches other controller in a subsystem based on input controller

Return type:: list

avocado.utils.nvme.get_block_size(controller_name, shared_ns=False)

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_controllers_with_nqn(nqn)

Fetches controllers from subsystem based on input Non-Volatile Memory Express Qualified Name

Return type:: list

avocado.utils.nvme.get_controllers_with_subsys(subsys)

Fetches controllers from nvme subsystem with input as subsystem name

Return type:: list

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

avocado.utils.nvme.get_current_ns_list(controller_name, shared_ns=False)

Returns the list of namespaces in the nvme controller

Parameters:: controller_name – Name of the nvme controller like nvme0, nvme1
Return type:: list

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, shared_ns=False)

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_namespace_absolute_path(namespace)

Returns absolute path for nvme namespace

Return type:: String

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:

list

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

avocado.utils.nvme.get_nvme_subsystem()

Fetches subsystem data and returns dictionary of all subsystems

Return type:: dict

avocado.utils.nvme.get_subsys_name_with_nqn(nqn)

Fetches subsystem name based on input Non-Volatile Memory Express Qualified Name

Return type:: string

avocado.utils.nvme.get_subsystem_using_ctrl_name(ctrl)

Fetches subsystem name with controller name as input

Return type:: string

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 (int) – Minimum (initial) value on the progress bar
maximum (int) – Maximum (final) value on the progress bar
width (int) – Number of columns, that is screen width
title (str) – Optional title to display with the progress bar

Raises:

AssertionError – When maximum is not greater than minimum

append_amount(amount)

Increments the current amount value by the specified amount.

Parameters:: amount (int or float) – The value to add to the current amount

draw()

Prints the updated progress bar text to the screen.

Only prints when the progress bar has changed from the previous state to avoid unnecessary screen updates. Uses carriage return to overwrite the previous progress bar on the same line.

update_amount(amount)

Performs sanity checks and updates the current amount value.

The amount is clamped between the minimum and maximum values set during initialization. After updating the amount, the progress bar is refreshed and redrawn.

Parameters:: amount (int or float) – The new amount value to set

update_percentage(percentage)

Updates the progress bar to the specified percentage value.

Parameters:: percentage (int or float) – The percentage value to set (0-100)

avocado.utils.output.display_data_size(size)

Display data size in human readable units (SI).

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

avocado.utils.partition module

Utility for handling partitions.

class avocado.utils.partition.MtabLock(timeout=60)

Bases: object

device = '/etc/mtab'

class avocado.utils.partition.Partition(device, loop_size=0, mountpoint=None, mkfs_flags='', mount_options=None)

Bases: object

Class for handling partitions and filesystems

Parameters:

device – The device in question (e.g.”/dev/hda2”). If device is a file it will be mounted as loopback.
loop_size – Size of loopback device (in MB). Defaults to 0.
mountpoint – Where the partition to be mounted to.
mkfs_flags – Optional flags for mkfs
mount_options – Add mount options optionally

get_mountpoint(filename=None)

Find the mount point of this partition object.

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

static list_mount_devices(): Lists mounted file systems and swap on devices.

static list_mount_points(): Lists the mount points.

mkfs(fstype=None, args='')

Format a partition to filesystem type

Parameters:

fstype – the filesystem type, such as “ext3”, “ext2”. Defaults to previously set type or “ext2” if none has set.
args – arguments to be passed to mkfs command.

mount(mountpoint=None, fstype=None, args='', mnt_check=True)

Mount this partition to a mount point

Parameters:

mountpoint – If you have not provided a mountpoint to partition object or want to use a different one, you may specify it here.
fstype – Filesystem type. If not provided partition object value will be used.
args – Arguments to be passed to “mount” command.
mnt_check – Flag to check/avoid checking existing device/mountpoint

unmount(force=True, mountpoint=None)

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.

Parameters:

force – Whether to force unmount if the standard unmount fails.
mountpoint – Optional mountpoint to unmount. If not provided, the current mountpoint of the partition object will be used.

Returns:

1 on success, 2 on force umount success

Raises:

PartitionError – On failure

exception avocado.utils.partition.PartitionError(partition, reason, details=None)

Bases: Exception

Generic PartitionError

avocado.utils.path module

Module to handle file and directory paths. It provides functions to manipulate file and directory paths, check permissions, and inspect files.

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

Inspects paths to provide information about them.

Parameters:: path (str) – The path to inspect.

get_first_line()

Reads and returns the first line of the file from path.

Returns:: The first line of the file or an empty string if the file does not exist or is empty.
Return type:: str

has_exec_permission()

Checks if the file from path has execute permissions for the user.

Returns:: True if the file has execute permissions, False otherwise.
Return type:: bool

is_empty()

Checks if the file in path is empty.

Returns:: True if the file is empty, False otherwise.
Return type:: bool

is_python()

Checks if the file in path is a Python script.

Returns:: True if the file is a Python script, False otherwise.
Return type:: bool

is_script(language=None)

Checks if the file in the path is a script, optionally checking for a specific language.

Parameters:: language (str, optional) – The scripting language to check for (e.g., “python”). If None, checks for any shebang.
Returns:: True if the file is a script (and matches the language, if provided), False otherwise.
Return type:: bool

avocado.utils.path.SHEBANG = '#!': The indicator for a script file, usually the first line of the file.

avocado.utils.path.check_readable(path)

Verify that the given path exists and is readable.

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

Parameters:: path (str) – the path to test
Raises:: OSError – path does not exist or path could not be read

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

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

Parameters:

cmd (str) – Command to be found.
default (str or None) – 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.

Raises:

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.

Parameters:: path (str) – the complete filename path. if a non-absolute path is given, it’s transformed into an absolute path first.
Returns:: the maximum length of a file name
Return type:: int

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

Translate a user specified path to a real path.

If user_path is relative, append it to base_path. If user_path is absolute, return it as is.

Parameters:

base_path (type) – The base path of relative user specified paths.
base_path – str
user_path (str) – The user specified path.

Returns:

The resolved path.

Return type:

avocado.utils.path.get_path_mount_point(path)

Returns the mount point for a given file path.

Parameters:: path (str) – the complete filename path. if a non-absolute path is given, it’s transformed into an absolute path first.
Returns:: the mount point for a given file path
Return type:: str

avocado.utils.path.init_dir(*args)

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

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

avocado.utils.path.usable_ro_dir(directory)

Verify whether dir exists and we can access its contents.

Check if a usable RO directory is there.

Parameters:: directory (str) – Directory to check.
Returns:: True if the directory is accessible, False otherwise.
Return type:: bool

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 (str) – Directory to check.
create (bool) – whether to create the directory if it does not exist.

Returns:

True if the directory is usable for rw, False otherwise.

Return type:

avocado.utils.pci module

Module for all PCI devices related functions.

avocado.utils.pci.add_vendor_id(full_pci_address, driver)

Retrieve and add the vendor ID of a PCI device to the specified driver.

Parameters:

full_pci_address – Full PCI device address, including domain (e.g., 0000:03:00.0).
driver – Driver to associate with the vendor ID of the PCI device.

avocado.utils.pci.attach_driver(full_pci_address, driver)

Unbind the device from its existing driver and bind it to the given driver.

Parameters:

full_pci_address – Full PCI device address (e.g., 0000:03:00.0)
driver – Driver to be attached to the specified PCI device

Raises:

ValueError – If driver or full_pci_address is None, or if the driver could not be attached successfully due to an OS error.

Warning:

This function may unbind the device from its current driver, which can temporarily make the device unavailable until it is reattached.

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.check_msix_capability(full_pci_address)

Check whether the PCI device supports Extended Message Signaled Interrupts.

Parameters:: full_pci_address – Full PCI address including domain (0000:03:00.0)
Returns:: True if supported, False otherwise

avocado.utils.pci.device_supports_irqs(full_pci_address, count)

Check if the device supports at least the specified number of interrupts.

Parameters:

full_pci_address – Full PCI device address including domain (e.g., 0000:03:00.0)
count – Number of IRQs the device should support

Returns:

True if supported, False otherwise

avocado.utils.pci.get_cfg(dom_pci_address)

Gets the hardware configuration data of the given PCI address.

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

avocado.utils.pci.get_disks_in_pci_address(pci_address)

Gets disks in a PCI address.

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

avocado.utils.pci.get_domains()

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

Returns:: List of PCI domains.
Return type:: list of str

avocado.utils.pci.get_driver(pci_address)

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

Parameters:: pci_address – Any segment of a PCI address (1f, 0000:00:1f, …)
Returns:: driver of a PCI address.
Return type:: str

avocado.utils.pci.get_interfaces_in_pci_address(pci_address, pci_class)

Gets interface in a PCI address.

e.g: host = pci.get_interfaces_in_pci_address(“0001:01:00.0”, “net”): [‘enP1p1s0f0’] host = pci.get_interfaces_in_pci_address(“0004:01:00.0”, “fc_host”) [‘host6’]

Parameters:

pci_address – Any segment of a PCI address (1f, 0000:00:1f, …)
class – Adapter type (FC(fc_host), FCoE(net), NIC(net), SCSI(scsi)..)

Returns:

list of generic interfaces in a PCI address.

avocado.utils.pci.get_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:: str

avocado.utils.pci.get_memory_address(pci_address)

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

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

avocado.utils.pci.get_nics_in_pci_address(pci_address)

Gets network interface(nic) in a PCI address.

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

avocado.utils.pci.get_num_interfaces_in_pci(dom_pci_address)

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

Parameters:: dom_pci_address – Partial PCI address including domain address (0000, 0000:00:1f, 0000:00:1f.2, etc)
Returns:: number of devices in a PCI domain.
Return type:: int

avocado.utils.pci.get_pci_addresses()

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

Returns:: list of full PCI addresses including domain (0000:00:14.0)
Return type:: list of str

avocado.utils.pci.get_pci_class_name(pci_address)

Gets pci class name for given pci bus address

e.g: >>> pci.get_pci_class_name(“0000:01:00.0”): ‘scsi_host’

Parameters:: pci_address – Any segment of a PCI address(1f, 0000:00:if, …)
Returns:: class name for corresponding pci bus address

avocado.utils.pci.get_pci_fun_list(pci_address)

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

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

avocado.utils.pci.get_pci_id(pci_address)

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

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

avocado.utils.pci.get_pci_id_from_sysfs(full_pci_address)

Gets the PCI ID from sysfs of given PCI address.

Parameters:: full_pci_address – Full PCI address including domain (0000:03:00.0)
Returns:: PCI ID of a PCI address from sysfs.

avocado.utils.pci.get_pci_info(pci_address)

Gets PCI info of given PCI address.

Parameters:: pci_address – Any segment of a PCI address (1f, 0000:00:1f, …)
Returns:: Dictionary attribute name as key and attribute value as value.
Return type:: Dict

avocado.utils.pci.get_pci_prop(pci_address, prop)

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

Parameters:

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

Returns:

specific PCI ID of a PCI address.

Return type:

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

avocado.utils.pci.get_vpd(dom_pci_address)

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

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

avocado.utils.pci.is_accelerator()

Checks if any PCI device is of class ‘accelerator’.

Returns:: True if an accelerator device is found, False otherwise.
Return type:: bool

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

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

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

check_daxctl_subcmd(command): Check if given sub command is supported by daxctl

check_ndctl_subcmd(command): Check if given sub command is supported by ndctl

static check_subcmd(binary, command)

Check if given sub command is supported by binary

Parameters:: command – sub command of ndctl to check for existence
Returns:: True if sub command is available
Return type:: bool

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

Creates namespace with specified options

Parameters:

region – Region on which namespace has to be created
bus – Bus with which namespace has to be created
n_type – Type of namespace to be created [pmem/blk]
mode – Mode of namespace to be created, defaults to fsdax
memmap – Metadata mapping for created namespace
name – Optional name provided for namespace
size – Size with which namespace has to be created
uuid – Optional uuid provided for namespace
sector_size – Sector size with which namespace has to be created
align – Alignment with which namespace has to be created
reconfig – Optionally reconfigure namespace providing existing namespace/region name
force – Force creation of namespace
autolabel – Optionally autolabel the namespace

Returns:

True on success

Raise:

PMemException, if command fails.

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

Destroy namespaces, skipped in case of legacy namespace

Parameters:

namespace – name of the namespace to be destroyed
region – Filter namespace by region
bus – Filter namespace by bus
force – Force a namespace to be destroyed

Returns:

True on Success

Raise:

PMemException, if command fails.

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

Disable namespaces

Parameters:

namespace – name of the namespace to be disabled
region – Filter namespace by region
bus – Filter namespace by bus
verbose – Enable True command with debug information

Returns:

True on success

Raise:

PMemException, if command fails.

disable_region(name='all')

Disable given region

Parameters:: name – name of the region to be disabled
Returns:: True on success
Raise:: PMemException, if command fails.

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

Enable namespaces

Parameters:

namespace – name of the namespace to be enabled
region – Filter namespace by region
bus – Filter namespace by bus
verbose – Enable True command with debug information

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

enable_region(name='all')

Enable given region

Parameters:: name – name of the region to be enabled
Returns:: True on success
Raise:: PMemException, if command fails.

get_slot_count(region)

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

Parameters:: region – Region for which slot count is found
Returns:: Number of slots for given region 0 in case region is not available/command fails
Return type:: int

static is_region_legacy(region)

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

Parameters:: region – Region for which legacy check is made
Returns:: True if given region is legacy, else False

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

Read an infoblock from the specified medium

Parameters:

namespace – Read the infoblock from given namespace
inp_file – Input file to read the infoblock from
kwargs

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

Returns:: By default return list of json objects, if json_form is True Return as raw data, if json_form is False Return file path if op_file is specified
Raise:: PMemException, if command fails.

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

Reconfigure devdax device into devdax or system-ram mode

Parameters:

device – Device from which memory is to be online
mode – Mode with which device is to be configured, default:devdax
region – Optionally filter device by region
no_online – Optionally don’t online the memory(only system-ram)
no_movable – Optionally mark memory non-movable(only system-ram)

Returns:

Property of configured device

Return type:

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:: bool
Raise:: PMemException, if command fails.

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

Bases: Exception

Error raised for all PMem failures

avocado.utils.podman module

This module provides an basic API for interacting with podman.

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

class avocado.utils.podman.AsyncPodman(podman_bin=None)

Bases: _Podman

async collect_container_aiu_metrics(container_id, output_file, dtcompiler_export_dir=None, stats_command='aiu-smi --csv', timeout=None)

Start collecting AIU metrics from a container in the background using nohup.

This method runs a podman exec command in the background to continuously collect AIU metrics from a running container.

Parameters:

container_id (str) – Container identification string.
output_file (str) – Path to output file where stats will be saved (e.g., /path/to/aiu_metrics.csv).
dtcompiler_export_dir (str) – Optional DTCOMPILER_EXPORT_DIR environment variable value.
stats_command (str) – Command to run inside container for collecting stats (default: “aiu-smi –csv”).
timeout (int) – Optional timeout in seconds. If specified, stats collection will automatically stop after this duration. If None, collection runs indefinitely.

Returns:

Process object for the background process.

Return type:

subprocess.Popen

async collect_container_stats(container_id, output_dir, interval=1, duration=60)

Collect Podman CPU and memory stats and write as JSON.

This method periodically collects container statistics (CPU and memory usage) and saves them to a JSON file for analysis. Supports collecting stats for a specific container or all running containers.

Parameters:

container_id (str) – Container identification string or “all” for all containers.
output_dir (str) – Base directory where stats JSON files will be saved. Container-specific subdirectories will be created.
interval (int) – Interval in seconds between stat collections (default: 1).
duration (int) – Total duration in seconds to collect stats (default: 60).

Returns:

Path to the generated JSON stats file (or list of paths if container_id=”all”).

Return type:

str or list

async copy_to_container(container_id, src, dst)

Copy artifacts from src to container:dst.

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

Parameters:

container_id (str) – string with the container identification.
src (str) – what file or directory you are trying to copy.
dst (str) – the destination inside the container.

Return type:

tuple with returncode, stdout and stderr.

async exec_command(container_id, command, user=None, workdir=None, env=None, interactive=False, tty=False)

Execute a command in a running container.

Parameters:

container_id (str) – Container identification string.
command (str or list) – Command to execute. Can be a string or list of arguments.
user (str) – Optional user to run the command as (e.g., “root”, “1000”, “1000:1000”).
workdir (str) – Optional working directory for the command.
env (dict) – Optional dictionary of environment variables to set.
interactive (bool) – Keep STDIN open even if not attached (default: False).
tty (bool) – Allocate a pseudo-TTY (default: False).

Return type:

tuple with returncode, stdout and stderr.

async execute(*args)

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

Parameters:: args – Variable length argument list to be used as argument during execution.
Return type:: tuple with returncode, stdout and stderr.

async get_container_info(container_id)

Return all information about specific container.

Parameters:: container_id (str) – identifier of container
Return type:: dict

async get_multiple_container_logs(container_ids, tail=None)

Get logs from multiple containers concurrently.

Parameters:

container_ids (list) – List of container IDs.
tail (int) – Number of lines to show from the end of the logs.

Return type:

list of tuples (container_id, returncode, stdout, stderr).

async get_python_version(image)

Return the current Python version installed in an image.

Parameters:: image (str) – Image name. i.e: ‘fedora:33’.
Return type:: tuple with both: major, minor numbers and executable path.

async inspect(container_id)

Inspect a container and return detailed information.

Parameters:: container_id (str) – Container identification string.
Return type:: tuple with returncode, stdout (JSON), stderr.

async list_containers(all_containers=True)

List containers.

Parameters:: all_containers (bool) – If True, list all containers including stopped ones.
Return type:: tuple with returncode, stdout (JSON list), stderr.

async login(registry, username=None, password=None, api_key=None, api_key_username='iamapikey', password_stdin=False)

Login to a container registry.

Parameters:

registry (str) – Registry URL.
username (str) – Username for authentication (optional if using API key).
password (str) – Password for authentication (optional if using API key).
api_key (str) – API key for authentication (alternative to username/password).
api_key_username (str) – Username to use with API key authentication (default: “iamapikey” for IBM Cloud). Other registries may use different conventions (e.g., “oauth2accesstoken” for GCR).
password_stdin (bool) – If True, read password from stdin.

Return type:

tuple with returncode, stdout, stderr.

async logs(container_id, follow=False, tail=None)

Get container logs.

Parameters:

container_id (str) – Container identification string.
follow (bool) – If True, follow log output.
tail (int) – Number of lines to show from the end of the logs.

Return type:

tuple with returncode, stdout, stderr.

async pull(image)

Pull an image from a registry.

Parameters:: image (str) – Image name to pull.
Return type:: tuple with returncode, stdout, stderr.

async remove(container_id, force=False)

Remove a container.

Parameters:

container_id (str) – Container identification string.
force (bool) – If True, force removal of running container.

Return type:

tuple with returncode, stdout, stderr.

async remove_multiple_containers(container_ids, force=False)

Remove multiple containers concurrently.

Parameters:

container_ids (list) – List of container IDs to remove.
force (bool) – If True, force removal of running containers.

Return type:

list of tuples (container_id, returncode, stdout, stderr).

async restart(container_id, timeout=10)

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

Parameters:

container_id (str) – Container identification string to restart.
timeout (int) – Timeout in seconds to wait for container to stop before killing it (default: 10).

Return type:

tuple with returncode, stdout and stderr.

async run_multiple_vllm_containers(num_containers, image, aiu_ids_list, host_models_dir, vllm_model_path, aiu_world_size, max_model_len, max_batch_size, memory='100G', shm_size='2G', device='/dev/vfio', privileged='true', pids_limit='0', userns='keep-id', group_add='keep-groups', port_mapping='127.0.0.1::8000', vllm_spyre_use_cb='1', vllm_dt_chunk_len=None, vllm_spyre_use_chunked_prefill=None, enable_prefix_caching=True, additional_vllm_args=None, container_name_prefix='vllm-container')

Run multiple VLLM containers concurrently with different AIU IDs.

Parameters:

num_containers (int) – Number of containers to create.
image (str) – Container image to run.
aiu_ids_list (list) – List of AIU PCIe IDs for each container. Must provide exactly num_containers AIU ID sets.
host_models_dir (str) – Host directory containing models.
vllm_model_path (str) – Path to model inside container.
aiu_world_size (int) – AIU world size (tensor parallelism).
max_model_len (int) – Maximum model length.
max_batch_size (int) – Maximum batch size.
memory (str) – Memory limit (default: “100G”).
shm_size (str) – Shared memory size (default: “2G”).
device (str) – Device to mount (default: “/dev/vfio”).
privileged (str) – Run in privileged mode (default: “true”).
pids_limit (str) – PIDs limit (default: “0”).
userns (str) – User namespace mode (default: “keep-id”).
group_add (str) – Group add mode (default: “keep-groups”).
port_mapping (str) – Port mapping (default: “127.0.0.1::8000”).
vllm_spyre_use_cb (str) – Use CB flag (default: “1”).
vllm_dt_chunk_len (int) – Optional DT chunk length.
vllm_spyre_use_chunked_prefill (int) – Optional chunked prefill flag.
enable_prefix_caching (bool) – Enable VLLM prefix caching (default: True).
additional_vllm_args (list) – Additional VLLM command-line arguments as list of strings.
container_name_prefix (str) – Prefix for container names.

Return type:

list of tuples (container_name, returncode, stdout, stderr).

async run_vllm_container(image, aiu_ids, host_models_dir, vllm_model_path, aiu_world_size, max_model_len, max_batch_size, memory='100G', shm_size='2G', device='/dev/vfio', privileged='true', pids_limit='0', userns='keep-id', group_add='keep-groups', port_mapping='127.0.0.1::8000', vllm_spyre_use_cb='1', vllm_dt_chunk_len=None, vllm_spyre_use_chunked_prefill=None, enable_prefix_caching=True, additional_vllm_args=None, container_name=None)

Run a VLLM container with AIU support.

Parameters:

image (str) – Container image to run.
aiu_ids (str) – Space-separated AIU PCIe IDs.
host_models_dir (str) – Host directory containing models.
vllm_model_path (str) – Path to model inside container.
aiu_world_size (int) – AIU world size (tensor parallelism).
max_model_len (int) – Maximum model length.
max_batch_size (int) – Maximum batch size.
memory (str) – Memory limit (default: “100G” - adjust based on model size).
shm_size (str) – Shared memory size (default: “2G” - increase for larger batches).
device (str) – Device to mount (default: “/dev/vfio”).
privileged (str) – Run in privileged mode (default: “true”).
pids_limit (str) – PIDs limit (default: “0” - unlimited).
userns (str) – User namespace mode (default: “keep-id”).
group_add (str) – Group add mode (default: “keep-groups”).
port_mapping (str) – Port mapping in format [host_ip]:[host_port]:container_port (default: "127.0.0.1::8000" - localhost with random host port to container port 8000). Examples: "127.0.0.1:8000:8000" (fixed host port 8000), "0.0.0.0::8000" (all interfaces, random host port), "::8000" (all interfaces, random host port).
vllm_spyre_use_cb (str) – Use CB flag (default: “1”).
vllm_dt_chunk_len (int) – Optional DT chunk length.
vllm_spyre_use_chunked_prefill (int) – Optional chunked prefill flag.
enable_prefix_caching (bool) – Enable VLLM prefix caching (default: True).
additional_vllm_args (list) – Additional VLLM command-line arguments as list of strings.
container_name (str) – Optional container name.

Return type:

tuple with returncode, stdout (container ID), stderr.

async send_vllm_inference_request(port, model_path, prompt, max_tokens=512, temperature=1.0, system_message='You are a helpful AI assistant.', host='127.0.0.1', use_jq=True)

Send an inference request to VLLM server using curl.

This method sends a chat completion request to a running VLLM container and returns the response.

Parameters:

port (int) – Port number where VLLM server is listening.
model_path (str) – Model path as configured in VLLM (e.g., “/models/granite-3.3-8b-instruct”).
prompt (str) – User prompt/query to send to the model.
max_tokens (int) – Maximum number of tokens to generate (default: 512).
temperature (float) – Sampling temperature (default: 1.0).
system_message (str) – System message to set context (default: “You are a helpful AI assistant.”).
host (str) – Host address (default: “127.0.0.1”).
use_jq (bool) – Whether to pipe output through jq for formatting (default: True).

Returns:

Tuple of (returncode, response_text, error_text).

Return type:

tuple

async start(container_id)

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

Parameters:: container_id (str) – Container identification string to start.
Return type:: tuple with returncode, stdout and stderr.

async start_multiple_containers(container_ids)

Start multiple containers concurrently.

Parameters:: container_ids (list) – List of container IDs to start.
Return type:: list of tuples (container_id, returncode, stdout, stderr).

async stats(container_id, no_stream=True)

Get container resource usage statistics.

Parameters:

container_id (str) – Container identification string.
no_stream (bool) – If True, output stats once and exit.

Return type:

tuple with returncode, stdout, stderr.

async stop(container_id)

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

Parameters:: container_id (str) – Container identification string to stop.
Return type:: tuple with returncode, stdout and stderr.

async stop_multiple_containers(container_ids)

Stop multiple containers concurrently.

Parameters:: container_ids (list) – List of container IDs to stop.
Return type:: list of tuples (container_id, returncode, stdout, stderr).

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

Bases: _Podman

collect_container_aiu_metrics(container_id, output_file, dtcompiler_export_dir=None, stats_command='aiu-smi --csv', timeout=None)

Start collecting AIU metrics from a container in the background using nohup.

This method runs a podman exec command in the background to continuously collect AIU metrics from a running container.

Parameters:

container_id (str) – Container identification string.
output_file (str) – Path to output file where stats will be saved (e.g., /path/to/aiu_metrics.csv).
dtcompiler_export_dir (str) – Optional DTCOMPILER_EXPORT_DIR environment variable value.
stats_command (str) – Command to run inside container for collecting stats (default: “aiu-smi –csv”).
timeout (int) – Optional timeout in seconds. If specified, stats collection will automatically stop after this duration. If None, collection runs indefinitely.

Returns:

Process object for the background process.

Return type:

subprocess.Popen

collect_container_stats(container_id, output_dir, interval=1, duration=60)

Collect Podman CPU and memory stats and write as JSON.

This method periodically collects container statistics (CPU and memory usage) and saves them to a JSON file for analysis. Supports collecting stats for a specific container or all running containers.

Parameters:

container_id (str) – Container identification string or “all” for all containers.
output_dir (str) – Base directory where stats JSON files will be saved. Container-specific subdirectories will be created.
interval (int) – Interval in seconds between stat collections (default: 1).
duration (int) – Total duration in seconds to collect stats (default: 60).

Returns:

Path to the generated JSON stats file (or list of paths if container_id=”all”).

Return type:

str or list

copy_to_container(container_id, src, dst)

Copy artifacts from src to container:dst.

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

Parameters:

container_id (str) – string with the container identification.
src (str) – what file or directory you are trying to copy.
dst (str) – the destination inside the container.

Return type:

tuple with returncode, stdout and stderr.

exec_command(container_id, command, user=None, workdir=None, env=None, interactive=False, tty=False)

Execute a command in a running container.

Parameters:

container_id (str) – Container identification string.
command (str or list) – Command to execute. Can be a string or list of arguments.
user (str) – Optional user to run the command as (e.g., “root”, “1000”, “1000:1000”).
workdir (str) – Optional working directory for the command.
env (dict) – Optional dictionary of environment variables to set.
interactive (bool) – Keep STDIN open even if not attached (default: False).
tty (bool) – Allocate a pseudo-TTY (default: False).

Return type:

tuple with returncode, stdout and stderr.

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.

Parameters:: container_id (str) – identifier of container
Return type:: dict

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.

inspect(container_id)

Inspect a container and return detailed information.

Parameters:: container_id (str) – Container identification string.
Return type:: tuple with returncode, stdout (JSON), stderr.

list_containers(all_containers=True)

List containers.

Parameters:: all_containers (bool) – If True, list all containers including stopped ones.
Return type:: tuple with returncode, stdout (JSON list), stderr.

login(registry, username=None, password=None, api_key=None, api_key_username='iamapikey', password_stdin=False)

Login to a container registry.

Parameters:

registry (str) – Registry URL.
username (str) – Username for authentication (optional if using API key).
password (str) – Password for authentication (optional if using API key).
api_key (str) – API key for authentication (alternative to username/password).
api_key_username (str) – Username to use with API key authentication (default: “iamapikey” for IBM Cloud). Other registries may use different conventions (e.g., “oauth2accesstoken” for GCR).
password_stdin (bool) – If True, read password from stdin.

Return type:

tuple with returncode, stdout, stderr.

logs(container_id, follow=False, tail=None)

Get container logs.

Parameters:

container_id (str) – Container identification string.
follow (bool) – If True, follow log output.
tail (int) – Number of lines to show from the end of the logs.

Return type:

tuple with returncode, stdout, stderr.

pull(image)

Pull an image from a registry.

Parameters:: image (str) – Image name to pull.
Return type:: tuple with returncode, stdout, stderr.

remove(container_id, force=False)

Remove a container.

Parameters:

container_id (str) – Container identification string.
force (bool) – If True, force removal of running container.

Return type:

tuple with returncode, stdout, stderr.

restart(container_id, timeout=10)

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

Parameters:

container_id (str) – Container identification string to restart.
timeout (int) – Timeout in seconds to wait for container to stop before killing it (default: 10).

Return type:

tuple with returncode, stdout and stderr.

run_vllm_container(image, aiu_ids, host_models_dir, vllm_model_path, aiu_world_size, max_model_len, max_batch_size, memory='100G', shm_size='2G', device='/dev/vfio', privileged='true', pids_limit='0', userns='keep-id', group_add='keep-groups', port_mapping='127.0.0.1::8000', vllm_spyre_use_cb=None, vllm_dt_chunk_len=None, vllm_spyre_use_chunked_prefill=None, enable_prefix_caching=None, max_num_batched_tokens=None, additional_vllm_args=None, container_name=None, user=None, dtlog_level=None, dtcompiler_keep_export=None, vllm_spyre_require_precompiled_decoders=None, enable_flex_timing=None, flex_print_end_to_end_breakdown=None, flex_skip_timestamp_calibration=None, flex_scheduler_print_raw_timestamps=None, flex_global_profile_prefix=None)

Run a VLLM container with AIU support.

Parameters:

image (str) – Container image to run.
aiu_ids (str) – Space-separated AIU PCIe IDs.
host_models_dir (str) – Host directory containing models.
vllm_model_path (str) – Path to model inside container.
aiu_world_size (int) – AIU world size (tensor parallelism).
max_model_len (int) – Maximum model length.
max_batch_size (int) – Maximum batch size.
memory (str) – Memory limit (default: “100G” - adjust based on model size).
shm_size (str) – Shared memory size (default: “2G” - increase for larger batches).
device (str) – Device to mount (default: “/dev/vfio”).
privileged (str) – Run in privileged mode (default: “true”).
pids_limit (str) – PIDs limit (default: “0” - unlimited).
userns (str) – User namespace mode (default: “keep-id”).
group_add (str) – Group add mode (default: “keep-groups”).
port_mapping (str) – Port mapping in format [host_ip]:[host_port]:container_port (default: "127.0.0.1::8000" - localhost with random host port to container port 8000). Examples: "127.0.0.1:8000:8000" (fixed host port 8000), "0.0.0.0::8000" (all interfaces, random host port), "::8000" (all interfaces, random host port).
vllm_spyre_use_cb (str) – Optional VLLM Spyre use CB flag (e.g., “1”). If None, not set.
vllm_dt_chunk_len (int) – Optional DT chunk length. If None, not set.
vllm_spyre_use_chunked_prefill (int) – Optional chunked prefill flag. If None, not set.
enable_prefix_caching (bool) – Optional enable VLLM prefix caching. If None, not set.
max_num_batched_tokens (int) – Optional maximum number of batched tokens. If None, not set.
additional_vllm_args (list) – Additional VLLM command-line arguments as list of strings.
container_name (str) – Optional container name.
user (str) – Optional user to run container as (e.g., “1000:1000”).
dtlog_level (str) – Optional DT log level (e.g., “warning”). If None, not set.
dtcompiler_keep_export (str) – Optional DT compiler keep export flag (e.g., “true”). If None, not set.
vllm_spyre_require_precompiled_decoders (str) – Optional require precompiled decoders flag (e.g., “0”). If None, not set.
enable_flex_timing (str) – Optional enable flex timing flag (e.g., “0”). If None, not set.
flex_print_end_to_end_breakdown (str) – Optional flex print end-to-end breakdown flag (e.g., “0”). If None, not set.
flex_skip_timestamp_calibration (str) – Optional flex skip timestamp calibration flag (e.g., “0”). If None, not set.
flex_scheduler_print_raw_timestamps (str) – Optional flex scheduler print raw timestamps flag (e.g., “0”). If None, not set.
flex_global_profile_prefix (str) – Optional flex global profile prefix (e.g., “flex-logs”). If None, not set.

Return type:

tuple with returncode, stdout (container ID), stderr.

send_vllm_inference_request(port, model_path, prompt, max_tokens=512, temperature=1.0, system_message='You are a helpful AI assistant.', host='127.0.0.1', use_jq=True)

Send an inference request to VLLM server using curl.

This method sends a chat completion request to a running VLLM container and returns the response.

Parameters:

port (int) – Port number where VLLM server is listening.
model_path (str) – Model path as configured in VLLM (e.g., “/models/granite-3.3-8b-instruct”).
prompt (str) – User prompt/query to send to the model.
max_tokens (int) – Maximum number of tokens to generate (default: 512).
temperature (float) – Sampling temperature (default: 1.0).
system_message (str) – System message to set context (default: “You are a helpful AI assistant.”).
host (str) – Host address (default: “127.0.0.1”).
use_jq (bool) – Whether to pipe output through jq for formatting (default: True).

Returns:

Tuple of (returncode, response_text, error_text).

Return type:

tuple

start(container_id)

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

Parameters:: container_id (str) – Container identification string to start.
Return type:: tuple with returncode, stdout and stderr.

stats(container_id, no_stream=True)

Get container resource usage statistics.

Parameters:

container_id (str) – Container identification string.
no_stream (bool) – If True, output stats once and exit.

Return type:

tuple with returncode, stdout, stderr.

stop(container_id)

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

Parameters:: container_id (str) – Container identification string to stop.
Return type:: tuple with returncode, stdout and stderr.

exception avocado.utils.podman.PodmanException: Bases: Exception

avocado.utils.podman.download_model_from_hf(hf_model_id, local_dir, model_name)

Download a model from Hugging Face Hub.

Parameters:

hf_model_id – Hugging Face model ID (e.g., ‘ibm-granite/granite-3.3-8b-instruct’)
local_dir – Local directory to download the model
model_name – Local model directory name

Returns:

True if download successful, False otherwise

avocado.utils.podman.install_huggingface_cli()

Install Hugging Face CLI if not already installed.

Returns:: True if installed successfully, False otherwise

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 raised when a command fails execution.

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

Return stderr decoded as text.

Returns:: The stderr content as a string.
Return type:: str
Raises:: TypeError – If stderr cannot be decoded.

stdout: The raw stdout (bytes)

property stdout_text

Return stdout decoded as text.

Returns:: The stdout content as a string.
Return type:: str
Raises:: TypeError – If stdout cannot be decoded.

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.

Initialize FDDrainer to read from a file descriptor in a thread.

Stores data locally in a file-like data object.

Parameters:

fd (int) – a file descriptor that will be read (drained) from
result (CmdResult) – a CmdResult instance associated with the process used to detect if the process is still running and if there’s still data to be read.
name (str) – a descriptive name that will be passed to the Thread name
logger (logging.Logger) – the logger that will be used to (interactively) write the content from the file descriptor
logger_prefix (str) – the prefix used when logging the data
stream_logger (logging.Logger) – a logger for streaming output
ignore_bg_processes (bool) – 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 (bool) – whether to log in both the logger and stream_logger

flush(): Wait for drainer thread to complete and flush stream handlers.

start(): Start the drainer thread to read from the file descriptor.

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.

Create 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 (bool) – 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()

Report PID of this process.

Returns:: Process ID.
Return type:: int

get_stderr()

Get the full stderr of the subprocess so far.

Returns:: Standard error of the process.
Return type:: bytes

get_stdout()

Get the full stdout of the subprocess so far.

Returns:: Standard output of the process.
Return type:: bytes

get_user_id()

Report user id of this process.

Returns:: User ID of the process owner.
Return type:: int or None

is_sudo_enabled()

Return whether the subprocess is running with sudo enabled.

Returns:: True if running as root (UID 0), False otherwise.
Return type:: bool

kill()

Send a signal.SIGKILL to the process.

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

poll()

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

Returns:: Return code if process has finished, None otherwise.
Return type:: int or 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 or None) – Time (seconds) we’ll wait until the process is finished. If it’s not, we’ll try to terminate it and its 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:

CmdResult

send_signal(sig)

Send the specified signal to the process.

Parameters:: sig (int) – Signal to send.

start()

Start running the subprocess.

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

Returns:: Subprocess PID.
Return type:: int

stop(timeout=None)

Stop background subprocess.

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

Parameters:: timeout (float or None) – Time (seconds) we’ll wait until the process is finished. If it’s not, we’ll try to terminate it and its 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).
Returns:: Exit status of the process.
Return type:: int

terminate()

Send a signal.SIGTERM to the process.

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

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

Wait for subprocess to complete, fill results when done.

Parameters:

timeout (float or None) – 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:

Exit status of the process.

Return type:

int

Raises:

AssertionError – If the process becomes a zombie.

avocado.utils.process.binary_from_shell_cmd(cmd)

Extract the first binary path from a shell-like command string.

This function parses a shell command and returns the first binary/executable found, skipping environment variable assignments.

Note

This is a naive implementation that handles common patterns like environment variable assignments before the binary name.

Parameters:: cmd (str) – A shell-like command string to parse.
Returns:: The first binary/executable found in the command.
Return type:: str
Raises:: ValueError – If no binary can be extracted from the command.

Example:

>>> binary_from_shell_cmd("binary")
'binary'
>>> binary_from_shell_cmd("VAR=VAL binary -args")
'binary'
>>> binary_from_shell_cmd("FOO=bar ./script.py")
'./script.py'

avocado.utils.process.can_sudo(cmd=None)

Check whether sudo is available or if running as root.

This function checks if the current process has the ability to run commands with elevated privileges. It first checks if the process is running as root (UID 0), then checks if sudo is installed and functional.

Parameters:: cmd (str or None) – Optional command to test sudo capabilities with. If provided, tests whether this specific command can be run with sudo. If not provided, tests basic sudo functionality.
Returns:: True if sudo is available or running as root, False otherwise.
Return type:: bool

Example:

>>> can_sudo()
True
>>> can_sudo("ls /root")
True

avocado.utils.process.cmd_split(s, comments=False, posix=True): This is kept for compatibility purposes, but is now deprecated and will be removed in later versions. Please use shlex.split() instead.

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

Gets a list of all capabilities for a process.

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

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

Parameters:: pid (int) – the process ID (PID), if one is not given, the current PID is used (given by os.getpid())
Returns:: all capabilities
Return type:: list

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

Get the list of child process IDs for a given parent process.

This function scans the /proc filesystem to find all child processes of the specified parent PID.

Note

This is currently Linux specific.

Parameters:

parent_pid (int) – The PID of the parent process.
recursive (bool) – If True, also returns grandchildren and all descendants. If False, only returns direct children.

Returns:

List of child process IDs.

Return type:

list of int

Example:

>>> get_children_pids(1)
[234, 456, 789]
>>> get_children_pids(1, recursive=True)
[234, 456, 789, 1011, 1213]

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

Run a command and return lines matching a pattern.

This function executes a command and searches its output for lines containing the specified pattern, returning all matching lines.

Parameters:

command (str) – The command to execute.
pattern (str) – Pattern to search for in the output. Matching is done on a line-by-line basis using substring matching.

Returns:

List of lines from the command output that contain the pattern.

Return type:

list of str

Example:

>>> get_command_output_matching("ls -la", "txt")
['file1.txt', 'file2.txt']

avocado.utils.process.get_owner_id(pid)

Get the user ID of the process owner.

This function reads the /proc filesystem to determine the user ID that owns the specified process.

Note

This is currently Linux specific.

Parameters:: pid (int) – The process ID to query.
Returns:: The user ID of the process owner, or None if not found.
Return type:: int or None

Example:

>>> get_owner_id(1)
0
>>> get_owner_id(999999)
None

avocado.utils.process.get_parent_pid(pid)

Get the parent process ID for a given process.

This function reads the /proc filesystem to determine the parent PID.

Note

This is currently Linux specific.

Parameters:: pid (int) – The PID of the child process.
Returns:: The parent process ID.
Return type:: int
Raises:: IOError – If the /proc entry cannot be read.

Example:

>>> get_parent_pid(1234)
1

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

Return output (stdout or stderr) of executing cmd in a shell.

Because commands module is removed in Python3 and it redirect stderr to stdout, we port commands.getoutput to make code compatible.

Parameters:

cmd (str) – Command line to run.
timeout (float or None) – 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 (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)

Return (status, output) of executing cmd in a shell.

Because commands module is removed in Python3 and it redirect stderr to stdout, we port commands.getstatusoutput to make code compatible.

Parameters:

cmd (str) – Command line to run.
timeout (float or None) – 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 (bool) – Whether the command requires admin privileges to run, so that sudo will be prepended to the command. The assumption here is that the user running the command has a sudo configuration such that a password won’t be prompted. If that’s not the case, the command will straight out fail.
ignore_bg_processes (bool) – Whether to ignore background processes.
logger (logging.Logger) – User’s custom logger, which will be logging the subprocess outputs. When this parameter is not set, the avocado.utils.process logger will be used.

Returns:

Exit status and command output (stdout and stderr).

Return type:

tuple

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

Check if a process has a given Linux capability.

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

Parameters:

capability (str) – The name of the capability (e.g., “cap_sys_admin”). Refer to capabilities(7) man page for more information. Note: capability names are UPPERCASE in capabilities(7) (e.g., CAP_SYS_ADMIN) but must be lowercase in Python (e.g., “cap_sys_admin”).
pid (int or None) – The process ID to check. If None, checks the current process.

Returns:

True if the capability is available, False otherwise.

Return type:

Example:

>>> has_capability("cap_chown")
True
>>> has_capability("cap_sys_admin", pid=1234)
False

avocado.utils.process.kill_process_by_pattern(pattern)

Send SIGTERM signal to processes matching a pattern.

This function uses the pkill command to terminate processes whose command line matches the given pattern.

Parameters:: pattern (str) – Pattern to match against process command lines. This is matched using pkill’s -f flag, which matches against the full command line.

Example:

>>> kill_process_by_pattern("firefox")
>>> kill_process_by_pattern("python.*test_script")

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 (int) – The pid of the process to signal.
sig (int or None) – The signal to send to the processes, defaults to signal.SIGKILL
send_sigcont (bool) – Send SIGCONT to allow killing stopped processes.
timeout (int or float) – How long to wait for the pid(s) to die (negative=infinity, 0=don’t wait, positive=number_of_seconds).

Returns:

List of all PIDs we sent signal to.

Return type:

list

Raises:

RuntimeError – If timeout is reached waiting for processes to die.

avocado.utils.process.pid_exists(pid)

Check if a process with the given PID exists.

This function uses os.kill with signal 0 to check if a process exists without actually sending a signal to it.

Parameters:: pid (int) – The process ID number to check.
Returns:: True if the process exists, False otherwise.
Return type:: bool

Example:

>>> pid_exists(1)
True
>>> pid_exists(999999)
False

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 (int) – The parent PID of the process to verify.
Returns:: True if any process in the tree is defunct, False otherwise.
Return type:: bool

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 or None) – 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 (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.
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:

A CmdResult object.

Return type:

CmdResult

Raises:

CmdInputError – If the command is empty.
CmdError – If ignore_status=False and command fails.

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

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

This function safely sends a signal to a process, handling cases where the process might not exist or require elevated privileges.

Parameters:

pid (int) – The process ID to send the signal to.
signal (int) – The signal number to send (e.g., signal.SIGTERM).

Returns:

True if signal was sent successfully, False otherwise.

Return type:

Example:

>>> safe_kill(1234, signal.SIGTERM)
True

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 or None) – 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 (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.
encoding (str) – the encoding to use for the text representation of the command result stdout and stderr, by default avocado.utils.astring.ENCODING
logger (logging.Logger) – User’s custom logger, which will be logging the subprocess outputs. When this parameter is not set, the avocado.utils.process logger will be used.

Returns:

Exit code.

Return type:

int

Raises:

CmdError – If ignore_status=False and command fails.

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 or None) – 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 (bool) – Whether the command requires admin privileges to run, so that sudo will be prepended to the command. The assumption here is that the user running the command has a sudo configuration such that a password won’t be prompted. If that’s not the case, the command will straight out fail.
ignore_bg_processes (bool) – Whether to ignore background processes.
strip_trail_nl (bool) – Whether to strip the trailing newline.
encoding (str) – the encoding to use for the text representation of the command result stdout and stderr, by default avocado.utils.astring.ENCODING
logger (logging.Logger) – User’s custom logger, which will be logging the subprocess outputs. When this parameter is not set, the avocado.utils.process logger will be used.

Returns:

Command output.

Return type:

bytes

Raises:

CmdError – If ignore_status=False and command fails.

avocado.utils.script module

Module to handle script file creation and management.

This module provides utilities for creating executable script files, both permanent and temporary, with proper file permissions and automatic cleanup capabilities.

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

This class provides methods to create, save, and remove script files with configurable permissions. It supports context manager protocol for automatic cleanup.

Creates an instance of Script.

When used as a context manager, the script is automatically saved on entry and removed on exit.

Parameters:

path (str) – The path where the script file will be created.
content (str or bytes) – The content to write to the script file.
mode (int) – File permissions mode. Defaults to 0775 (rwxrwxr-x).
open_mode (str) – File open mode (‘w’ for text, ‘wb’ for binary).

remove()

Remove script file from the file system.

Returns:: True if the script file was removed, False if it did not exist.
Return type:: bool

save()

Store script content to the file system.

Creates parent directories if they do not exist and sets the specified file permissions.

Returns:: True if script has been stored successfully.
Return type:: bool

class avocado.utils.script.TemporaryScript(name, content, prefix='avocado_script', mode=509, open_mode='w')

Bases: Script

Class that represents a temporary script in an auto-managed directory.

The script is created in a temporary directory that is automatically cleaned up when the instance is garbage collected or when used as a context manager.

Creates an instance of TemporaryScript.

The script is created in a newly created temporary directory. When used as a context manager, both the script and its directory are automatically removed on exit. The directory is also removed when the object is garbage collected.

Parameters:

name (str) – The script filename (not the full path).
content (str or bytes) – The content to write to the script file.
prefix (str) – Prefix for the temporary directory name.
mode (int) – File permissions mode. Defaults to 0775 (rwxrwxr-x).
open_mode (str) – File open mode (‘w’ for text, ‘wb’ for binary).

remove()

Remove script file from the file system.

Returns:: True if the script file was removed, False if it did not exist.
Return type:: bool

avocado.utils.script.make_script(path, content, mode=509)

Creates and saves a new script file to the file system.

This is a convenience function that creates a Script instance, saves it, and returns the path.

Parameters:

path (str) – The path where the script file will be created.
content (str or bytes) – The content to write to the script file.
mode (int) – File permissions mode. Defaults to 0775 (rwxrwxr-x).

Returns:

The path to the created script file.

Return type:

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

Creates and saves a new temporary script in a temporary directory.

This is a convenience function that creates a TemporaryScript instance and saves it. Note that the script’s temporary directory will be removed when the TemporaryScript object is garbage collected.

Parameters:

name (str) – The script filename (not the full path).
content (str or bytes) – The content to write to the script file.
prefix (str) – Prefix for the temporary directory name.
mode (int) – File permissions mode. Defaults to 0775 (rwxrwxr-x).

Returns:

The full path to the created script file.

Return type:

avocado.utils.service module

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

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

Example of use:

# Get the system service manager
service_manager = ServiceManager()

# Stating service/unit "sshd"
service_manager.start("sshd")

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

# Disabling and stopping a list of services
services_to_disable = ['ntpd', 'httpd']

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

Returns:: SysVInitServiceManager or SystemdServiceManager
Return type:: _GenericServiceManager

avocado.utils.service.SpecificServiceManager(service_name, run=<function run>)

Get the service manager for a specific service.

Example of use:

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

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

avocado.utils.service.convert_systemd_target_to_runlevel(target)

Convert systemd target to runlevel.

Parameters:: target (str) – systemd target
Returns:: sys_v runlevel
Return type:: str
Raises:: ValueError – when systemd target is unknown

avocado.utils.service.convert_sysv_runlevel(level)

Convert runlevel to systemd target.

Parameters:: level (str or int) – sys_v runlevel
Returns:: systemd target
Return type:: str
Raises:: ValueError – when runlevel is unknown

avocado.utils.service.get_name_of_init(run=<function run>)

Internal function to determine what executable is PID 1

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

Returns:: executable name for PID 1, aka init
Return type:: str

avocado.utils.service.service_manager(run=<function run>)

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

Example of use:

# Get the system service manager
service_manager = ServiceManager()

# Stating service/unit "sshd"
service_manager.start("sshd")

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

# Disabling and stopping a list of services
services_to_disable = ['ntpd', 'httpd']

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

Returns:: SysVInitServiceManager or SystemdServiceManager
Return type:: _GenericServiceManager

avocado.utils.service.specific_service_manager(service_name, run=<function run>)

Get the service manager for a specific service.

Example of use:

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

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

avocado.utils.service.sys_v_init_command_generator(command)

Generate lists of command arguments for sys_v style inits.

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

avocado.utils.service.sys_v_init_result_parser(command)

Parse results from sys_v style commands.

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

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

avocado.utils.service.systemd_command_generator(command)

Generate list of command line argument strings for systemctl.

One argument per string for compatibility Popen

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

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

avocado.utils.service.systemd_result_parser(command)

Parse results from systemd style commands.

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

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

avocado.utils.softwareraid module

This module provides APIs to work with software raid.

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

Bases: object

Perform software raid related operations.

Parameters:

name (str) – Name of the software raid to be created
level – Level of software raid to be created
disks (list) – List of disks for software raid
metadata (str) – Metadata level for software raid
spare_disks (list) – List of spare disks for software raid

add_disk(disk)

Adds disk specified to software raid.

Parameters:: disk (str) – disk to be added.
Returns:: True if add is successful, False otherwise.
Return type:: bool

assemble()

Assembles software raid.

Returns:: True if assembled, False otherwise.
Return type:: bool

clear_superblock()

Zeroes superblocks in member devices of raid.

Returns:: True if zeroed, False otherwise.
Return type:: bool

create()

Creates software raid.

Returns:: True if raid is created. False otherwise.
Return type:: bool

exists()

checks if softwareraid exists or not

Mdadm:: must be super-user(root) to perform this action
Returns:: True if exists, False otherwise.
Return type:: bool

get_detail()

Returns mdadm details.

Returns:: mdadm –detail output
Return type:: str

is_recovering()

Checks if raid is recovering.

Returns:: True if recovering, False otherwise.
Return type:: bool

remove_disk(disk)

Removes disk specified from software raid.

Parameters:: disk (str) – disk to be removed.
Returns:: True if remove is successful, False otherwise.
Return type:: bool

stop()

Stops software raid.

Returns:: True if stopped, False otherwise.
Return type:: bool

avocado.utils.ssh module

Provides utilities to carry out an SSH session.

Example of use:

from avocado.utils import ssh

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

exception avocado.utils.ssh.NWException

Bases: Exception

Base Exception Class for all exceptions

avocado.utils.ssh.SSH_CLIENT_BINARY = '/usr/bin/ssh': The SSH client binary to use, if one is found in the system

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

Bases: object

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

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

Parameters:

host (str) – a host name or IP address
port (int) – port number
user (str) – the name of the remote user
key (str) – path to a key for authentication purpose
password (str) – password for authentication purpose

DEFAULT_OPTIONS = (('StrictHostKeyChecking', 'no'), ('UpdateHostKeys', 'no'), ('ControlPath', '~/.ssh/avocado-master-%r@%h:%p'))

MASTER_OPTIONS = (('ControlMaster', 'yes'), ('ControlPersist', 'yes'))

cleanup_master(): Removes master file if exists.

cmd(command, ignore_status=True, 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:: bool

property control_master

copy_files(source, destination, recursive=False)

Copy Files to and from remote through scp session.

Parameters:

source – Source file
destination – Destination file location
recursive – Scp option for copy file. if set to True copy files inside directory recursively.

Type:

Type:

Type:

Returns:

True if success and an exception if not.

Return type:

get_raw_ssh_command(command)

Returns the raw command that will be executed locally

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

Parameters:: command (str) – the command to execute over the SSH session
Returns:: The raw SSH command, that can be executed locally for the execution of a remote command.
Return type:: str

quit()

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

Returns:: if closing the session was successful or not
Return type:: bool

avocado.utils.stacktrace module

Traceback standard module plus some additional APIs.

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

Recursive method to obtain unpickable objects along with location

Parameters:

path_prefix – Path to this object
obj – The sub-object under introspection

Returns:

[($path_to_the_object, $value), …]

avocado.utils.stacktrace.log_exc_info(exc_info, logger=None)

Log exception info to logger_name.

Parameters:

exc_info – Exception info produced by sys.exc_info()
logger – Name or logger instance (defaults to ‘’)

avocado.utils.stacktrace.log_message(message, logger=None)

Log message to logger.

Parameters:

message – Message
logger – Name or logger instance (defaults to ‘’)

avocado.utils.stacktrace.prepare_exc_info(exc_info)

Prepare traceback info.

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

avocado.utils.stacktrace.str_unpickable_object(obj)

Return human readable string identifying the unpickable objects

Parameters:: obj – The object for analysis
Raises:: ValueError – In case the object is pickable

avocado.utils.stacktrace.tb_info(exc_info)

Prepare traceback info.

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

avocado.utils.sysinfo module

class avocado.utils.sysinfo.Collectible(log_path)

Bases: ABC

Abstract class for representing sysinfo collectibles.

abstract collect()

property name

exception avocado.utils.sysinfo.CollectibleException

Bases: Exception

Base exception for all collectible errors.

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

Bases: Collectible

Collectible command.

Parameters:

cmd – String with the command.
timeout – Timeout for command execution.
locale – Force LANG for sysinfo collection

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

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

Bases: Command

Collectible daemon.

Parameters:

cmd – String with the command.
timeout – Timeout for command execution.
locale – Force LANG for sysinfo collection

collect(): Stop daemon execution and returns it’s logs. :raise OSError

run(): Start running the daemon as a subprocess. :raise CollectibleException

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

Bases: Collectible

Track the content of systemd journal.

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

collect(): Returns the content of systemd journal :raise CollectibleException

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

Bases: Collectible

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

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

Parameters:

path – Path to the log file.
log_path – Basename of the file where output is logged (optional).

collect(): Collect all of the new data present in the log file. :raise CollectibleException

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

Bases: Collectible

Collectible system file.

Parameters:

path – Path to the log file.
log_path – Basename of the file where output is logged (optional).

collect(): Reads the log file. :raise CollectibleException

avocado.utils.vmimage module

Provides VM images acquired from official repositories

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

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')

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')

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

Uses multiple fallback mirrors to handle periodic URL changes as Fedora versions are released, archived, or mirrors become unavailable.

MIRRORS = ['https://dl.fedoraproject.org/pub/fedora/linux/releases/', 'https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/']

get_image_url(): Probes the higher image available for the current parameters.

name = 'Fedora'

class avocado.utils.vmimage.FedoraImageProviderBase(version, build, arch)

Base Fedora Image Provider

This provider uses fallback mirrors to handle URL changes that occur periodically as Fedora versions are released and archived.

HTML_ENCODING = 'iso-8859-1'

MIRRORS = []

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

Uses multiple fallback mirrors for secondary architectures.

MIRRORS = ['https://dl.fedoraproject.org/pub/fedora-secondary/releases/', 'https://archives.fedoraproject.org/pub/archive/fedora-secondary/releases/']

get_image_url(): Probes the higher image available for the current parameters.

name = 'FedoraSecondary'

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

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

Parameters:: image_file_name (str) – pattern with parameters
Returns:: dict with parameters
Return type:: dict or None

get_image_url(): Probes the higher image available for the current parameters.

get_version(): Probes the higher version available for the current parameters.

get_versions(): Return all available versions for the current parameters.

property version

property version_pattern

exception avocado.utils.vmimage.ImageProviderError

Bases: Exception

Generic error class for ImageProvider

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

JeOS Image Provider

name = 'JeOS'

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

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')