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:
- 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.
- 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).
- 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:
- MOFCompiler Class - Describes the
MOFCompiler
class, which allows invoking the MOF compiler programmatically. - Repository connections - Describes the
BaseRepositoryConnection
class that defines the interface for connecting to a CIM repository, and theMOFWBEMConnection
class that is a connection to an in-memory repository on top of an underlying repository, and is used by the MOF compiler to provide rollback support. - Exceptions - Describes the exceptions that can be raised by the MOF compiler API.
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 aMOFWBEMConnection
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
orFakedWBEMConnection
), 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: 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
- handle (BaseRepositoryConnection or
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:EnumerateInstanceNames()
- Enumerate the paths of CIM instances in the repository.CreateInstance()
- Create a CIM instance in the repository.ModifyInstance()
- Modify a CIM instance in the repository.DeleteInstance()
- Delete a CIM instance in the repository.GetClass()
- Retrieve a CIM class from the repository.ModifyClass()
- Modify a CIM class in the repository.CreateClass()
- Create a CIM class in the repository.DeleteClass()
- Delete a CIM class in the repository.EnumerateQualifiers()
- Enumerate CIM qualifier types in the repository.GetQualifier()
- Retrieve a CIM qualifier type from the repository.SetQualifier()
- Create or modify a CIM qualifier type in the repository.DeleteQualifier()
- Delete a qualifier type from the repository.
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
-
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
-
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
-
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
- parser_token – PLY parser token for the error (that is, the