# Класс `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)