0.9.4.0 - finished docu for the additions

Simont3 · Dec 17, 2015 · d4ee92e · d4ee92e
1 parent ac8e8fd
commit d4ee92e
Show file tree

Hide file tree

Showing 6 changed files with 168 additions and 69 deletions.
diff --git a/src/CHANGELOG.rst b/src/CHANGELOG.rst
@@ -1,7 +1,7 @@
 Release History
 ===============
 
-**0.9.4-0 2015-XX-XX**
+**0.9.4-0 2015-12-17**
 
 *   Added:
 

diff --git a/src/docs/40_mapi/40-3_mapi-chargeback.rst b/src/docs/40_mapi/40-3_mapi-chargeback.rst
@@ -1,44 +1,49 @@
 MAPI - Chargeback Resources
 ===========================
 
-.. versionadded:: 0.9.4
+..  versionadded:: 0.9.4
 
-.. automodule:: hcpsdk.mapi
-   :synopsis: Access to selected Management API (:term:`MAPI`) functionality.
+..  automodule:: hcpsdk.mapi
+    :synopsis: Access to selected Management API (:term:`MAPI`) functionality.
 
 This class allows to request chargback reports from HCP.
 
+| HCP needs to have MAPI enabled for the system itself as well as for every
+  *Tenant* to collect from.
+| A system-level user can collect summed-up reports from all *Tenants* that
+  have MAPI enabled; he can collect *Namespace*-level reports from all
+  *Tenants* that have granted system-level admin access.
+| A *Tenant*-level admin can collect reports for *Namespaces* as well as
+  a summed-up report for the *Tenant* itself.
+
 
 Classes
 ^^^^^^^
 
-.. _hcpsdk_mapi_chargeback:
-
-.. autoclass:: Chargeback
+..  _hcpsdk_mapi_chargeback:
 
-   **Class constants:**
+..  autoclass:: Chargeback
 
-  Collection periods:
+    **Class constants:**
 
-     .. attribute:: CBG_DAY
-     .. attribute:: CBG_HOUR
-     .. attribute:: CBG_TOTAL
+        Collection periods:
 
-  Output formats:
+            .. attribute:: CBG_DAY
+            .. attribute:: CBG_HOUR
+            .. attribute:: CBG_TOTAL
 
-     .. attribute:: CBM_CSV
-     .. attribute:: CBM_JSON
-     .. attribute:: CBM_XML
+        Output formats:
 
+            .. attribute:: CBM_CSV
+            .. attribute:: CBM_JSON
+            .. attribute:: CBM_XML
 
-   **Class attributes**
 
+    **Class methodes**
 
-   **Class methodes:**
+        .. automethod:: request
 
-   .. automethod:: request
-
-   .. automethod:: close
+        .. automethod:: close
 
 
 Exceptions
@@ -49,9 +54,61 @@ Exceptions
 Sample Code
 ^^^^^^^^^^^
 
-None, yet.
-
-Sample Output
-^^^^^^^^^^^^^
+Note that the last record in this example shows the *Tenants* overall values,
+while the the record before shows statistics for a single *Namespace*.
+
+::
+
+    >>> import hcpsdk
+    >>> auth = hcpsdk.NativeAuthorization('service', 'service01')
+    >>> tgt = hcpsdk.Target('admin.hcp73.archivas.com', auth,
+                            port=hcpsdk.P_MAPI)
+    >>> cb = hcpsdk.mapi.Chargeback(tgt)
+    >>> result = cb.request(tenant='m',
+                            granularity=hcpsdk.mapi.Chargeback.CBG_TOTAL,
+                            fmt=hcpsdk.mapi.Chargeback.CBM_JSON)
+    >>> print(result.read())
+    {
+      "chargebackData" : [ {
+        "systemName" : "hcp73.archivas.com",
+        "tenantName" : "m",
+        "namespaceName" : "n1",
+        "startTime" : "2015-11-04T15:27:29+0100",
+        "endTime" : "2015-12-17T20:35:33+0100",
+        "valid" : false,
+        "deleted" : "false",
+        "bytesOut" : 0,
+        "reads" : 0,
+        "writes" : 0,
+        "deletes" : 0,
+        "tieredObjects" : 0,
+        "tieredBytes" : 0,
+        "metadataOnlyObjects" : 0,
+        "metadataOnlyBytes" : 0,
+        "bytesIn" : 0,
+        "storageCapacityUsed" : 25306468352,
+        "ingestedVolume" : 25303387299,
+        "objectCount" : 7219
+      }, {
+        "systemName" : "hcp73.archivas.com",
+        "tenantName" : "m",
+        "startTime" : "2015-11-04T15:27:29+0100",
+        "endTime" : "2015-12-17T20:35:33+0100",
+        "valid" : false,
+        "deleted" : "false",
+        "bytesOut" : 2156,
+        "reads" : 2,
+        "writes" : 1,
+        "deletes" : 1,
+        "tieredObjects" : 0,
+        "tieredBytes" : 0,
+        "metadataOnlyObjects" : 0,
+        "metadataOnlyBytes" : 0,
+        "bytesIn" : 5944,
+        "storageCapacityUsed" : 25607081984,
+        "ingestedVolume" : 25427708304,
+        "objectCount" : 65607
+      } ]
+    }
+    >>> cb.close()
 
-None, yet.
diff --git a/src/docs/40_mapi/40-4-mapi-tenant.rst b/src/docs/40_mapi/40-4-mapi-tenant.rst
@@ -8,6 +8,8 @@ MAPI - Tenant Resources
 
 This class allows to work with the *Tenant* resources in HCP.
 
+| HCP needs to have MAPI enabled at the system-level.
+
 
 Methods
 ^^^^^^^
@@ -34,10 +36,6 @@ Classes
 
     ..  automethod:: close
 
-
-
-
-
 Exceptions
 ^^^^^^^^^^
 
@@ -46,9 +44,63 @@ Exceptions
 Sample Code
 ^^^^^^^^^^^
 
-None, yet.
 
-Sample Output
-^^^^^^^^^^^^^
 
-None, yet.
+..  code-block:: text
+    :emphasize-lines: 13-19
+
+    >>> from pprint import pprint
+    >>> import hcpsdk
+    >>> auth = hcpsdk.NativeAuthorization('service', 'service01')
+    >>> tgt = hcpsdk.Target('admin.hcp73.archivas.com', auth, port=hcpsdk.P_MAPI)
+    >>> tenants = hcpsdk.mapi.listtenants(tgt)
+    >>> pprint(tenants)
+    [<hcpsdk.mapi.tenant.Tenant object at 0x1032ce6a0>,
+     <hcpsdk.mapi.tenant.Tenant object at 0x1032ce748>,
+     <hcpsdk.mapi.tenant.Tenant object at 0x1032ce7b8>,
+     <hcpsdk.mapi.tenant.Tenant object at 0x1032ce828>,
+     <hcpsdk.mapi.tenant.Tenant object at 0x1032ce898>,
+     <hcpsdk.mapi.tenant.Tenant object at 0x1032ce908>]
+    >>> tenants[0].name
+    'Default'
+    >>> pprint(tenants[0].info())
+    {'snmpLoggingEnabled': False,
+     'syslogLoggingEnabled': False,
+     'systemVisibleDescription': '',
+     'tenantVisibleDescription': ''}
+
+..  Warning::
+
+    | The :term:`Default Tenant` has far less properties compared to the
+      :term:`usual Tenants <Tenant>` HCP provides.
+    | See :doc:`Appendix 1 <../A0_appendixes/A1_apdx1_defns>`.
+
+..  code-block:: text
+    :emphasize-lines: 1-22
+
+    >>> tenants[1].name
+    'm'
+    >>> pprint(tenants[1].info())
+    {'administrationAllowed': True,
+     'authenticationTypes': {'authenticationType': ['LOCAL', 'EXTERNAL']},
+     'complianceConfigurationEnabled': True,
+     'dataNetwork': '[hcp_system]',
+     'hardQuota': '200.00 GB',
+     'managementNetwork': '[hcp_system]',
+     'maxNamespacesPerUser': 100,
+     'name': 'm',
+     'namespaceQuota': 'None',
+     'replicationConfigurationEnabled': True,
+     'searchConfigurationEnabled': True,
+     'servicePlanSelectionEnabled': True,
+     'snmpLoggingEnabled': False,
+     'softQuota': 85,
+     'syslogLoggingEnabled': False,
+     'systemVisibleDescription': 'Der üblicherweise als erstes erzeugte Tenant...',
+     'tags': {'tag': []},
+     'tenantVisibleDescription': '',
+     'versioningConfigurationEnabled': True}
+    >>> for t in tenants:
+    ...     t.close()
+    ...
+    >>>
diff --git a/src/docs/B0_glossary.rst b/src/docs/B0_glossary.rst
@@ -13,19 +13,25 @@ Glossary
         for more details.
 
     Tenant
-        A Tenant within HCP is an administrative entity that allows to configure and
-        manage a set of :term:`namespaces <Namespace>` within a configurable storage quota, along with the
-        user account required to access data.
+        A Tenant within HCP is an administrative entity that allows to
+        configure and manage a set of :term:`namespaces <Namespace>` within a
+        configurable storage quota, along with the user account required to
+        access data.
+
+    Default Tenant
+        The legacy Tenant, containing the :term:`Default Namespace`, only.
+        Seldomly used in our days, deprecated.
+        (*default.hcp.domain.com*)
 
     Namespace
-        A Namespace is a addressable data store, separated from other namespaces, having
-        an individual filesystem-like structure, several access protocols along with a
-        set of other configurables.
+        A Namespace is a addressable data store, separated from other
+        namespaces, having an individual filesystem-like structure, several
+        access protocols along with a set of other configurables.
 
     Default Namespace
-        The legacy Namespace, a relict from the time before HCP version 3. Doesn't support
-        user authentication. Seldomly used in our days, deprecated.
-        (*default.default.hcp.domain.com* or *www.hcp.domain.com*)
+        The legacy Namespace, a relict from the time before HCP version 3.
+        Doesn't support user authentication. Seldomly used in our days,
+        deprecated. (*default.default.hcp.domain.com* or *www.hcp.domain.com*)
 
     Data Access Account
         A local user within a :term:`Tenant`

diff --git a/src/hcpsdk/mapi/chargeback/__init__.py b/src/hcpsdk/mapi/chargeback/__init__.py
@@ -61,8 +61,14 @@ class Chargeback(object):
 
     def __init__(self, target, timeout=600, debuglevel=0):
         '''
-        :param target:      an hcpsdk.Target object
-        :param timeout:     the connection timeout
+        :param target:      an hcpsdk.Target object pointing to an HCP FQDN
+                            starting with **admin.** for access from a system
+                            level account or **<tenant>.** for a tenant level
+                            account
+        :param timeout:     the connection timeout; relatively high per
+                            default, as generating the report can take longer
+                            than **hcpsdk**\ s default of 30 seconds on a busy
+                            system
         :param debuglevel:  0..9 (used in *http.client*)
         '''
         self.logger = logging.getLogger(__name__ + '.Chargeback')
@@ -80,7 +86,7 @@ def __init__(self, target, timeout=600, debuglevel=0):
     def request(self, tenant=None, start=None, end=None,
                 granularity=CBG_TOTAL, fmt=CBM_JSON):
         '''
-        Request a chargeback report
+        Request a chargeback report for a Tenant.
 
         :param tenant:      the *Tenant* to collect from
         :param start:       starttime (a datetime object)
@@ -148,6 +154,6 @@ def request(self, tenant=None, start=None, end=None,
 
     def close(self):
         '''
-        Close the underlying *hcpsdk.Connection* object
+        Close the underlying *hcpsdk.Connection* object.
         '''
         self.con.close()
diff --git a/src/hcpsdk/mapi/tenant/__init__.py b/src/hcpsdk/mapi/tenant/__init__.py
@@ -122,28 +122,6 @@ def info(self, cache=True):
 
         :param cache:   a bool indicating if cached information shall be used
         :return:        a dict holding the Tenants settings
-
-        ::
-
-            {'administrationAllowed': True,
-             'authenticationTypes': {'authenticationType': ['LOCAL', 'EXTERNAL']},
-             'complianceConfigurationEnabled': True,
-             'dataNetwork': '[hcp_system]',
-             'hardQuota': '200.00 GB',
-             'managementNetwork': '[hcp_system]',
-             'maxNamespacesPerUser': 100,
-             'name': 'm',
-             'namespaceQuota': 'None',
-             'replicationConfigurationEnabled': True,
-             'searchConfigurationEnabled': True,
-             'servicePlanSelectionEnabled': True,
-             'snmpLoggingEnabled': False,
-             'softQuota': 85,
-             'syslogLoggingEnabled': False,
-             'systemVisibleDescription': 'Der üblicherweise als erstes erzeugte Tenant...',
-             'tags': {'tag': []},
-             'tenantVisibleDescription': '',
-             'versioningConfigurationEnabled': True}
         """
 
         if not self._settings or not cache: