4.11. Support for PUnit and Units qualifiers

The pywbem.siunit_obj() and pywbem.siunit() functions translate the PUnit and Units qualifier values into human readable SI conformant unit strings.

New in pywbem 1.1 as experimental and finalized in 1.3.

Note: These functions do not perform any class operations; they take the qualifiers as input.

The reason the Units qualifier is still supported is that the DMTF CIM Schema (as of its version 2.49) still contains a number of schema elements that have the Units qualifier but not the PUnit qualifier set.

The format and valid base units for the PUnit qualifier and the valid values for the Units qualifier are defined in Annex C of DSP0004. Pywbem supports the definitions from DSP0004 version 2.8, with two extensions:

Pywbem supports the following additional Units qualifier values that are used in the DMTF CIM Schema (as of its version 2.49) but are not defined in DSP0004:

Additional `Units` values
`-dBm`
`Blocks`
`Percentage`
`Proportion`
`Tenths of Revolutions per Minute`

Pywbem supports a slightly more flexible version of the PUnit format that is used in DMTF CIM Schema version 2.49 but not defined in DSP0004: The numeric element may appear anywhere in the formula and not just at the end.

By default, the string value returned from these functions may contain the following Unicode characters outside of the 7-bit ASCII range. If the use_ascii parameter is True, these Unicode characters are replaced with 7-bit ASCII text as follows:

Unicode character code	Unicode	7-bit ASCII
U+00B0: DEGREE SIGN	`°`	`deg`
U+00B5: MICRO SIGN	`µ`	`u`
U+2030: PER MILLE SIGN	`‰`	`1/1000`
U+2126: OHM SIGN	`Ω`	`Ohm`
U+00B2: SUPERSCRIPT TWO	`²`	`^2`
U+00B3: SUPERSCRIPT THREE	`³`	`^3`

Examples:

PUnit("byte / second * 10^3") -> kB/s
PUnit("byte * 2^10") -> KiB
PUnit("hertz * 10^6") -> MHz
PUnit("ampere * 10^-3") -> mA
Units("KiloBits per Second") -> kbit/s
Units("Tenths of Degrees C") -> 1/10 °C

Limitations:

For PUnit qualifiers, vendor-defined base units are not supported (e.g. vendor:myunit).
For PUnit qualifiers, space characters within the parenthesis of decibel (e.g. decibel ( A )) are not supported.
For Units qualifiers, arbitrary numeric values that are part of the Units value (e.g. <numeric-value> NanoSeconds or Amps at <numeric-value> Volts) are not generally supported, but only for those cases that are used in the DMTF CIM Schema (as of its version 2.49):
- 250 NanoSeconds
- Amps at 120 Volts

pywbem.siunit_obj(cim_obj, use_ascii=False)[source]

Returns a human readable SI conformant unit string from the PUnit or Units qualifiers of the specified CIM object.

New in pywbem 1.1 as experimental and finalized in 1.3.

If the CIM object has both the PUnit and Units qualifiers set, then PUnit is used and Units is ignored.

Parameters

cim_obj (CIMProperty or CIMMethod or CIMParameter) – CIM object with qualifiers.
use_ascii (bool) – Replace any Unicode characters in the returned string with 7-bit ASCII replacements, as described above.

Returns

Human readable SI conformant unit string, or None if the CIM object has neither the PUnit nor the Units qualifiers set.

Return type

unicode string

Raises

TypeError – Invalid type for cim_obj
ValueError – Invalid format in PUnit qualifier
ValueError – Unknown base unit in PUnit qualifier
ValueError – Unknown unit in Units qualifier

Example:

>>> cls = conn.GetClass("CIM_StorageSetting", IncludeQualifiers=True)
>>> prop = cls['InterconnectSpeed']
>>> print(pywbem.siunit_obj(prop))
bit/s

pywbem.siunit(punit=None, units=None, use_ascii=False)[source]

Returns a human readable SI conformant unit string from the specified PUnit or Units qualifier values.

New in pywbem 1.1 as experimental and finalized in 1.3.

If both punit and units are specified, then punit is used and units is ignored.

Parameters

punit (string) – Value of the PUnit qualifier, or None.
units (string) – Value of the Units qualifier, or None.
use_ascii (bool) – Replace any Unicode characters in the returned string with 7-bit ASCII replacements, as described above.

Returns

Human readable SI conformant unit string, or None if both qualifier value input parameters were None.

Return type

unicode string

Raises

TypeError – Invalid type for punit or unit
ValueError – Invalid format in PUnit qualifier
ValueError – Unknown base unit in PUnit qualifier
ValueError – Unknown unit in Units qualifier

Examples:

>>> print(pywbem.siunit(punit="byte / second * 10^3"))
kB/s
>>> print(pywbem.siunit(punit="byte * 2^10"))
KiB
>>> print(pywbem.siunit(punit="hertz * 10^6"))
MHz
>>> print(pywbem.siunit(punit="ampere * 10^-3"))
mA
>>> print(pywbem.siunit(units="KiloBits per Second"))
kbit/s
>>> print(pywbem.siunit(units="Tenths of Degrees C"))
1/10 °C
>>> print(pywbem.siunit(units="Tenths of Degrees C", use_ascii=True))
1/10 degC