`COT.vm_description` package reference¶

Support for various virtual machine description formats (OVF, OVA, etc.).

The VMDescription class describes the abstract API that is implemented by various subclasses.

In general, other modules should not access subclasses directly but should instead use the factory() API to derive the appropriate subclass object.

API¶

`VMDescription`	Abstract class for reading, editing, and writing VM definitions.
`VMInitError`	Class representing errors encountered when trying to init/load a VM.

VM description modules¶

COT.vm_description.ovf Package for handling OVF and OVA virtual machine description files.

exception VMInitError[source]¶

Bases: exceptions.EnvironmentError

Class representing errors encountered when trying to init/load a VM.

class VMDescription(input_file, output_file=None)[source]¶

Bases: object

Abstract class for reading, editing, and writing VM definitions.

Examples

Because instantiating this class creates a temporary directory (working_dir), it's important to always clean up. This can be done explicitly:

>>> foo = VMDescription("foo.txt", None)
>>> tmpdir = foo.working_dir
>>> os.path.exists(tmpdir)
True
>>> foo.destroy()
>>> os.path.exists(tmpdir)
False

or implicitly by using this class as a context manager:

>>> with VMDescription("foo.txt", None) as foo:
...     tmpdir = foo.working_dir
...     os.path.exists(tmpdir)
...
True
>>> os.path.exists(tmpdir)
False

If the specific VM class is unknown, you can use the factory() method to try to obtain an appropriate subclass:

>>> try:    
...     with VMDescription.factory("foo.txt", None) as foo:
...         print(foo.__class__.__name__)
... except VMInitError as e:
...     print(e)
[Errno 2] Unknown VM description type for input file...

Properties

`input_file`	Data file to read in.
`output_file`	Filename that `write()` will output to.
`working_dir`	Temporary directory this instance can use for storage.
`platform`	The Platform instance object associated with this VM.
`config_profiles`	The list of supported configuration profiles.
`default_config_profile`	The name of the default configuration profile.
`environment_properties`	The array of environment properties.
`environment_transports`	The list of environment transport methods.
`networks`	The list of network names currently defined in this VM.
`network_descriptions`	The list of network descriptions currently defined in this VM.
`system_types`	List of virtual system type(s) supported by this virtual machine.
`version_short`	A short string describing the product version.
`version_long`	A long string describing the product version.

__init__(input_file, output_file=None)[source]¶

Read the given VM description file into memory.

Also creates a temporary directory as a working directory.

Parameters:	input_file (str) -- Data file to read in. output_file (str) -- File name to write to. If this VM is read-only, (there will never be an output file) this value should be `None` If the output filename is not yet known, use `""` and subsequently set `output` when it is determined.

add_controller_device(device_type, subtype, address, ctrl_item=None)[source]¶

Create a new IDE or SCSI controller, or update existing one.

Parameters:	device_type (str) -- `'ide'` or `'scsi'` subtype (str) -- Subtype such as `'virtio'` (optional) address (int) -- Controller address such as 0 or 1 (optional) ctrl_item (object) -- Existing controller device to update (optional)
Returns:	object -- New or updated controller device object

add_disk(disk_repr, file_id, drive_type, disk=None)[source]¶

Add a new disk object to the VM or overwrite the provided one.

Parameters:	disk_repr (DiskRepresentation) -- Disk file representation file_id (str) -- Identifier string for the file/disk mapping drive_type (str) -- 'harddisk' or 'cdrom' disk (object) -- Existing disk object to overwrite
Returns:	object -- New or updated disk object

add_disk_device(drive_type, address, name, description, disk, file_obj, ctrl_item, disk_item=None)[source]¶

Add a new disk device to the VM or update the provided one.

Parameters:

drive_type (str) -- 'harddisk' or 'cdrom'
address (str) -- Address on controller, such as "1:0" (optional)
name (str) -- Device name string (optional)
description (str) -- Description string (optional)
disk (object) -- Disk object to map to this device
file_obj (object) -- File object to map to this device
ctrl_item (object) -- Controller object to serve as parent
disk_item (object) -- Existing disk device to update instead of making a new device.

Returns:

object -- New or updated disk device object.

add_file(file_path, file_id, file_obj=None, disk=None)[source]¶

Add a new file object to the VM or overwrite the provided one.

Parameters:	file_path (str) -- Path to file to add file_id (str) -- Identifier string for the file in the VM file_obj (object) -- Existing file object to overwrite disk (object) -- Existing disk object referencing `file`.
Returns:	object -- New or updated file object

check_sanity_of_disk_device(disk, file_obj, disk_item, ctrl_item)[source]¶

Check if the given disk is linked properly to the other objects.

Parameters:	disk (object) -- Disk object to validate file_obj (object) -- File object which this disk should be linked to (optional) disk_item (object) -- Disk device object which should link to this disk (optional) ctrl_item (object) -- Controller device object which should link to the `disk_item`
Raises:	`ValueMismatchError` -- if the given items are not linked properly.

config_file_to_properties(file_path, user_configurable=None)[source]¶

Import each line of a text file into a configuration property.

Parameters:	file_path (str) -- File name to import. user_configurable (bool) -- Should the properties be configurable at deployment time by the user?

convert_disk_if_needed(disk_image, kind)[source]¶

Convert the disk to a more appropriate format if needed.

Parameters:	disk_image (DiskRepresentation) -- Disk to inspect and possibly convert kind (str) -- Image type (harddisk/cdrom).
Returns:	DiskRepresentation -- `disk_image`, if no conversion was required, or a new `DiskRepresentation` instance representing a converted image that has been created in `output_dir`.

create_configuration_profile(pid, label, description)[source]¶

Create/update a configuration profile with the given ID.

Parameters:	pid (str) -- Profile identifier label (str) -- Brief descriptive label for the profile description (str) -- Verbose description of the profile

create_network(label, description)[source]¶

Define a new network with the given label and description.

Also serves to update the description of an existing network label.

Parameters:	label (str) -- Brief label for the network description (str) -- Verbose description of the network

delete_configuration_profile(profile)[source]¶

Delete the configuration profile with the given ID.

Parameters:	profile (str) -- Profile identifier

destroy()[source]¶

Clean up after ourselves.

Deletes self.working_dir and its contents.

classmethod detect_type_from_name(filename)[source]¶

Check the given filename to see if it looks like a type we support.

Does not check file contents, as the given filename may not yet exist.

Parameters:	filename (str) -- File name or path
Returns:	str -- A string representing a recognized and supported type of file
Raises:	`ValueUnsupportedError` -- if COT can't recognize the file type or doesn't know how to handle this file type.

classmethod factory(input_file, *args, **kwargs)[source]¶

Factory method to select and create the appropriate subclass.

Parameters:	input_file (str) -- Input file to test against each class's `detect_type_from_name()` implementation. args -- Passed through to selected subclass `__init__()`. *kwargs -- Passed through to selected subclass `__init__()`.
Returns:	VMDescription -- appropriate subclass instance.
Raises:	`VMInitError` -- if no appropriate subclass is identified `VMInitError` -- if the selected subclass fails instantiation

find_device_location(device)[source]¶

Find the controller type and address of a given device object.

Parameters:	device (object) -- Hardware device object.
Returns:	tuple -- `(type, address)`, such as `("ide", "1:0")`.

find_empty_drive(drive_type)[source]¶

Find a disk device that exists but contains no data.

Parameters:	drive_type (str) -- Disk drive type, such as 'cdrom' or 'harddisk'
Returns:	object -- Hardware device object, or None.

find_open_controller(controller_type)[source]¶

Find the first open slot on a controller of the given type.

Parameters:	controller_type (str) -- `'ide'` or `'scsi'`
Returns:	tuple -- `(controller_device, address_string)` or `(None, None)`

get_common_subtype(device_type)[source]¶

Get the sub-type common to all devices of the given type.

Parameters:	device_type (str) -- Device type such as `'ide'` or `'memory'`.
Returns:	str -- Subtype string common to all devices of this type, or `None`, if multiple such devices exist and they do not all have the same sub-type.

get_file_ref_from_disk(disk)[source]¶

Get the file reference from the given opaque disk object.

Parameters:	disk (object) -- Disk object to query
Returns:	str -- String that can be used to identify the file associated with this disk

get_id_from_disk(disk)[source]¶

Get the identifier string associated with the given Disk object.

Parameters:	disk (object) -- Disk object
Returns:	str -- Identifier string associated with this object

get_id_from_file(file_obj)[source]¶

Get the file ID from the given opaque file object.

Parameters:	file_obj (object) -- File object to query
Returns:	str -- Identifier string associated with this object

get_nic_count(profile_list)[source]¶

Get the number of NICs under the given profile(s).

Parameters:	profile_list (list) -- Profile(s) of interest.
Returns:	dict -- `{ profile_name : nic_count }`

get_path_from_file(file_obj)[source]¶

Get the file path from the given opaque file object.

Parameters:	file_obj (object) -- File object to query
Returns:	str -- Relative path to the file associated with this object

get_property_value(key)[source]¶

Get the value of the given property.

Parameters:	key (str) -- Property identifier
Returns:	str -- Value of this property, or `None`

get_serial_connectivity(profile)[source]¶

Get the serial port connectivity strings under the given profile.

Parameters:	profile (str) -- Profile of interest.
Returns:	list -- List of connectivity strings

get_serial_count(profile_list)[source]¶

Get the number of serial ports under the given profile(s).

Parameters:	profile_list (list) -- Change only the given profiles
Returns:	dict -- `{ profile_name : serial_count }`

info_string(width=79, verbosity_option=None)[source]¶

Get a descriptive string summarizing the contents of this VM.

Parameters:	width (int) -- Line length to wrap to where possible. verbosity_option (str) -- 'brief', None (default), or 'verbose'
Returns:	str -- Wrapped, appropriately verbose string.

predicted_output_size()[source]¶

Estimate how much disk space (in bytes) is needed to write out.

Returns:	int -- Estimated number of bytes consumed when writing out to `output_file` (plus any associated files).

profile_info_string(width=79, verbosity_option=None)[source]¶

Get a string summarizing available configuration profiles.

Parameters:	width (int) -- Line length to wrap to if possible verbosity_option (str) -- 'brief', None (default), or 'verbose'
Returns:	str -- Appropriately formatted and verbose string.

remove_file(file_obj, disk=None, disk_drive=None)[source]¶

Remove the given file object from the VM.

Parameters:	file_obj (object) -- File object to remove disk (object) -- Disk object referencing `file` disk_drive (object) -- Disk drive mapping `file` to a device

search_from_controller(controller, address)[source]¶

From the controller type and device address, look for existing disk.

Parameters:	controller (str) -- `'ide'` or `'scsi'` address (str) -- Device address such as `'1:0'`
Returns:	tuple -- `(file, disk, controller_device, disk_device)`, opaque objects of which any or all may be `None`

search_from_file_id(file_id)[source]¶

From the given file ID, try to find any existing objects.

Parameters:	file_id (str) -- File ID to search from
Returns:	tuple -- `(file, disk, controller_device, disk_device)`, opaque objects of which any or all may be `None`

search_from_filename(filename)[source]¶

From the given filename, try to find any existing objects.

Parameters:	filename (str) -- Filename to search from
Returns:	tuple -- `(file, disk, controller_device, disk_device)`, opaque objects of which any or all may be `None`

set_cpu_count(cpus, profile_list)[source]¶

Set the number of CPUs.

Parameters:	cpus (int) -- Number of CPUs profile_list (list) -- Change only the given profiles

set_ide_subtype(subtype, profile_list)[source]¶

Set the device subtype for the IDE controller(s).

Deprecated since version 1.5: Use set_ide_subtypes() instead.

Parameters:	subtype (str) -- IDE subtype string profile_list (list) -- Change only the given profiles

set_ide_subtypes(type_list, profile_list)[source]¶

Set the device subtype list for the IDE controller(s).

Parameters:	type_list (list) -- IDE subtype string list profile_list (list) -- Change only the given profiles

set_memory(megabytes, profile_list)[source]¶

Set the amount of RAM, in megabytes.

Parameters:	megabytes (int) -- Memory value, in megabytes profile_list (list) -- Change only the given profiles

set_nic_count(count, profile_list)[source]¶

Set the given profile(s) to have the given number of NICs.

Parameters:	count (int) -- number of NICs profile_list (list) -- Change only the given profiles

set_nic_mac_addresses(mac_list, profile_list)[source]¶

Set the MAC addresses for NICs under the given profile(s).

Note

If the length of mac_list is less than the number of NICs, will use the last entry in the list for all remaining NICs.

Parameters:	mac_list (list) -- List of MAC addresses to assign to NICs profile_list (list) -- Change only the given profiles

set_nic_names(name_list, profile_list)[source]¶

Set the device names for NICs under the given profile(s).

Parameters:	name_list (list) -- List of names to assign. profile_list (list) -- Change only the given profiles

set_nic_networks(network_list, profile_list)[source]¶

Set the NIC to network mapping for NICs under the given profile(s).

Note

If the length of network_list is less than the number of NICs, will use the last entry in the list for all remaining NICs.

Parameters:	network_list (list) -- List of networks to map NICs to profile_list (list) -- Change only the given profiles

set_nic_type(nic_type, profile_list)[source]¶

Set the hardware type for NICs.

Deprecated since version 1.5: Use set_nic_types() instead.

Parameters:	nic_type (str) -- NIC hardware type profile_list (list) -- Change only the given profiles.

set_nic_types(type_list, profile_list)[source]¶

Set the hardware type(s) for NICs.

Parameters:	type_list (list) -- NIC hardware type(s) profile_list (list) -- Change only the given profiles.

set_property_value(key, value, user_configurable=None, property_type=None, label=None, description=None)[source]¶

Set the value of the given property (converting value if needed).

Parameters:	key (str) -- Property identifier value (object) -- Value to set for this property user_configurable (bool) -- Should this property be configurable at deployment time by the user? property_type (str) -- Value type - 'string' or 'boolean' label (str) -- Brief explanatory label for this property description (str) -- Detailed description of this property
Returns:	str -- the (converted) value that was set.

set_scsi_subtype(subtype, profile_list)[source]¶

Set the device subtype for the SCSI controller(s).

Deprecated since version 1.5: Use set_scsi_subtypes() instead.

Parameters:	subtype (str) -- SCSI subtype string profile_list (list) -- Change only the given profiles

set_scsi_subtypes(type_list, profile_list)[source]¶

Set the device subtype list for the SCSI controller(s).

Parameters:	type_list (list) -- SCSI subtype string list profile_list (list) -- Change only the given profiles

set_serial_connectivity(conn_list, profile_list)[source]¶

Set the serial port connectivity under the given profile(s).

Parameters:	conn_list (list) -- List of connectivity strings profile_list (list) -- Change only the given profiles

set_serial_count(count, profile_list)[source]¶

Set the given profile(s) to have the given number of NICs.

Parameters:	count (int) -- Number of serial ports profile_list (list) -- Change only the given profiles

validate_hardware()[source]¶

Check sanity of hardware properties for this VM/product/platform.

Returns:	bool -- `True` if hardware is sane, `False` if not.

write()[source]¶: Write the VM description to output_file, if any.

config_profiles¶

The list of supported configuration profiles.

If there are no profiles defined, returns an empty list. If there is a default profile, it will be first in the list.

default_config_profile¶

The name of the default configuration profile.

Returns:	str -- Profile name or `None` if none are defined.

environment_properties¶

The array of environment properties.

Returns:	list -- Array of dicts (one per property) with the keys `"key"`, `"value"`, `"qualifiers"`, `"type"`, `"label"`, and `"description"`.

environment_transports¶: The list of environment transport methods.

input_file¶: Data file to read in.

network_descriptions¶: The list of network descriptions currently defined in this VM.

networks¶: The list of network names currently defined in this VM.

output_file¶: Filename that write() will output to.

platform¶

The Platform instance object associated with this VM.

An instance of Platform or a more specific subclass if recognized as such.

product_class¶: The product class identifier, such as com.cisco.csr1000v.

system_types¶: List of virtual system type(s) supported by this virtual machine.

verbosity_options = {None: 1, 'brief': 0, 'verbose': 2}¶

version_long¶: A long string describing the product version.

version_short¶: A short string describing the product version.

working_dir¶

Temporary directory this instance can use for storage.

Will be automatically erased when destroy() is called.

COT.vm_description package reference¶

API¶

VM description modules¶

`COT.vm_description` package reference¶