diff --git a/doc/src/associated_objects.rst b/doc/src/associated_objects.rst index 570a32d..1e33c89 100644 --- a/doc/src/associated_objects.rst +++ b/doc/src/associated_objects.rst @@ -55,7 +55,7 @@ object, run following: the returned object shall match the value of this parameter. Default value is `None`. - Other parameters reffer to: + Other parameters refer to: * ``IncludeQualifiers`` -- Bool flag indicating, if all qualifiers for each object (including qualifiers on the object and on any returned properties) diff --git a/doc/src/classes.rst b/doc/src/classes.rst index 5a56aad..c11f139 100644 --- a/doc/src/classes.rst +++ b/doc/src/classes.rst @@ -132,8 +132,7 @@ See the next example: Creating a new instance ^^^^^^^^^^^^^^^^^^^^^^^ LMIShell is able to create an object of specific class, if the provider support -this operation. The next example shows, how to add a specific user account to -the desired group. +this operation. See the following example: @@ -208,14 +207,15 @@ Useful Properties ----------------- Following part describes few useful :py:class:`LMIClass` properties. -Class name +Class Name ^^^^^^^^^^ Every class object can return a name of the CIM class, see following: .. code-block:: python > cls.classname - 'ClassName' + ClassName + > Namespace ^^^^^^^^^ @@ -225,7 +225,28 @@ corresponding namespace for each class, run following: .. code-block:: python > cls.namespace - 'NamespaceOfClassName' + Namespace + > + +Connection Object +^^^^^^^^^^^^^^^^^ +This property returns a connection object, which was used to retrieve the +class (refer to :ref:`startup_connection`). See next example: + +.. code-block:: python + + > cls.connection + LMIConnection(URI='uri', user='user'...) + > + +Wrapped Object +^^^^^^^^^^^^^^ +This property returns a wrapped :py:mod:`pywbem` object. See the example: + +.. code-block:: python + + > instance.wrapped_object + CIMClass(u'ClassName', ...) > Documentation diff --git a/doc/src/conf.py b/doc/src/conf.py index be003f1..6da35ec 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -101,9 +101,9 @@ copyright = '2012-2013, Red Hat Inc.' # built documents. # # The short X.Y version. -version = '0.7' +version = '0.9' # The full version, including alpha/beta/rc tags. -release = '0.7' +release = '0.9' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/doc/src/index.rst b/doc/src/index.rst index da23cf4..e598cae 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -3,38 +3,54 @@ OpenLMI Tools documentation `OpenLMI Tools` currently consist of *LMIShell* and the content of the documentation itself is devoted to the LMIShell. -LMIShell provides a (non)interactive or interactive way how to access CIM -objects provided by *OpenPegasus* or *sblim-sfcb* broker. +LMIShell +-------- .. only:: html - Contents: + LMIShell provides a (non)interactive way how to access CIM objects provided + by *OpenPegasus* or *sblim-sfcb* broker. The shell is based on a python + interpreter and added logic, therefore what you can do in pure python, it is + possible in LMIShell. There are classes added to manipulate with CIM + classes, instance names, instances, etc. Additional classes are added to + fulfill wrapper pattern and expose only those methods, which are necessary + for the purpose of a shell. - -.. only:: man + **Contents:** .. toctree:: + :maxdepth: 1 + + startup + namespaces + classes + instances + instance_names + associated_objects + association_objects + indications + return_values + interactive_interface + builtins + code - man_page - -.. toctree:: - :maxdepth: 1 +.. only:: man - structure - startup - namespaces - classes - instances - instance_names - associated_objects - association_objects - indications - return_values - interactive_interface - builtins + LMIShell provides a (non)interactive way how to access CIM objects provided + by *OpenPegasus* or *sblim-sfcb* broker. -.. only:: html + .. toctree:: - .. toctree:: :maxdepth: 1 + man_page + startup + namespaces + classes + instances + instance_names + associated_objects + association_objects + indications + return_values + interactive_interface + builtins - code diff --git a/doc/src/instance_names.rst b/doc/src/instance_names.rst index ec2fc0d..ec0c2cf 100644 --- a/doc/src/instance_names.rst +++ b/doc/src/instance_names.rst @@ -36,21 +36,55 @@ Useful Properties Following part describes :py:class:`LMIInstanceName` useful properties. -Class name +Class Name ^^^^^^^^^^ -To get a class name of the instance name, execute: +The property returns a string representation of the class name. See next +example: .. code-block:: python > instance_name.classname + ClassName > -Path -^^^^ -To get a path string from the instance name, execute following: +Namespace +^^^^^^^^^ +The property returns a string representation of namesapce. See next example: .. code-block:: python - > instance_name.path - ... + > instance_name.namespace + Namespace + > + +Host Name +^^^^^^^^^ +This property returns a string representation of the host name, where the CIM +instance is located. + +.. code-block:: python + + > instance_name.hostname + Hostname + > + +Connection Object +^^^^^^^^^^^^^^^^^ +This property returns a connection object, which was used to retrieve the +instance name (refer to :ref:`startup_connection`). See next example: + +.. code-block:: python + + > instance.connection + LMIConnection(URI='uri', user='user'...) + > + +Wrapped Object +^^^^^^^^^^^^^^ +This property returns a wrapped :py:mod:`pywbem` object. See the example: + +.. code-block:: python + + > instance.wrapped_object + CIMInstanceName(classname=u'ClassName', keybindings=NocaseDict(...), host=u'hostname', namespace='namespace') > diff --git a/doc/src/instances.rst b/doc/src/instances.rst index 771c27e..7ca285a 100644 --- a/doc/src/instances.rst +++ b/doc/src/instances.rst @@ -39,8 +39,8 @@ To execute a method within an object, run this: ) > -**NOTE:** Method parameters are passed in a dictionary, as seen in the previous -example. +**NOTE:** Instances **do not** auto-refresh after a method calls. It is +necessary to perform this operation by hand (See :ref:`instances_refreshing`). To get the result from a method call, see following: @@ -65,6 +65,7 @@ classes: * :py:class:`LMI_StorageJob` * :py:class:`LMI_SoftwareInstallationJob` +* :py:class:`LMI_SoftwareVerificationJob` * :py:class:`LMI_NetworkJob` LMIShell first tries to use indications as the waiting method. If it fails, @@ -79,7 +80,7 @@ Following example illustrates, how to perform a synchronous method call: ... "Param2" : value2, ...}) > -**NOTE:** See the prefix ``Sync`` of a method name. +**NOTE:** See the prefix `Sync` of a method name. When a synchronous method call is done: @@ -231,6 +232,14 @@ A single instance can be removed from the CIMOM by executing: **NOTE:** After executing the :py:meth:`.LMIInstance.delete` method, all the object properties, methods will become inaccessible. +Deletion of the instance can be verified by: + +.. code-block:: python + + > instance.is_deleted + True + > + Documentation ------------- For an instance object, you can also use a documentation method, which will @@ -260,7 +269,7 @@ Useful Properties ----------------- Following part describes :py:class:`LMIInstance` useful properties. -Class name +Class Name ^^^^^^^^^^ Each instance object provide a property, that returns its class name. To get a string of the class name, run following: @@ -268,6 +277,7 @@ string of the class name, run following: .. code-block:: python > instance.classname + ClassName > Namespace @@ -278,18 +288,37 @@ To get a string of the namespace name, run following: .. code-block:: python > instance.namespace - 'root/cimv2' + Namespace > Path ^^^^ -To retrieve a unique identification object for an instance, -:py:class:`CIMNamespaceName`, execute following: +To retrieve a unique, wrapped, identification object for the instance, +:py:class:`LMIInstanceName`, execute following: .. code-block:: python > instance.path - namespace:ClassName.CreationClassName="CreationClassName", \ - SystemName="SystemName",Name="InstanceName", \ - SystemCreationClassName="SystemCreationClassName" + LMIInstanceName(classname="ClassName"...) + > + +Connection Object +^^^^^^^^^^^^^^^^^ +This property returns a connection object, which was used to retrieve the +instance (refer to :ref:`startup_connection`). See next example: + +.. code-block:: python + + > instance.connection + LMIConnection(URI='uri', user='user'...) + > + +Wrapped Object +^^^^^^^^^^^^^^ +This property returns a wrapped :py:mod:`pywbem` object. See the example: + +.. code-block:: python + + > instance.wrapped_object + CIMInstance(classname=u'ClassName', ...) > diff --git a/doc/src/startup.rst b/doc/src/startup.rst index 307eb37..eae1732 100644 --- a/doc/src/startup.rst +++ b/doc/src/startup.rst @@ -75,20 +75,28 @@ See following example: Credentials validation ^^^^^^^^^^^^^^^^^^^^^^ Function :py:func:`.connect` returns either :py:class:`LMIConnection` object, if -provided credentials are OK, otherwise ``None`` is returned: +the connection can be established, otherwise ``None`` is returned. Suppose, the +LMIShell is run in verbose mode (:option:`-v`, :option:`--verbose`, :option:`-m` +or :option:`--more-verbose` is used). See following example of creating a connection: .. code-block:: python > # correct username or password > c = connect("host", "username", "password") + INFO: Connected to host > isinstance(c, LMIConnection) True > # wrong login username or password > c = connect("host", "wrong_username", "wrong_password") + ERROR: Error connecting to host, > c is None True > +**NOTE:** By default, LMIShell prints out only error messages, when calling a +:py:func:`.connect`; no INFO messages will be print out. It is possible to +suppress all the messages by passing :option:`-q` or :option:`--quiet`). + Server's certificate validation ------------------------------- When using https transport protocol, LMIShell tries to validate each