educommon 3.10.1__tar.gz → 3.11.1__tar.gz

{educommon-3.10.1/src/educommon.egg-info → educommon-3.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: educommon
-Version: 3.10.1
+Version: 3.11.1
 Summary: Общая кодовая база для проектов БЦ Образование
 Home-page: https://stash.bars-open.ru/projects/EDUBASE/repos/educommon
 Author: BARS Group
@@ -20,7 +20,7 @@ Classifier: Framework :: Django :: 3.0
 Classifier: Framework :: Django :: 3.1
 Classifier: Framework :: Django :: 3.2
 Requires-Dist: packaging<24,>=21.3
-Requires-Dist: Django<4,>=2.2
+Requires-Dist: Django<4,>=3.1
 Requires-Dist: django-mptt
 Requires-Dist: python-dateutil
 Requires-Dist: termcolor
@@ -39,3 +39,9 @@ Requires-Dist: m3-simple-report<2,>=1.4.1
 Requires-Dist: m3-spyne-smev<2,>=0.2.4
 Requires-Dist: python-magic==0.4.15
 Requires-Dist: distro<2,>=1.3.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: summary

{educommon-3.10.1 → educommon-3.11.1}/setup.py

@@ -49,7 +49,7 @@ def main():
         ),
         install_requires=(
             'packaging>=21.3,<24',
-            'Django>=2.2,<4',
+            'Django>=3.1,<4',
             'django-mptt',
             'python-dateutil',
             'termcolor',

educommon-3.11.1/src/educommon/async_task/migrations/0003_alter_runningtask_options.py

@@ -0,0 +1,18 @@
+# Generated by Django 3.2.23 on 2025-02-04 13:16
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('async_task', '0002_task_type_and_status_data'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='runningtask',
+            name='options',
+            field=models.JSONField(blank=True, null=True, verbose_name='Дополнительные опции задачи'),
+        ),
+    ]

{educommon-3.10.1 → educommon-3.11.1}/src/educommon/async_task/models.py

@@ -9,9 +9,6 @@ from celery import (
 from django.contrib.contenttypes.models import (
     ContentType,
 )
-from django.contrib.postgres.fields import (
-    JSONField,
-)
 from django.db.models import (
     PROTECT,
     SET_NULL,
@@ -22,6 +19,7 @@ from django.db.models import (
     Index,
     PositiveIntegerField,
     UUIDField,
+    JSONField,
 )
 from m3.db import (
     BaseObjectModel,

{educommon-3.10.1 → educommon-3.11.1}/src/educommon/django/db/fields.py

@@ -24,6 +24,9 @@ from educommon.django.db.validators import (
 from educommon.utils.misc import (
     cached_property,
 )
+from educommon.utils.phone_number.modelfields import (
+    PhoneField,
+)
 
 
 __all__ = [
@@ -41,7 +44,8 @@ __all__ = [
     'PassportNumberField',
     'INNField',
     'KPPField',
-    'OGRNField'
+    'OGRNField',
+    'PhoneField',
 ]
 
 

educommon-3.11.1/src/educommon/utils/phone_number/enums.py

@@ -0,0 +1,47 @@
+from enum import (
+    Enum,
+)
+
+
+class PhoneFieldType(Enum):
+    """Тип номера телефона для поля модели."""
+
+    COMMON = 'COMMON'
+    E164 = 'E164'
+    RU = 'RU'
+    RU_E164 = 'RU_E164'
+    RU_LOCAL = 'RU_LOCAL'
+    RU_MOBILE = 'RU_MOBILE'
+
+    values = {
+        COMMON: 'Общий формат телефона',
+        E164: 'Международный формат телефона',
+        RU: 'Общий формат российского номера',
+        RU_E164: 'Российский номер в международном формате',
+        RU_LOCAL: 'Российский городской номер',
+        RU_MOBILE: 'Российский мобильный номер',
+    }
+
+    @classmethod
+    def get_choices(cls):
+        return list(cls.values.items())
+
+
+class PhoneNumberType(Enum):
+    """Тип формата номера телефона."""
+
+    E164 = 'E164'
+    RU_E164 = 'RU_E164'
+    RU_LOCAL = 'RU_LOCAL'
+    UNKNOWN = 'UNKNOWN'
+
+    values = {
+        E164: 'Международный формат телефона',
+        RU_E164: 'Российский номер в международном формате',
+        RU_LOCAL: 'Российский городской номер',
+        UNKNOWN: 'Неизвестный формат',
+    }
+
+    @classmethod
+    def get_choices(cls):
+        return list(cls.values.items())

educommon-3.11.1/src/educommon/utils/phone_number/modelfields.py

@@ -0,0 +1,91 @@
+from django.db.models import (
+    CharField,
+)
+
+from educommon.utils.phone_number.enums import (
+    PhoneFieldType,
+)
+from educommon.utils.phone_number.phone_number import (
+    PhoneNumber,
+    to_python,
+)
+from educommon.utils.phone_number.validators import (
+    validate_common_phone_number,
+    validate_e164_phone_number,
+    validate_ru_e164_phone_number,
+    validate_ru_mobile_phone_number,
+    validate_ru_phone_number,
+)
+
+
+PHONE_FIELD_TYPE_TO_VALIDATOR = {
+    PhoneFieldType.COMMON: validate_common_phone_number,
+    PhoneFieldType.E164: validate_e164_phone_number,
+    PhoneFieldType.RU: validate_ru_phone_number,
+    PhoneFieldType.RU_E164: validate_ru_e164_phone_number,
+    PhoneFieldType.RU_MOBILE: validate_ru_mobile_phone_number,
+}
+
+
+class PhoneNumberDescriptor:
+    """Дескриптор для поля с номером телефона инстанса модели.
+
+    Возвращает PhoneNumber при доступе к полю телефона.
+
+    Позволяет для поля задавать номер телефона как:
+       instance.phone = PhoneNumber(...)
+    либо
+        instance.phone = '+7 (900) 555-55-55'
+    """
+
+    def __init__(self, field):
+        self.field = field
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+
+        if self.field.name in instance.__dict__:
+            value = instance.__dict__[self.field.name]
+        else:
+            instance.refresh_from_db(fields=[self.field.name])
+            value = getattr(instance, self.field.name)
+
+        return value
+
+    def __set__(self, instance, value):
+        instance.__dict__[self.field.name] = to_python(value)
+
+
+class PhoneField(CharField):
+    """Поле с номером телефона."""
+
+    attr_class = PhoneNumber
+    descriptor_class = PhoneNumberDescriptor
+
+    empty_values = [*CharField.empty_values, PhoneNumber('')]
+
+    def __init__(self, *args, phone_type: PhoneFieldType = PhoneFieldType.COMMON, **kwargs):
+        kwargs.setdefault('max_length', 31)
+        super().__init__(*args, **kwargs)
+
+        self.validators.append(
+            PHONE_FIELD_TYPE_TO_VALIDATOR.get(phone_type, validate_common_phone_number)
+        )
+
+    def to_python(self, value):
+        """Преобразование входящего значения в ожидаемый тип Python."""
+        return to_python(value)
+
+    def from_db_value(self, value, expression, connection):
+        """Преобразование значения полученного из БД."""
+        return self.to_python(value)
+
+    def get_prep_value(self, value):
+        """Подготовка значения перед сохранением в БД."""
+        if isinstance(value, PhoneNumber):
+            value = value.cleaned
+        elif value:
+            value = to_python(value).cleaned
+
+        return value or super().get_prep_value(value)

educommon-3.11.1/src/educommon/utils/phone_number/phone_number.py

@@ -0,0 +1,273 @@
+import re
+from typing import (
+    Any,
+    Optional,
+    Union,
+)
+
+from educommon.utils.phone_number.enums import (
+    PhoneNumberType,
+)
+
+
+PHONE_REGEX = re.compile(
+    r'^(?:'                                             # группа с кодом страны и кодом региона
+    r'(\+[1-6,90]{1,3}|\+?7|\+?8)?-?\s*'                # опциональный код страны (+XXX, для России может быть +7, 7, 8)
+    r'\(?(\d{3}(?:[-\s]?\d{0,2}(?=[)-.\s]))?)\)?[-.\s]*'  # оцпиональный код региона/города в необязательных скобках
+    r')?'                                                 # группа с кодом страны и кодом региона может отсутствовать
+    r'(\d{1,2}[-.\s]*\d?)[-.\s]*(\d[-.\s]*\d)[-.\s]*(\d[-.\s]*\d)$'  # абонентский номер в формате XXX-XX-XX
+                                                                     # первая группа может состоять от 1 до 3 цифр
+)
+
+# российский мобильный номер вида +7 (9XX) XXX-XX-XX
+RU_MOBILE_PHONE_REGEX = re.compile(r'^(\+?7|8)?-?\s*\(?(9\d{2})\)?[-.\s]*(\d{3})[-.\s]*(\d{2})[-.\s]*(\d{2})$')
+
+# местный номер в формате: XXX-XX-XX, XX-XX-XX, X-XX-XX
+LOCAL_PHONE_REGEX = re.compile(r'^(\d{1,3})[-.\s]*(\d{2})[-.\s]*(\d{2})$')
+
+RU_PHONE_CODE = '+7'
+
+
+class PhoneNumber:
+    """Телефонный номер.
+
+    В качестве параметра принимает строку с номером телефона в различных форматах,
+    производит разбор и валидацию номера, приводит его к единому формату.
+
+    Поддерживаемые форматы:
+      +XXX (XXX) XXX-XX-XX - в общем виде
+      +7 (XXX) XXX-XX-XX - российский формат
+      8 (XXX) XXX-XX-XX, (XXX-XX) X-XX-XX - российский формат городских номеров
+      XXX-XX-XX, XX-XX-XX, X-XX-X - местные российские номера
+
+    Свойство cleaned возвращает номер в очищенном виде для возможности сохранения в БД.
+    Примеры входной строки и её преобразования в cleaned:
+      +12 (555) 888-77-66 -> +12(555)8887766
+      +7 (900) 555-44-33 -> +79005554433
+      8 800 555-44-33 -> +78005554433
+      (818) 222-11-00 -> +78182221100
+      (818-53) 2-11-00 -> +7(81853)21100
+      222 44 55 -> 2224455
+      2-44-55 -> 24455
+
+    Возвращаемое текстовое представление номера в формате:
+    +XXX (XXX) XXX-XX-XX
+    """
+
+    def __init__(
+        self,
+        phone: Optional[str],
+        *,
+        need_sanitize: bool = False,
+    ) -> None:
+        """Инициализация.
+
+        Args:
+            need_sanitize: Признак необходимости дополнительной очистки номера перед выполнением парсинга
+        """
+        self.raw_phone = phone or ''
+        self._need_sanitize = need_sanitize
+
+        self._cleaned = ''
+
+        self.country_code = ''
+        self.region_code = ''
+        self.subscriber_part_1 = ''
+        self.subscriber_part_2 = ''
+        self.subscriber_part_3 = ''
+
+        self._is_parsed = False
+        self._is_e164 = False
+
+        self.parse()
+
+    @staticmethod
+    def _sanitize(value: str) -> str:
+        """Очистка значения от незначащих символов."""
+        return value.replace(' ', '').replace('-', '')
+
+    @staticmethod
+    def _only_digits(value: str) -> str:
+        """Возвращает из строки только цифры."""
+        return ''.join(ch for ch in value if ch.isdigit())
+
+    @property
+    def _sanitized(self) -> str:
+        """Возвращает введенный номер в очищенном виде."""
+        return self._sanitize(self.raw_phone)
+
+    def parse(self):
+        """Разбор номера."""
+        if self._is_parsed or not self.raw_phone:
+            return
+
+        raw_phone = self._sanitized if self._need_sanitize else self.raw_phone.strip()
+        regex_match = PHONE_REGEX.search(raw_phone)
+
+        self._is_parsed = True
+
+        if regex_match:
+            self.subscriber_part_1 = self._only_digits(regex_match.group(3))
+            self.subscriber_part_2 = self._only_digits(regex_match.group(4))
+            self.subscriber_part_3 = self._only_digits(regex_match.group(5))
+
+            self.region_code = regex_match.group(2)
+            if self.region_code:
+                self.region_code = self._sanitize(self.region_code)
+
+            country_code = regex_match.group(1)
+
+            if country_code in ('8', '7') or (not country_code and self.region_code):
+                self.country_code = RU_PHONE_CODE
+            else:
+                self.country_code = country_code
+
+            if self.country_code == RU_PHONE_CODE and (len(self.region_code) + len(self.subscriber_part_1)) != 6:
+                # у российских номеров код региона и первый блок абонентского номера в сумме должны быть 6 цифр
+                return
+
+            if self.region_code:
+                self._is_e164 = True
+
+                if len(self.region_code) != 3 or len(self.country_code) > 2:
+                    cleaned_template = '{0}({1}){2}{3}{4}'
+                else:
+                    cleaned_template = '{0}{1}{2}{3}{4}'
+
+                self._cleaned = cleaned_template.format(
+                    self.country_code,
+                    self.region_code,
+                    self.subscriber_part_1,
+                    self.subscriber_part_2,
+                    self.subscriber_part_3,
+                )
+
+            else:
+                self._cleaned = '{0}{1}{2}'.format(
+                    self.subscriber_part_1,
+                    self.subscriber_part_2,
+                    self.subscriber_part_3,
+                )
+
+    @property
+    def type(self) -> PhoneNumberType:
+        """Тип номера."""
+        if self.is_valid:
+            if self.country_code == RU_PHONE_CODE:
+                return PhoneNumberType.RU_E164
+
+            elif self.country_code:
+                return PhoneNumberType.E164
+
+            elif not self.country_code:
+                return PhoneNumberType.RU_LOCAL
+
+        return PhoneNumberType.UNKNOWN
+
+    @property
+    def is_valid(self) -> bool:
+        """Признак корректности введенного номера."""
+        return True if self._is_parsed and self._cleaned else False
+
+    @property
+    def is_e164(self):
+        """Признак, что номер в международном формате."""
+        return self._is_e164
+
+    @property
+    def is_russia(self) -> bool:
+        """Признак, что номер российский."""
+        return (
+            self._cleaned.startswith(RU_PHONE_CODE)
+            or (self.is_valid and not self.region_code)
+        )
+
+    @property
+    def cleaned(self) -> str:
+        """Очищенный номер.
+
+        Используется для сохранения в БД.
+        """
+        return self._cleaned
+
+    @property
+    def formatted(self) -> str:
+        """Отформатированный номер для отображения пользователю."""
+        if not self.is_valid:
+            return ''
+
+        formatted_number = '{0}-{1}-{2}'.format(
+            self.subscriber_part_1,
+            self.subscriber_part_2,
+            self.subscriber_part_3,
+        )
+
+        if self._is_e164:
+            formatted_number = '{0} ({1}) {2}'.format(
+                self.country_code,
+                self.region_code,
+                formatted_number,
+            )
+
+        return formatted_number
+
+    def __str__(self) -> str:
+        """Текстовое представление."""
+        if self.is_valid:
+            return self.formatted
+        else:
+            return self.raw_phone
+
+    def __repr__(self) -> str:
+        """Представление объекта."""
+        if self.is_valid or not self.raw_phone:
+            return '<{0}: {1}>'.format(type(self).__name__, str(self) or "''")
+
+        else:
+            return '<Invalid {0}: raw_phone="{1}">'.format(type(self).__name__, self.raw_phone)
+
+    def __len__(self):
+        return len(self.cleaned)
+
+    def __bool__(self):
+        return bool(self.cleaned)
+
+    def __hash__(self):
+        return hash(self.cleaned)
+
+    def __eq__(self, other_phone) -> bool:
+        if isinstance(other_phone, str):
+            other_phone = PhoneNumber(other_phone)
+
+        elif not isinstance(other_phone, PhoneNumber):
+            return False
+
+        self_str = self.formatted if self.is_valid else self.raw_phone
+        other_str = other_phone.formatted if other_phone.is_valid else other_phone.raw_phone
+
+        return self_str == other_str
+
+    def __add__(self, other: str) -> str:
+        """Конкатенация со строкой."""
+        return str(self) + other
+
+    def __radd__(self, other: str) -> str:
+        """Конкатенация со строкой."""
+        return other + str(self)
+
+
+def to_python(value: Any) -> Union[PhoneNumber, str, None]:
+    """Преобразование значения к объекту номера телефона."""
+    if value in (None, ''):
+        phone_number = value
+
+    elif isinstance(value, str):
+        phone_number = PhoneNumber(value)
+
+    elif isinstance(value, PhoneNumber):
+        phone_number = value
+
+    else:
+        raise TypeError(f'Невозможно преобразовать {type(value).__name__} к PhoneNumber.')
+
+    return phone_number

educommon-3.11.1/src/educommon/utils/phone_number/validators.py

@@ -0,0 +1,92 @@
+from typing import (
+    Union,
+)
+
+from django.core.exceptions import (
+    ValidationError,
+)
+
+from educommon.utils.phone_number.phone_number import (
+    PhoneNumber,
+    to_python,
+)
+
+
+def validate_common_phone_number(phone_number: Union[str, PhoneNumber]):
+    """Валидация номера телефона в общем формате."""
+    phone_number = to_python(phone_number)
+
+    if isinstance(phone_number, PhoneNumber) and not phone_number.is_valid:
+        raise ValidationError(
+            'Неверный формат! Примеры допустимых форматов: '
+            '+XXX (XXX) XXX XX XX, 8 (XXXXX) X-XX-XX, XXX-XX-XX',
+            code='invalid',
+        )
+
+
+def validate_e164_phone_number(phone_number: Union[str, PhoneNumber]):
+    """Валидация номера телефона в международном формате."""
+    phone_number = to_python(phone_number)
+
+    if (
+        isinstance(phone_number, PhoneNumber)
+        and not phone_number.is_valid
+        or not phone_number.is_e164
+    ):
+        raise ValidationError(
+            'Неверный формат! Примеры допустимых форматов: '
+            '+XXX (XXX) XXX XX XX, +7 (XXX) XXX-XX-XX, 8 (XXXXX) X-XX-XX',
+            code='invalid',
+        )
+
+
+def validate_ru_phone_number(phone_number: Union[str, PhoneNumber]):
+    """Валидация российского номера телефона в общем формате."""
+    phone_number = to_python(phone_number)
+
+    if (
+        isinstance(phone_number, PhoneNumber)
+        and not phone_number.is_valid
+        or not phone_number.is_russia
+    ):
+        raise ValidationError(
+            'Неверный формат! Примеры допустимых форматов: '
+            '+7 (XXX) XXX-XX-XX, 8 (XXXXX) X-XX-XX, XXX-XX-XX',
+            code='invalid',
+        )
+
+
+def validate_ru_e164_phone_number(phone_number: Union[str, PhoneNumber]):
+    """Валидация российского номера телефона в международном формате."""
+    phone_number = to_python(phone_number)
+
+    if (
+        isinstance(phone_number, PhoneNumber)
+        and not phone_number.is_valid
+        or not (phone_number.is_russia and phone_number.is_e164)
+    ):
+        raise ValidationError(
+            'Неверный формат! Примеры допустимых форматов: '
+            '+7 (XXX) XXX-XX-XX, 8 (XXXXX) X-XX-XX, (XXX) XXX-XX-XX',
+            code='invalid',
+        )
+
+
+def validate_ru_mobile_phone_number(phone_number: Union[str, PhoneNumber]):
+    """Валидация российского мобильного номера телефона."""
+    phone_number = to_python(phone_number)
+
+    if (
+        isinstance(phone_number, PhoneNumber)
+        and not phone_number.is_valid
+        or not (
+            phone_number.region_code
+            and len(phone_number.region_code) == 3
+            and phone_number.region_code.startswith('9')
+        )
+    ):
+        raise ValidationError(
+            'Неверный формат! Примеры допустимых форматов: '
+            '+7 (9XX) XXX-XX-XX, 7 (9XX) XXX XX XX, 89XXXXXXXXX',
+            code='invalid',
+        )

{educommon-3.10.1 → educommon-3.11.1}/src/educommon/version.conf

@@ -4,8 +4,8 @@
 # нормальной установки обновлений.
 
 [version]
-BRANCH = tags/3.10.1
-VERSION = 3.10.1
-REVISION = 00d0a35e160f94820482deca72a676cb2d334a8b
-VERSION_DATE = 13.09.2024
-REVISION_DATE = 13.09.2024
+BRANCH = tags/3.11.1
+VERSION = 3.11.1
+REVISION = e5d97ae13ca313d7f2354fff33f7c666c9ed1bad
+VERSION_DATE = 04.02.2025
+REVISION_DATE = 04.02.2025

{educommon-3.10.1 → educommon-3.11.1/src/educommon.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: educommon
-Version: 3.10.1
+Version: 3.11.1
 Summary: Общая кодовая база для проектов БЦ Образование
 Home-page: https://stash.bars-open.ru/projects/EDUBASE/repos/educommon
 Author: BARS Group
@@ -20,7 +20,7 @@ Classifier: Framework :: Django :: 3.0
 Classifier: Framework :: Django :: 3.1
 Classifier: Framework :: Django :: 3.2
 Requires-Dist: packaging<24,>=21.3
-Requires-Dist: Django<4,>=2.2
+Requires-Dist: Django<4,>=3.1
 Requires-Dist: django-mptt
 Requires-Dist: python-dateutil
 Requires-Dist: termcolor
@@ -39,3 +39,9 @@ Requires-Dist: m3-simple-report<2,>=1.4.1
 Requires-Dist: m3-spyne-smev<2,>=0.2.4
 Requires-Dist: python-magic==0.4.15
 Requires-Dist: distro<2,>=1.3.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: summary

{educommon-3.10.1 → educommon-3.11.1}/src/educommon.egg-info/SOURCES.txt

@@ -34,6 +34,7 @@ src/educommon/async_task/tasks.py
 src/educommon/async_task/ui.py
 src/educommon/async_task/migrations/0001_initial.py
 src/educommon/async_task/migrations/0002_task_type_and_status_data.py
+src/educommon/async_task/migrations/0003_alter_runningtask_options.py
 src/educommon/async_task/migrations/__init__.py
 src/educommon/async_task/templates/ui-js/async-task-list-win.js
 src/educommon/async_task/templates/ui-js/async-task-revoke.js
@@ -314,6 +315,11 @@ src/educommon/utils/fonts/Tahoma.ttf
 src/educommon/utils/fonts/__init__.py
 src/educommon/utils/licence/__init__.py
 src/educommon/utils/licence/converters.py
+src/educommon/utils/phone_number/__init__.py
+src/educommon/utils/phone_number/enums.py
+src/educommon/utils/phone_number/modelfields.py
+src/educommon/utils/phone_number/phone_number.py
+src/educommon/utils/phone_number/validators.py
 src/educommon/utils/system_app/__init__.py
 src/educommon/utils/system_app/management/__init__.py
 src/educommon/utils/system_app/management/commands/__init__.py
@@ -361,6 +367,7 @@ tests/test_django_db_utils.py
 tests/test_interval_mixins.py
 tests/test_patches.py
 tests/test_personal_data_fields.py
+tests/test_phone_number.py
 tests/test_report.py
 tests/test_service_db_router.py
 tests/test_utils.py

{educommon-3.10.1 → educommon-3.11.1}/src/educommon.egg-info/requires.txt

@@ -1,5 +1,5 @@
 packaging<24,>=21.3
-Django<4,>=2.2
+Django<4,>=3.1
 django-mptt
 python-dateutil
 termcolor