Python SDK 1.8.0 release

Python SDK 1.8.0 release

README.md

@@ -9,7 +9,7 @@ Welcome to DocumentDB.
     https://www.python.org/download/releases/2.7
 
 
-    If you use Microsoft Visual Studio as IDE (we use 2013), please install the
+    If you use Microsoft Visual Studio as IDE (we use 2015), please install the
     following extension for Python.
     http://microsoft.github.io/PTVS/
 

changelog.md

@@ -1,3 +1,7 @@
+## Changes in 1.8.0 : ##
+
+- Added the support for geo-replicated database accounts.
+
 ## Changes in 1.7.0 : ##
 
 - Added the support for Time To Live(TTL) feature for documents.

doc/conf.py

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

pydocumentdb/constants.py

@@ -0,0 +1,32 @@
+#The MIT License (MIT)
+#Copyright (c) 2014 Microsoft Corporation
+
+#Permission is hereby granted, free of charge, to any person obtaining a copy
+#of this software and associated documentation files (the "Software"), to deal
+#in the Software without restriction, including without limitation the rights
+#to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#copies of the Software, and to permit persons to whom the Software is
+#furnished to do so, subject to the following conditions:
+
+#The above copyright notice and this permission notice shall be included in all
+#copies or substantial portions of the Software.
+
+#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+#OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+#SOFTWARE.
+
+class _Constants(object):
+    """Constants used in the pydocumentdb package"""
+
+    UserConsistencyPolicy = 'userConsistencyPolicy'
+
+    #GlobalDB related constants
+    WritableLocations = 'writableLocations'
+    ReadableLocations = 'readableLocations'
+    Name = 'name'
+    DatabaseAccountEndpoint = 'databaseAccountEndpoint'
+

pydocumentdb/document_client.py

@@ -6,10 +6,12 @@
 
 import pydocumentdb.base as base
 import pydocumentdb.documents as documents
+import pydocumentdb.constants as constants
 import pydocumentdb.http_constants as http_constants
 import pydocumentdb.query_iterable as query_iterable
 import pydocumentdb.runtime_constants as runtime_constants
 import pydocumentdb.synchronized_request as synchronized_request
+import pydocumentdb.global_endpoint_manager as global_endpoint_manager
 
 
 try:
@@ -79,7 +81,7 @@ def __init__(self,
                                   documents.ConnectionPolicy())
 
         self.retry_policy = documents.RetryPolicy()
-
+        
         self.partition_resolvers = {}
 
         self.partition_key_definition_cache = {}
@@ -98,11 +100,25 @@ def __init__(self,
         # Keeps the latest response headers from server.
         self.last_response_headers = None
 
+        self._global_endpoint_manager = global_endpoint_manager._GlobalEndpointManager(self)
+
         # Query compatibility mode.
         # Allows to specify compatibility mode used by client when making query requests. Should be removed when
         # application/sql is no longer supported.
         self._query_compatibility_mode = DocumentClient._QueryCompatibilityMode.Default
 
+    @property
+    def WriteEndpoint(self):
+        """Gets the curent write endpoint for a geo-replicated database account.
+        """
+        return self._global_endpoint_manager.WriteEndpoint
+
+    @property
+    def ReadEndpoint(self):
+        """Gets the curent read endpoint for a geo-replicated database account.
+        """
+        return self._global_endpoint_manager.ReadEndpoint
+
     def RegisterPartitionResolver(self, database_link, partition_resolver):
         """Registers the partition resolver associated with the database link
 
@@ -1549,7 +1565,9 @@ def ReadMedia(self, media_link):
 
         """
         default_headers = self.default_headers
-        url_connection = self.url_connection
+        # ReadMedia will always use WriteEndpoint since it's not replicated in readable Geo regions
+        url_connection = self._global_endpoint_manager.WriteEndpoint
+
         path = base.GetPathFromLink(media_link)
         media_id = base.GetResourceIdOrFullNameFromLink(media_link)
         attachment_id = base.GetAttachmentIdFromMediaId(media_id)
@@ -1594,7 +1612,9 @@ def UpdateMedia(self, media_link, readable_stream, options=None):
             initial_headers[http_constants.HttpHeaders.ContentType] = (
                 runtime_constants.MediaTypes.OctetStream)
 
-        url_connection = self.url_connection
+        # UpdateMedia will use WriteEndpoint since it uses PUT operation
+        url_connection = self._global_endpoint_manager.WriteEndpoint
+
         path = base.GetPathFromLink(media_link)
         media_id = base.GetResourceIdOrFullNameFromLink(media_link)
         attachment_id = base.GetAttachmentIdFromMediaId(media_id)
@@ -1789,7 +1809,9 @@ def ExecuteStoredProcedure(self, sproc_link, params, options=None):
         if params and not type(params) is list:
             params = [params]
 
-        url_connection = self.url_connection
+        # ExecuteStoredProcedure will use WriteEndpoint since it uses POST operation
+        url_connection = self._global_endpoint_manager.WriteEndpoint
+
         path = base.GetPathFromLink(sproc_link)
         sproc_id = base.GetResourceIdOrFullNameFromLink(sproc_link)
         headers = base.GetHeaders(self,
@@ -1950,13 +1972,16 @@ def fetch_fn(options):
                                     options), self.last_response_headers
         return query_iterable.QueryIterable(options, self.retry_policy, fetch_fn)
 
-    def GetDatabaseAccount(self):
+    def GetDatabaseAccount(self, url_connection=None):
         """Gets database account info.
 
         :Returns:
             documents.DatabaseAccount
 
         """
+        if url_connection is None:
+            url_connection = self.url_connection
+
         initial_headers = dict(self.default_headers)
         headers = base.GetHeaders(self,
                                   initial_headers,
@@ -1965,7 +1990,7 @@ def GetDatabaseAccount(self):
                                   '',  # id
                                   '',  # type
                                   {});
-        result, self.last_response_headers = self.__Get(self.url_connection,
+        result, self.last_response_headers = self.__Get(url_connection,
                                                         '',
                                                         headers)
         database_account = documents.DatabaseAccount()
@@ -1981,7 +2006,13 @@ def GetDatabaseAccount(self):
             database_account.CurrentMediaStorageUsageInMB = (
                 self.last_response_headers[
                     http_constants.HttpHeaders.CurrentMediaStorageUsageInMB])
-        database_account.ConsistencyPolicy = result['userConsistencyPolicy']
+        database_account.ConsistencyPolicy = result.get(constants._Constants.UserConsistencyPolicy)
+
+        # WritableLocations and ReadableLocations fields will be available only for geo-replicated database accounts
+        if constants._Constants.WritableLocations in result:
+            database_account._WritableLocations = result[constants._Constants.WritableLocations]
+        if constants._Constants.ReadableLocations in result:
+            database_account._ReadableLocations = result[constants._Constants.ReadableLocations]
         return database_account
 
     def Create(self, body, path, type, id, initial_headers, options=None):
@@ -2010,7 +2041,9 @@ def Create(self, body, path, type, id, initial_headers, options=None):
                                   id,
                                   type,
                                   options)
-        result, self.last_response_headers = self.__Post(self.url_connection,
+        # Create will use WriteEndpoint since it uses POST operation
+        url_connection = self._global_endpoint_manager.WriteEndpoint
+        result, self.last_response_headers = self.__Post(url_connection,
                                                          path,
                                                          body,
                                                          headers)
@@ -2045,7 +2078,9 @@ def Upsert(self, body, path, type, id, initial_headers, options=None):
 
         headers[http_constants.HttpHeaders.IsUpsert] = True
 
-        result, self.last_response_headers = self.__Post(self.url_connection,
+        # Upsert will use WriteEndpoint since it uses POST operation
+        url_connection = self._global_endpoint_manager.WriteEndpoint
+        result, self.last_response_headers = self.__Post(url_connection,
                                                          path,
                                                          body,
                                                          headers)
@@ -2077,7 +2112,9 @@ def Replace(self, resource, path, type, id, initial_headers, options=None):
                                   id,
                                   type,
                                   options)
-        result, self.last_response_headers = self.__Put(self.url_connection,
+        # Replace will use WriteEndpoint since it uses PUT operation
+        url_connection = self._global_endpoint_manager.WriteEndpoint
+        result, self.last_response_headers = self.__Put(url_connection,
                                                         path,
                                                         resource,
                                                         headers)
@@ -2108,7 +2145,9 @@ def Read(self, path, type, id, initial_headers, options=None):
                                   id,
                                   type,
                                   options)
-        result, self.last_response_headers = self.__Get(self.url_connection,
+        # Read will use ReadEndpoint since it uses GET operation
+        url_connection = self._global_endpoint_manager.ReadEndpoint
+        result, self.last_response_headers = self.__Get(url_connection,
                                                         path,
                                                         headers)
         return result
@@ -2138,7 +2177,9 @@ def DeleteResource(self, path, type, id, initial_headers, options=None):
                                   id,
                                   type,
                                   options)
-        result, self.last_response_headers = self.__Delete(self.url_connection,
+        # Delete will use WriteEndpoint since it uses DELETE operation
+        url_connection = self._global_endpoint_manager.WriteEndpoint
+        result, self.last_response_headers = self.__Delete(url_connection,
                                                            path,
                                                            headers)
         return result
@@ -2156,7 +2197,8 @@ def __Get(self, url, path, headers):
             dicts
 
         """
-        return synchronized_request.SynchronizedRequest(self.connection_policy,
+        return synchronized_request.SynchronizedRequest(self._global_endpoint_manager,
+                                                        self.connection_policy,
                                                         'GET',
                                                         url,
                                                         path,
@@ -2178,7 +2220,8 @@ def __Post(self, url, path, body, headers):
             dicts
 
         """
-        return synchronized_request.SynchronizedRequest(self.connection_policy,
+        return synchronized_request.SynchronizedRequest(self._global_endpoint_manager,
+                                                        self.connection_policy,
                                                         'POST',
                                                         url,
                                                         path,
@@ -2200,7 +2243,8 @@ def __Put(self, url, path, body, headers):
             dicts
 
         """
-        return synchronized_request.SynchronizedRequest(self.connection_policy,
+        return synchronized_request.SynchronizedRequest(self._global_endpoint_manager,
+                                                        self.connection_policy,
                                                         'PUT',
                                                         url,
                                                         path,
@@ -2221,7 +2265,8 @@ def __Delete(self, url, path, headers):
             dicts
 
         """
-        return synchronized_request.SynchronizedRequest(self.connection_policy,
+        return synchronized_request.SynchronizedRequest(self._global_endpoint_manager,
+                                                        self.connection_policy,
                                                         'DELETE',
                                                         url,
                                                         path,
@@ -2284,7 +2329,9 @@ def __QueryFeed(self,
             def __GetBodiesFromQueryResult(result):
                 return [create_fn(self, body) for body in result_fn(result)]
 
-        url_connection = self.url_connection
+        # Query operations will use ReadEndpoint even though it uses GET(for feed requests) and POST(for regular query operations)
+        url_connection = self._global_endpoint_manager.ReadEndpoint
+
         initial_headers = self.default_headers.copy()
         # Copy to make sure that default_headers won't be changed.
         if query == None:

pydocumentdb/documents.py

@@ -38,7 +38,20 @@ def __init__(self):
         self.ReservedDocumentStorageInMB = 0
         self.ProvisionedDocumentStorageInMB = 0
         self.ConsistencyPolicy = None
+        self._WritableLocations = []
+        self._ReadableLocations = []
 
+    @property
+    def WritableLocations(self):
+        """Gets the list of writable locations for a geo-replicated database account.
+        """
+        return self._WritableLocations
+
+    @property
+    def ReadableLocations(self):
+        """Gets the list of readable locations for a geo-replicated database account.
+        """
+        return self._ReadableLocations
 
 class ConsistencyLevel(object):
     """Represents the consistency levels supported for DocumentDB client
@@ -255,6 +268,15 @@ class ConnectionPolicy(object):
           attachment content (aka media) download mode.
         - `SSLConfiguration`: documents.SSLConfiguration, gets or sets the SSL configuration.
         - `ProxyConfiguration`: documents.ProxyConfiguration, gets or sets the proxy configuration.
+        - `EnableEndpointDiscovery`: boolean, gets or sets endpoint discovery flag for geo-replicated database accounts.
+           When EnableEndpointDiscovery is true, the client will automatically discover the
+           current write and read locations and direct the requests to the correct location
+           taking into consideration of the user's preference(if provided) as PreferredLocations.
+        - `PreferredLocations`: list, gets or sets the preferred locations for geo-replicated database accounts.
+           When EnableEndpointDiscovery is true and PreferredLocations is non-empty, 
+           the client will use this list to evaluate the final location, taking into consideration
+           the order specified in PreferredLocations list. The locations in this list are specified as the names of
+           the azure documentdb locations like, 'West US', 'East US', 'Central India' and so on.
     """
 
     __defaultRequestTimeout = 60000  # milliseconds
@@ -269,6 +291,8 @@ def __init__(self):
         self.MediaReadMode = MediaReadMode.Buffered
         self.SSLConfiguration = None
         self.ProxyConfiguration = None
+        self.EnableEndpointDiscovery = True;
+        self.PreferredLocations = []
 
 
 class RetryPolicy(object):