From c216b44b2ae7d1723588c682f44671b890fe64a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D1=82=D0=B5=D0=BF=D0=B0=D0=BD=D0=B5=D0=BD=D0=BA?= =?UTF-8?q?=D0=BE=20=D0=9E=D0=BB=D1=8C=D0=B3=D0=B0?= Date: Tue, 16 Feb 2021 12:28:08 +0300 Subject: [PATCH 1/6] Make models documentation --- docs/source/code.rst | 11 ++++++++--- docs/source/index.rst | 1 + main/extra_func.py | 19 ++++++++++++++----- main/models.py | 12 ++++++++++++ requirements.txt | 2 +- 5 files changed, 36 insertions(+), 9 deletions(-) diff --git a/docs/source/code.rst b/docs/source/code.rst index 1c8af9f..3c660f7 100644 --- a/docs/source/code.rst +++ b/docs/source/code.rst @@ -1,6 +1,11 @@ -***** -TODOs -***** + +Models +------ + +.. automodule:: main.models + :members: + + Extra Functions --------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index 778a091..2fcbe88 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,6 +15,7 @@ Welcome to ZenDesk Access Controller's documentation! todo.rst + Indices and tables ================== diff --git a/main/extra_func.py b/main/extra_func.py index 305e897..3f679c8 100644 --- a/main/extra_func.py +++ b/main/extra_func.py @@ -6,7 +6,7 @@ from zenpy.lib.exception import APIException from main.models import UserProfile -# Дополнительные функции + def set_and_get_name(user_profile: UserProfile): """ Функция устанавливает поле :class:`username` текущим именем в Zendesk @@ -22,10 +22,13 @@ def set_and_get_name(user_profile: UserProfile): return user_profile.user.username -def set_and_get_email(user_profile: UserProfile): # TODO: Переделать с получением данных через API +def set_and_get_email(user_profile: UserProfile): """ Функция устанавливает поле :class:`user.email` текущей почтой в Zendesk + .. TODO:: + Переделать с получением данных через API + :param UP: Объект профиля пользователя :type UP: :class:`main.models.UserProfile` :return: Почта пользователя @@ -34,10 +37,13 @@ def set_and_get_email(user_profile: UserProfile): # TODO: Переделать return user_profile.user.email -def set_and_get_role(user_profile: UserProfile): # TODO: Переделать с получением данных через API +def set_and_get_role(user_profile: UserProfile): """ Функция устанавливает поле :class:`role` текущей ролью в Zendesk + .. TODO:: + Переделать с получением данных через API + :param UP: Объект профиля пользователя :type UP: :class:`main.models.UserProfile` :return: Роль пользователя @@ -46,10 +52,13 @@ def set_and_get_role(user_profile: UserProfile): # TODO: Переделать return user_profile.role -def load_and_get_image(user_profile: UserProfile): # TODO: Переделать с получением изображения через API +def load_and_get_image(user_profile: UserProfile): """ Функция загружает и устанавливает изображение в поле :class:`image` + .. TODO:: + Переделать с получением изображения через API + :param UP: Объект профиля пользователя :type UP: :class:`main.models.UserProfile` :return: Название изображения @@ -88,7 +97,7 @@ def check_user_auth(email: str, password: str) -> bool: :param password: Пароль пользователя :type password: :class:`str` :return: True, если входные данные верны, иначе False - :raise :class:`APIException`: исключение, вызываемое если пользователь не аутентифицирован + :raise: :class:`APIException`: исключение, вызываемое если пользователь не аутентифицирован :rtype: :class:`bool` """ try: diff --git a/main/models.py b/main/models.py index 96d04db..53b404d 100644 --- a/main/models.py +++ b/main/models.py @@ -5,6 +5,18 @@ from django.db import models class UserProfile(models.Model): + """ + Модель профиля пользователя + + :param user: OneToOneField к модели :class:`django.contrib.auth.models.User` + :param role: Код роли пользователя + :type role: :class:`integer` + :param image: Аватарка + :type image: :class:`img` + :param name: Имя пользователя на нашем сайте + :type name: :class:`str` + """ + user = models.OneToOneField(to=User, on_delete=models.CASCADE) role = models.IntegerField() image = models.ImageField(upload_to='user_avatars') diff --git a/requirements.txt b/requirements.txt index e40b267..b2e4c64 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,7 +2,7 @@ Django==3.1.6 Pillow==8.1.0 zenpy~=2.0.24 -django-registration==3.1.1 +django_registration==3.1.1 # Documentation From 6edb0d2c17bcd7a899e9649c74489826533cb024 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D1=82=D0=B5=D0=BF=D0=B0=D0=BD=D0=B5=D0=BD=D0=BA?= =?UTF-8?q?=D0=BE=20=D0=9E=D0=BB=D1=8C=D0=B3=D0=B0?= Date: Tue, 16 Feb 2021 15:41:55 +0300 Subject: [PATCH 2/6] Add new context --- docs/source/code.rst | 11 ++++++----- docs/source/index.rst | 13 +++++++++++-- docs/source/todo.rst | 1 + main/extra_func.py | 8 ++++---- 4 files changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/source/code.rst b/docs/source/code.rst index 3c660f7..2d0af4e 100644 --- a/docs/source/code.rst +++ b/docs/source/code.rst @@ -1,21 +1,22 @@ - +****** Models ------- +****** .. automodule:: main.models :members: - +*************** Extra Functions ---------------- +*************** .. automodule:: main.extra_func :members: +***** Views ------ +***** .. automodule:: main.views :members: diff --git a/docs/source/index.rst b/docs/source/index.rst index 2fcbe88..4cbdce9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,13 +6,22 @@ Welcome to ZenDesk Access Controller's documentation! ===================================================== +Структура документации: +----------------------- + +Документация пользователя +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Документация разработчика +~~~~~~~~~~~~~~~~~~~~~~~~~ + .. toctree:: :maxdepth: 2 :caption: Contents: - code.rst - todo.rst + code + todo diff --git a/docs/source/todo.rst b/docs/source/todo.rst index d6ad446..64946f9 100644 --- a/docs/source/todo.rst +++ b/docs/source/todo.rst @@ -3,3 +3,4 @@ TODOs ***** .. todolist:: + diff --git a/main/extra_func.py b/main/extra_func.py index 3f679c8..f44ff2a 100644 --- a/main/extra_func.py +++ b/main/extra_func.py @@ -12,7 +12,7 @@ def set_and_get_name(user_profile: UserProfile): Функция устанавливает поле :class:`username` текущим именем в Zendesk .. TODO:: - Переделать с получением данных через API + Переделать функцию set_and_get_name с получением данных через API :param UP: Объект профиля пользователя :type UP: :class:`main.models.UserProfile` @@ -27,7 +27,7 @@ def set_and_get_email(user_profile: UserProfile): Функция устанавливает поле :class:`user.email` текущей почтой в Zendesk .. TODO:: - Переделать с получением данных через API + Переделать функцию set_and_get_email с получением данных через API :param UP: Объект профиля пользователя :type UP: :class:`main.models.UserProfile` @@ -42,7 +42,7 @@ def set_and_get_role(user_profile: UserProfile): Функция устанавливает поле :class:`role` текущей ролью в Zendesk .. TODO:: - Переделать с получением данных через API + Переделать функцию set_and_get_role с получением данных через API :param UP: Объект профиля пользователя :type UP: :class:`main.models.UserProfile` @@ -57,7 +57,7 @@ def load_and_get_image(user_profile: UserProfile): Функция загружает и устанавливает изображение в поле :class:`image` .. TODO:: - Переделать с получением изображения через API + Переделать функцию load_and_get_image с получением изображения через API :param UP: Объект профиля пользователя :type UP: :class:`main.models.UserProfile` From 774cbbe8029c4845ba2d68336b7d53dc7b1f3982 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D1=82=D0=B5=D0=BF=D0=B0=D0=BD=D0=B5=D0=BD=D0=BA?= =?UTF-8?q?=D0=BE=20=D0=9E=D0=BB=D1=8C=D0=B3=D0=B0?= Date: Thu, 18 Feb 2021 09:19:00 +0300 Subject: [PATCH 3/6] Fix warnings --- main/extra_func.py | 55 +++++++++++++++++++++++++++++++++++++++++----- main/models.py | 20 ++++++++--------- 2 files changed, 58 insertions(+), 17 deletions(-) diff --git a/main/extra_func.py b/main/extra_func.py index 73c533b..7a0a2de 100644 --- a/main/extra_func.py +++ b/main/extra_func.py @@ -6,9 +6,20 @@ from zenpy.lib.exception import APIException from main.models import UserProfile -# Дополнительные функции class ZendeskAdmin: - # Класс существует, чтобы в каждой фунциии отдельно не проверять аккаунт администратора + """ + Класс **ZendeskAdmin** существует, чтобы в каждой фунциии отдельно не проверять аккаунт администратора + + :param credentials: Полномочия пользователя (первым указывается учетная запись организации в Zendesk) + :type credentials: :class:`list of dictionaries` + :param email: Email пользователя, указанный в Zendesk + :type email: :class:`email` + :param token: Токен пользователя (формируется в Zendesk) + :type token: :class:`str` + :param password: Пароль пользователя, указанный в Zendesk + :type password: :class:`str` + """ + credentials = { 'subdomain': 'ngenix1612197338' } @@ -23,22 +34,54 @@ class ZendeskAdmin: return True if self.admin.search(email, type='user') else False def get_user_name(self, email: str) -> str: + """ + Функция **get_user_name** возвращает имя пользователя + + :param user_name: Имя пользователя + :type user_name: :class:`str` + """ user = self.admin.users.search(email).values[0] return user.name def get_user_role(self, email: str) -> str: + """ + Функция **get_user_role** возвращает роль пользователя + + :param user_role: Роль пользователя + :type user_role: :class:`str` + """ user = self.admin.users.search(email).values[0] return user.role def get_user_id(self, email: str) -> str: + """ + Функция **get_user_id** возвращает id пользователя + + :param user_id: ID пользователя + :type user_id: :class:`str` + """ user = self.admin.users.search(email).values[0] return user.id def get_user_image(self, email: str) -> str: + """ + Функция **get_user_image** возвращает аватар пользователя + + :param user_image: Аватар пользователя + :type user_image: :class:`img` + """ user = self.admin.users.search(email).values[0] return user.photo['content_url'] if user.photo else None def create_admin(self) -> None: + """ + Функция **Create_admin()** создает администратора, проверяя наличие вводимых данных в env. + + :param credentials: В список полномочий администратора вносятся email, token, password из env + :raise: :class:`ValueError`: исключение, вызываемое если email не введен в env + :raise: :class:`APIException`: исключение, вызываемое если пользователя с таким email не существует в Zendesk + """ + if self.email is None: raise ValueError('access_controller email not in env') self.credentials['email'] = os.getenv('ACCESS_CONTROLLER_API_EMAIL') @@ -58,10 +101,10 @@ class ZendeskAdmin: def update_profile(user_profile: UserProfile): """ - Функция обновляет профиль пользователя в соотвтетствии с текущим в Zendesk + Функция обновляет профиль пользователя в соотвтетствии с текущим в Zendesk - :param user_profile: Объект профиля пользователя - :type user_profile: :class:`main.models.UserProfile` + :param user_profile: Объект профиля пользователя + :type user_profile: :class:`main.models.UserProfile` """ user_profile.name = ZendeskAdmin().get_user_name(user_profile.user.email) user_profile.role = ZendeskAdmin().get_user_role(user_profile.user.email) @@ -90,7 +133,7 @@ def check_user_auth(email: str, password: str) -> bool: :param password: Пароль пользователя :type password: :class:`str` :return: True, если входные данные верны, иначе False - :raise :class:`APIException`: исключение, вызываемое если пользователь не аутентифицирован + :raise: :class:`APIException`: исключение, вызываемое если пользователь не аутентифицирован :rtype: :class:`bool` """ creds = { diff --git a/main/models.py b/main/models.py index e7d356d..3e3fe29 100644 --- a/main/models.py +++ b/main/models.py @@ -36,18 +36,16 @@ def save_user_profile(sender, instance, **kwargs): class RoleChangeLogs(models.Model): """ - Модель для логирования изменений ролей пользователя + Модель для логирования изменений ролей пользователя - :param user: Пользователь, которому присвоили другую роль, - ForeignKey к модели :class:`django.contrib.auth.models.User` - :param name: Имя пользователя - :type name: :class:`str` - :param new_role: Присвоенная роль - :type new_role: :class:`str` - :param change_time: Дата изменения роли` - :type change_time: :class:`datetime.datetime` - :param changed_by: Кем была изменена роль, - ForeignKey к модели :class:`django.contrib.auth.models.User` + :param user: Пользователь, которому присвоили другую роль, ForeignKey к модели :class:`django.contrib.auth.models.User` + :param name: Имя пользователя + :type name: :class:`str` + :param new_role: Присвоенная роль + :type new_role: :class:`str` + :param change_time: Дата изменения роли` + :type change_time: :class:`datetime.datetime` + :param changed_by: Кем была изменена роль, ForeignKey к модели :class:`django.contrib.auth.models.User` """ user = models.ForeignKey(to=User, on_delete=models.CASCADE) name = models.TextField() From f25e2cd6ad1adca49fd7d45c4913ad7e4036a8dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D1=82=D0=B5=D0=BF=D0=B0=D0=BD=D0=B5=D0=BD=D0=BA?= =?UTF-8?q?=D0=BE=20=D0=9E=D0=BB=D1=8C=D0=B3=D0=B0?= Date: Thu, 18 Feb 2021 09:23:11 +0300 Subject: [PATCH 4/6] Add forms documentation --- docs/source/code.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/source/code.rst b/docs/source/code.rst index 2d0af4e..246e791 100644 --- a/docs/source/code.rst +++ b/docs/source/code.rst @@ -6,6 +6,13 @@ Models :members: +****** +Forms +****** + +.. automodule:: main.forms + :members: + *************** Extra Functions *************** From ae5ed94bc91f2a97c4a94782164bf59422e472b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D1=82=D0=B5=D0=BF=D0=B0=D0=BD=D0=B5=D0=BD=D0=BA?= =?UTF-8?q?=D0=BE=20=D0=9E=D0=BB=D1=8C=D0=B3=D0=B0?= Date: Thu, 18 Feb 2021 10:49:17 +0300 Subject: [PATCH 5/6] Change extra_func documentation --- main/extra_func.py | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/main/extra_func.py b/main/extra_func.py index 7a0a2de..d510430 100644 --- a/main/extra_func.py +++ b/main/extra_func.py @@ -10,13 +10,13 @@ class ZendeskAdmin: """ Класс **ZendeskAdmin** существует, чтобы в каждой фунциии отдельно не проверять аккаунт администратора - :param credentials: Полномочия пользователя (первым указывается учетная запись организации в Zendesk) + :param credentials: Полномочия (первым указывается учетная запись организации в Zendesk) :type credentials: :class:`list of dictionaries` - :param email: Email пользователя, указанный в Zendesk + :param email: Email администратора, указанный в env :type email: :class:`email` - :param token: Токен пользователя (формируется в Zendesk) + :param token: Токен администратора (формируется в Zendesk, указывается в env) :type token: :class:`str` - :param password: Пароль пользователя, указанный в Zendesk + :param password: Пароль администратора, указанный в env :type password: :class:`str` """ @@ -31,6 +31,14 @@ class ZendeskAdmin: self.create_admin() def check_user(self, email: str) -> bool: + """ + Функция **check_user** осуществляет проверку существования пользователя в Zendesk + + :param email: Электронная почта пользователя + :type email: :class:`email` + :return: True, если существует, иначе False + :rtype: :class:`bool` + """ return True if self.admin.search(email, type='user') else False def get_user_name(self, email: str) -> str: From cc44bdf068d346b96ea2161032dee649398d6763 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D1=82=D0=B5=D0=BF=D0=B0=D0=BD=D0=B5=D0=BD=D0=BA?= =?UTF-8?q?=D0=BE=20=D0=9E=D0=BB=D1=8C=D0=B3=D0=B0?= Date: Thu, 18 Feb 2021 11:44:13 +0300 Subject: [PATCH 6/6] Add template of users documentation --- docs/source/code.rst | 5 +++++ docs/source/index.rst | 11 +---------- docs/source/overview.rst | 18 ++++++++++++++++++ docs/source/todo.rst | 5 +++++ 4 files changed, 29 insertions(+), 10 deletions(-) create mode 100644 docs/source/overview.rst diff --git a/docs/source/code.rst b/docs/source/code.rst index 246e791..85d207b 100644 --- a/docs/source/code.rst +++ b/docs/source/code.rst @@ -1,3 +1,7 @@ +Документация разработчика +========================= + + ****** Models ****** @@ -13,6 +17,7 @@ Forms .. automodule:: main.forms :members: + *************** Extra Functions *************** diff --git a/docs/source/index.rst b/docs/source/index.rst index 4cbdce9..83cf46a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,20 +6,11 @@ Welcome to ZenDesk Access Controller's documentation! ===================================================== -Структура документации: ------------------------ - -Документация пользователя -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Документация разработчика -~~~~~~~~~~~~~~~~~~~~~~~~~ - - .. toctree:: :maxdepth: 2 :caption: Contents: + overview code todo diff --git a/docs/source/overview.rst b/docs/source/overview.rst new file mode 100644 index 0000000..447e273 --- /dev/null +++ b/docs/source/overview.rst @@ -0,0 +1,18 @@ + +Документация пользователя +========================= + +**Управление правами доступа** + + +**ZenDesk Access Controller** - Web-приложение, для выдачи прав пользователям системы по запросу самого пользователя. + +Например, из 12 человек 3 сейчас работают с правами администратора, по окончании рабочей смены они сдают свои права (освобождают места) и другие пользователи могут запросить эти права в свое пользование. + +Оставшиеся 9 человек получают права легкого агента - без прав редактирования, а только чтение. + +**Интерфейс пользователя:** + + + +.. |copy| unicode:: 0xA9 .. Школа программистов S101, группа 2. 2021гю diff --git a/docs/source/todo.rst b/docs/source/todo.rst index 64946f9..a8d024b 100644 --- a/docs/source/todo.rst +++ b/docs/source/todo.rst @@ -1,3 +1,8 @@ +Что необходимо доделать? +======================= + + + ***** TODOs *****