Spaces\Users\Memberships endpoints (#124)

* Spaces Users and Memberships behind a feature flag

* Example usage of Spaces\Users\Memberships

* PubNub SDK v6.4.0 release.

Co-authored-by: Client Engineering Bot <60980775+Client Engineering [email protected]>

Author: seba-aln

.pubnub.yml

@@ -1,5 +1,5 @@
 name: python
-version: 6.3.3
+version: 6.4.0
 schema: 1
 scm: github.com/pubnub/python
 sdks:
@@ -18,7 +18,7 @@ sdks:
         distributions:
           - distribution-type: library
             distribution-repository: package
-            package-name: pubnub-6.3.3
+            package-name: pubnub-6.4.0
             location: https://pypi.org/project/pubnub/
             supported-platforms:
               supported-operating-systems:
@@ -97,8 +97,8 @@ sdks:
           -
             distribution-type: library
             distribution-repository: git release
-            package-name: pubnub-6.3.3
-            location: https://github.com/pubnub/python/releases/download/v6.3.3/pubnub-6.3.3.tar.gz
+            package-name: pubnub-6.4.0
+            location: https://github.com/pubnub/python/releases/download/v6.4.0/pubnub-6.4.0.tar.gz
             supported-platforms:
               supported-operating-systems:
                 Linux:
@@ -169,6 +169,11 @@ sdks:
                 license-url: https://github.com/aio-libs/aiohttp/blob/master/LICENSE.txt
                 is-required: Required
 changelog:
+  - date: 2022-07-13
+    version: v6.4.0
+    changes:
+      - type: feature
+        text: "Spaces Users and Membership endpoint implementation. This functionality is hidden behind a feature flag. By default it is disabled. To enable it there should be an environment variable named `PN_ENABLE_ENTITIES` set to `True`."
   - date: 2022-06-25
     version: v6.3.3
     changes:

CHANGELOG.md

@@ -1,3 +1,9 @@
+## v6.4.0
+July 13 2022
+
+#### Added
+- Spaces Users and Membership endpoint implementation. This functionality is hidden behind a feature flag. By default it is disabled. To enable it there should be an environment variable named `PN_ENABLE_ENTITIES` set to `True`.
+
 ## v6.3.3
 June 25 2022
 

examples/entities.py

@@ -0,0 +1,108 @@
+import os
+
+from pubnub.models.consumer.entities.space import Space
+from pubnub.models.consumer.entities.user import User
+from pubnub.pnconfiguration import PNConfiguration
+from pubnub.pubnub import PubNub
+
+pnconfig = PNConfiguration()
+
+pnconfig.subscribe_key = os.getenv('SUB_KEY')
+pnconfig.publish_key = os.getenv('PUB_KEY')
+pnconfig.secret_key = os.getenv('SEC_KEY')
+pnconfig.user_id = "my_uuid"
+
+pnconfig.non_subscribe_request_timeout = 60
+pnconfig.connect_timeout = 14
+pnconfig.reconnect_policy
+print(pnconfig.subscribe_key)
+
+pubnub = PubNub(pnconfig)
+
+space_id = 'blah'
+user_id = 'jason-id'
+
+create_space = pubnub.create_space(
+    space_id=space_id,
+    name=f'Space ID {space_id}',
+    description=f'This space ID is {space_id} and is made for demo purpose only',
+    custom={"created_by": "me"},
+    space_status='Primary',
+    space_type='COM',
+    sync=True
+)
+
+print(f"create space result:{create_space.result.__dict__}")
+
+update_space = pubnub.update_space(
+    space_id=space_id,
+    name=f'EDIT Space ID {space_id}',
+    description=f'EDIT: This space ID is {space_id} and is made for demo purpose only',
+    custom={"created_by": "EDIT me"},
+    sync=True
+)
+print(f"update space result: {update_space.result.__dict__}")
+
+fetch_space = pubnub.fetch_space(space_id=space_id, include_custom=True, sync=True)
+print(f"fetch space result: {fetch_space.result.__dict__}")
+
+space_id2 = space_id + '2'
+create_space = pubnub.create_space(space_id2) \
+    .set_name(f'Space ID {space_id}') \
+    .description(f'This space ID is {space_id} and is made for demo purpose only') \
+    .custom({
+        "created_by": "me"
+    }) \
+    .sync()
+
+all_spaces = pubnub.fetch_spaces(include_custom=True, include_total_count=True).sync()
+
+print(f"fetch spaces result: {all_spaces.result.__dict__}")
+
+rm_space = pubnub.remove_space(space_id2).sync()
+print(f"remove space result: {rm_space.result.__dict__}")
+
+user = pubnub.create_user(user_id=user_id, name='Jason', email='[email protected]', sync=True)
+
+users = pubnub.fetch_user(user_id=user_id, sync=True)
+print(f"fetch_user: {users.result.__dict__}")
+
+membership = pubnub.add_memberships(user_id=user_id, spaces=Space(space_id=space_id, custom={"a": "b"}), sync=True)
+print(f"add_memberships (user_id): {membership.result.__dict__}")
+
+memberships = pubnub.fetch_memberships(user_id=user_id, include_custom=True, sync=True)
+print(f"fetch_memberships (user_id): {memberships.result.__dict__}")
+
+print("-------")
+
+membership = pubnub.update_memberships(user_id=user_id, spaces=Space(space_id=space_id, custom={"c": "d"}), sync=True)
+print(f"add_memberships (user_id): {membership.result.__dict__}")
+
+memberships = pubnub.fetch_memberships(user_id=user_id, include_custom=True, sync=True)
+print(f"fetch_memberships (user_id): {memberships.result.__dict__}")
+
+print("-------")
+
+membership = pubnub.add_memberships(
+    user_id=user_id, spaces=[Space(space_id='some_2nd_space_id'), Space(space_id='some_3rd_space_id')], sync=True
+)
+print(f"add_memberships (user_id): {membership.result.__dict__}")
+
+memberships = pubnub.fetch_memberships(user_id=user_id, include_custom=True, sync=True)
+print(f"fetch_memberships (user_id): {memberships.result.__dict__}")
+
+print("-------")
+
+membership = pubnub.remove_memberships(user_id=user_id, spaces=Space(space_id=space_id), sync=True)
+print(f"remove_memberships (user_id): {membership.result.__dict__}")
+
+memberships = pubnub.fetch_memberships(user_id=user_id, include_custom=True, sync=True)
+print(f"fetch_memberships (user_id): {memberships.result.__dict__}")
+
+print("-------")
+
+membership = pubnub.add_memberships(space_id=space_id, users=[User(user_id=user_id, custom={"1": "2"})], sync=True)
+print(f"add_memberships (space_id): {membership.result.__dict__}")
+
+memberships = pubnub.fetch_memberships(space_id=space_id, include_custom=True, sync=True)
+print(f"fetch_memberships (space_id): {memberships.result.__dict__}")

pubnub/endpoints/entities/endpoint.py

@@ -0,0 +1,231 @@
+import logging
+from abc import ABCMeta
+
+from pubnub import utils
+from pubnub.endpoints.endpoint import Endpoint
+from pubnub.errors import PNERR_SPACE_MISSING, PNERR_USER_ID_MISSING
+from pubnub.exceptions import PubNubException
+from pubnub.models.consumer.entities.page import Next, Previous
+
+logger = logging.getLogger("pubnub")
+
+
+class EntitiesEndpoint(Endpoint):
+    __metaclass__ = ABCMeta
+
+    def __init__(self, pubnub):
+        Endpoint.__init__(self, pubnub)
+
+    def is_auth_required(self):
+        return True
+
+    def connect_timeout(self):
+        return self.pubnub.config.connect_timeout
+
+    def request_timeout(self):
+        return self.pubnub.config.non_subscribe_request_timeout
+
+    def validate_params(self):
+        self.validate_subscribe_key()
+        self.validate_specific_params()
+
+    def validate_specific_params(self):
+        pass
+
+    def encoded_params(self):
+        params = {}
+        if isinstance(self, ListEndpoint):
+            if self._filter:
+                params["filter"] = utils.url_encode(str(self._filter))
+        return params
+
+    def custom_params(self):
+        params = {}
+        inclusions = []
+
+        if isinstance(self, IncludeCustomEndpoint):
+            if self._include_custom:
+                inclusions.append("custom")
+
+        if isinstance(self, UserIDIncludeEndpoint):
+            if self._uuid_details_level:
+                if self._uuid_details_level == UserIDIncludeEndpoint.USER_ID:
+                    inclusions.append("user_id")
+                elif self._uuid_details_level == UserIDIncludeEndpoint.USER_ID_WITH_CUSTOM:
+                    inclusions.append("user_id.custom")
+
+        if isinstance(self, SpaceIDIncludeEndpoint):
+            if self._space_details_level:
+                if self._space_details_level == SpaceIDIncludeEndpoint.CHANNEL:
+                    inclusions.append("space")
+                elif self._space_details_level == SpaceIDIncludeEndpoint.CHANNEL_WITH_CUSTOM:
+                    inclusions.append("space.custom")
+
+        if isinstance(self, ListEndpoint):
+            if self._filter:
+                params["filter"] = str(self._filter)
+
+            if self._limit:
+                params["limit"] = int(self._limit)
+
+            if self._include_total_count:
+                params["count"] = bool(self._include_total_count)
+
+            if self._sort_keys:
+                joined_sort_params_array = []
+                for sort_key in self._sort_keys:
+                    joined_sort_params_array.append("%s:%s" % (sort_key.key_str(), sort_key.dir_str()))
+
+                params["sort"] = ",".join(joined_sort_params_array)
+
+            if self._page:
+                if isinstance(self._page, Next):
+                    params["start"] = self._page.hash
+                elif isinstance(self._page, Previous):
+                    params["end"] = self._page.hash
+                else:
+                    raise ValueError()
+
+        if len(inclusions) > 0:
+            params["include"] = ",".join(inclusions)
+
+        return params
+
+
+class CustomAwareEndpoint:
+    __metaclass__ = ABCMeta
+
+    def __init__(self):
+        self._custom = None
+
+    def custom(self, custom):
+        self._custom = dict(custom)
+        return self
+
+
+class SpaceEndpoint:
+    __metaclass__ = ABCMeta
+
+    def __init__(self):
+        self._space_id = None
+
+    def space_id(self, space):
+        self._space_id = str(space)
+        return self
+
+    def _validate_space_id(self):
+        if self._space_id is None or len(self._space_id) == 0:
+            raise PubNubException(pn_error=PNERR_SPACE_MISSING)
+
+
+class UserEndpoint:
+    __metaclass__ = ABCMeta
+
+    def __init__(self):
+        self._user_id = None
+
+    def user_id(self, user_id):
+        self._user_id = str(user_id)
+        return self
+
+    def _effective_user_id(self):
+        if self._user_id is not None:
+            return self._user_id
+        else:
+            return self.pubnub.config.user_id
+
+    def _validate_user_id(self):
+        if self._effective_user_id() is None or len(self._effective_user_id()) == 0:
+            raise PubNubException(pn_error=PNERR_USER_ID_MISSING)
+
+
+class UsersEndpoint:
+    __metaclass__ = ABCMeta
+
+    def __init__(self):
+        self._users = None
+
+    def users(self, users):
+        self._users = users
+        return self
+
+
+class SpacesEndpoint:
+    __metaclass__ = ABCMeta
+
+    def __init__(self):
+        self._spaces = None
+
+    def spaces(self, spaces):
+        self._spaces = spaces
+        return self
+
+
+class ListEndpoint:
+    __metaclass__ = ABCMeta
+
+    def __init__(self):
+        self._limit = None
+        self._filter = None
+        self._include_total_count = None
+        self._sort_keys = None
+        self._page = None
+
+    def limit(self, limit):
+        self._limit = int(limit)
+        return self
+
+    def filter(self, filter):
+        self._filter = str(filter)
+        return self
+
+    def include_total_count(self, include_total_count):
+        self._include_total_count = bool(include_total_count)
+        return self
+
+    def sort(self, *sort_keys):
+        self._sort_keys = sort_keys
+        return self
+
+    def page(self, page):
+        self._page = page
+        return self
+
+
+class IncludeCustomEndpoint:
+    __metaclass__ = ABCMeta
+
+    def __init__(self):
+        self._include_custom = None
+
+    def include_custom(self, include_custom):
+        self._include_custom = bool(include_custom)
+        return self
+
+
+class UserIDIncludeEndpoint:
+    __metaclass__ = ABCMeta
+
+    USER_ID = 1
+    USER_ID_WITH_CUSTOM = 2
+
+    def __init__(self):
+        self._user_id_details_level = None
+
+    def include_user_id(self, user_id_details_level):
+        self._user_id_details_level = user_id_details_level
+        return self
+
+
+class SpaceIDIncludeEndpoint:
+    __metaclass__ = ABCMeta
+
+    SPACE = 1
+    SPACE_WITH_CUSTOM = 2
+
+    def __init__(self):
+        self._space_details_level = None
+
+    def include_space(self, space_details_level):
+        self._space_details_level = space_details_level
+        return self