20251009

help/class_desc/classes/file.md

@@ -0,0 +1,242 @@
+# Класс `File`
+
+Класс `File` предоставляет разнообразные инструменты для работы с файлами в Python, начиная от простых операций, таких
+как проверка существования файла, и заканчивая более продвинутыми возможностями, такими как поиск файлов по маске,
+вычисление размера файла и его хэша.
+
+## Основная информация
+
+- **Имя файла**: anb_python_components\classes\file.py
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0.0
+- **Дата начала поддержки**: с версии 1.0
+
+## Атрибуты и методы класса
+
+### Словарь сообщений об ошибках (`FILE_SIZE_ERROR_MESSAGES`)
+
+Этот словарь используется для локализованных сообщений об ошибках, которые возникают при попытке получить размер файла.
+Каждое сообщение связано с определенным видом ошибки, и его можно настроить индивидуально для нужд приложения.
+
+**Содержимое словаря**:
+
+- `'file_not_exist'`: Сообщение выдается, если файл по указанному пути отсутствует.
+- `'not_a_file'`: Сообщение появляется, если путь ведет не к файлу, а к каталогу или другому ресурсу.
+- `'cannot_get_size'`: Сообщается, если возникли трудности с определением размера файла (например, из-за отсутствия
+  разрешения на чтение).
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.file import File
+
+error_msg = File.FILE_SIZE_ERROR_MESSAGES['file_not_exist']
+print(error_msg)  # Файл не существует!
+```
+
+### Словарь локализации размеров файлов (`FILE_SIZE_UNITS`)
+
+Этот список используется для перевода единиц измерения размера файла на человеческий язык. Каждая единица измеряется
+следующим образом:
+
+- `'байт'`: Байты.
+- `'КБ'`: Килобайты.
+- `'МБ'`: Мегабайты.
+- `'ГБ'`: Гигабайты.
+- `'ТБ'`: Терабайты.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.file import File
+
+units = File.FILE_SIZE_UNITS
+print(units[2])  # МБ
+```
+
+### Метод `is_exist`
+
+Проверяет, существует ли файл по указанному пути.
+
+**Параметры**:
+
+- **`file_path: str`**: Путь к файлу.
+
+**Возвращает**:
+
+- `True`, если файл существует, иначе `False`.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.file import File
+
+if File.is_exist('/path/to/file.txt'):
+    print("Файл существует.")
+```
+
+### Метод `find`
+
+Рекурсивно ищет файлы по указанному шаблону в каталоге.
+
+Параметры:
+
+- **`directory`**: Каталог для поиска.
+- **`pattern`**: Маска имени файла (по умолчанию `'*'`).
+- **`exclude_list`**: Список директорий, которые нужно исключить из поиска.
+
+Возвращает:
+
+- Список путей к найденным файлам.
+
+Пример использования:
+
+```python
+from anb_python_components.classes.file import File
+
+files = File.find('/home/user/', '*.txt')
+for file in files:
+    print(file)
+```
+
+### Метод `extract_file_name`
+
+Извлекает имя файла из полного пути.
+
+Параметры:
+
+- **`file_path`**: Полный путь к файлу.
+
+Возвращает:
+
+- Имя файла.
+
+Пример использования:
+
+```python
+from anb_python_components.classes.file import File
+
+name = File.extract_file_name('/home/user/document.txt')
+print(name)  # document.txt
+```
+
+### Метод `extract_file_extension`
+
+Извлекает расширение файла из полного пути.
+
+Параметры:
+
+- **`file_path`**: Полный путь к файлу.
+- **`with_dot`**: Включать ли точку перед расширением (по умолчанию `True`).
+
+Возвращает:
+
+- Расширение файла.
+
+Пример использования:
+
+```python
+from anb_python_components.classes.file import File
+
+extension = File.extract_file_extension('/home/user/image.jpg')
+print(extension)  # .jpg
+```
+
+### Метод `relative_path`
+
+Возвращает относительный путь к файлу относительно заданной директории.
+
+Параметры:
+
+- **`full_path`**: Полный путь к файлу.
+- **`base_path`**: Базовая директория.
+
+Возвращает:
+
+- Относительный путь к файлу или **`False`**, если путь не относится к заданной директории.
+
+Пример использования:
+
+```python
+from anb_python_components.classes.file import File
+
+rel_path = File.relative_path('/home/user/images/cat.png', '/home/user/')
+print(rel_path)  # images/cat.png
+```
+
+### Метод `size`
+
+Получает размер файла и сохраняет результат в объект `ActionState`.
+
+Параметры:
+
+- **`file_name`**: Путь к файлу.
+- **`error_localization`**: Сообщения об ошибках (опционально).
+
+Возвращает:
+
+- Объект `ActionState`, содержащий размер файла или информацию об ошибке.
+
+Пример использования:
+
+```python
+from anb_python_components.classes.file import File
+
+result = File.size('/path/to/file.txt')
+if result.is_success():
+    print("Размер файла:", result.value)
+else:
+    print("Ошибка:", result.get_string_messages())
+```
+
+### Метод `size_to_string`
+
+Преобразует размер файла в строку с указанием единицы измерения (байты, КБ, МБ и т.д.).
+
+Параметры:
+
+- **`file_size`**: Размер файла в байтах.
+- **`localize_file_size`**: Локализация единиц измерения (опционально).
+- **`decimal_separator`**: Разделитель десятичной точки (по умолчанию `.`, может быть настроен на региональный формат).
+
+Возвращает:
+
+- Форматированную строку с размером файла.
+
+Пример использования:
+
+```python
+from anb_python_components.classes.file import File
+
+formatted_size = File.size_to_string(1024 * 1024)
+print(formatted_size)  # 1.00 MB
+```
+
+### Метод `hash`
+
+Вычисляет хэш файла, используя заданный алгоритм.
+
+Параметры:
+
+- **`file_name`**: Путь к файлу.
+- **`hash_algorithm`**: Алгоритм хэширования (по умолчанию SHA-256).
+
+Возвращает:
+
+- Хэш файла в виде шестнадцатеричной строки.
+
+Пример использования:
+
+```python
+from anb_python_components.classes.file import File
+
+file_hash = File.hash('/path/to/file.txt', 'sha256')
+print(file_hash)
+```
+
+## Заключение
+
+Класс `File` предоставляет широкий спектр полезных методов для работы с файлами, облегчая стандартные операции с файлами
+и помогая решать задачи, связанные с управлением файлами в приложениях.
+
+[На главную](../../index.md)