7. MOF compiler API

The language in which CIM classes, CIM Instances, etc. are specified, is called MOF (for Managed Object Format). It is defined in DSP0004.

MOF compilers take MOF files as input, compile them and use the result (CIM classes, instances, and/or qualifier declarations) to update a target CIM repository. The repository may initially be empty, or may contain CIM classes, instances, and/or qualifier declarations that are used to resolve dependencies the new MOF compilation may have.

The pywbem package includes a MOF compiler that is provided in two forms:

  • as an API (described in this chapter)
  • as a command (described in section mof_compiler)

The pywbem MOF compiler will compile MOF files whose syntax complies with DSP0004, with some limitations:

  1. Although there is no formal keyword list of illegal words for property/parameter.etc. names , there is a list of mof syntax tokens in DSP0004 section A.3. Generally these should not be used as property names. The pywbem MOF compiler largely enforces this so that words like ‘indication’ are not allowed as property/parameter/etc. names.
  2. The key properties of instances with aliases must be initialized in the instance specification, or their default values must be non-NULL. (See pywbem issue #1079).
  3. An alias must be defined before it is used. In DSP0004, no such requirement is documented. (See pywbem issue #1079).

The MOF compiler API provides for invoking the MOF compiler, it supports plugging in a user-provided CIM repository (see BaseRepositoryConnection), and it supports a rollback capability that undoes compilation effects (see rollback()).

The MOF compiler API consists of the following parts, which are described in the remaining sections of this chapter:

7.1. MOFCompiler Class

class pywbem.MOFCompiler(handle, search_paths=None, verbose=False, log_func=<function _print_logger>)[source]

A MOF compiler. See MOF compiler API for an explanation of MOF compilers in general.

A MOF compiler may be associated with one CIM repository. The repository is used for looking up dependent CIM elements (e.g. the superclass specified in a class whose MOF definition is being compiled), and it is also updated with the result of the compilation. A repository contains CIM namespaces, and the namespaces contain CIM classes, instances and qualifier types.

The association of a MOF compiler with a CIM repository is established when creating an object of this class. The interactions with the CIM repository are defined in the abstract base class BaseRepositoryConnection.

Parameters:
  • handle (BaseRepositoryConnection or WBEMConnection) –

    A handle identifying the CIM repository that will be associated with the MOF compiler.

    If the provided object is a repository connection (i.e. derived from BaseRepositoryConnection, typically that would be a MOFWBEMConnection object), it is directly used by the MOF compiler to interface with the repository.

    If the provided object is a WBEM connection (i.e. WBEMConnection or FakedWBEMConnection), the MOF compiler connects directly to interface defined by handle.

    None means that no CIM repository will be associated. In this case, the MOF compiler can only process standalone MOF that does not depend on existing CIM elements in the repository.

  • search_paths (iterable of string or string) –

    Directory path name(s) where the MOF compiler will search for MOF dependent files if the MOF element they define is not in the target namespace of the CIM repository. The compiler searches the specified directories and their subdirectories.

    MOF dependent files are:

    • The MOF file defining the superclass of a class that is compiled. The MOF file searched for is ‘<classname>.mof’.
    • The MOF file defining the qualifier type of a qualifier that is specified on a MOF element that is compiled. The MOF files searched for are ‘qualifiers.mof’ and ‘qualifiers_optional.mof’.
    • The MOF file of a class specified in a reference property or in the EmbeddedInstance qualifier that is compiled. The MOF file searched for is ‘<classname>.mof’. This is only partly implemented, see issue #1138.

    Note that MOF include files are not searched for; they are specified in the pragma include directive as a file path relative to the including file.

  • verbose (bool) – Indicates whether to issue more detailed compiler messages.
  • log_func (callable) – A logger function that is invoked for each compiler message. The logger function must take one parameter of string type. The default logger function prints to stdout.

Methods

compile_file Compile a MOF file into a namespace of the associated CIM repository.
compile_string Compile a string of MOF statements into a namespace of the associated CIM repository.
find_mof Find the MOF file that defines a particular CIM class, in the search path of the MOF compiler.
rollback Rollback any changes to the CIM repository that were performed by compilations using this MOF compiler object, since the object was created.

Attributes

Details

compile_string(mof, ns, filename=None)[source]

Compile a string of MOF statements into a namespace of the associated CIM repository.

Parameters:
  • mof (string) – The string of MOF statements to be compiled.
  • ns (string) – The name of the CIM namespace in the associated CIM repository that is used for lookup of any dependent CIM elements, and that is also the target of the compilation.
  • filename (string) – The path name of the file that the MOF statements were read from. This information is used only in compiler messages.
Raises:
  • IOError – MOF file not found.
  • MOFParseError – Syntax error in the MOF.
  • Any exceptions that are raised by the repository connection class.
compile_file(filename, ns)[source]

Compile a MOF file into a namespace of the associated CIM repository.

Parameters:
  • filename (string) – The path name of the MOF file containing the MOF statements to be compiled.
  • ns (string) – The name of the CIM namespace in the associated CIM repository that is used for lookup of any dependent CIM elements, and that is also the target of the compilation.
Raises:
  • IOError – MOF file not found.
  • MOFParseError – Syntax error in the MOF.
  • Any exceptions that are raised by the repository connection class.
find_mof(classname)[source]

Find the MOF file that defines a particular CIM class, in the search path of the MOF compiler.

The MOF file is found based on its file name: It is assumed that the base part of the file name is the CIM class name.

Example: The class “CIM_ComputerSystem” is expected to be in a file “CIM_ComputerSystem.mof”.

Parameters:classame (string) – The name of the CIM class to look up.
Returns:Path name of the MOF file defining the CIM class, if it was found. None, if it was not found.
Return type:string
rollback(verbose=False)[source]

Rollback any changes to the CIM repository that were performed by compilations using this MOF compiler object, since the object was created.

7.2. Repository connections

class pywbem.BaseRepositoryConnection[source]

An abstract base class for implementing CIM repository connections (or an entire CIM repository) for use by the MOF compiler. This class defines the interface that is used by the MOFCompiler class when it interacts with its associated CIM repository.

Class MOFCompiler invokes only the WBEM operations that are defined as methods on this class:

Raises:Implementation classes should raise only exceptions derived from Error. Other exceptions are considered programming errors.

Methods

CreateClass Create a CIM class in a namespace of the CIM repository.
CreateInstance Create a CIM instance in a namespace of the CIM repository.
DeleteClass Delete a CIM class in a namespace of the CIM repository.
DeleteInstance Delete a CIM instance in a namespace of the CIM repository.
DeleteQualifier Delete a CIM qualifier type in a namespace of the CIM repository.
EnumerateInstanceNames Enumerate the instance paths of CIM instances in a namespace of the CIM repository.
EnumerateQualifiers Enumerate the CIM qualifier types in a namespace of the CIM repository.
GetClass Retrieve a CIM class in a namespace of the CIM repository.
GetQualifier Retrieve a CIM qualifier type in a namespace of the CIM repository.
ModifyClass Modify a CIM class in a namespace of the CIM repository.
ModifyInstance Modify a CIM instance in a namespace of the CIM repository.
SetQualifier Create or modify a CIM qualifier type in a namespace of the CIM repository.

Attributes

default_namespace The default repository namespace.

Details

default_namespace

The default repository namespace.

This property is settable.

Type:string
EnumerateInstanceNames(*args, **kwargs)[source]

Enumerate the instance paths of CIM instances in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.EnumerateInstanceNames().

CreateInstance(*args, **kwargs)[source]

Create a CIM instance in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.CreateInstance().

ModifyInstance(*args, **kwargs)[source]

Modify a CIM instance in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.ModifyInstance().

DeleteInstance(*args, **kwargs)[source]

Delete a CIM instance in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.DeleteInstance().

GetClass(*args, **kwargs)[source]

Retrieve a CIM class in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.GetClass().

ModifyClass(*args, **kwargs)[source]

Modify a CIM class in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.ModifyClass().

CreateClass(*args, **kwargs)[source]

Create a CIM class in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.CreateClass().

DeleteClass(*args, **kwargs)[source]

Delete a CIM class in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.DeleteClass().

EnumerateQualifiers(*args, **kwargs)[source]

Enumerate the CIM qualifier types in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.EnumerateQualifiers().

GetQualifier(*args, **kwargs)[source]

Retrieve a CIM qualifier type in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.GetQualifier().

SetQualifier(*args, **kwargs)[source]

Create or modify a CIM qualifier type in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.SetQualifier().

DeleteQualifier(*args, **kwargs)[source]

Delete a CIM qualifier type in a namespace of the CIM repository.

For a description of the parameters, see pywbem.WBEMConnection.DeleteQualifier().

class pywbem.MOFWBEMConnection(conn=None)[source]

A CIM repository connection to an in-memory repository on top of an optional underlying WBEM connection.

If a WBEM connection is provided with the conn parameter, that connection is the target for any operations that acquire CIM objects and the in-memory store acts as a cache for CIM qualifiers declarations, CIM Classes, and CIM Instances created and as a rollback log in support of rolling back the operations. This is the mode in which the MOF compiler uses this class.

If the underlying WBEM connection is not provided, the in-memory repository acts as a CIM repository that is targeted by the operations. This mode is used for testing only.

MOFWBEMConnection only implements the BaseRepositoryConnection methods required to implement the mof compiler rollback functionality.

This class implements the BaseRepositoryConnection interface.

This implementation sets the path component of instances created including keybindings using property values in the instance. It does NOT confirm that all key properties are included in the path.

Raises:The methods of this class may raise any exceptions described for class WBEMConnection.
Parameters:conn (BaseRepositoryConnection) –

The underlying repository connection.

None means that there is no underlying repository and all operations performed through this object will fail.

Methods

CreateClass Create a CIM class in the local repository of this class.
CreateInstance Create a CIM instance in the local repository of this class.
DeleteClass This method is only invoked by rollback() (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.
DeleteInstance This method is only invoked by rollback() (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.
DeleteQualifier This method is only invoked by rollback() (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.
EnumerateInstanceNames This method is used by the MOF compiler only when it creates a namespace in the course of handling CIM_ERR_NAMESPACE_NOT_FOUND.
EnumerateQualifiers Enumerate the qualifier types in the local repository of this class.
GetClass Retrieve a CIM class from the local repository of this class.
GetQualifier Retrieve a qualifier type from the local repository of this class.
ModifyClass This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create a class.
ModifyInstance This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create an instance.
SetQualifier Create or modify a qualifier type in the local repository of this class.
getns string: Return the default repository namespace to be used.
rollback Remove classes and instances from the underlying repository, that have been created in the local repository of this class.
setns Set the default repository namespace to be used.

Attributes

default_namespace The default repository namespace to be used.

Details

getns()

string: Return the default repository namespace to be used.

This method exists for compatibility. Use the default_namespace property instead.

setns(value)

Set the default repository namespace to be used.

This method exists for compatibility. Use the default_namespace property instead.

default_namespace

The default repository namespace to be used.

The default repository namespace is the default namespace of the underlying repository connection if there is such an underlying connection, or the default namespace of this object.

Initially, the default namespace of this object is ‘root/cimv2’.

This property is settable. Setting it will cause the default namespace of the underlying repository connection to be updated if there is such an underlying connection, or the default namespace of this object.

Type:string
EnumerateInstanceNames(*args, **kwargs)[source]

This method is used by the MOF compiler only when it creates a namespace in the course of handling CIM_ERR_NAMESPACE_NOT_FOUND. Because the operations of this class silently create every namespace that is needed and never return that error, this method is never called, and is therefore not implemented.

ModifyInstance(*args, **kwargs)[source]

This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create an instance. Because CreateInstance() overwrites existing instances, this method is never called, and is therefore not implemented. NOTE: This error means that the mof compiler logic to attempt modifyinstance if createinstance fails does not attempt the modifyinstance.

CreateInstance(*args, **kwargs)[source]

Create a CIM instance in the local repository of this class. This implementation does not test for duplicate instances but appends each new instance to the repository.

For a description of the parameters, see pywbem.WBEMConnection.CreateInstance().

DeleteInstance(*args, **kwargs)[source]

This method is only invoked by rollback() (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.

GetClass(*args, **kwargs)[source]

Retrieve a CIM class from the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.GetClass().

ModifyClass(*args, **kwargs)[source]

This method is used by the MOF compiler only in the course of handling CIM_ERR_ALREADY_EXISTS after trying to create a class. Because CreateClass() overwrites existing classes, this method is never called, and is therefore not implemented.

CreateClass(*args, **kwargs)[source]

Create a CIM class in the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.CreateClass().

DeleteClass(*args, **kwargs)[source]

This method is only invoked by rollback() (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.

EnumerateQualifiers(*args, **kwargs)[source]

Enumerate the qualifier types in the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.EnumerateQualifiers().

GetQualifier(*args, **kwargs)[source]

Retrieve a qualifier type from the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.GetQualifier().

SetQualifier(*args, **kwargs)[source]

Create or modify a qualifier type in the local repository of this class.

For a description of the parameters, see pywbem.WBEMConnection.SetQualifier().

DeleteQualifier(*args, **kwargs)[source]

This method is only invoked by rollback() (on the underlying repository), and never by the MOF compiler, and is therefore not implemented.

rollback(verbose=False)[source]

Remove classes and instances from the underlying repository, that have been created in the local repository of this class.

Limitations:

1. At this point, only classes and instances will be removed, but not qualifiers.

2. This may not work with instances created by other means, ex. other mof_compilers because of amgiguity in the definition of instance names for associations (ex. The namespace component in reference properties)

3. This only removes the classes specifically defined in the compiled mof and not any classes installed as prerquisits as part of the compile (ex. superclasses, classes defined by references)

7.3. Exceptions

The MOF compiler API may raise the exceptions that can be raised by the WBEM client library API, and in addition the MOFParseError exception.

class pywbem.MOFParseError(parser_token=None, msg=None)[source]

Exception raised when MOF cannot be parsed correctly, e.g. for syntax errors. Derived from Error.

Parameters:
  • parser_token – PLY parser token for the error (that is, the p argument of a PLY parser function). This token contains information on the location of the error in the MOF file, which is copied into this object, and is accessible via properties.
  • msg (string) – Message text supplied by the creator of the error

Methods

get_err_msg Return a multi-line error message for being printed, in the following format.
with_traceback Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Attributes

args
column Position within the line in the MOF file or MOF string where the error occurred (1-based).
conn_id Connection ID of the connection in whose context the error happened.
conn_str String that identifies the connection in exception messages.
context MOF context, consisting of a first line that is the MOF line in error, and a second line that uses the ‘^’ character to indicate the position of the token in error in the MOF line.
file File name of the MOF file where the error occurred.
lineno Line number in the MOF file or MOF string where the error occurred (1-based).
msg Brief description of the problem.

Details

lineno

Line number in the MOF file or MOF string where the error occurred (1-based).

Type:integer
column

Position within the line in the MOF file or MOF string where the error occurred (1-based).

Type:integer
file

File name of the MOF file where the error occurred.

None if the error occurred in a MOF string that was compiled.

Type:string
context

MOF context, consisting of a first line that is the MOF line in error, and a second line that uses the ‘^’ character to indicate the position of the token in error in the MOF line.

Type:string
msg

Brief description of the problem.

Type:string
get_err_msg()[source]

Return a multi-line error message for being printed, in the following format. The text in angle brackets refers to the same-named properties of the exception instance:

Syntax error:<file>:<lineno>: <msg>
<context - MOF line>
<context - position indicator line>
Returns:Multi-line error message.
Return type:string