babaev-an / ANB Python Components
CI/CD
Реестр контейнеров и пакетов

class_desc/classes/file.md

Класс 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': Сообщается, если возникли трудности с определением размера файла (например, из-за отсутствия разрешения на чтение).

Пример использования:

from anb_python_components import File

error_msg = File.FILE_SIZE_ERROR_MESSAGES['file_not_exist']
print(error_msg)  # Файл не существует!

Словарь локализации размеров файлов (FILE_SIZE_UNITS)

Этот список используется для перевода единиц измерения размера файла на человеческий язык. Каждая единица измеряется следующим образом:

  • 'байт': Байты.
  • 'КБ': Килобайты.
  • 'МБ': Мегабайты.
  • 'ГБ': Гигабайты.
  • 'ТБ': Терабайты.

Пример использования:

from anb_python_components import File

units = File.FILE_SIZE_UNITS
print(units[2])  # МБ

Метод is_exist

Проверяет, существует ли файл по указанному пути.

Параметры:

  • file_path: str: Путь к файлу.

Возвращает:

  • True, если файл существует, иначе False.

Пример использования:

from anb_python_components import File

if File.is_exist('/path/to/file.txt'):
    print("Файл существует.")

Метод find

Рекурсивно ищет файлы по указанному шаблону в каталоге.

Параметры:

  • directory: Каталог для поиска.
  • pattern: Маска имени файла (по умолчанию '*').
  • exclude_list: Список директорий, которые нужно исключить из поиска.

Возвращает:

  • Список путей к найденным файлам.

Пример использования:

from anb_python_components import File

files = File.find('/home/user/', '*.txt')
for file in files:
    print(file)

Метод extract_file_name

Извлекает имя файла из полного пути.

Параметры:

  • file_path: Полный путь к файлу.

Возвращает:

  • Имя файла.

Пример использования:

from anb_python_components import File

name = File.extract_file_name('/home/user/document.txt')
print(name)  # document.txt

Метод extract_file_extension

Извлекает расширение файла из полного пути.

Параметры:

  • file_path: Полный путь к файлу.
  • with_dot: Включать ли точку перед расширением (по умолчанию True).

Возвращает:

  • Расширение файла.

Пример использования:

from anb_python_components import File

extension = File.extract_file_extension('/home/user/image.jpg')
print(extension)  # .jpg

Метод relative_path

Возвращает относительный путь к файлу относительно заданной директории.

Параметры:

  • full_path: Полный путь к файлу.
  • base_path: Базовая директория.

Возвращает:

  • Относительный путь к файлу или False, если путь не относится к заданной директории.

Пример использования:

from anb_python_components 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, содержащий размер файла или информацию об ошибке.

Пример использования:

from anb_python_components 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: Разделитель десятичной точки (по умолчанию ., может быть настроен на региональный формат).

Возвращает:

  • Форматированную строку с размером файла.

Пример использования:

from anb_python_components import File

formatted_size = File.size_to_string(1024 * 1024)
print(formatted_size)  # 1.00 MB

Метод hash

Вычисляет хэш файла, используя заданный алгоритм.

Параметры:

  • file_name: Путь к файлу.
  • hash_algorithm: Алгоритм хэширования (по умолчанию SHA-256).

Возвращает:

  • Хэш файла в виде шестнадцатеричной строки.

Пример использования:

from anb_python_components import File

file_hash = File.hash('/path/to/file.txt', 'sha256')
print(file_hash)

Заключение

Класс File предоставляет широкий спектр полезных методов для работы с файлами, облегчая стандартные операции с файлами и помогая решать задачи, связанные с управлением файлами в приложениях.

На главную

Назад