The DwfLibrary class

The DwfLibrary class is the entry point to all pydwf functionality. Most importantly, it is needed to obtain DwfDevice instances.

Using the DwfLibrary class

The DwfLibrary class is defined in the pydwf.core.dwf_library module. The top-level pydwf package imports it from that module to make it available to user scripts. To use the DwfLibrary class, you should import it from the top-level pydwf package and create an instance:

from pydwf import DwfLibrary

dwf = DwfLibrary()

print("DWF library version:", dwf.getVersion())

After instantiating a DwfLibrary, you can use the handful of methods the instance provides. These methods are documented as part of the DwfLibrary class in the next section.

Three attributes are provided to access particular sub-APIs of a DwfLibrary instance:

deviceEnum provides device enumeration functionality;
deviceControl provides device control functionality;
spectrum provides signal processing functionality.

In most programs, the DwfLibrary instance is only used for opening a DwfDevice, using either one of the DeviceControl.open() or DeviceControl.openEx() methods, or the pydwf.utilities.openDwfDevice() convenience function; the latter takes a DwfLibrary instance as a parameter.

DwfLibrary reference

class DwfLibrary

The DwfLibrary class provides access to miscellaneous library functionality through the handful of methods it provides, and to device enumeration, device control, and signal processing functionality via its deviceEnum, deviceControl, and spectrum attributes.

DwfLibrary attributes

deviceEnum

Provides access to the device enumeration functionality.

Type:: DeviceEnumeration

deviceControl

Provides access to the device control functionality.

Type:: DeviceControl

spectrum

Provides access to the signal processing functionality.

Type:: Spectrum

DwfLibrary methods

__init__(check_library_version: bool = False) → None

Initialize a DwfLibrary instance.

A single DwfLibrary instance should be created by a user of pydwf to serve as an entry point to all pydwf functionality.

When initializing a DwfLibrary, the shared library libdwf on top of which pydwf is built is loaded into memory using Python’s standard ctypes module.

A version check can be enabled to make sure that the shared library version corresponds exactly to the version that was used while developing and testing the current pydwf version (3.20.1), and an exception is raised if a mismatch is detected. Enabling this flag is recommended for critical applications.

After passing the version check (if enabled), the functions provided by the shared library are type-annotated. This means that calls into the shared library with incompatible parameter types will raise an exception. This mechanism helps to catch many bugs while using pydwf.

As a last initialization step, the deviceEnum, deviceControl, and spectrum attributes are initialized. They can be used by a user program to access the device enumeration, device control functionality, and signal processing functionality.

Parameters:: check_library_version (bool) – If True, the version number of the C library will be checked against the version of the C library from which the type information used by pydwf was derived. In case of a mismatch, an exception will be raised.
Raises:: PyDwfError – The version check could not be performed due to an unexpected low-level error while querying the shared library version, or a version mismatch was detected.

getLastError() → DwfErrorCode

Retrieve the last error code in the calling process.

The error code is cleared when other API functions are called and is only set when an API function fails during execution.

Note

When using pydwf there is no need to call this method directly, since low-level errors reported by the C library are automatically converted to a DwfLibraryError exception, which includes both the error code and the corresponding message.

Returns:: The DWF error code of last API call.
Return type:: DwfErrorCode
Raises:: DwfLibraryError – the last error code cannot be retrieved.

getLastErrorMsg() → str

Retrieve the last error message.

The error message is cleared when other API functions are called and is only set when an API function fails during execution.

Note

When using pydwf there is no need to call this method directly, since low-level errors reported by the C library are automatically converted to a DwfLibraryError exception, which includes both the error code and the corresponding message.

Returns:

The error message of the last API call.

The string may consist of multiple messages, separated by a newline character, that describe the events leading to the error.

Return type:

str

Raises:

DwfLibraryError – The last error message cannot be retrieved.

getVersion() → str

Retrieve the library version string.

Returns:: The version of the DWF C library, composed of major, minor, and build numbers (e.g., “3.20.1”).
Return type:: str
Raises:: DwfLibraryError – The library version string cannot be retrieved.

paramSet(device_parameter: DwfDeviceParameter, value: int) → None

Configure a default device parameter value.

Device parameters are settings of a specific DwfDevice. Refer to the device parameters section for more information.

This method sets a default device parameter value to be used for devices that are opened subsequently.