Repository :
http://git.fedorahosted.org/cgit/cura-tools.git
On branch : 0.9-fixes
---------------------------------------------------------------
commit 0829622196f2020f2e7613a7186b38516a4e89f8
Author: Peter Hatina <phatina(a)redhat.com>
Date: Mon Dec 9 11:02:53 2013 +0100
update documentation
---------------------------------------------------------------
doc/src/_static/lmi-scheme.png | Bin 12551 -> 0 bytes
doc/src/associated_objects.rst | 2 +-
doc/src/classes.rst | 31 ++++++++++++++++---
doc/src/index.rst | 64 +++++++++++++++++++++++++---------------
doc/src/instance_names.rst | 48 +++++++++++++++++++++++++----
doc/src/instances.rst | 49 ++++++++++++++++++++++++------
doc/src/startup.rst | 10 +++++-
7 files changed, 156 insertions(+), 48 deletions(-)
diff --git a/doc/src/_static/lmi-scheme.png b/doc/src/_static/lmi-scheme.png
deleted file mode 100644
index efdf9c2..0000000
Binary files a/doc/src/_static/lmi-scheme.png and /dev/null differ
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/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, <error message>
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