Merge pull request #60 from Kinto/get-endpoint-should-be-public

_get_endpoint should be part of the public.

Author: Natim

README.rst

@@ -267,6 +267,25 @@ It is possible (but not recommended) to force this value in the clients:
                   retry=10,
                   retry_after=5)
 
+
+Generating endpoint paths
+-------------------------
+
+You may want to generate some endpoint paths, you can use the
+get_endpoint utility to do so:
+
+.. code-block:: python
+
+    client = Client(server_url='http://localhost:8888/v1',
+                    auth=('token', 'your-token'),
+                    bucket="payments",
+                    collection="receipts")
+    print(client.get_endpoint("record",
+                              id="c6894b2c-1856-11e6-9415-3c970ede22b0"))
+
+    # '/buckets/payments/collections/receipts/records/c6894b2c-1856-11e6-9415-3c970ede22b0'
+
+
 Command-line scripts
 --------------------
 

kinto_client/__init__.py

@@ -79,7 +79,7 @@ def clone(self, **kwargs):
     @contextmanager
     def batch(self, **kwargs):
         if self._server_settings is None:
-            resp, _ = self.session.request("GET", self._get_endpoint('root'))
+            resp, _ = self.session.request("GET", self.get_endpoint('root'))
             self._server_settings = resp['settings']
 
         batch_max_requests = self._server_settings['batch_max_requests']
@@ -90,7 +90,18 @@ def batch(self, **kwargs):
         batch_session.send()
         batch_session.reset()
 
-    def _get_endpoint(self, name, bucket=None, collection=None, id=None):
+    def get_endpoint(self, name, bucket=None, collection=None, id=None):
+        """Return the endpoint with named parameters.
+
+           Please always use the method as if it was defined like this:
+
+               get_endpoint(self, name, *,
+                            bucket=None, collection=None, id=None)
+
+           Meaning that bucket, collection and id should always be
+           named parameters.
+
+        """
         kwargs = {
             'bucket': bucket or self._bucket_name,
             'collection': collection or self._collection_name,
@@ -151,7 +162,7 @@ def _create_if_not_exists(self, resource, **kwargs):
     # Server Info
 
     def server_info(self):
-        endpoint = self._get_endpoint('root')
+        endpoint = self.get_endpoint('root')
         resp, _ = self.session.request('get', endpoint)
         return resp
 
@@ -166,15 +177,15 @@ def create_bucket(self, bucket=None, data=None, permissions=None,
                                               permissions=permissions,
                                               safe=safe)
         headers = DO_NOT_OVERWRITE if safe else None
-        endpoint = self._get_endpoint('bucket', bucket)
+        endpoint = self.get_endpoint('bucket', bucket=bucket)
         resp, _ = self.session.request('put', endpoint, data=data,
                                        permissions=permissions,
                                        headers=headers)
         return resp
 
     def update_bucket(self, bucket=None, data=None, permissions=None,
                       safe=True, if_match=None, method='put'):
-        endpoint = self._get_endpoint('bucket', bucket)
+        endpoint = self.get_endpoint('bucket', bucket=bucket)
         headers = self._get_cache_headers(safe, data, if_match)
         resp, _ = self.session.request(method, endpoint, data=data,
                                        permissions=permissions,
@@ -186,33 +197,33 @@ def patch_bucket(self, *args, **kwargs):
         return self.update_bucket(*args, **kwargs)
 
     def get_buckets(self):
-        endpoint = self._get_endpoint('buckets')
+        endpoint = self.get_endpoint('buckets')
         return self._paginated(endpoint)
 
     def get_bucket(self, bucket=None):
-        endpoint = self._get_endpoint('bucket', bucket)
+        endpoint = self.get_endpoint('bucket', bucket=bucket)
         try:
             resp, _ = self.session.request('get', endpoint)
         except KintoException as e:
             raise BucketNotFound(bucket or self._bucket_name, e)
         return resp
 
     def delete_bucket(self, bucket=None, safe=True, if_match=None):
-        endpoint = self._get_endpoint('bucket', bucket)
+        endpoint = self.get_endpoint('bucket', bucket=bucket)
         headers = self._get_cache_headers(safe, if_match=if_match)
         resp, _ = self.session.request('delete', endpoint, headers=headers)
         return resp['data']
 
     def delete_buckets(self, safe=True, if_match=None):
-        endpoint = self._get_endpoint('buckets')
+        endpoint = self.get_endpoint('buckets')
         headers = self._get_cache_headers(safe, if_match=if_match)
         resp, _ = self.session.request('delete', endpoint, headers=headers)
         return resp['data']
 
     # Collections
 
     def get_collections(self, bucket=None):
-        endpoint = self._get_endpoint('collections', bucket)
+        endpoint = self.get_endpoint('collections', bucket=bucket)
         return self._paginated(endpoint)
 
     def create_collection(self, collection=None, bucket=None,
@@ -226,7 +237,9 @@ def create_collection(self, collection=None, bucket=None,
                                               permissions=permissions,
                                               safe=safe)
         headers = DO_NOT_OVERWRITE if safe else None
-        endpoint = self._get_endpoint('collection', bucket, collection)
+        endpoint = self.get_endpoint('collection',
+                                     bucket=bucket,
+                                     collection=collection)
         try:
             resp, _ = self.session.request('put', endpoint, data=data,
                                            permissions=permissions,
@@ -238,12 +251,15 @@ def create_collection(self, collection=None, bucket=None,
                        "this collection.")
                 e = KintoException(msg, e)
             raise e
+
         return resp
 
     def update_collection(self, data=None, collection=None, bucket=None,
                           permissions=None, method='put',
                           safe=True, if_match=None):
-        endpoint = self._get_endpoint('collection', bucket, collection)
+        endpoint = self.get_endpoint('collection',
+                                     bucket=bucket,
+                                     collection=collection)
         headers = self._get_cache_headers(safe, data, if_match)
         resp, _ = self.session.request(method, endpoint, data=data,
                                        permissions=permissions,
@@ -255,19 +271,23 @@ def patch_collection(self, *args, **kwargs):
         return self.update_collection(*args, **kwargs)
 
     def get_collection(self, collection=None, bucket=None):
-        endpoint = self._get_endpoint('collection', bucket, collection)
+        endpoint = self.get_endpoint('collection',
+                                     bucket=bucket,
+                                     collection=collection)
         resp, _ = self.session.request('get', endpoint)
         return resp
 
     def delete_collection(self, collection=None, bucket=None,
                           safe=True, if_match=None):
-        endpoint = self._get_endpoint('collection', bucket, collection)
+        endpoint = self.get_endpoint('collection',
+                                     bucket=bucket,
+                                     collection=collection)
         headers = self._get_cache_headers(safe, if_match=if_match)
         resp, _ = self.session.request('delete', endpoint, headers=headers)
         return resp['data']
 
     def delete_collections(self, bucket=None, safe=True, if_match=None):
-        endpoint = self._get_endpoint('collections', bucket)
+        endpoint = self.get_endpoint('collections', bucket=bucket)
         headers = self._get_cache_headers(safe, if_match=if_match)
         resp, _ = self.session.request('delete', endpoint, headers=headers)
         return resp['data']
@@ -276,12 +296,15 @@ def delete_collections(self, bucket=None, safe=True, if_match=None):
 
     def get_records(self, collection=None, bucket=None, **kwargs):
         """Returns all the records"""
-        # XXX Add filter and sorting.
-        endpoint = self._get_endpoint('records', bucket, collection)
+        endpoint = self.get_endpoint('records',
+                                     bucket=bucket,
+                                     collection=collection)
         return self._paginated(endpoint, **kwargs)
 
     def get_record(self, id, collection=None, bucket=None):
-        endpoint = self._get_endpoint('record', bucket, collection, id)
+        endpoint = self.get_endpoint('record', id=id,
+                                     bucket=bucket,
+                                     collection=collection)
         resp, _ = self.session.request('get', endpoint)
         return resp
 
@@ -299,7 +322,9 @@ def create_record(self, data, id=None, collection=None, permissions=None,
         # Make sure that no record already exists with this id.
         headers = DO_NOT_OVERWRITE if safe else None
 
-        endpoint = self._get_endpoint('record', bucket, collection, id)
+        endpoint = self.get_endpoint('record', id=id,
+                                     bucket=bucket,
+                                     collection=collection)
         try:
             resp, _ = self.session.request('put', endpoint, data=data,
                                            permissions=permissions,
@@ -320,7 +345,9 @@ def update_record(self, data, id=None, collection=None, permissions=None,
         id = id or data.get('id')
         if id is None:
             raise KeyError('Unable to update a record, need an id.')
-        endpoint = self._get_endpoint('record', bucket, collection, id)
+        endpoint = self.get_endpoint('record', id=id,
+                                     bucket=bucket,
+                                     collection=collection)
         headers = self._get_cache_headers(safe, data, if_match)
         resp, _ = self.session.request(method, endpoint, data=data,
                                        headers=headers,
@@ -333,23 +360,27 @@ def patch_record(self, *args, **kwargs):
 
     def delete_record(self, id, collection=None, bucket=None,
                       safe=True, if_match=None):
-        endpoint = self._get_endpoint('record', bucket, collection, id)
+        endpoint = self.get_endpoint('record', id=id,
+                                     bucket=bucket,
+                                     collection=collection)
         headers = self._get_cache_headers(safe, if_match=if_match)
         resp, _ = self.session.request('delete', endpoint, headers=headers)
         return resp['data']
 
     def delete_records(self, collection=None, bucket=None,
                        safe=True, if_match=None):
-        endpoint = self._get_endpoint('records', bucket, collection)
+        endpoint = self.get_endpoint('records',
+                                     bucket=bucket,
+                                     collection=collection)
         headers = self._get_cache_headers(safe, if_match=if_match)
         resp, _ = self.session.request('delete', endpoint, headers=headers)
         return resp['data']
 
     def __repr__(self):
-        endpoint = self._get_endpoint(
+        endpoint = self.get_endpoint(
             'collection',
-            self._bucket_name,
-            self._collection_name
+            bucket=self._bucket_name,
+            collection=self._collection_name
         )
         absolute_endpoint = utils.urljoin(self.session.server_url, endpoint)
         return "<KintoClient %s>" % absolute_endpoint