Merge branch 'release-v3.5.0'

* release-v3.5.0:
  Add custom environment loading
  Update CWOM versions

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.4.5
+current_version = 3.5.0
 commit = False
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\.(?P<release>[a-z]+)(?P<build>\d*))?
 serialize = 

docs/source/conf.py

@@ -73,9 +73,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'3.4.5'
+version = u'3.5.0'
 # The full version, including alpha/beta/rc tags.
-release = u'3.4.5'
+release = u'3.5.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/start.rst

@@ -83,6 +83,18 @@ Contributors:
   * Ryan Geyer
 
 
+Turbonomic REST API Guides
+==========================
+
+The following published user guides are available to aid in developing against
+the Turbonomic API. Additional resources are availble at https://docs.turbonomic.com/.
+
+  * `XL 8.0.1 <https://docs.turbonomic.com/docApp/doc/index.html?config=8.0.json#!/MAPPED&DEFAULT_DEDICATED_XL&showToc=1>_`
+  * `XL 7.22.2 <https://docs.turbonomic.com/pdfdocs/Turbonomic_User_Guide_7.21.2.pdf>_`
+  * `Unofficial User Guide <http://rsnyc.sdf.org/vmt/>`_ for 6.0.
+  * `6.0 <https://archive.turbonomic.com/wp-content/uploads/docs/Turbonomic_REST_API_PRINT_60.pdf>`_
+  * `5.9 <https://archive.turbonomic.com/wp-content/uploads/docs/VMT_REST2_API_PRINT.pdf>`_
+
 License
 =======
 

vmtconnect/__about__.py

@@ -13,7 +13,7 @@
 
 __title__ = 'vmtconnect'
 __description__ = 'Turbonomic API Client'
-__version__ = '3.4.5'
+__version__ = '3.5.0'
 __author__ = 'R.A. Stern'
 __author_email__ = 'richard.stern@turbonomic.com'
 __license__ = 'Apache 2.0'

vmtconnect/__init__.py

@@ -19,7 +19,9 @@
 import datetime
 import json
 import math
+import os
 import re
+import sys
 import warnings
 
 import requests
@@ -114,6 +116,15 @@
     '<=': 'LTE'
 }
 
+ENV = {}
+GLOBAL_ENV = 'vmtconnect.env'
+SCRIPT_ENV = None
+
+try:
+    SCRIPT_ENV = os.path.splitext(sys.argv[0])[0] + '.env'
+except Exception:
+    pass
+
 
 
 ## ----------------------------------------------------
@@ -495,7 +506,7 @@ class Pager:
         **kwargs: Additional :py:class:`requests.Request` keyword arguments.
 
     Attributes:
-        all (list): Collect and list of all responses combined.
+        all (list): Collect and list all responses combined.
         complete (bool): Flag indicating the cursor has been exhausted.
         next (list): Next response object. Calling this
             updates the :py:class:`~Pager` internal state.
@@ -517,6 +528,11 @@ class Pager:
         Some versions of Turbonomic have endpoints that return malformed, or
         non-working pagination headers. These are chiefly XL versions prior to
         7.21.2.
+
+        It is possible a cursor may expire before you've processed all results
+        for extremely large sets. A :py:class:`VMTNextCursorMissingError` will
+        be returned when the cursor is no longer availble. Therefore, you should
+        always catch this error type when working with a :py:class:`~Pager`.
     """
     def __init__(self, conn, response, filter=None, filter_float=False, **kwargs):
         self.__conn = conn
@@ -701,7 +717,7 @@ class Connection:
         side certificates using **cert**: the private key to your local certificate
         must be unencrypted. Currently, Requests, which vmt-connect relies on,
         does not support using encrypted keys. Requests uses certificates from
-        the package certifi.
+        the package certifi which should be kept up to date.
 
         The /api/v2 path was added in 6.4, and the /api/v3 path was added in XL
         branch 7.21. The XL API is not intended to be an extension of the Classic
@@ -749,6 +765,8 @@ def __init__(self, host=None, username=None, password=None, auth=None,
         # we have a circular dependency:
         #   we need to know the version to know which base path to use
         #   we need the base path to query the version
+        # vmtconnect will attempt to resolve this by trying all known base paths
+        # until the correct one is found, or fail if it cannot sort it out
         self.__use_session(use_session)
         self.base_path = self.__resolve_base_path(base_url)
 
@@ -769,7 +787,7 @@ def __init__(self, host=None, username=None, password=None, auth=None,
         except HTTPError:
             if self.last_response.status_code == 301 and self.protocol == 'http' \
             and self.last_response.headers.get('Location', '').startswith('https'):
-                msg = 'HTTP 301 Redirect to HTTPS detected using HTTP protocol, forcing to HTTPS'
+                msg = 'HTTP 301 Redirect to HTTPS detected when using HTTP, switching to HTTPS'
                 warnings.warn(msg, HTTPWarning)
                 self.protocol = 'https'
                 self.__login()
@@ -778,7 +796,7 @@ def __init__(self, host=None, username=None, password=None, auth=None,
         except HTTP401Error:
             raise
         except Exception as e:
-            # because classic accepts encoded credentials, we'll manually attach here
+            # because classic accepts encoded credentials, we'll try manually attach here
             self.headers.update(
                 {'Authorization': f'Basic {self.__basic_auth.decode()}'}
             )
@@ -796,7 +814,7 @@ def __init__(self, host=None, username=None, password=None, auth=None,
 
         # for inventory caching - used to prevent thrashing the API with
         # repeated calls for full inventory lookups within some expensive calls
-        # <!> deprecated
+        # <!> deprecated due to pagination and XL
         self.__inventory_cache_timeout = 600
         self.__inventory_cache = {'Market': {'data': None,
                                              'expires': datetime.datetime.now()
@@ -1701,9 +1719,7 @@ def add_group(self, dto):
             Group object in :obj:`dict` form.
 
         See Also:
-            REST API Guide `5.9 <https://archive.turbonomic.com/wp-content/uploads/docs/VMT_REST2_API_PRINT.pdf>`_,
-            `6.0 <https://archive.turbonomic.com/wp-content/uploads/docs/Turbonomic_REST_API_PRINT_60.pdf>`_,
-            and the `Unofficial User Guide <http://rsnyc.sdf.org/vmt/>`_.
+            https://turbonomic.github.io/vmt-connect/start.html#turbonomic-rest-api-guides
         """
         return self.request('groups', method='POST', dto=dto)
 
@@ -1832,9 +1848,7 @@ def search(self, **kwargs):
             A list of search results.
 
         See Also:
-            REST API Guide `5.9 <https://archive.turbonomic.com/wp-content/uploads/docs/VMT_REST2_API_PRINT.pdf>`_,
-            `6.0 <https://archive.turbonomic.com/wp-content/uploads/docs/Turbonomic_REST_API_PRINT_60.pdf>`_,
-            and the `Unofficial User Guide <http://rsnyc.sdf.org/vmt/>`_.
+            https://turbonomic.github.io/vmt-connect/start.html#turbonomic-rest-api-guides
 
             Search criteria list: `http://<host>/vmturbo/rest/search/criteria`
         """
@@ -1991,3 +2005,23 @@ def __init__(self, *args, **kwargs):
 def enumerate_stats(data, entity=None, period=None, stat=None):
     """Provided as an alias for backwards compatibility only."""
     return util.enumerate_stats(data, entity, period, stat)
+
+
+def __register_env(data):
+    for k, v in data.items():
+        try:
+            ENV[k] = v
+        except Exception as e:
+            pass
+
+
+
+# ----------------------------------------------------
+#  Load local environments if found
+# ----------------------------------------------------
+for file in [GLOBAL_ENV, SCRIPT_ENV]:
+    try:
+        with open(file, 'r') as fp:
+            __register_env(json.load(fp))
+    except Exception as e:
+        pass

vmtconnect/versions.py

@@ -57,6 +57,10 @@
         '2.3.18': '6.4.22',
         '2.3.19': '6.4.23',
         '2.3.20': '6.4.24',
-        '2.3.21': '6.4.25'
+        '2.3.21': '6.4.25',
+        '2.3.22': '6.4.26',
+        '2.3.23': '6.4.27',
+        '2.3.24': '6.4.28',
+        '2.3.25': '6.4.29'
     }
 }