Package pywbem :: Module cim_operations

[frames] | no frames]

# Module cim_operations

source code

CIM operations over HTTP.

The WBEMConnection class in this module opens a connection to a remote WBEM server. Across this connection you can run various CIM operations. Each method of this class corresponds fairly directly to a single CIM operation.

Classes
| CIMError Exception indicating that the WBEM server has returned an error response with a CIM status code.
| WBEMConnection A client's connection to a WBEM server.

Functions

check_utf8_xml_chars(utf8_xml, meaning) Examine a UTF-8 encoded XML string and raise a pywbem.ParseError exception if the response contains Bytes that are invalid UTF-8 sequences (incorrectly encoded or ill-formed) or that are invalid XML characters. | source code

is_subclass(ch, ns, super, sub) Determine if one class is a subclass of another | source code

PegasusUDSConnection(creds=None, **kwargs) | source code

SFCBUDSConnection(creds=None, **kwargs) | source code

OpenWBEMUDSConnection(creds=None, **kwargs) | source code

Variables
| DEFAULT_NAMESPACE = ``'``root/cimv2``'``

Function Details

### check_utf8_xml_chars(utf8_xml, meaning)

source code

Examine a UTF-8 encoded XML string and raise a pywbem.ParseError exception if the response contains Bytes that are invalid UTF-8 sequences (incorrectly encoded or ill-formed) or that are invalid XML characters.

This function works in both "wide" and "narrow" Unicode builds of Python and supports the full range of Unicode characters from U+0000 to U+10FFFF.

This function is just a workaround for the bad error handling of Python's `xml.dom.minidom` package. It replaces the not very informative ExpatError "not well-formed (invalid token): line: x, column: y" with a pywbem.ParseError providing more useful information.

Notes on Unicode support in Python:

1. For internally representing Unicode characters in the unicode type, a "wide" Unicode build of Python uses UTF-32, while a "narrow" Unicode build uses UTF-16. The difference is visible to Python programs for Unicode characters assigned to code points above U+FFFF: The "narrow" build uses 2 characters (a surrogate pair) for them, while the "wide" build uses just 1 character. This affects all position- and length-oriented functions, such as `len()` or string slicing.
2. In a "wide" Unicode build of Python, the Unicode characters assigned to code points U+10000 to U+10FFFF are represented directly (using code points U+10000 to U+10FFFF) and the surrogate code points U+D800...U+DFFF are never used; in a "narrow" Unicode build of Python, the Unicode characters assigned to code points U+10000 to U+10FFFF are represented using pairs of the surrogate code points U+D800...U+DFFF.

Notes on the Unicode code points U+D800...U+DFFF ("surrogate code points"):

1. These code points have no corresponding Unicode characters assigned, because they are reserved for surrogates in the UTF-16 encoding.

2. The UTF-8 encoding can technically represent the surrogate code points. ISO/IEC 10646 defines that a UTF-8 sequence containing the surrogate code points is ill-formed, but it is technically possible that such a sequence is in a UTF-8 encoded XML string.

3. The Python escapes `\u` and `\U` used in literal strings can represent the surrogate code points (as well as all other code points, regardless of whether they are assigned to Unicode characters).

4. The Python `str.encode()` and `str.decode()` functions successfully translate the surrogate code points back and forth for encoding UTF-8.

   For example, `'\xed\xb0\x80'.decode("utf-8") = u'\udc00'`.

5. Because Python supports the encoding and decoding of UTF-8 sequences also for the surrogate code points, the "narrow" Unicode build of Python can be (mis-)used to transport each surrogate unit separately encoded in (ill-formed) UTF-8.

   For example, code point U+10122 can be (illegally) created from a sequence of code points U+D800,U+DD22 represented in UTF-8:

   > `'\xED\xA0\x80\xED\xB4\xA2'.decode("utf-8") = u'\U00010122'`

   while the correct UTF-8 sequence for this code point is:

   > `u'\U00010122'.encode("utf-8") = '\xf0\x90\x84\xa2'`

Notes on XML characters:

1. The legal XML characters are defined in W3C XML 1.0 (Fith Edition):

       Char ::= #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] |
                [#x10000-#x10FFFF]

   These are the code points of Unicode characters using a non-surrogate representation.

Parameters:
  - `utf8_xml` (string) - The UTF-8 encoded XML string to be examined.
  - `meaning` (string) - Short text with meaning of the XML string, for messages in exceptions.

Exceptions:

`TypeError`, if invoked with incorrect Python object type for `utf8_xml`.

pywbem.ParseError, if `utf8_xml` contains Bytes that are invalid UTF-8 sequences (incorrectly encoded or ill-formed) or invalid XML characters.

### is_subclass(ch, ns, super, sub)

source code

    Determine if one class is a subclass of another

    Keyword Arguments:
    ch -- A CIMOMHandle.  Either a pycimmb.CIMOMHandle or a
        pywbem.WBEMConnection.
    ns -- Namespace.
    super -- A string containing the super class name.
    sub -- The subclass.  This can either be a string or a pywbem.CIMClass.