diff --git a/docs/source/code.rst b/docs/source/code.rst index 85d207b..7c5a05d 100644 --- a/docs/source/code.rst +++ b/docs/source/code.rst @@ -2,9 +2,9 @@ ========================= -****** +******* Models -****** +******* .. automodule:: main.models :members: diff --git a/main/extra_func.py b/main/extra_func.py index ada4a88..f51be0f 100644 --- a/main/extra_func.py +++ b/main/extra_func.py @@ -11,16 +11,16 @@ from main.models import UserProfile, RoleChangeLogs class ZendeskAdmin: """ - Класс **ZendeskAdmin** существует, чтобы в каждой фунциии отдельно не проверять аккаунт администратора + Класс **ZendeskAdmin** существует, чтобы в каждой фунциии отдельно не проверять аккаунт администратора. - :param credentials: Полномочия (первым указывается учетная запись организации в Zendesk) - :type credentials: :class:`dict` - :param email: Email администратора, указанный в env - :type email: :class:`str` - :param token: Токен администратора (формируется в Zendesk, указывается в env) - :type token: :class:`str` - :param password: Пароль администратора, указанный в env - :type password: :class:`str` + :param credentials: Полномочия (первым указывается учетная запись организации в Zendesk) + :type credentials: :class:`dict` + :param email: Email администратора, указанный в env + :type email: :class:`str` + :param token: Токен администратора (формируется в Zendesk, указывается в env) + :type token: :class:`str` + :param password: Пароль администратора, указанный в env + :type password: :class:`str` """ credentials: dict = { @@ -41,41 +41,56 @@ class ZendeskAdmin: def check_user(self, email: str) -> bool: """ - Функция **check_user** осуществляет проверку существования пользователя в Zendesk по email + Функция осуществляет проверку существования пользователя в Zendesk по email. + + :param email: + :return: """ return True if self.admin.search(email, type='user') else False def get_user_name(self, email: str) -> str: """ - Функция **get_user_name** возвращает имя пользователя по его email + Функция возвращает имя пользователя по его email. + + :param email: + :return: """ user = self.admin.users.search(email).values[0] return user.name def get_user_role(self, email: str) -> str: """ - Функция **get_user_role** возвращает роль пользователя по его email + Функция возвращает роль пользователя по его email. + + :param email: + :return: """ user = self.admin.users.search(email).values[0] return user.role def get_user_id(self, email: str) -> str: """ - Функция **get_user_id** возвращает id пользователя по его email + Функция возвращает id пользователя по его email + + :param email: + :return: """ user = self.admin.users.search(email).values[0] return user.id def get_user_image(self, email: str) -> str: """ - Функция **get_user_image** возвращает url-ссылку на аватар пользователя по его email + Функция возвращает url-ссылку на аватар пользователя по его email. + + :param email: + :return: """ user = self.admin.users.search(email).values[0] return user.photo['content_url'] if user.photo else None def get_user(self, email: str): """ - Функция **get_user** возвращает пользователя (объект) по его email + Функция возвращает пользователя (объект) по его email :param email: email пользователя :return: email пользователя, найденного в БД @@ -84,19 +99,22 @@ class ZendeskAdmin: def get_user_org(self, email: str) -> str: """ - Функция **get_user_org** возвращает организацию, к которой относится пользователь по его email + Функция возвращает организацию, к которой относится пользователь по его email. + + :param email: + :return: """ user = self.admin.users.search(email).values[0] return user.organization.name if user.organization else None def create_admin(self) -> Zenpy: """ - Функция **Create_admin()** создает администратора, проверяя наличие вводимых данных в env. + Функция создает администратора, проверяя наличие вводимых данных в env. - :param credentials: В список полномочий администратора вносятся email, token, password из env - :type credentials: :class:`dict` - :raise: :class:`ValueError`: исключение, вызываемое если email не введен в env - :raise: :class:`APIException`: исключение, вызываемое если пользователя с таким email не существует в Zendesk + :param credentials: В список полномочий администратора вносятся email, token, password из env + :type credentials: :class:`dict` + :raise: :class:`ValueError`: исключение, вызываемое если email не введен в env + :raise: :class:`APIException`: исключение, вызываемое если пользователя с таким email не существует в Zendesk """ if self.email is None: @@ -118,7 +136,11 @@ class ZendeskAdmin: def update_role(user_profile: UserProfile, role: str) -> UserProfile: """ - Функция **update_role** меняет роль пользователя. + Функция меняет роль пользователя. + + :param user_profile: + :param role: + :return: """ zendesk = ZendeskAdmin() user = zendesk.get_user(user_profile.user.email) @@ -128,21 +150,28 @@ def update_role(user_profile: UserProfile, role: str) -> UserProfile: def make_engineer(user_profile: UserProfile) -> UserProfile: """ - Функция **make_engineer** устанавливапет пользователю роль инженера. + Функция устанавливапет пользователю роль инженера. + + :param user_profile: + :return: """ update_role(user_profile, ROLES['engineer']) def make_light_agent(user_profile: UserProfile) -> UserProfile: """ - Функция **make_light_agent** устанавливапет пользователю роль легкого агента. + Функция устанавливапет пользователю роль легкого агента. + + :param user_profile: + :return: """ update_role(user_profile, ROLES['light_agent']) def get_users_list() -> list: """ - Функция **get_users_list** возвращает список пользователей Zendesk, относящихся к организации. + Функция возвращает список пользователей Zendesk, относящихся к организации. + :return: """ zendesk = ZendeskAdmin() admin = zendesk.get_user(zendesk.email) @@ -152,7 +181,10 @@ def get_users_list() -> list: def update_profile(user_profile: UserProfile) -> UserProfile: """ - Функция обновляет профиль пользователя в соотвтетствии с текущим в Zendesk + Функция обновляет профиль пользователя в соотвтетствии с текущим в Zendesk. + + :param user_profile: + :return: """ user = ZendeskAdmin().get_user(user_profile.user.email) user_profile.name = user.name @@ -164,21 +196,31 @@ def update_profile(user_profile: UserProfile) -> UserProfile: def check_user_exist(email: str) -> bool: """ - Функция проверяет, существует ли пользователь + Функция проверяет, существует ли пользователь. + + :param email: + :return: """ return ZendeskAdmin().check_user(email) def get_user_organization(email: str) -> str: """ - Функция возвращает организацию пользователя + Функция возвращает организацию пользователя. + + :param email: + :return: """ return ZendeskAdmin().get_user_org(email) def daterange(start_date, end_date) -> list: """ - Возвращает список дней с start_date по end_date исключая правую границу + Функция возвращает список дней с start_date по end_date, исключая правую границу. + + :param start_date: + :param end_date: + :return: """ dates = [] for n in range(int((end_date - start_date).days)): @@ -188,8 +230,12 @@ def daterange(start_date, end_date) -> list: def get_timedelta(log, time=None) -> timedelta: """ - Возвращает объект класса timedelta, который хранит промежуток времени от начала суток до момента, - который находится в log (объект класса RoleChangeLogs) или в time(datetime.time), если введён + Функция возвращает объект класса timedelta, который хранит промежуток времени от начала суток до момента, + который находится в log (объект класса RoleChangeLogs) или в time(datetime.time), если введён. + + :param log: + :param time: + :return: """ if time is None: time = log.change_time.time() @@ -199,7 +245,10 @@ def get_timedelta(log, time=None) -> timedelta: def last_day_of_month(day): """ - Возвращает последний день любого месяца + Функция возвращает последний день любого месяца. + + :param day: + :return: """ next_month = day.replace(day=28) + timedelta(days=4) return next_month - timedelta(days=next_month.day) @@ -224,8 +273,10 @@ class StatisticData: def get_statistic(self): """ - Вернуть словарь statistic с применением формата отображения и интеравала работы(если они есть) - None, если были ошибки при создании + Функция возвращает словарь statistic с применением формата отображения и интеравала работы(если они есть). + None, если были ошибки при создании. + + :return: """ if self.is_valid_statistic(): stat = self.statistic @@ -237,13 +288,18 @@ class StatisticData: def is_valid_statistic(self): """ - Были ли ошибки при создании статистики + Функция проверяет были ли ошибки при создании статистики. + + :return: """ return not self.errors and self.statistic def set_interval(self, interval): """ - Устанавливает интервал работы + Функция устанавливает интервал работы. + + :param interval: + :return: """ if interval not in ['months', 'days']: self.errors += ['Интервал работы должен быть в днях или месяцах'] @@ -253,7 +309,10 @@ class StatisticData: def set_display(self, display_format): """ - Устанавливает формат отображения + Функция устанавливает формат отображения. + + :param display_format: + :return: """ if display_format not in ['days', 'hours']: self.errors += ['Формат отображения должен быть в часах или днях'] @@ -263,9 +322,9 @@ class StatisticData: def get_data(self): """ - Вернуть данные - data - массив объектов RoleChangeLogs, является списком логов пользователя - data может быть пустым списком + Функция возвращает данные - массив объектов RoleChangeLogs. + + :return: """ if self.is_valid_data(): return self.data @@ -274,13 +333,18 @@ class StatisticData: def is_valid_data(self): """ - Были ли ошибки при получении логов + Функция определяет были ли ошибки при получении логов. + + :return: """ return not self.errors def _use_display(self, stat): """ - Приводит данные к формату отображения + Функция приводит данные к формату отображения. + + :param stat: + :return: """ if not self.is_valid_statistic() or not self.display: return stat @@ -294,7 +358,10 @@ class StatisticData: def _use_interval(self, stat): """ - Объединяет ключи и значения в соответствии с интервалом работы + Функция объединяет ключи и значения в соответствии с интервалом работы. + + :param stat: + :return: """ if not self.is_valid_statistic() or not self.interval: return stat @@ -323,7 +390,9 @@ class StatisticData: def _set_data(self): """ - Получение логов в диапазоне дат start_date-end_date для пользователя с почтой email + Функция возвращает логи в диапазоне дат start_date-end_date для пользователя с указанным email. + + :return: """ if not self.check_time(): self.errors += ['Конец диапазона должен быть позже начала диапазона и раньше текущего времени'] @@ -338,7 +407,9 @@ class StatisticData: def _set_statistic(self): """ - Функция заполняет словарь, в котором ключ - дата, значение - кол-во проработанных в этот день секунд + Функция заполняет словарь, в котором ключ - дата, значение - кол-во проработанных в этот день секунд. + + :return: """ self.clear_statistic() if not self.get_data(): @@ -370,15 +441,20 @@ class StatisticData: def fill_daterange(self, first, last, val=24 * 3600): """ - Заполение диапазона дат значением val - по умолчанию val = кол-во секунд в 1 дне + Функция заполеняет диапазон дат значением val (по умолчанию val = кол-во секунд в 1 дне). + + :param first: + :param last: + :param val: + :return: """ for day in daterange(first, last): self.statistic[day] = val def clear_statistic(self): """ - Обнуление всех дней + Функция осуществляет обновление всех дней + :return: """ self.statistic.clear() self.fill_daterange(self.start_date, self.end_date + timedelta(days=1), 0) diff --git a/main/models.py b/main/models.py index 112e29e..b3e235c 100644 --- a/main/models.py +++ b/main/models.py @@ -5,7 +5,10 @@ from django.dispatch import receiver class UserProfile(models.Model): - """Модель профиля пользователя""" + """ + Модель профиля пользователя + + """ class Meta: permissions = ( @@ -31,7 +34,11 @@ def save_user_profile(sender, instance, **kwargs): class RoleChangeLogs(models.Model): - """Модель для логирования изменений ролей пользователя""" + """ + Модель для логирования изменений ролей пользователя + + """ + user = models.ForeignKey(to=User, on_delete=models.CASCADE, help_text='Пользователь, которому присвоили другую роль') name = models.TextField(help_text='Имя пользователя') @@ -40,3 +47,4 @@ class RoleChangeLogs(models.Model): change_time = models.DateTimeField(help_text='Дата и время изменения роли') changed_by = models.ForeignKey(to=User, on_delete=models.CASCADE, related_name='changed_by', help_text='Кем была изменена роль') +