20251009

help/class_desc/classes/directory.md

@@ -0,0 +1,85 @@
+# Класс `Directory`
+
+Класс `Directory` предоставляет инструменты для работы с каталогами (директориями) в операционной системе. Основными
+функциями класса являются проверка существования директорий и их рекурсивное удаление. Этот класс полезен для
+автоматизированных задач по управлению структурой папок в приложениях.
+
+## Основная информация
+
+- **Имя файла**: anb_python_components\classes\directory.py
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0.0
+- **Дата начала поддержки**: с версии 1.0
+
+## Атрибуты и методы класса
+
+### Словарь `REMOVE_DIRECTORY_ERROR_MESSAGES`
+
+Словарь сообщений об ошибках для удаления директории.
+
+```python
+REMOVE_DIRECTORY_ERROR_MESSAGES: dict[str, str] = {
+        'directory_not_exist': "Директория не существует или нет доступа на запись!",
+        'error_deleting_directory': 'Ошибка удаления каталога: %s. Код возврата: %d!',
+        'unhandled_error': 'Ошибка удаления директории %s: %s!'
+        }
+```
+
+### Метод `remove`
+
+Удаляет директорию вместе со всеми поддиректориями и файлами.
+
+**Параметры**:
+
+- **`directory: str`**: путь к директории, которую нужно удалить.
+- **`error_messages: dict[str, str] | None = None`**: словарь с сообщениями об ошибках (опционально). Если задан как
+  `None`, то используется словарь `Directory.REMOVE_DIRECTORY_ERROR_MESSAGES`. По умолчанию, `None`.
+
+**Возвращает**:
+
+- Объект `ActionState`, содержащий результат операции и возможные сообщения об ошибках.
+
+Пример использования:
+
+```python
+from anb_python_components.classes.directory import Directory
+
+result = Directory.remove("/path/to/folder")
+if result.is_success():
+    print("Директория успешно удалена.")
+else:
+    print("Ошибка:", result.get_string_messages())
+```
+
+### Метод `is_exists`
+
+Проверяет существование директории и (при необходимости) права доступа к ней.
+
+**Параметры**:
+
+- **`directory: str`**: путь к директории.
+- **`check_access_level: str`**: строка, содержащая комбинации символов 'r', 'w', 'x' для проверки соответствующих прав
+  доступа (чтение, запись, исполнение). По умолчанию, `""`.
+
+**Возвращает**:
+
+- `True`, если директория существует и доступна по указанным параметрам, иначе `False`.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.directory import Directory
+
+exists = Directory.is_exists("/path/to/folder", check_access_level = "rw")
+if exists:
+    print("Директория существует и доступна для чтения и записи.")
+else:
+    print("Проблемы с доступом к директории.")
+```
+
+## Заключение
+
+Класс `Directory` позволяет упростить управление файловой системой, особенно полезными будут методы удаления и проверки
+доступности директорий, которые помогают повысить устойчивость приложений к ошибкам.
+
+[На главную](../../index.md)