20251009
This commit is contained in:
85
help/class_desc/classes/directory.md
Normal file
85
help/class_desc/classes/directory.md
Normal file
@@ -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)
|
||||
242
help/class_desc/classes/file.md
Normal file
242
help/class_desc/classes/file.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user