typing and comments

tracim/tracim/controllers/jitsi_meet.py

@@ -19,7 +19,7 @@ class JitsiMeetController(TIMRestController):
 
     allow_only = not_anonymous()
 
-    def _before(self, *args, **kw):
+    def _before(self, *args, **kw) -> None:
         TIMRestPathContextSetup.current_user()
         try:
             TIMRestPathContextSetup.current_workspace()
@@ -28,20 +28,34 @@ class JitsiMeetController(TIMRestController):
 
     @tg.require(current_user_is_reader())
     @expose('tracim.templates.videoconf.jitsi_meet')
-    def get(self):
+    def get(self) -> DictLikeClass:
+        """
+        Jitsi-Meet Room page
+        """
         user = tmpl_context.current_user
         return self._jitsi_room(jitsi_user=user)
 
     @tg.require(current_user_is_reader())
     @expose('tracim.templates.videoconf.invite')
-    def invite(self):
+    def invite(self) -> DictLikeClass:
+        """
+        Modal windows : Invitation to Jitsi-Meet room
+        """
+        # TODO - G.M - 14-02-2017 - Allow to invite not Anonymous user ?
+        # Jitsi-Meet allow to set user info through token
+        # invite already "named" user should be possible
         return self._jitsi_room()
 
     @classmethod
     def _jitsi_room(
             cls,
             jitsi_user: typing.Union[JitsiMeetUser, User, None]=None,
-    ):
+    )-> DictLikeClass:
+        """
+        Get all infos to generate DictLikeClass usable for JitsiMeetRoom
+        Templates.
+        :param jitsi_user: User who access to room
+        """
         cfg = CFG.get_instance()
         if not cfg.JITSI_MEET_ACTIVATED:
             abort(404)

tracim/tracim/lib/jitsi_meet/room.py

@@ -9,14 +9,6 @@ from tracim.model.data import User
 import uuid
 
 
-class JitsiMeetNoTokenGenerator(Exception):
-    pass
-
-
-class JitsiMeetTokenNotActivated(Exception):
-    pass
-
-
 class JitsiMeetRoom(object):
     def __init__(
             self,
@@ -38,11 +30,19 @@ class JitsiMeetRoom(object):
         )
         self.room = self._generate_room_name(receivers)
 
-    def _set_domain(self):
+    def _set_domain(self) -> None:
+        """
+        Set domain according to config
+        :return:
+        """
         cfg = CFG.get_instance()
         self.domain = cfg.JITSI_MEET_DOMAIN
 
-    def _set_token_params(self):
+    def _set_token_params(self) -> None:
+        """
+        Set params related to token according to config.
+        :return: nothing
+        """
         cfg = CFG.get_instance()
         self.use_token = cfg.JITSI_MEET_USE_TOKEN
         if self.use_token:
@@ -58,9 +58,18 @@ class JitsiMeetRoom(object):
             self,
             receivers: Workspace,
             issuer: typing.Union[User, JitsiMeetUser, None],
-    ):
+    ) -> None:
+        """
+        Set context of JWT token for Jitsi Meet
+        :param issuer: user who initiated Jitsi Meet talk
+        if None, default user is created. Can be both Tracim User or
+        JitsiMeetUser.
+        :param receivers: User or Room who can talk with sender. Now, only
+        Workspace are supported.
+        :return: nothing.
+        """
 
-        # User
+        # INFO - G.M - 13-02-2018 - Convert all issuers values as JitsiMeetUser
         if isinstance(issuer, JitsiMeetUser):
             user = issuer
         elif isinstance(issuer, User):
@@ -71,10 +80,11 @@ class JitsiMeetRoom(object):
             )
         else:
             user = JitsiMeetUser(
+                # INFO - G.M - 13-02-2018 - create unique id for anonymous user
                 jitsi_meet_user_id=str(uuid.uuid4()),
             )
 
-        # Group
+        # INFO - G.M - 13-02-2018 - Associate
         group = receivers.label
 
         self.context = JitsiMeetContext(
@@ -83,7 +93,14 @@ class JitsiMeetRoom(object):
         )
 
     @classmethod
-    def _generate_room_name(cls, workspace: Workspace):
+    def _generate_room_name(cls, workspace: Workspace) -> str:
+        """
+        Generate Jitsi-Meet room name related to workspace
+        that should be unique, always the same for same workspace in same Tracim
+        instance but should also no contains any special characters
+        :param workspace: Tracim Workspace
+        :return: room name as str.
+        """
         cfg = CFG.get_instance()
         room = "{uuid}{workspace_id}{workspace_label}".format(
             uuid=cfg.TRACIM_INSTANCE_UUID,
@@ -94,6 +111,10 @@ class JitsiMeetRoom(object):
         return str_as_alpha_num_str(room)
 
     def generate_token(self) -> str:
+        """
+        Generate Jitsi-Meet related JWT token
+        :return: JWT token as str
+        """
         if not self.use_token:
             raise JitsiMeetTokenNotActivated
 
@@ -110,7 +131,7 @@ class JitsiMeetRoom(object):
 
     def generate_url(self, token=None) -> str:
         """
-        Generate url with or without token
+        Generate Jitsi-Meet url with or without token
         :return: url as string
         """
         if token:
@@ -122,3 +143,10 @@ class JitsiMeetRoom(object):
                                  self.room,
                                  )
         return "https://{}".format(url)
+
+class JitsiMeetNoTokenGenerator(Exception):
+    pass
+
+
+class JitsiMeetTokenNotActivated(Exception):
+    pass

tracim/tracim/lib/jitsi_meet/token.py

@@ -2,6 +2,10 @@ import datetime
 import typing
 import jwt
 
+# Jitsi Meet Token
+# Data model and methods to convert dict as JWT token
+# see https://github.com/jitsi/lib-jitsi-meet/blob/52eb3decf6542413c739ce2209456fac728a89d5/doc/tokens.md  # nopep8
+
 
 class JitsiMeetUser(object):
 
@@ -11,9 +15,9 @@ class JitsiMeetUser(object):
             name: typing.Optional[str] = None,
             email: typing.Optional[str] = None,
             avatar_url: typing.Optional[str] = None,
-    ):
+    ) -> None:
         """
-
+        User data for Jitsi-Meet token
         :param avatar_url: url for user avatar_url
         :param name: display name of user
         :param email: email of user
@@ -25,6 +29,10 @@ class JitsiMeetUser(object):
         self.jitsi_meet_user_id = jitsi_meet_user_id
 
     def as_dict(self) -> dict:
+        """
+        Generate dict for JWT token
+        :return: user as dict
+        """
         data = {
             'id': self.jitsi_meet_user_id,
         }
@@ -44,10 +52,9 @@ class JitsiMeetContext(object):
             user: typing.Optional[JitsiMeetUser]=None,
             callee: typing.Optional[JitsiMeetUser]=None,
             group: str="default",
-    ):
+    ) -> None:
         """
-        Context as in JitsiToken Payload
-        see https://github.com/jitsi/lib-jitsi-meet/blob/52eb3decf6542413c739ce2209456fac728a89d5/doc/tokens.md  # nopep8
+        context as in Jitsi-Meet Token
         :param user: Current user
         :param callee: User Who respond in 1-to-1 conf
         :param group: Used only for stats
@@ -57,6 +64,10 @@ class JitsiMeetContext(object):
         self.group = group
 
     def as_dict(self) -> dict:
+        """
+        Generate dict for JWT token
+        :return: context as dict
+        """
         data = {}
         if self.callee:
             data['callee'] = self.callee.as_dict()
@@ -78,14 +89,14 @@ class JitsiMeetToken(object):
             alg: str,
             duration: int,
             context: typing.Optional[JitsiMeetContext] = None,
-    )-> None:
+    ) -> None:
         """
-        JWT token generator for JitsiMeet,
+        JWT token generator for Jitsi-Meet,
         :param app_id: application identifier
         :param secret: secret share between token generator and XMPP server
         :param alg: algorithm used
         :param duration: duration of token
-        :param domain: jitsi-meet domain
+        :param domain: Jitsi-Meet domain
         :param room: room name
         """
         self.room = room
@@ -97,6 +108,10 @@ class JitsiMeetToken(object):
         self.context = context
 
     def generate(self) -> str:
+        """
+        Generate JWT token
+        :return: JWT token as str
+        """
         now = datetime.datetime.utcnow()
         exp = now+datetime.timedelta(seconds=self.duration)
         data = {