educommon 3.12.0__py3-none-any.whl → 3.13.2__py3-none-any.whl

educommon/audit_log/migrations/0009_reinstall_audit_log.py

@@ -8,7 +8,6 @@ from educommon.audit_log.utils.operations import (
 
 
 class Migration(migrations.Migration):
-
     dependencies = [
         ('audit_log', '0008_table_logged'),
     ]

educommon/audit_log/models.py

@@ -66,15 +66,10 @@ if TYPE_CHECKING:
 
 
 class Table(ReadOnlyMixin, BaseModel):
+    """Модель для хранения информации о таблицах, отслеживаемых системой аудита."""
 
-    name = models.CharField(
-        max_length=250,
-        verbose_name='Имя таблицы'
-    )
-    schema = models.CharField(
-        max_length=250,
-        verbose_name='Схема таблицы'
-    )
+    name = models.CharField(max_length=250, verbose_name='Имя таблицы')
+    schema = models.CharField(max_length=250, verbose_name='Схема таблицы')
     logged = models.BooleanField(
         default=True,
         verbose_name='Отслеживаемость таблицы',
@@ -87,6 +82,18 @@ class Table(ReadOnlyMixin, BaseModel):
 
 
 class AuditLog(ReadOnlyMixin, BaseModel):
+    """Модель для хранения записей журнала изменений.
+
+    Каждая запись описывает изменение конкретного объекта определённой модели,
+    с указанием пользователя, действия, IP-адреса и зафиксированных данных.
+
+    Поля:
+        - table: ссылка на таблицу, в которой произошло изменение;
+        - data: сериализованные значения объекта до изменения;
+        - changes: изменения (только изменённые поля);
+        - operation: тип действия (создание, изменение, удаление);
+        - user_id, user_type_id, ip, time: информация об авторе действия.
+    """
 
     OPERATION_CREATE = 1
     OPERATION_UPDATE = 2
@@ -94,7 +101,7 @@ class AuditLog(ReadOnlyMixin, BaseModel):
     OPERATION_CHOICES = (
         (OPERATION_CREATE, 'Создание'),
         (OPERATION_UPDATE, 'Изменение'),
-        (OPERATION_DELETE, 'Удаление')
+        (OPERATION_DELETE, 'Удаление'),
     )
 
     user_id = models.IntegerField(
@@ -107,36 +114,17 @@ class AuditLog(ReadOnlyMixin, BaseModel):
         db_index=True,
         verbose_name='Тип пользователя',
     )
-    ip = models.GenericIPAddressField(
-        null=True,
-        verbose_name='IP адрес'
-    )
-    time = models.DateTimeField(
-        auto_now_add=True,
-        db_index=True,
-        verbose_name='Дата, время'
-    )
+    ip = models.GenericIPAddressField(null=True, verbose_name='IP адрес')
+    time = models.DateTimeField(auto_now_add=True, db_index=True, verbose_name='Дата, время')
     table = models.ForeignKey(
         Table,
         verbose_name='Таблица',
         on_delete=models.CASCADE,
     )
-    object_id = models.IntegerField(
-        db_index=True,
-        verbose_name='Объект модели'
-    )
-    data = HStoreField(
-        null=True,
-        verbose_name='Объект'
-    )
-    changes = HStoreField(
-        null=True,
-        verbose_name='Изменения'
-    )
-    operation = models.SmallIntegerField(
-        choices=OPERATION_CHOICES,
-        verbose_name='Действие'
-    )
+    object_id = models.IntegerField(db_index=True, verbose_name='Объект модели')
+    data = HStoreField(null=True, verbose_name='Объект')
+    changes = HStoreField(null=True, verbose_name='Изменения')
+    operation = models.SmallIntegerField(choices=OPERATION_CHOICES, verbose_name='Действие')
 
     @property
     def transformed_data(self) -> Dict[str, Any]:
@@ -153,6 +141,7 @@ class AuditLog(ReadOnlyMixin, BaseModel):
         return True
 
     def get_read_only_error_message(self, delete):
+        """Возвращает сообщение об ошибке при попытке изменить или удалить запись."""
         action_text = 'удалить' if delete else 'изменить'
         result = 'Нельзя {} запись лога.'.format(action_text)
         return result
@@ -170,10 +159,7 @@ class AuditLog(ReadOnlyMixin, BaseModel):
         """
         model = self.model
         if model:
-            result = {
-                field.get_attname_column()[1]: field
-                for field in model._meta.fields
-            }
+            result = {field.get_attname_column()[1]: field for field in model._meta.fields}
             return result
 
     @property
@@ -248,10 +234,7 @@ class AuditLog(ReadOnlyMixin, BaseModel):
 
             items = value[1:-1]
             if items:
-                return [
-                    base_field.to_python(item)
-                    for item in items.split(',')
-                ]
+                return [base_field.to_python(item) for item in items.split(',')]
 
     class Meta:
         verbose_name = 'Запись журнала изменений'
@@ -290,10 +273,13 @@ class PostgreSQLError(BaseModel):
 
 class LoggableModelMixin(models.Model):
     """Делает модель логируемой."""
+
     need_to_log = True
 
     class Meta:
         abstract = True
+
+
 # -----------------------------------------------------------------------------
 # Передача параметров контекста журналирования изменений в задания Celery.
 
@@ -341,13 +327,21 @@ def _set_audit_log_context_for_task(kwargs, **_):
 
 @task_postrun.connect(dispatch_uid=_package_name + 'unset')
 def _unset_audit_log_context_for_task(task, kwargs, **_):
+    """Очищает параметры журнала изменений после выполнения Celery-задания."""
     if hasattr(thread_data, 'audit_log_params'):
         del thread_data.audit_log_params
 
 
 @receiver(connection_created, dispatch_uid=_package_name + 'send')
 def _send_audit_log_context_to_db(**kwargs):
+    """Передаёт параметры контекста журнала изменений в БД при подключении.
+
+    Используется для установки параметров в PostgreSQL через set_config,
+    чтобы аудит знал, кто инициировал изменения.
+    """
     if hasattr(thread_data, 'audit_log_params'):
         for name, value in thread_data.audit_log_params.items():
             set_db_param('audit_log.' + name, value)
+
+
 # -----------------------------------------------------------------------------

educommon/audit_log/permissions.py

@@ -8,15 +8,17 @@ PERM__AUDIT_LOG__ERRORS__DELETE = PERM_GROUP__AUDIT_LOG_ERRORS + '/delete'
 
 
 permissions = (
-    (PERM__AUDIT_LOG__VIEW,
-     'Просмотр',
-     'Разрешает просмотр журнала изменений.'),
-    (PERM__AUDIT_LOG__ERRORS__VIEW,
-     'Просмотр журнала ошибок PostgreSQL',
-     'Разрешает просмотр журнала ошибок PostgreSQL.'),
-    (PERM__AUDIT_LOG__ERRORS__DELETE,
-     'Удаление записей журнала ошибок PostgreSQL',
-     'Разрешает удаление записей из журнала ошибок PostgreSQL.'),
+    (PERM__AUDIT_LOG__VIEW, 'Просмотр', 'Разрешает просмотр журнала изменений.'),
+    (
+        PERM__AUDIT_LOG__ERRORS__VIEW,
+        'Просмотр журнала ошибок PostgreSQL',
+        'Разрешает просмотр журнала ошибок PostgreSQL.',
+    ),
+    (
+        PERM__AUDIT_LOG__ERRORS__DELETE,
+        'Удаление записей журнала ошибок PostgreSQL',
+        'Разрешает удаление записей из журнала ошибок PostgreSQL.',
+    ),
 )
 
 

educommon/audit_log/proxies.py

@@ -56,11 +56,10 @@ class LogProxy(AuditLog):
                 try:
                     result = model.objects.get(id=user_id).person.fullname
                 except model.DoesNotExist:
-                    result = '{}({})'.format(
-                        model._meta.verbose_name, user_id
-                    )
+                    result = f'{model._meta.verbose_name}({user_id})'
         else:
             result = ''
+
         return result
 
     @property
@@ -113,7 +112,7 @@ class LogProxy(AuditLog):
             {
                 'name': self.get_field_string(key),
                 'old': self.convert_field_value(key, data.get(key, '')),
-                'new': self.convert_field_value(key, new_data.get(key, ''))
+                'new': self.convert_field_value(key, new_data.get(key, '')),
             }
             for key in keys
         ]
@@ -132,10 +131,12 @@ class LogProxy(AuditLog):
             field = self.fields.get(column_name)
             if field and field.verbose_name:
                 name = force_str(field.verbose_name)
+
         return name
 
     def convert_field_value(self, column_name, value):
         """Возвращает значение поля."""
+
         def get_choice(choices, choice_id):
             if choice_id:
                 choice_id = int(choice_id)
@@ -153,18 +154,14 @@ class LogProxy(AuditLog):
                             related = get_related(field)
                             model = related.parent_model
                             field_name = related.relation.field_name
-                            qs = model._default_manager.filter(
-                                **{field_name: value}
-                            )[:1]
+                            qs = model._default_manager.filter(**{field_name: value})[:1]
                             if qs:
                                 value = '{{{}}} {}'.format(
                                     qs[0].id,
                                     self._get_object_verbose_name(qs[0]),
                                 )
                     elif isinstance(field, BooleanField):
-                        value_map = {
-                            't': 'Да', 'f': 'Нет'
-                        }
+                        value_map = {'t': 'Да', 'f': 'Нет'}
                         value = value_map.get(value, value)
                     elif isinstance(field, IntegerField) and field.choices:
                         value = get_choice(field.choices, value)
@@ -173,11 +170,8 @@ class LogProxy(AuditLog):
         return force_str(value)
 
     @property
-    def object_string(self):
-        """Отображаемое имя экземпляра модели.
-
-        :rtype str
-        """
+    def object_string(self) -> str:
+        """Отображаемое имя экземпляра модели."""
         instance = self.instance
         if instance:
             return self._get_object_verbose_name(instance)
@@ -190,10 +184,7 @@ class LogProxy(AuditLog):
 
         if self.model:
             result = self.model()
-            fields_dict = {
-                field.name: field for field in
-                self.model._meta.fields
-            }
+            fields_dict = {field.name: field for field in self.model._meta.fields}
             for key, value in self.data.items():
                 field = fields_dict.get(key)
                 converted_value = value
@@ -210,15 +201,13 @@ class LogProxy(AuditLog):
                         elif isinstance(field, FloatField):
                             converted_value = float(value)
                         elif isinstance(field, FileField):
-                            file_path = os.path.join(
-                                settings.MEDIA_ROOT,
-                                converted_value
-                            )
+                            file_path = os.path.join(settings.MEDIA_ROOT, converted_value)
                             if not os.path.exists(file_path):
                                 converted_value = None
                     except (ValueError, TypeError):
                         pass
                 setattr(result, key, converted_value)
+
         return result
 
     @staticmethod

educommon/audit_log/ui.py

@@ -21,7 +21,12 @@ class ViewChangeWindow(BaseWindow):
     """Окно просмотра изменений."""
 
     def _init_components(self):
-        super(ViewChangeWindow, self)._init_components()
+        """Метод создаёт визуальные компоненты.
+
+        Метод отражает поля модели, но не определяет расположение компонентов в окне.
+        """
+        super()._init_components()
+
         self.grid = ExtObjectGrid(region='center')
         self.grid.add_column(data_index='name', header='Поле')
         self.grid.add_column(data_index='old', header='Старое значение')
@@ -30,35 +35,33 @@ class ViewChangeWindow(BaseWindow):
 
         self.user_field = ExtStringField(label='Пользователь')
         self.unit_field = ExtStringField(label='Учреждение')
-        self.top_region = ExtContainer(
-            region='north', layout='hbox', height=32
-        )
+        self.top_region = ExtContainer(region='north', layout='hbox', height=32)
 
     def _do_layout(self):
-        super(ViewChangeWindow, self)._do_layout()
+        """Метод располагает уже созданные визуальные компоненты на окне."""
+        super()._do_layout()
 
         self.layout = 'border'
         self.width, self.height = 750, 400
 
         self.grid.cls = 'word-wrap-grid'
 
-        self.top_region.items.extend((
-            formed(self.user_field, flex=1, style=dict(padding='5px')),
-            formed(self.unit_field, flex=1, style=dict(padding='5px'))
-        ))
+        self.top_region.items.extend(
+            (
+                formed(self.user_field, flex=1, style=dict(padding='5px')),
+                formed(self.unit_field, flex=1, style=dict(padding='5px')),
+            )
+        )
         self.items.extend((self.top_region, self.grid))
 
     def set_params(self, params):
+        """Метод принимает словарь, содержащий параметры окна, передаваемые в окно слоем экшнов."""
         self.grid.action_data = params['grid_action']
         log_record = params['object']
-        self.title = '{}: {}'.format(
-            log_record.get_operation_display(),
-            log_record.model_name
-        )
+        self.title = '{}: {}'.format(log_record.get_operation_display(), log_record.model_name)
         if log_record.user:
             self.user_field.value = '{} / {}'.format(
-                log_record.user.person.fullname,
-                log_record.user.person.user.username
+                log_record.user.person.fullname, log_record.user.person.user.username
             )
             unit = getattr(log_record.user, 'unit', None)
             if unit:

educommon/audit_log/utils/__init__.py

@@ -1,3 +1,4 @@
+# TODO - EDUSCHL-23454
 import os
 from contextlib import (
     closing,
@@ -72,11 +73,7 @@ def configure(force_update_triggers: bool = False):
     params['need_to_update_triggers'] = force_update_triggers or changed_table
     params['lock_id'] = PG_LOCK_ID
 
-    execute_sql_file(
-        settings.DEFAULT_DB_ALIAS,
-        os.path.join(SQL_FILES_DIR, 'configure_audit_log.sql'),
-        params
-    )
+    execute_sql_file(settings.DEFAULT_DB_ALIAS, os.path.join(SQL_FILES_DIR, 'configure_audit_log.sql'), params)
 
 
 def get_all_table_names(db_alias: str, schema: str) -> Set[str]:
@@ -97,11 +94,7 @@ def get_all_table_names(db_alias: str, schema: str) -> Set[str]:
 
 def get_need_to_log_table_names() -> Set[str]:
     """Возвращает перечень наименований таблиц моделей, которые отмечены как отслеживаемые."""
-    table_names = {
-        model._meta.db_table
-        for model in apps.get_models()
-        if getattr(model, 'need_to_log', False)
-    }
+    table_names = {model._meta.db_table for model in apps.get_models() if getattr(model, 'need_to_log', False)}
 
     return table_names
 
@@ -114,9 +107,7 @@ def update_or_create_tables(need_to_log_table_names: Iterable[str]) -> bool:
     Table = apps.get_model('audit_log', 'Table')
 
     need_to_log_table_names = set(need_to_log_table_names)
-    existed_table_names = set(
-        Table.objects.filter(schema='public').values_list('name', flat=True)
-    )
+    existed_table_names = set(Table.objects.filter(schema='public').values_list('name', flat=True))
 
     to_create_table_names = need_to_log_table_names - existed_table_names
     to_disable_table_names = existed_table_names - need_to_log_table_names
@@ -141,10 +132,7 @@ def update_or_create_tables(need_to_log_table_names: Iterable[str]) -> bool:
 
     # Создание записей таблиц, которые теперь отслеживаемые
     Table.objects.bulk_create(
-        objs=[
-            Table(name=table, schema='public')
-            for table in to_create_table_names
-        ],
+        objs=[Table(name=table, schema='public') for table in to_create_table_names],
     )
 
     if to_create_table_names or enabled_count or disabled_count:
@@ -229,10 +217,8 @@ def is_initialized(database_alias):
     # Проверка наличия таблицы postgresql_errors
     with closing(connections[database_alias].cursor()) as cursor:
         cursor.execute(
-            'select 1 '
-            'from information_schema.tables '
-            'where table_schema = %s and table_name = %s',
-            ('audit', 'postgresql_errors')
+            'select 1 from information_schema.tables where table_schema = %s and table_name = %s',
+            ('audit', 'postgresql_errors'),
         )
         if cursor.fetchone() is None:
             return False
@@ -251,12 +237,12 @@ def is_initialized(database_alias):
     for function_name in function_names:
         with closing(connections[database_alias].cursor()) as cursor:
             cursor.execute(
-                "select 1 "
-                "from pg_proc proc "
-                "inner join pg_namespace ns on ns.oid = proc.pronamespace "
-                "where proc.proname = %s and ns.nspname = %s "
-                "limit 1",
-                [function_name, 'audit']
+                'select 1 '
+                'from pg_proc proc '
+                'inner join pg_namespace ns on ns.oid = proc.pronamespace '
+                'where proc.proname = %s and ns.nspname = %s '
+                'limit 1',
+                [function_name, 'audit'],
             )
             if cursor.fetchone() is None:
                 return False
@@ -304,7 +290,7 @@ def get_db_connection_params():
         dbname=target_db_conf['NAME'],
         port=target_db_conf['PORT'],
         user=target_db_conf['USER'],
-        password=target_db_conf['PASSWORD']
+        password=target_db_conf['PASSWORD'],
     )
 
 
@@ -355,10 +341,7 @@ def make_hstore_filter(field, value):
     :param str value: значение, по которому фильтруется queryset.
     Если строка, то разбивается на отдельные слова.
     """
-    result = reduce(
-        and_,
-        (Q(**{'%s__values__icontains' % field: x}) for x in value.split(' '))
-    )
+    result = reduce(and_, (Q(**{f'{field}__values__icontains': x}) for x in value.split(' ')))
     return result
 
 
@@ -375,11 +358,7 @@ def make_name_filter(field, value):
     result = None
     for model in (Employee, SysAdmin):
         type_id = ContentType.objects.get_for_model(model).id
-        user_ids = list(
-            model.objects.filter(
-                **{'person__{}__icontains'.format(field): value}
-            ).values_list('id', flat=True)
-        )
+        user_ids = list(model.objects.filter(**{f'person__{field}__icontains': value}).values_list('id', flat=True))
         qobj = Q(user_id__in=user_ids, user_type_id=type_id)
         if result:
             result |= qobj
@@ -389,6 +368,13 @@ def make_name_filter(field, value):
 
 
 class ModelRegistry:
+    """Реестр моделей Django по имени таблицы.
+
+    Позволяет получать класс модели по имени таблицы из базы данных.
+    Использует кэшируемое свойство для построения соответствия
+    между именами таблиц и их моделями, включая автоматически
+    создаваемые модели, но исключая proxy-модели.
+    """
 
     @cached_property
     def table_model(self):
@@ -415,16 +401,9 @@ def get_model_choices(excluded=None):
     table_class = apps.get_model('audit_log', 'Table')
     if excluded:
         total_exclude += tuple(excluded)
-    tables = (
-        table
-        for table in table_class.objects.iterator()
-        if (table.schema, table.name) not in total_exclude
-    )
+    tables = (table for table in table_class.objects.iterator() if (table.schema, table.name) not in total_exclude)
 
-    result = sorted(
-        ((table.id, get_table_name(table)) for table in tables),
-        key=lambda x: x[1]
-    )
+    result = sorted(((table.id, get_table_name(table)) for table in tables), key=lambda x: x[1])
 
     return tuple(result)
 
@@ -435,12 +414,7 @@ def _get_m2m_model_fields(model):
     :return Два поля типа ForeignKey или None, если таблица не
             соответствует автоматически созданной.
     """
-    result = [
-        field
-        for field
-        in model._meta.get_fields()
-        if isinstance(field, related.ForeignKey)
-    ]
+    result = [field for field in model._meta.get_fields() if isinstance(field, related.ForeignKey)]
     if len(result) == 2:
         return result
 
@@ -454,16 +428,10 @@ def get_table_name(table):
         if model._meta.auto_created:
             fields = _get_m2m_model_fields(model)
             if fields:
-                names = [
-                    get_related(f).parent_model._meta.verbose_name
-                    for f in fields
-                ]
+                names = [get_related(f).parent_model._meta.verbose_name for f in fields]
                 verbose_name = 'Связь {}, {}'.format(names[0], names[1])
 
-        return '{} - {}'.format(
-            verbose_name,
-            class_name
-        )
+        return f'{verbose_name} - {class_name}'
     else:
         return table.name
 

educommon/audit_log/utils/operations.py

@@ -32,6 +32,7 @@ class ReinstallAuditLog(Operation):
 
     @staticmethod
     def _read_sql(filename):
+        """Читает SQL-файл и экранирует знаки процента."""
         sql_file_path = os.path.join(SQL_FILES_DIR, filename)
         with codecs.open(sql_file_path, 'r', 'utf-8') as sql_file:
             sql = sql_file.read().replace('%', '%%')
@@ -39,17 +40,30 @@ class ReinstallAuditLog(Operation):
 
     @property
     def _install_sql(self):
+        """Генерирует SQL-скрипт для установки схемы audit_log.
+
+        Подставляет параметры подключения к БД и lock_id
+        в шаблон SQL-файла install_audit_log.sql.
+        """
         params = get_db_connection_params()
         params['lock_id'] = PG_LOCK_ID
         return self._read_sql('install_audit_log.sql').format(**params)
 
     def state_forwards(self, app_label, state):
+        """Не изменяет состояние проекта в памяти.
+
+        Метод требуется по контракту абстрактного базового класса Operation.
+        """
         pass
 
-    def database_forwards(self, app_label, schema_editor, from_state,
-                          to_state):
+    def database_forwards(self, app_label, schema_editor, from_state, to_state):
+        """Применяет SQL-скрипт установки audit_log, если используется основная БД."""
         if schema_editor.connection.alias == settings.DEFAULT_DB_ALIAS:
             schema_editor.execute(self._install_sql)
 
     def database_backwards(self, app_label, schema_editor, from_state, to_state):
+        """Откат миграции не реализован (no-op).
+
+        Метод присутствует, чтобы соответствовать контракту Django.
+        """
         return None

educommon/auth/__init__.py

@@ -1,4 +1 @@
 """Средства аутентификации и авторизации."""
-from __future__ import (
-    absolute_import,
-)

educommon/auth/rbac/__init__.py

@@ -3,12 +3,10 @@
 .. note::
    RBAC - Role Based Access Control.
 """
+
 from django import (
     VERSION as _django_version,
 )
 
 
-assert _django_version >= (1, 8), (
-    "{} app doesn't support Django {}.{}."
-    .format(__name__, *_django_version[:2])
-)
+assert _django_version >= (1, 8), "{} app doesn't support Django {}.{}.".format(__name__, *_django_version[:2])