Change extra_func documentation

main/extra_func.py

@@ -13,9 +13,9 @@ class ZendeskAdmin:
         Класс **ZendeskAdmin** существует, чтобы в каждой фунциии отдельно не проверять аккаунт администратора
 
         :param credentials:  Полномочия (первым указывается учетная запись организации в Zendesk)
-        :type credentials: :class:`list of dictionaries`
+        :type credentials: :class:`dict`
         :param email: Email администратора, указанный в env
-        :type email: :class:`email`
+        :type email: :class:`str`
         :param token: Токен администратора (формируется в Zendesk, указывается в env)
         :type token: :class:`str`
         :param password: Пароль администратора, указанный в env
@@ -23,7 +23,7 @@ class ZendeskAdmin:
 
     """
 
-    credentials:dict = {
+    credentials: dict = {
         'subdomain': 'ngenix1612197338'
     }
     email: str = os.getenv('ACCESS_CONTROLLER_API_EMAIL')
@@ -36,14 +36,12 @@ class ZendeskAdmin:
     def check_user(self, email: str) -> bool:
         """
             Функция **check_user** осуществляет проверку существования пользователя в Zendesk по email
-
         """
         return True if self.admin.search(email, type='user') else False
 
     def get_user_name(self, email: str) -> str:
         """
             Функция **get_user_name** возвращает имя пользователя по его email
-
         """
         user = self.admin.users.search(email).values[0]
         return user.name
@@ -51,7 +49,6 @@ class ZendeskAdmin:
     def get_user_role(self, email: str) -> str:
         """
             Функция **get_user_role** возвращает роль пользователя по его email
-
         """
         user = self.admin.users.search(email).values[0]
         return user.role
@@ -59,7 +56,6 @@ class ZendeskAdmin:
     def get_user_id(self, email: str) -> str:
         """
             Функция **get_user_id** возвращает id пользователя по его email
-
         """
         user = self.admin.users.search(email).values[0]
         return user.id
@@ -67,23 +63,29 @@ class ZendeskAdmin:
     def get_user_image(self, email: str) -> str:
         """
             Функция **get_user_image** возвращает аватар пользователя по его email
-
         """
         user = self.admin.users.search(email).values[0]
         return user.photo['content_url'] if user.photo else None
 
     def get_user(self, email: str) -> str:
+        """
+            Функция **get_user** возвращает пользователя (объект) по его email
+        """
         return self.admin.users.search(email).values[0]
 
     def get_user_org(self, email: str) -> str:
+        """
+            Функция **get_user_org** возвращает организацию, к которой относится пользователь по его email
+        """
         user = self.admin.users.search(email).values[0]
         return user.organization.name
 
-    def create_admin(self) -> None:
+    def create_admin(self) -> Zenpy:
         """
                 Функция **Create_admin()** создает администратора, проверяя наличие вводимых данных в env.
 
                 :param credentials: В список полномочий администратора вносятся email, token, password из env
+                :type credentials: :class:`dict`
                 :raise: :class:`ValueError`: исключение, вызываемое если email не введен в env
                 :raise: :class:`APIException`: исключение, вызываемое если пользователя с таким email не существует в Zendesk
         """
@@ -105,34 +107,43 @@ class ZendeskAdmin:
             raise ValueError('invalid access_controller`s login data')
 
 
-def update_role(user_profile, role):
+def update_role(user_profile: UserProfile, role: str) -> UserProfile:
+    """
+        Функция **update_role** меняет роль пользователя.
+    """
     zendesk = ZendeskAdmin()
     user = zendesk.get_user(user_profile.user.email)
     user.custom_role_id = role
     zendesk.admin.users.update(user)
 
 
-def make_engineer(user_profile):
+def make_engineer(user_profile: UserProfile) -> UserProfile:
+    """
+        Функция **make_engineer** устанавливапет пользователю роль инженера.
+    """
     update_role(user_profile, ROLES['engineer'])
 
 
-def make_light_agent(user_profile):
+def make_light_agent(user_profile: UserProfile) -> UserProfile:
+    """
+        Функция **make_light_agent** устанавливапет пользователю роль легкого агента.
+    """
     update_role(user_profile, ROLES['light_agent'])
 
 
-def get_users_list():
+def get_users_list() -> list:
+    """
+        Функция **get_users_list** возвращает список пользователей Zendesk, относящихся к организации.
+    """
     zendesk = ZendeskAdmin()
     admin = zendesk.get_user(zendesk.email)
     org = next(zendesk.admin.users.organizations(user=admin))
     return zendesk.admin.organizations.users(org)
 
 
-def update_profile(user_profile: UserProfile):
+def update_profile(user_profile: UserProfile) -> UserProfile:
     """
-    Функция обновляет профиль пользователя в соотвтетствии с текущим в Zendesk
-
-    :param user_profile: Объект профиля пользователя
-    :type user_profile: :class:`main.models.UserProfile`
+        Функция обновляет профиль пользователя в соотвтетствии с текущим в Zendesk
     """
     user = ZendeskAdmin().get_user(user_profile.user.email)
     user_profile.name = user.name
@@ -143,12 +154,7 @@ def update_profile(user_profile: UserProfile):
 
 def check_user_exist(email: str) -> bool:
     """
-    Функция проверяет, существует ли пользователь
-
-    :param email: Электронная почта пользователя
-    :type email: :class:`str`
-    :return: True, если существует, иначе False
-    :rtype: :class:`bool`
+        Функция проверяет, существует ли пользователь
     """
     return ZendeskAdmin().check_user(email)
 
@@ -156,11 +162,6 @@ def check_user_exist(email: str) -> bool:
 def get_user_organization(email: str) -> str:
     """
     Функция возвращает организацию пользователя
-
-    :param email: Электронная почта пользователя
-    :type email: :class:`str`
-    :return: Название организации
-    :rtype: :class:`str`
     """
     return ZendeskAdmin().get_user_org(email)
 
@@ -169,13 +170,7 @@ def check_user_auth(email: str, password: str) -> bool:
     """
     Функция проверяет, верны ли входные данные
 
-    :param email: Электроная почта пользователя
-    :type email: :class:`str`
-    :param password: Пароль пользователя
-    :type password: :class:`str`
-    :return: True, если входные данные верны, иначе False
     :raise: :class:`APIException`: исключение, вызываемое если пользователь не аутентифицирован
-    :rtype: :class:`bool`
     """
     creds = {
         'email': email,