20251005

help/class_desc/extensions/guid_extension.md

@@ -0,0 +1,92 @@
+# Класс `GUIDExtension`
+
+Класс `GUIDExtension` предназначен для расширения функциональности работы с глобальным уникальным идентификатором
+(GUID). Он предоставляет дополнительные методы для генерации новых GUID, проверки их валидности, парсинга из строк и
+сравнения между собой.
+
+## Основная информация
+
+- **Имя файла**: anb_python_components\extensions\guid_extension.py
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0.0
+- **Дата начала поддержки**: с версии 1.0
+
+## Атрибуты и методы класса
+
+### Метод `generate`
+
+Генерирует новый случайный GUID, следуя стандартам RFC 4122. Новый GUID создается с использованием криптографически
+стойких алгоритмов генерации чисел.
+
+**Пример использования**:
+
+```python
+from anb_python_components.extensions.guid_extension import GUIDExtension
+
+new_guid = GUIDExtension.generate()
+print(new_guid)  # Пример: 123e4567-e89b-12d3-a456-426655440000
+```
+
+### Метод `is_equal`
+
+Проверяет равенство двух GUID, поддерживая передачу обоих как строк, так и объектов типа `GUID`.
+
+**Пример использования**:
+
+```python
+from anb_python_components.extensions.guid_extension import GUIDExtension
+from anb_python_components.types.guid import GUID
+
+guid1 = "123e4567-e89b-12d3-a456-426655440000"
+guid2 = GUID("123e4567-e89b-12d3-a456-426655440000")
+
+equal = GUIDExtension.is_equal(guid1, guid2)
+print(equal)  # True
+```
+
+### Метод `validate`
+
+Проверяет, соответствует ли строка или объект правильному формату GUID.
+
+**Пример использования**:
+
+```python
+from anb_python_components.extensions.guid_extension import GUIDExtension
+
+valid = GUIDExtension.validate("123e4567-e89b-12d3-a456-426655440000")
+print(valid)  # True
+```
+
+### Метод `is_invalid_or_empty`
+
+Проверяет, является ли GUID недействительным или пустым.
+
+**Пример использования**:
+
+```python
+from anb_python_components.extensions.guid_extension import GUIDExtension
+
+invalid = GUIDExtension.is_invalid_or_empty("invalid-guid")
+print(invalid)  # True
+```
+
+### Метод `parse`
+
+Парсит строку в GUID, возвращая объект типа `GUID`. Может вернуть пустой GUID, если передано недопустимое значение.
+
+**Пример использования**:
+
+```python
+from anb_python_components.extensions.guid_extension import GUIDExtension
+
+parsed_guid = GUIDExtension.parse("123e4567-e89b-12d3-a456-426655440000")
+print(parsed_guid)  # 123e4567-e89b-12d3-a456-426655440000
+```
+
+## Заключение
+
+Класс `GUIDExtension` позволяет создать надежную систему работы с GUID в Python-проектах, облегчая генерацию, проверку и
+сравнение идентификаторов. Благодаря этому обеспечивается дополнительная защита от возможных проблем с передачей
+некорректных данных.
+
+[На главную](../../index.md)