Pywbem - A WBEM client and related utilities, written in pure Python
====================================================================

.. |pywbem-version| replace:: 0.11.0

.. PyPI download statistics are broken, but the new PyPI warehouse makes PyPI
.. download statistics available through Google BigQuery
.. (https://bigquery.cloud.google.com).
.. Query to list package downloads by version:
..
   SELECT
     file.project,
     file.version,
     COUNT(*) as total_downloads,
     SUM(CASE WHEN REGEXP_EXTRACT(details.python, r"^([^\.]+\.[^\.]+)") = "2.6" THEN 1 ELSE 0 END) as py26_downloads,
     SUM(CASE WHEN REGEXP_EXTRACT(details.python, r"^([^\.]+\.[^\.]+)") = "2.7" THEN 1 ELSE 0 END) as py27_downloads,
     SUM(CASE WHEN REGEXP_EXTRACT(details.python, r"^([^\.]+)\.[^\.]+") = "3" THEN 1 ELSE 0 END) as py3_downloads,
   FROM
     TABLE_DATE_RANGE(
       [the-psf:pypi.downloads],
       TIMESTAMP("19700101"),
       CURRENT_TIMESTAMP()
     )
   WHERE
     file.project = 'pywbem'
   GROUP BY
     file.project, file.version
   ORDER BY
     file.version DESC

.. image:: https://img.shields.io/pypi/v/pywbem.svg
    :target: https://pypi.python.org/pypi/pywbem/
    :alt: Version on Pypi

.. # .. image:: https://img.shields.io/pypi/dm/pywbem.svg
.. #     :target: https://pypi.python.org/pypi/pywbem/
.. #     :alt: Pypi downloads

.. image:: https://travis-ci.org/pywbem/pywbem.svg?branch=master
    :target: https://travis-ci.org/pywbem/pywbem
    :alt: Travis test status (master)

.. image:: https://ci.appveyor.com/api/projects/status/i022iaeu3dao8j5x/branch/master?svg=true
    :target: https://ci.appveyor.com/project/andy-maier/pywbem
    :alt: Appveyor test status (master)

.. image:: https://readthedocs.org/projects/pywbem/badge/?version=latest
    :target: http://pywbem.readthedocs.io/en/latest/
    :alt: Docs build status (latest)

.. image:: https://img.shields.io/coveralls/pywbem/pywbem.svg
    :target: https://coveralls.io/r/pywbem/pywbem
    :alt: Test coverage (master)

.. contents:: **Contents:**
   :local:

Overview
--------

Pywbem is a WBEM client and WBEM indication listener, written in pure Python.
It runs on Python 2 and Python 3.

The major components of pywbem are shown in this diagram:

.. image:: images/pywbemcomponents.png
    :width: 400px
    :align: right
    :height: 250px
    :alt: alternate text

A WBEM client allows issuing operations to a WBEM server, using the CIM
operations over HTTP (CIM-XML) protocol defined in the DMTF standards
DSP0200 and DSP0201. The CIM/WBEM infrastructure is used for a wide
variety of systems management tasks supported by systems running WBEM servers.
See `WBEM Standards <http://www.dmtf.org/standards/wbem>`_ for more
information about WBEM and these standards.

A `WBEM indication listener`_ allows receiving indications generated by a
WBEM server.

.. _WBEM indication listener: http://pywbem.readthedocs.io/en/stable/indication.html#wbemlistener

Pywbem also includes higher level classes to support typical WBEM client
activities:

* `WBEMSubscriptionManager`_ -  provides APIs for viewing and managing
  indication subscriptions on a WBEM server.

.. _WBEMSubscriptionManager: http://pywbem.readthedocs.io/en/stable/indication.html#wbemsubscriptionmanager

* `WBEMServer`_ - provides APIs for managing basic characteristics of
  a WBEM server including:

.. _WBEMServer: http://pywbem.readthedocs.io/en/stable/server.html

  - finding CIM namespaces and the Interop namespace,
  - finding WBEM management profiles,
  - finding basic information about the WBEM server.


Installation
------------

.. |os-setup-link-pre| raw:: html

    <a href="https://github.com/pywbem/pywbem/raw/v

.. |os-setup-link-post| raw:: html

    /pywbem_os_setup.sh">pywbem_os_setup.sh</a>

.. |os-setup-link| replace:: |os-setup-link-pre|\ |pywbem-version|\ |os-setup-link-post|

* You first need to ensure that prerequisite OS-level packages are installed:

  * Download the |os-setup-link| script (for pywbem version |pywbem-version|)

  * Execute that script:

    .. code-block:: bash

        $ ./pywbem_os_setup.sh

* Then, install the pywbem Python package using Pip:

  .. code-block:: bash

      $ pip install pywbem

  This will also install any prerequisite Python packages.

For more details and alternative ways to install, see the
`Installation section`_ in the pywbem documentation.

.. _Installation section: http://pywbem.readthedocs.io/en/stable/intro.html#installation

Usage
-----

For information on how to use pywbem, or how to contribute to it, go to the
`pywbem documentation`_ .

.. _pywbem documentation: http://pywbem.readthedocs.io/en/stable/

Documentation
-------------

The lastest pywbem documentation is available on ReadTheDocs:

* `Documentation for latest version on Pypi`_

.. _Documentation for latest version on Pypi: http://pywbem.readthedocs.io/en/stable/

* `Documentation for master branch in the Git repo`_

.. _Documentation for master branch in the Git repo: http://pywbem.readthedocs.io/en/latest/

The documentation includes API documentation, user documentation,
tutorial documentation, developer documentation.

This includes a number of Jupyter notebooks that act as a
`pywbem tutorial`_ and provide working examples of pywbem API usage.

.. _pywbem tutorial: http://pywbem.readthedocs.io/en/stable/tutorial.html

There are also a number of `presentations`_ on the status, concepts, and implementation
of pywbem available in readthedocs.

.. _presentations: http://pywbem.github.io/pywbem/documentation.html

Command line tools
------------------

Pywbem includes two command line tools:

*  `wbemcli`_ - An interactive shell for issuing WBEM operations against a WBEM
   server. In addition to executing the WBEM operations directly, simple
   scripts can be created to be executed within `wbemcli`.

.. _wbemcli: http://pywbem.readthedocs.io/en/stable/utilities.html#wbemcli

*  `mof_compiler`_ - A MOF compiler to compile MOF into repositories (e.g.
   WBEM servers) or to test compile MOF.

.. _mof_compiler: http://pywbem.readthedocs.io/en/stable/utilities.html#mof-compiler


QuickStart
----------

The following simple example script lists the namespaces and the Interop
namespace in a particular WBEM server:

.. code-block:: python

    #!/usr/bin/env python

    import pywbem

    server_uri = 'http://localhost'
    user = 'fred'
    password = 'blah'

    conn = pywbem.WBEMConnection(server_uri, (user, password),
                                 default_namespace=namespace)

    server = pywbem.WBEMServer(conn)

    print("Interop namespace:\n  %s" % server.interop_ns)

    print("All namespaces:")
    for ns in server.namespaces:
        print("  %s" % ns)

Project Planning
----------------

For each upcoming release, the bugs and feature requests that are planned to
be addressed in that release are listed in the
`issue tracker <https://github.com/pywbem/pywbem/issues>`_
with an according milestone set that identifies the target release.
The due date on the milestone definition is the planned release date.
There is usually also an issue that sets out the major goals for an upcoming
release.

Planned Next Release
--------------------

Pywbem 0.12.0 is in development.

Pywbem github `Issue 771`_ defines the basic direction for release 0.12.0

.. _Issue 771: https://github.com/pywbem/pywbem/issues/771

Contributing
------------

For information on how to contribute to pywbem, see the Development
section in the documentation.

License
-------

Pywbem is provided under the
`GNU Lesser General Public License (LGPL) version 2.1
<https://raw.githubusercontent.com/pywbem/pywbem/master/pywbem/LICENSE.txt>`_,
or (at your option) any later version.
