diff --git a/docs/appendix.rst b/docs/appendix.rst index f8cfe1b17..7037ada94 100644 --- a/docs/appendix.rst +++ b/docs/appendix.rst @@ -84,7 +84,7 @@ This documentation uses a few special terms to refer to Python types: in the current directory. Multiple connections files may exist in different directories. This allows connection definitions to be predefined and pywbemcli commands executed against them using only the - connection definition name (via the ``--name`` general option). + connection definition name (via the :ref:`--name general option`). MOF MOF (Managed Object Format) is the language used by the DMTF to @@ -177,7 +177,8 @@ This documentation uses a few special terms to refer to Python types: the default connection is defined. A connection definition in the :term:`connections file` becomes the default connection on pywbemcli startup if it is specified using the - :ref:`connection select command` and the ``--default option`` is used. + :ref:`connection select command` and the + ``--default``/``-d`` command option is used. current connection The connection definition in pywbemcli that is currently active; it is the diff --git a/docs/pywbemcli/cmdlineinterface.rst b/docs/pywbemcli/cmdlineinterface.rst index dae19677e..5b3c75a64 100644 --- a/docs/pywbemcli/cmdlineinterface.rst +++ b/docs/pywbemcli/cmdlineinterface.rst @@ -63,7 +63,7 @@ begin with ``-``. Command groups are named after the objects the commands operate on (ex. ``class``, ``instance``, ``qualifier``, ``server``). Executing -.. code-block::text +.. code-block:: text $ pywbemcli --help ... @@ -427,7 +427,7 @@ Pywbemcli terminates with one of the following program exit codes: These Python tracebacks should never happen and are always considered a reason to open a bug in the - `pywbemtools issue tracker `_`. + `pywbemtools issue tracker `_. Note that an error message with a traceback from a mock Python script does not fall into this category and is an issue in that Python script and not diff --git a/docs/pywbemcli/commands.rst b/docs/pywbemcli/commands.rst index 5d70cca7c..ac277b9d8 100644 --- a/docs/pywbemcli/commands.rst +++ b/docs/pywbemcli/commands.rst @@ -32,8 +32,8 @@ with mock files that are located in the pywbemtools ``tests/unit`` subdirectory. .. _`Class command group`: -Class command group -------------------- +``class`` command group +----------------------- The ``class`` command group has commands that act on CIM classes: @@ -54,8 +54,8 @@ See :ref:`pywbemcli class --help`. .. _`Class associators command`: -Class associators command -^^^^^^^^^^^^^^^^^^^^^^^^^ +``class associators`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``class associators`` command lists the CIM classes that are associated with the specified source class. @@ -86,8 +86,8 @@ See :ref:`pywbemcli class associators --help` for the exact help output of the c .. _`Class delete command`: -Class delete command -^^^^^^^^^^^^^^^^^^^^ +``class delete`` command +^^^^^^^^^^^^^^^^^^^^^^^^ The ``class delete`` command deletes the specified class on the server. @@ -119,8 +119,8 @@ See :ref:`pywbemcli class delete --help` for the exact help output of the comman .. _`Class enumerate command`: -Class enumerate command -^^^^^^^^^^^^^^^^^^^^^^^ +``class enumerate`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``class enumerate`` command enumerates the subclasses of the specified class, or the root classes of the class hierarchy. @@ -172,8 +172,8 @@ See :ref:`pywbemcli class enumerate --help` for the exact help output of the com .. _`Class find command`: -Class find command -^^^^^^^^^^^^^^^^^^ +``class find`` command +^^^^^^^^^^^^^^^^^^^^^^ The ``class find`` command lists classes with a class name that matches the :term:`Unix-style path name pattern` specified in the ``CLASSNAME-GLOB`` @@ -241,8 +241,8 @@ See :ref:`pywbemcli class find --help` for the exact help output of the command. .. _`Class get command`: -Class get command -^^^^^^^^^^^^^^^^^ +``class get`` command +^^^^^^^^^^^^^^^^^^^^^ The ``class get`` command gets the specified class. @@ -299,8 +299,8 @@ See :ref:`pywbemcli class get --help` for the exact help output of the command. .. _`Class invokemethod command`: -Class invokemethod command -^^^^^^^^^^^^^^^^^^^^^^^^^^ +``class invokemethod`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``class invokemethod`` command invokes a CIM method on the specified class and displays the return value and any output parameters. @@ -335,8 +335,8 @@ See :ref:`pywbemcli class invokemethod --help` for the exact help output of the .. _`Class references command`: -Class references command -^^^^^^^^^^^^^^^^^^^^^^^^ +``class references`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``class references`` command lists the CIM classes that reference the specified source class. @@ -365,8 +365,8 @@ See :ref:`pywbemcli class references --help` for the exact help output of the co .. _`Class tree command`: -Class tree command -^^^^^^^^^^^^^^^^^^ +``class tree`` command +^^^^^^^^^^^^^^^^^^^^^^ The ``class tree`` command displays the subclass or superclass hierarchy of the specified class. @@ -402,8 +402,8 @@ See :ref:`pywbemcli class tree --help` for the exact help output of the command. .. _`Instance command group`: -Instance command group ----------------------- +``instance`` command group +-------------------------- The ``instance`` command group has commands that act on CIM instances: @@ -427,8 +427,8 @@ See :ref:`pywbemcli instance --help`. .. _`Instance associators command`: -Instance associators command -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``instance associators`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``instance associators`` command lists the CIM instances that are associated with the specified source instance. @@ -471,8 +471,8 @@ See :ref:`pywbemcli instance associators --help` for the exact help output of th .. _`Instance count command`: -Instance count command -^^^^^^^^^^^^^^^^^^^^^^ +``instance count`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``instance count`` command counts the CIM instances of some or all classes in the namespaces specified with the ``-namespace``/``-n`` command option, or @@ -533,8 +533,8 @@ See :ref:`pywbemcli instance count --help` for the exact help output of the comm .. _`Instance create command`: -Instance create command -^^^^^^^^^^^^^^^^^^^^^^^ +``instance create`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``instance create`` command creates a CIM instance in the namespace specified with the ``-namespace``/``-n`` command option, or otherwise in the @@ -567,8 +567,8 @@ See :ref:`pywbemcli instance create --help` for the exact help output of the com .. _`Instance delete command`: -Instance delete command -^^^^^^^^^^^^^^^^^^^^^^^ +``instance delete`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``instance delete`` command deletes a CIM instance. @@ -589,8 +589,8 @@ See :ref:`pywbemcli instance delete --help` for the exact help output of the com .. _`Instance enumerate command`: -Instance enumerate command -^^^^^^^^^^^^^^^^^^^^^^^^^^ +``instance enumerate`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``instance enumerate`` command lists the CIM instances of the specified class (including subclasses) in a namespace. @@ -628,8 +628,8 @@ See :ref:`pywbemcli instance enumerate --help` for the exact help output of the .. _`Instance get command`: -Instance get command -^^^^^^^^^^^^^^^^^^^^ +``instance get`` command +^^^^^^^^^^^^^^^^^^^^^^^^ The ``instance get`` command gets a CIM instance. @@ -672,8 +672,8 @@ See :ref:`pywbemcli instance get --help` for the exact help output of the comman .. _`Instance invokemethod command`: -Instance invokemethod command -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``instance invokemethod`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``instance invokemethod`` command invokes a CIM method on the specified instance and displays the return value and any output parameters. @@ -719,8 +719,8 @@ See :ref:`pywbemcli instance invokemethod --help` for the exact help output of t .. _`Instance modify command`: -Instance modify command -^^^^^^^^^^^^^^^^^^^^^^^ +``instance modify`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``instance modify`` command modifies the properties of an existing CIM instance. @@ -760,8 +760,8 @@ See :ref:`pywbemcli instance modify --help` for the exact help output of the com .. _`Instance references command`: -Instance references command -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``instance references`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``instance references`` command lists the CIM instances that reference the specified source instance. @@ -795,17 +795,17 @@ See :ref:`pywbemcli instance references --help` for the exact help output of the .. _`Instance query command`: -Instance query command -^^^^^^^^^^^^^^^^^^^^^^ +``instance query`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``instance query`` command executes a query for CIM instances in a namespace. The query is specified with the ``QUERY`` argument and must be a valid query -in the query language specified with the ``--query-language`` command option. -The default for that option is ``DMTF:CQL`` (see :term:`CQL`). +in the query language specified with the ``--query-language``/``--ql`` command +option. The default for that option is ``DMTF:CQL`` (see :term:`CQL`). -The namespace is specified with the ``-namespace``/``-n`` command option, or +The namespace is specified with the ``--namespace``/``-n`` command option, or otherwise is the default namespace of the connection. Valid output formats are :term:`CIM object output formats` or @@ -817,8 +817,8 @@ See :ref:`pywbemcli instance query --help` for the exact help output of the comm .. _`Instance shrub command`: -Instance shrub command -^^^^^^^^^^^^^^^^^^^^^^ +``instance shrub`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``instance shrub`` command executes a set of requests to get the association relationships for a non-association CIM instance defined by @@ -837,18 +837,18 @@ command option, or otherwise is the default namespace of the connection. Valid output formats are :term:`Table output formats` or the default which displays the a visual tree. -The instance shrub command includes options to: +The ``instance shrub`` command includes command options to: -1. ``-s/--summary`` Show only the class components and a count of instancess. +1. ``--summary``/``-s``: Show only the class components and a count of instances. -2. ``-f/--fullpath`` option that shows the full path of the instances. The +2. ``--fullpath``/``-f``: Show the full path of the instances. The default is to attempt to shorten the path by removing path components that are the same for all instances displayed. This can be important for some of the components of the model where instance paths include keys like ``CreationClassName`` and 'SystemCreationClassName'which are either already known or do not distinguish instances but make the instance name difficult to visualize on the console. These key bindings are replaced with the - character ``~`` as a placemarker unless the ``--fullpath`` option is + character ``~`` as a placemarker unless the ``--fullpath``/``-f`` option is defined. Thus, a full path might look like: @@ -859,13 +859,11 @@ But the shortened path would be: ``/:CIM_FCPort.~,~,~,DeviceID="ACME+CF2A5091300089+SP_A+10"`` - This command is primarily a diagnostic and test tool to help users understand what comprises CIM association relationships. See :ref:`pywbemcli instance shrub --help` for the exact help output of the command. - Example: .. code-block:: text @@ -892,13 +890,13 @@ contains 3 reference properties. The tag ``refinst`` on each instance defines the corresponding reference instance so that the instances returned can be correlated back to their reference instances. -The resulting table output for the same command but with -o table is: +The resulting table output for the same command but with ``-o table`` is: Example: .. code-block:: text - $ pywbemcli instance shrub root/cimv2:TST_EP.InstanceID=1 + $ pywbemcli -o table instance shrub root/cimv2:TST_EP.InstanceID=1 Shrub of root/cimv2:TST_EP.InstanceID=1 +-----------+-------------------+--------------+--------------------+-------------------------+ @@ -922,8 +920,8 @@ Example: .. _`Qualifier command group`: -Qualifier command group ------------------------ +``qualifier`` command group +--------------------------- The ``qualifier`` command group has commands that act on CIM qualifier declarations: @@ -936,8 +934,8 @@ declarations: .. _`Qualifier get command`: -Qualifier get command -^^^^^^^^^^^^^^^^^^^^^ +``qualifier get`` command +^^^^^^^^^^^^^^^^^^^^^^^^^ The ``qualifier get`` command gets the specified qualifier declaration. @@ -964,8 +962,8 @@ See :ref:`pywbemcli qualifier get --help` for the exact help output of the comma .. _`Qualifier enumerate command`: -Qualifier enumerate command -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``qualifier enumerate`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``qualifier enumerate`` command enumerates the qualifier declarations in a namespace. @@ -1005,8 +1003,8 @@ See :ref:`pywbemcli qualifier enumerate --help` for the exact help output of the .. _`Server command group`: -Server command group --------------------- +``server`` command group +------------------------ The ``server`` command group has commands that interact with the WBEM server of the :term:`current connection` to access information about the @@ -1023,8 +1021,8 @@ WBEM server itself: .. _`Server brand command`: -Server brand command -^^^^^^^^^^^^^^^^^^^^ +``server brand`` command +^^^^^^^^^^^^^^^^^^^^^^^^ The ``server brand`` command gets the brand of the WBEM server of the :term:`current connection`. @@ -1054,8 +1052,8 @@ See :ref:`pywbemcli server brand --help` for the exact help output of the comman .. _`Server info command`: -Server info command -^^^^^^^^^^^^^^^^^^^ +``server info`` command +^^^^^^^^^^^^^^^^^^^^^^^ The ``server info`` command gets general information on the WBEM server of the :term:`current connection`. @@ -1100,8 +1098,8 @@ See :ref:`pywbemcli server info --help` for the exact help output of the command .. _`Server interop command`: -Server interop command -^^^^^^^^^^^^^^^^^^^^^^ +``server interop`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``server interop`` command gets the name of the Interop namespace of the WBEM server of the :term:`current connection`. @@ -1126,8 +1124,8 @@ See :ref:`pywbemcli server interop --help` for the exact help output of the comm .. _`Server namespaces command`: -Server namespaces command -^^^^^^^^^^^^^^^^^^^^^^^^^ +``server namespaces`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``server namespaces`` command lists the namespaces of the WBEM server of the :term:`current connection`. @@ -1159,8 +1157,8 @@ See :ref:`pywbemcli server namespaces --help` for the exact help output of the c .. _`Server profiles command`: -Server profiles command -^^^^^^^^^^^^^^^^^^^^^^^ +``server profiles`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``server profiles`` command lists the :term:`management profiles ` advertised by the @@ -1208,8 +1206,8 @@ See :ref:`pywbemcli server profiles --help` for the exact help output of the com .. _`Server centralinsts command`: -Server centralinsts command -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``server centralinsts`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``server centralinsts`` command gets the :term:`central instances` of the :term:`management profiles ` advertised by the @@ -1241,8 +1239,8 @@ See :ref:`pywbemcli server centralinsts --help` for the exact help output of the .. _`Connection command group`: -Connection command group ------------------------- +``connection`` command group +---------------------------- The ``connection`` command group has commands that manage named connection definitions that are persisted in a :term:`connections file`. @@ -1287,8 +1285,8 @@ The commands in this group are: .. _`Connection delete command`: -Connection delete command -^^^^^^^^^^^^^^^^^^^^^^^^^ +``connection delete`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``connection delete`` command deletes a connection definition from the :term:`connections file`. @@ -1323,8 +1321,8 @@ See :ref:`pywbemcli connection delete --help` for the exact help output of the c .. _`Connection export command`: -Connection export command -^^^^^^^^^^^^^^^^^^^^^^^^^ +``connection export`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``connection export`` command exports the current connection as a set of environment variables. @@ -1358,8 +1356,8 @@ See :ref:`pywbemcli connection export --help` for the exact help output of the c .. _`Connection list command`: -Connection list command -^^^^^^^^^^^^^^^^^^^^^^^ +``connection list`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``connection list`` command lists the connection definitions in the :term:`connections file` and also the current connection if it has not been @@ -1436,8 +1434,8 @@ See :ref:`pywbemcli connection list --help` for the exact help output of the com .. _`Connection save command`: -Connection save command -^^^^^^^^^^^^^^^^^^^^^^^ +``connection save`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``connection save`` command saves the current connection in the :term:`connections file` as a connection definition with the name specified @@ -1452,8 +1450,8 @@ See :ref:`pywbemcli connection save --help` for the exact help output of the com .. _`Connection select command`: -Connection select command -^^^^^^^^^^^^^^^^^^^^^^^^^ +``connection select`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``connection select`` command selects a connection definition from the :term:`connections file` to become the current connection. @@ -1464,7 +1462,7 @@ and prompts the user to pick the one to be selected. If there is only a single connection, that connection is selected without the user request. -If the ``--default`` command option is set, the connection definition in +If the ``--default``/``-d`` command option is set, the connection definition in addition becomes the default connection, by marking it accordingly in the :term:`connections file`. @@ -1513,8 +1511,8 @@ See :ref:`pywbemcli connection select --help` for the exact help output of the c .. _`Connection show command`: -Connection show command -^^^^^^^^^^^^^^^^^^^^^^^ +``connection show`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. index:: single: connection show command .. index:: pair: command; connection show @@ -1548,8 +1546,8 @@ See :ref:`pywbemcli connection show --help` for the exact help output of the com .. _`Connection test command`: -Connection test command -^^^^^^^^^^^^^^^^^^^^^^^ +``connection test`` command +^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. index:: single: connection test command @@ -1586,8 +1584,8 @@ See :ref:`pywbemcli connection test --help` for the exact help output of the com .. _`Repl command`: -Repl command ------------- +``repl`` command +---------------- .. index:: single: repl command @@ -1630,8 +1628,8 @@ search. .. _`Help command`: -Help command ------------- +``help`` command +---------------- .. index:: single: help command diff --git a/docs/pywbemcli/features.rst b/docs/pywbemcli/features.rst index 5692a3fb4..7cbf73605 100644 --- a/docs/pywbemcli/features.rst +++ b/docs/pywbemcli/features.rst @@ -25,7 +25,7 @@ syntactic implementation of the features. This includes: * The ability to receive either CIM instances or classes or only their names with only a change of an option on the commands that request CIM instances or - classes. The ``--names-only``/``-no`` command option defines whether only the + classes. The ``--names-only``/``--no`` command option defines whether only the name or the complete object will be displayed. * The ability to define complete INSTANCE name command arguments or @@ -95,21 +95,24 @@ DeleteQualifier Not Implemented Specifying CIM property and parameter values -------------------------------------------- -The :ref:`instance create command`, :ref:`instance modify command`, :ref:`class invokemethod command`, and -:ref:`instance invokemethod command` define the values of properties and parameters that -are to be applied to CIM instances and methods to be sent to the WBEM server. +The :ref:`instance create command`, :ref:`instance modify command`, +:ref:`class invokemethod command`, and :ref:`instance invokemethod command` +define the values of properties and parameters that are to be applied to CIM +instances and methods to be sent to the WBEM server. -For a single property or parameter this is the ``--property``/``-p`` or -``--parameter``/``-p`` option with the name and value in the form: +For a single property or parameter these are the ``--property``/``-p`` or +``--parameter``/``-p`` command options with its name and value in the form: .. code-block:: text + --property = + --parameter = -p = Where: * is the name of the of the property or parameter. -* is the value of the property or parameter The values represent the +* is the value of the property or parameter. The values represent the value of CIM types (ex. Uint32, String, etc.) or arrays of these types. .. code-block:: text @@ -148,21 +151,20 @@ The following are examples of scalar property definitions: -p pint=3 -p psint=-3 - For array properties the values are defined separated by commas: +For array properties the values are defined separated by commas: - .. code-block:: text +.. code-block:: text -p =(,) - For example: +For example: - .. code-block:: text +.. code-block:: text -p strarray=abc,def,ghjk -p strarray2=\"ab c\",def - .. _`Displaying CIM instances/classes or their names`: Displaying CIM instances/classes or their names @@ -173,12 +175,12 @@ The pywbem API includes different WBEM operations (ex. ``EnumerateInstances``, to request CIM objects or just their names. To simplify the overall command line syntax pywbemcli combines these into a single command (i.e. ``enumerate``, ``references``, ``associators``) in the :ref:`class command group` and the -:ref:`instance command group` and includes an option (``--no,`` or -``--names-only``) that determines whether the names or the CIM objects are -retrieved from the WBEM server. +:ref:`instance command group` and includes the +``--names-only``/``--no`` command option that determines whether the names or +the CIM objects are retrieved from the WBEM server. -Thus, for example an ``instance enumerate`` with and without the -``--names-only`` option: +Thus, for example an ``instance enumerate`` command with and without the +``--names-only``/``--no`` option: .. code-block:: text @@ -219,7 +221,7 @@ The instance name (INSTANCENAME argument) can be specified in two ways: * By specifying a complete untyped WBEM URI as defined in section :ref:`The INSTANCENAME command argument as a WBEM URI`. The namespace of the instance is the namespace specified in the WBEM URI, or the - namespace specified with the ``-namespace``/``-n`` command option, or the + namespace specified with the ``--namespace``/``-n`` command option, or the default namespace of the connection. Any host name in the WBEM URI will be ignored. @@ -227,13 +229,13 @@ The instance name (INSTANCENAME argument) can be specified in two ways: component of the WBEM URI, as defined in section :ref:`Interactively selecting INSTANCENAME command argument` (i.e. CLASSNAME.?). The namespace of the instance is the namespace specified with - the ``-namespace``/``-n`` command option, or the default namespace of the + the ``--namespace``/``-n`` command option, or the default namespace of the connection. If there is only a single instance, that instance is selected automaticaly with without user request. -* By specifying the WBEM URI without keybindings and using the --key option - to specify the keybindings ad defined in section - :ref:`Defining INSTANCENAME command argument with --key option`. The +* By specifying the WBEM URI without keybindings and using the + ``--key``/``-k`` command option to specify the keybindings ad defined in + section :ref:`Defining INSTANCENAME command argument with --key option`. The advantage of this technique is that it eliminates the use of the double quote surrounding the key values. @@ -372,15 +374,17 @@ interactive selection, as shown in the following example: .. _`Defining INSTANCENAME command argument with --key option`: -`Defining INSTANCENAME command argument with --key option` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Defining INSTANCENAME command argument with --key option +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The INSTANCENAME may be specified by a combination of the namespace/classname -as an argument with the --key option to define keybindings. Each --key option -definition defines a single keybinding in the form name=value. In general, -the value component does not require the double quote that is required with -WBEM_URL unless there are space characters in a string value. - - Example: +as an argument with the ``--key``/``-k`` command option to define keybindings. +Each ``--key``/``-k`` option definition defines a single keybinding in the form +``name=value``. +In general, the value component does not require the double quote that is +required with the WBEM URI format unless there are space characters in a string +value. + +Example:: CIM_Foo --key InstanceId=inst1 diff --git a/docs/pywbemcli/generaloptions.rst b/docs/pywbemcli/generaloptions.rst index f4eda0c3a..a4de3f978 100644 --- a/docs/pywbemcli/generaloptions.rst +++ b/docs/pywbemcli/generaloptions.rst @@ -195,8 +195,8 @@ applicable for all commands. For more details, see :ref:`Output formats`. Other miscellaneous general options """"""""""""""""""""""""""""""""""" -The :ref:`--verbose general option` displays extra information about the pywbemcli -internal processing. +The :ref:`--verbose general option` displays extra information about the +pywbemcli internal processing. The :ref:`--version general option` displays pywbemcli version information and the :ref:`--help general option` provides top level help @@ -207,15 +207,15 @@ information and the :ref:`--help general option` provides top level help General options descriptions """""""""""""""""""""""""""" -This section defines in detail the requirements, characteristics, and any special -syntax of each general option. +This section defines in detail the requirements, characteristics, and any +special syntax of each general option. .. index:: triple: --server; general options; server .. _`--server general option`: ---server general option -""""""""""""""""""""""" +``--server`` general option +""""""""""""""""""""""""""" The argument value of the ``--server``/``-s`` general option is a string that is the URL of the WBEM server to which pywbemcli will connect, in the format: @@ -253,8 +253,8 @@ Examples for the argument value of this option include: .. _`--name general option`: ---name general option -""""""""""""""""""""" +``--name`` general option +""""""""""""""""""""""""" The argument value of the ``--name``/``-n`` general option is a string that is the name of a connection definition in the :term:`connections file`. @@ -264,9 +264,9 @@ The parameters for this named connection definition will be loaded from the In the interactive mode the connection is not actually established until a command requiring access to the WBEM server is entered. -This option is mutually exclusive with :ref:`--server general option` and -:ref:`--mock-server general option` since each defines a connection to a WBEM -server. +This option is mutually exclusive with the :ref:`--server general option` and +the :ref:`--mock-server general option` since each defines a connection to a +WBEM server. The following example creates a connection definition named ``myserver`` in the connections file, and then uses that connection to execute @@ -286,8 +286,8 @@ connections. .. _`--default-namespace general option`: ---default-namespace general option -"""""""""""""""""""""""""""""""""" +``--default-namespace`` general option +"""""""""""""""""""""""""""""""""""""" The argument value of the ``--default-namespace``/``-d`` general option is a string that defines the default :term:`CIM namespace` to use for the target @@ -295,8 +295,8 @@ WBEM server. If this option is not specified, the default namespace will be ``root/cimv2``. -The default namespace will be used if the ``--namespace``/``-n`` command -option is not used on a command. +The default namespace will be used if the ``--namespace``/``-n`` command option +is not used on a command. Some commands execute against multiple or all namespaces, for example the the ``class find`` command. @@ -304,8 +304,8 @@ the ``class find`` command. .. _`--user general option`: ---user general option -""""""""""""""""""""" +``--user`` general option +""""""""""""""""""""""""" The argument value of the ``--user``/``-u`` general option is a string that is the user name for authenticating with the WBEM server. @@ -314,15 +314,15 @@ the user name for authenticating with the WBEM server. .. _`--password general option`: ---password general option -""""""""""""""""""""""""" +``--password`` general option +""""""""""""""""""""""""""""" -The argument value of the ``--password``/``-p`` general option is a string that is the -password for authenticating with the WBEM server. +The argument value of the ``--password``/``-p`` general option is a string that +is the password for authenticating with the WBEM server. -This option is normally required if the -:ref:`--user general option` is defined. If passwords are saved into the -:term:`connections file` they are not encrypted in the file. +This option is normally required if the :ref:`--user general option` is defined. +If passwords are saved into the :term:`connections file`, they are not encrypted +in the file. If the WBEM operations performed by any pywbemcli command require a password, the password is prompted for if ``--user``/``-u`` is used (in both modes of @@ -334,8 +334,8 @@ operation) and ``--password``/``-p`` is not used. Enter password: . . . -If both the ``--user``/``-u`` and ``--password``/``-p`` general options are -used, the command is executed without a password prompt: +If both ``--user``/``-u`` and ``--password``/``-p`` are used, the command is +executed without a password prompt: .. code-block:: text @@ -388,8 +388,8 @@ any subsequent pywbemcli commands: .. _`--timeout general option`: ---timeout general option -"""""""""""""""""""""""" +``--timeout`` general option +"""""""""""""""""""""""""""" The argument value of the ``--timeout``/``-t`` general option is an integer that defines the @@ -402,8 +402,8 @@ predefined timeout (normally 30 seconds) if this option is not defined. .. _`--verify general option`: ---verify general option -""""""""""""""""""""""" +``--verify`` general option +""""""""""""""""""""""""""" The pair of ``--verify`` and ``--no-verify`` general options control whether or not the client verifies any certificates received from the WBEM server. @@ -420,8 +420,8 @@ general option is used in interactive mode. .. _`--certfile general option`: ---certfile general option -""""""""""""""""""""""""" +``--certfile`` general option +""""""""""""""""""""""""""""" The argument value of the ``--certfile`` general option is the file path of a PEM file containing a X.509 client certificate to be presented to the WBEM @@ -438,8 +438,8 @@ https://pywbem.readthedocs.io/en/stable/client/security.html#authentication-type .. _`--keyfile general option`: ---keyfile general option -"""""""""""""""""""""""" +``--keyfile`` general option +"""""""""""""""""""""""""""" The argument value of the ``--keyfile`` general option is the file path of a PEM file containing the private key belonging to the public key that is @@ -447,17 +447,16 @@ part of the X.509 certificate. See :ref:`--certfile general option` for more information. Not required if the private key is part of the file defined in the -:ref:`--certfile general option`. ``keyfile`` is not allowed if -:ref:`--certfile general option` is not provided. Default: No client -key file. The client private key should then be part of the file defined by -``--certfile``. +``--certfile`` option. ``--keyfile`` is not allowed if ``--certfile`` is not +provided. Default: No client key file. The client private key should then be +part of the file defined by ``--certfile``. .. index:: triple: --ca-certs; general options; ca-certs .. _`--ca-certs general option`: ---ca-certs general option -"""""""""""""""""""""""""" +``--ca-certs`` general option +"""""""""""""""""""""""""""""" The argument value of the ``--ca-certs`` general option specifies which X.509 certificates are used on the client side for validating the X.509 @@ -497,7 +496,7 @@ The default behavior depends on the version of the installed pywbem package: The version of the installed pywbem package can be displayed using the :ref:`--version general option`. -Specifying the ``--no-verify`` general option (see :ref:`--verify general option`) +Specifying the ``--no-verify`` option (see :ref:`--verify general option`) bypasses client side verification of the WBEM server certificate. .. _PEM format: https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail @@ -509,8 +508,8 @@ bypasses client side verification of the WBEM server certificate. .. _`--timestats general option`: ---timestats general option -"""""""""""""""""""""""""" +``--timestats`` general option +"""""""""""""""""""""""""""""" The ``--timestats`` general option is a boolean option that enables the gathering and display of time @@ -522,15 +521,15 @@ operations executed, the size of the operations, and the execution time. .. _`--use-pull general option`: ---use-pull general option -"""""""""""""""""""""""""" +``--use-pull`` general option +"""""""""""""""""""""""""""""" The argument value of the ``--use-pull``/``-u`` general option determines whether the pull operations or :term:`traditional operations` are used for the ``instance enumerate``, ``instance references``, ``instance associators`` -and ``instance query`` commands. See :ref:`Pywbemcli and -the DMTF pull operations` for more information on pull operations. The choices -for the argument value are as follows: +and ``instance query`` commands. See +:ref:`Pywbemcli and the DMTF pull operations` for more information on pull +operations. The choices for the argument value are as follows: * ``yes`` - pull operations will be used and if the server does not support pull, the request will fail. @@ -542,8 +541,8 @@ for the argument value are as follows: .. _`--pull-max-cnt general option`: ---pull-max-cnt general option -"""""""""""""""""""""""""""""" +``--pull-max-cnt`` general option +""""""""""""""""""""""""""""""""" The argument value of the ``--pull-max-cnt`` general option is an integer passed to the WBEM server with the open and pull operation requests. @@ -556,8 +555,8 @@ DMTF pull operations` for more information on pull operations. .. _`--mock-server general option`: ---mock-server general option -"""""""""""""""""""""""""""" +``--mock-server`` general option +"""""""""""""""""""""""""""""""" The argument value of the ``--mock-server``/``-m`` general option is a file path of a MOF file or Python script that loads a mock WBEM server in the @@ -596,8 +595,8 @@ the files for a mock server. .. _`--output-format general option`: ---output-format general option -"""""""""""""""""""""""""""""" +``--output-format`` general option +"""""""""""""""""""""""""""""""""" The argument value of the ``--output-format``/``-o`` general option is a string that defines the output format in which the result of any pywbemcli commands @@ -609,8 +608,8 @@ For details, see :ref:`Output formats`. .. _`--log general option`: ---log general option -"""""""""""""""""""" +``--log`` general option +"""""""""""""""""""""""" The argument value of the ``--log``/``-l`` general option defines the destination and parameters of logging of the requests and responses to the WBEM @@ -622,8 +621,8 @@ For details, see :ref:`Pywbemcli defined logging`. .. _`--verbose general option`: ---verbose general option -"""""""""""""""""""""""" +``--verbose`` general option +"""""""""""""""""""""""""""" The ``--verbose``/``-v`` general option is a boolean option that enables the display of extra information about the processing. @@ -637,8 +636,8 @@ command completion. .. _`--pdb general option`: ---pdb general option -"""""""""""""""""""" +``--pdb`` general option +"""""""""""""""""""""""" The ``--pdb`` general option is a boolean option that enables debugging with the built-in pdb debugger. @@ -654,8 +653,8 @@ built-in pdb debugger. .. _`--version general option`: ---version general option -"""""""""""""""""""""""" +``--version`` general option +"""""""""""""""""""""""""""" The ``--version`` general option displays the version of the pywbemcli command and the version of the pywbem package used by it, and then exits. @@ -664,8 +663,8 @@ command and the version of the pywbem package used by it, and then exits. .. _`--help general option`: ---help general option -""""""""""""""""""""" +``--help`` general option +""""""""""""""""""""""""" The ``--help``/``-h`` general option displays help text which describes the command groups and general options, and then exits. @@ -762,8 +761,8 @@ Pywbemcli and the DMTF pull operations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The DMTF specifications and pywbem includes two ways to execute the enumerate -instance type operations (``Associators``, ``References``,`` -EnumerateInstances``, ``ExecQuery``): +instance type operations (``Associators``, ``References``, +``EnumerateInstances``, ``ExecQuery``): * The :term:`traditional operations` (ex. ``EnumerateInstances``) * The pull operations (ex. ``OpenEnumerateInstances``, etc.) @@ -834,9 +833,10 @@ pull operations are not supported in the WBEM server: Output formats ^^^^^^^^^^^^^^ -Pywbemcli supports multiple output formats to present command results. The output -format can be selected with the ``--output-format``/``-o`` option. The allowed -output formats are different for the various command groups and commands. +Pywbemcli supports multiple output formats to present command results. The +output format can be selected with the :ref:`--output-format general option`. +The allowed output formats are different for the various command groups and +commands. The output formats fall into several groups: @@ -881,87 +881,57 @@ Output formats for groups and commands Each of the commands may allow only a subset of the possible ouput formats. Thus, the `server brand` only outputs data in a table format so there is no defined -default format for the `--output-format` general option. - -The following shows the default format for each command the the alternate -format groups where the groups are: - -objects = xml|repr|txt - -table = table|plain|simple|grid|psql|rst|html - -+----------+---------------+----------+----------------+--------------------------------------------+ -|Group |Command | Default | Alternates | Comments | -+==========+===============+==========+================+============================================+ -| class | associators | 'mof' | objects | See Note 1 below. | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | delete | None | None | Nothing returned | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | enumerate | 'mof' | objects | See Note 1 below. | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | find | 'simple' | table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | get | 'mof' | objects | See Note 1 below. | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | invokemethod | 'mof' | objects | See Note 1 below. | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | references | 'mof' | objects | See Note 1 below. | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | tree | None | None | Only outputs as ascii tree | -+----------+---------------+----------+----------------+--------------------------------------------+ -|instance | associators | 'mof' | objects, table | output as cim object or table of properties| -+----------+---------------+----------+----------------+--------------------------------------------+ -| | count | 'simple' | table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | create | None | | Nothing returned | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | delete | None | | Nothing returned | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | enumerate | 'mof' | objects, table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | get | 'mof' | objects, table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | invokemethod | 'mof' | objexts, table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | modify | None | None | Nothing returned | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | references | 'mof' | table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -|qualifier | enumerate | 'mof' | table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | get | 'mof' | table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -|server | brand | 'text' | text | Alternate is table format | -+----------+---------------+----------+----------------+--------------------------------------------+ -| |centralinsts | 'simple' | table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | info | 'simple' | table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | interop | 'text' | text | Alternate is table format | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | namespaces | 'simple' | table | Alternate is text format | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | profiles | 'simple' | table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -|connection| delete | None | table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | export | None | table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | list | 'simple' | table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | save | None | table | | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | select | None | None | | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | show | None | | Currently ignores output format | -+----------+---------------+----------+----------------+--------------------------------------------+ -| | test | None | None | | -+----------+---------------+----------+----------------+--------------------------------------------+ +default format for the :ref:`--output-format general option`. + +The following shows the default format for each command and the alternate +formats where the values mean: + +objects: ``xml``, ``repr``, or ``txt`` + +table: ``table``, ``plain``, ``simple``, ``grid``, ``psql``, ``rst``, or ``html`` + +========== ============= ======== ============== ============================================ +Group Command Default Alternates Comments +========== ============= ======== ============== ============================================ +class associators 'mof' objects See Note 1 below +class delete None None Nothing returned +class enumerate 'mof' objects See Note 1 below +class find 'simple' table +class get 'mof' objects See Note 1 below +class invokemethod 'mof' objects See Note 1 below +class references 'mof' objects See Note 1 below +class tree None None Only outputs as ascii tree +instance associators 'mof' objects, table Output as cim object or table of properties +instance count 'simple' table +instance create None None Nothing returned +instance delete None None Nothing returned +instance enumerate 'mof' objects, table +instance get 'mof' objects, table +instance invokemethod 'mof' objects, table +instance modify None None Nothing returned +instance references 'mof' table +qualifier enumerate 'mof' table +qualifier get 'mof' table +server brand 'text' text Alternate is table format +server centralinsts 'simple' table +server info 'simple' table +server interop 'text' text Alternate is table format +server namespaces 'simple' table Alternate is text format +server profiles 'simple' table +connection delete None table +connection export None table +connection list 'simple' table +connection save None table +connection select None None +connection show None None Currently ignores output format +connection test None None +========== ============= ======== ============== ============================================ NOTES: -1. While the display of classes allows only CIM object display format (`mof`, etc.) the display with - the --names-only or --summary formats allows table output also. +1. The display of classes with the ``--names-only``/``--no`` or + ``--summary``/``-s`` command options allows table output formats in addition + to the objects output formats. .. index:: pair: output formats; table formats @@ -1169,8 +1139,8 @@ The output of CIM objects allows multiple formats as follows: This should be considered the output of last resort as it simply uses the ``__str__()`` method of the Python class for each CIM object to output. - Thus, for example the a ``class enumerate`` of a model with only a single - class is of the form: + Thus, for example a ``class enumerate`` command of a model with only a single + class creates output of the form: .. code-block:: text @@ -1185,7 +1155,7 @@ ASCII tree format This output format is an ASCII based output that shows the tree structure of the results of the ``class tree`` command. It is the only output format supported by this command, and therefore it is automatically selected and -cannot be specified explicitly with the ``--output-format`` option. +cannot be specified explicitly with the :ref:`--output-format general option`. .. code-block:: text @@ -1235,7 +1205,7 @@ Pywbemcli provides logging to either a file or the standard error stream of information passing between the pywbemcli client and a WBEM server using the standard Python logging facility. -Logging is configured and enabled using the ``--log`` general option on the +Logging is configured and enabled using the :ref:`--log general option` on the commmand line or the `PYWBEMCLI_LOG` environment variable. Pywbemcli can log operation calls that send diff --git a/docs/pywbemcli/mock_support.rst b/docs/pywbemcli/mock_support.rst index b022bfbc3..c6486f3a4 100644 --- a/docs/pywbemcli/mock_support.rst +++ b/docs/pywbemcli/mock_support.rst @@ -10,12 +10,12 @@ Mock WBEM server support Mock support overview --------------------- -Pywbemcli has support for mocking a WBEM server with the general option -:ref:`--mock-server general option` (``--mock-server/-m``) . This allows -executing pywbemcli against a mock WBEM server that is automatically created in -pywbemcli, rather than a real WBEM server. +Pywbemcli has support for mocking a WBEM server with the +:ref:`--mock-server general option`. This allows executing pywbemcli against a +mock WBEM server that is automatically created in pywbemcli, rather than a real +WBEM server. -The :ref:`--mock-server general option` is mutually exclusive with the +The ``--mock-server`` option is mutually exclusive with the :ref:`--server general option` and :ref:`--name general option`, since each defines a WBEM server. @@ -25,7 +25,7 @@ CIM namespaces. The operations performed against the mock WBEM server cause that mock repository to be inspected or manipulated accordingly. The mock repository can be loaded with CIM objects from files specified as an -argument to the :ref:`--mock-server general option`. Each use of the option +argument to the ``--mock-server`` option. Each use of the option specifies one file path of such a file. The option may be used multiple times and each specified file is processed sequentially, in the sequence of the options on the command line. @@ -44,8 +44,8 @@ The following types of files are supported for the ``--mock-server`` option: At this point, these CIM objects can be added to only one :term:`CIM namespace` in the repository of the mock WBEM server, namely the - default namespace of the connection (see ``--default-namespace`` global - option). + default namespace of the connection (see + :ref:`--default-namespace general option`). If a CIM object already exists in the repository, it is updated accordingly. @@ -68,8 +68,8 @@ The following types of files are supported for the ``--mock-server`` option: for the mock repository. * ``VERBOSE`` (bool): - A flag that contains the value of the boolean ``--verbose`` general - option of pywbemcli. + A flag that contains the value of the boolean + :ref:`--verbose general option` of pywbemcli. The Python script can for example create Python objects of type :class:`~pywbem.CIMQualifierDeclaration`, :class:`~pywbem.CIMClass` and @@ -81,7 +81,7 @@ The following types of files are supported for the ``--mock-server`` option: by implementing callbacks via :func:`pywbem_mock.method_callback_interface`, for handling CIM method invocations against the mock WBEM server. -Pywbemcli logging (``-l`` or ``--log`` general option) can be used together +Pywbemcli logging (see :ref:`--log general option`) can be used together with the mock support. Since the mock support does not use HTTP(S), only the "api" component in the log configuration string will generate any log output. @@ -154,9 +154,9 @@ and then to enumerate its CIM class names is:: The following is Python code (in a file ``tst_file.py``) that will add the same CIM objects as in the MOF file to the mock repository using -:meth:`~pywbem_mock.FakedWBEMConnection.add_cim_objects`. If the ``--verbose`` -general option is set on the pywbemcli command line, the mock repository will -be displayed: +:meth:`~pywbem_mock.FakedWBEMConnection.add_cim_objects`. If the +:ref:`--verbose general option` is set on the pywbemcli command line, the +mock repository will be displayed: .. code-block:: python @@ -262,7 +262,7 @@ course the Python script can contain logic, and it provides for implementing CIM method calls via callbacks. It is possible to mix MOF files and Python scripts by specifying the -``--mock-server`` option multiple times. +:ref:`--mock-server general option` multiple times. The pywbemcli command to use this Python file for loading into a mock WBEM server, and then to enumerate its CIM class names is::