Если вы когда-либо писали на Python и ловили себя на мысли «Опять писать парсер конфигурации…» или «Где-то у меня был код кеша, надо найти» — эта библиотека для вас.

XTools-py — это набор мощных и удобных инструментов для Python, которые помогают упростить рутинные задачи и ускорить разработку.
Вместо того чтобы тратить время на повторное изобретение велосипеда, вы получаете готовые и проверенные решения.

? Установка:

pip install xtools-py

✨ Возможности

• Find — быстрый поиск и работа с коллекциями данных.

• Matrix — операции с матрицами.

• Config — удобная работа с JSON, YAML, INI.

• Validator — валидация строк, чисел и других типов.

• Cache — простой кеш с TTL.

• DateTimeUtils — работа с датами и временем.

• MathUtils — расширенные математические функции.

• ColorUtils — преобразование и обработка цветов.

• EncryptionUtils — шифрование и хеширование.

• TextUtils — удобные манипуляции с текстом.

• UnitConverter — конвертация единиц измерения.

• AWS S3 — облачное хранилище (асинхронно/синхронно).

? Сравнение с другими библиотеками

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

1. Работа с конфигурацией

from xtools import Config

config = Config("config.json")
config.set("app.debug", True)
config.save()

2. Быстрый поиск данных

from xtools import Find

data = ["apple", "banana", "cherry"]
print(Find.get_max(data))  # banana

3. Валидация данных

from xtools import Validator

print(Validator.is_email("test@example.com"))  # True
print(Validator.is_int("123"))                 # True

4. Кеширование

from xtools import Cache

cache = Cache()
cache.set("key", "value", ttl=60)
print(cache.get("key"))  # value

5. Работа с датами

from xtools.utils import DateTimeUtils

print(DateTimeUtils.current_timestamp())
print(DateTimeUtils.format_date("2025-02-08", "%d.%m.%Y"))

6. Конвертация единиц измерения

from xtools import UnitConverter

print(UnitConverter.celsius_to_fahrenheit(25))  # 77.0
print(UnitConverter.meters_to_kilometers(1000))  # 1.0

5. Шифрование и дешифрование

from xtools import EncryptionUtils

key = EncryptionUtils.generate_key()
encrypted = EncryptionUtils.encrypt("Hello, World!", key)
decrypted = EncryptionUtils.decrypt(encrypted, key)

print(encrypted)
print(decrypted)  # Hello, World!

8. Работа с AWS S3 (синхронно)

from xtools.storage import S3Storage

s3 = S3Storage("my-bucket", "ACCESS_KEY", "SECRET_KEY")

# Загрузка файла
s3.upload_file("local.txt", "remote.txt")

# Список файлов
print(s3.list_files())

8. Работа с AWS S3 (асинхронно)

import asyncio
from xtools.storage import AsyncS3Storage

async def main():
    s3 = AsyncS3Storage("my-bucket", "ACCESS_KEY", "SECRET_KEY")
    await s3.upload_file("local.txt", "remote.txt")
    print(await s3.list_files())

asyncio.run(main())

Подробная документация

Конфигурации

Модуль Config в XTools-py — это удобный и надёжный слой работы с конфигурационными файлами, который поддерживает JSON, YAML и INI, даёт доступ к вложенным параметрам через «dot-notation», умеет подставлять значения по умолчанию, поддерживает переопределение через переменные окружения и безопасно сохраняет файлы атомарной записью. Идея — дать единый, простой API, чтобы не подключать сразу несколько разных библиотек и не писать однотипную обвязку в каждом проекте.

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

Файл config.yml:

app:
  debug: false
database:
  host: "localhost"
  port: 5432
  user: "app"
  password: null

Загрузка и доступ к параметрам

from xtools import Config

config = Config("config.yml", defaults={"app": {"debug": True}}, env_prefix="XT__")
print(config.get("database.host", "127.0.0.1"))  # localhost
config.set("database.password", "supersecret")
config.save()

Переопределение через переменные окружения

export XT__DATABASE__HOST=prod.db.example
export XT__APP__DEBUG=true

Перезапуск приложения — и config.update_from_env("XT__") прочитает новые значения.

Использование как контекстного менеджера

with Config("config.json", create=True) as cfg:
    cfg.set("app.version", "1.2.0")
# при выходе из with — cfg.save() выполнится автоматически

Интеграция с Validator

from xtools import Config, Validator

cfg = Config("config.yml")
port = cfg.get("database.port")
if not Validator.is_int(port):
    raise ValueError("Bad port in config")

Поиск данных

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

Работа с длинной

from XTools import Find

# Пример 1: один список чисел
print(Find.get_max([1, 3, 6]))
# Результат: {'max_number': 6}

# Пример 2: числа в виде строк
print(Find.get_max(['1', '3', '6']))
# Результат: {'max_number': 6}

# Пример 3: поиск самой длинной строки
print(Find.get_max(['hello', 'what is?', 'I using XTools']))
# Результат: {'max_len': 'I using XTools'}

# Пример 4: несколько списков
print(Find.get_max([1, 3, 6], ['hello', 'what is?', 'I using XTools']))
# Результат: {'max_number': 6, 'max_len': 'I using XTools'}

Работа с словарём

from XTools import Find

data = [
    {"name": "Alice", "age": 25},
    {"name": "Bob", "age": 30},
    {"name": "Charlie", "age": 25}
]

# Поиск по ключу и значению
results = Find.by_key_value(data, "age", 25)
print(results)
# Результат:
# [{'name': 'Alice', 'age': 25}, {'name': 'Charlie', 'age': 25}]

# Поиск по частичному совпадению
results = Find.contains(data, "name", "Al")
print(results)
# Результат:
# [{'name': 'Alice', 'age': 25}]

Кеширование

Класс Cache предназначен для быстрого и удобного хранения данных в памяти устройства.

Пример работы

from xtools import Cache

cache = Cache(ttl = 60, max_size = 100)
# ttl: int -> Время хранения данных (по умолчанию — 60 сек.)
# max_size: int -> Максимальный размер кэша (по умолчанию — 100 элементов).

cache.set("key", "value") # установка значений ключ = значение

print(cache.get("key"))  # value

cache.delete("key") # удаление пары по ключу

Пример с валидацией

from xtools import Cache, Validator

cache = Cache(ttl = 60, max_size = 25)
user_email = input("Enter you email > ")

if Validator.is_email(user_email):
  cache.set("user_email", user_email)

# После можно дальше в других файлах использовать кеш
user_email = cache.get("user_email")
print(f"You email: {user_email}")

Получение размера и очистка данных

from xtools import Cache

cache = Cache(ttl = 60, max_size = 25)

cache.size() # Получение длинны всего кеша

cache.clear() # Полная очистка всех данных

Работа с датами

Класс DateTimeUtils — это универсальный инструмент для упрощённой работы с датами и временем в Python. Он полностью построен на базе стандартного модуля datetime и предоставляет удобные методы, которые позволяют быстро выполнять как базовые, так и более сложные операции с датами.

Основные возможности класса:

• Получение текущей даты и времени в разных форматах (get_now, get_today).

• Преобразование строк в дату и обратно (parse_date, format_date).

• Арифметика дат — добавление или вычитание дней, часов, минут (+, -)

• Сравнение дат — сравнение, равенство между датами (==, !=, _>, _>=, _<, _<=)

• Разница между датами — в днях, часах, секундах (diff_days, diff_seconds).

Получение даты и форматирование

from xtools.utils import DateTimeUtils


now = DateTimeUtils.current_timestamp(timezone = 'Europe/Moscow')
# timezone: str -> Вернуть дату в выбранном часовом поясе. По умолчанию - Москва (+3ч)

now_sf = DateTimeUtils.format_date(date = now, format_string = "%d.%m.%Y")
# date: datetime -> Дата в формате datetime
# format_string: str -> Формат для даты

print(now_sf) # 09.09.2025

Парсинг даты и вычисление разниц

from xtools.utils import DateTimeUtils

DateTimeUtils.parse_date(date_string = "09.08.2025", format_string = "%d.%m.%Y")

# Вычисление разниц между двумя датами в днях.

old_date = DateTimeUtils.current_timestamp() # дата устаревшая
new_date = DateTimeUtils.current_timestamp() # дата новая

res = DateTimeUtils.date_difference(old_date, now_date)

print(res) # Получаете разница между датами в днях.

Отсчёт прошеднего времени

from xtools.utils import DateTimeUtils

date = DateTimeUtils.get_now() - timedelta(hours=1)
ago = DateTimeUtils.time_ago(date) # 1 дн назад

# ИЛИ, если хотите получить в строгом формате:

ago = DateTimeUtils.time_ago(date, only_number=True) # 1_day

Аргумент only_number позволяет управлять форматом результата:

•only_number=False (по умолчанию) — возвращает готовый текстовый шаблон для отображения пользователю.

Пример:

DateTimeUtils.time_ago(DateTimeUtils.get_now() - timedelta(hours=1)) # "1 ч назад"

•only_number=True — возвращает строгий формат для внутренней обработки или хранения.

Пример:

DateTimeUtils.time_ago(datetime.now() - timedelta(hours=1), only_number=True)
# ➜ "1_hour"

Строгий формат, возвращаемые данные:

Класс DateTime — это немного улучшенная версия библиотеки datetime.datetime. Она включает в себя небольшие удобства для работы в виде: Сохранения изменения дат, Предыдущая дата, Настоящая дата.

Пример работы:

from xtools.utils import DateTime

dt = DateTime(zone = 'Europe/Moscow') # По умолчанию зона установлена как МСК +3ч
print(dt) # результат: None
dt.now() - timedelta(hours=1)
print(dt) # результат: 2025-08-09 23:35:01.572607+03:00
dt.now()
print(dt) # результат: 2025-08-10 00:35:01.573608+03:00

# Предыдущие запросы
dt.now() - timedelta(hours=1)
dt.now()

print(dt.prev) # результат: 2025-08-09 23:35:01.572607+03:00
print(dt) # результат: 2025-08-10 00:35:01.573608+03:00

# Полный список запросов:
print(dt.results) # результат: 2025-08-10 00:35:01.573608+03:00, 
                              # 2025-08-10 00:35:01.573608+03:00

Поддерживются арифметические операции:

from xtools.utils import DateTime

dt = DateTime()
dt.now()

dt + timedelta(hours=1) # Результат: 2025-08-10 01:35:01.573608+03:00
# Идентично используя: Сложение (+) и Вычитание (-)

# Сложение двух классов
dt_a, dt_b = DateTime().now(), DateTime().now()
 
dt_a - dt_b # Результат: 0:00:00, т.к у нас одинаковые даты
# Идентично используя: Сложение (+) и Вычитание (-)

Поддерживаются сравнения и равенства:

from xtools.utils import DateTime

dt_a, dt_b = DateTime().now(), DateTime().now()

dt_a > dt_b 
dt_a < dt_b 
# Идентично используя: > | >= | <= | <

# Проверка на равенство или неравенство
dt_a == dt_b
dt_a != dt_b

# Проверка на None

dt = DateTime()
bool(dt) # Результат: False, по умолчанию результат равен None

dt = DateTime().now()
bool(dt) # Результат: True, т.к уже имеется результат

Работа с цветами

Класс ColorUtils предоставляет набор полезных методов для работы с цветами в различных форматах — HEX, RGB, HSL и др. Он упрощает преобразования между цветовыми системами, генерацию случайных цветов и их модификацию, что особенно полезно в разработке UI, графики или визуализаций данных.

С помощью ColorUtils можно:

• Конвертировать цвета
  Перевод из HEX в RGB и обратно, а также в HSL/HSV, что удобно при работе с CSS, PIL, matplotlib или другими инструментами.

• Генерировать случайные цвета
  Быстро создать цветовую палитру для тестирования или автоматической генерации тем оформления.

• Менять яркость и насыщенность
  Легко осветлять или затемнять цвет, повышать или понижать его насыщенность, что упрощает создание оттенков.

• Проверять корректность формата
  Методы для валидации введённого цвета, чтобы избежать ошибок в отрисовке.

• Создавать градиенты
  Автоматическая генерация плавных переходов между двумя цветами в нужном количестве шагов.

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

from XTools import ColorUtils

# Конвертация HEX → RGB
print(ColorUtils.hex_to_rgb("#FF5733")) # (255, 87, 51)

# Конвертация RGB → HEX
print(ColorUtils.rgb_to_hex((255, 87, 51))) # '#FF5733'

# Генерация случайного HEX-цвета
print(ColorUtils.random_hex()) # '#3E9CFF'

# Осветление цвета на 20%
print(ColorUtils.lighten("#FF5733", 0.2)) # '#FF7A59'

# Смена насыщенности цвета
print(ColorUtils.saturate("#FF5733", 0.2)) # '#ff5732'

# Создание градиента из 5 цветов
print(ColorUtils.gradient("#FF5733", "#33FF57", steps=5))
# Результат: ['#FF5733', '#BF8044', '#80A955', '#40D266', '#33FF57']

Конвертация единиц измерения

Класс UnitConverter предоставляет возможность конвертировать физические величины: температуры, расстояния и массы. Он упрощает работу и производит преобразование благодаря физическим формулам. Все методы работают в виде @staticmethod, что позволяет не создавать экземпляр

Функционал класса

1. Конвертация температуры

• celsius_to_fahrenheit(celsius: float) — переводит температуру из градусов Цельсия в градусы Фаренгейта.
  Формула: °F = °C × 9/5 + 32
  Пример: 25°C → 77°F

• fahrenheit_to_celsius(fahrenheit: float) — обратное преобразование из Фаренгейта в Цельсий.
  Формула: °C = (°F - 32) × 5/9
  Пример: 77°F → 25°C

2. Конвертация расстояния

• meters_to_kilometers(meters: float) — из метров в километры.
  Пример: 1500 м → 1.5 км

• kilometers_to_meters(kilometers: float) — из километров в метры.
  Пример: 1.5 км → 1500 м

3. Конвертация массы

• grams_to_kilograms(grams: float) — из граммов в килограммы.
  Пример: 2500 г → 2.5 кг

• kilograms_to_grams(kilograms: float) — из килограммов в граммы.
  Пример: 2.5 кг → 2500 г

4. Конвертация скорости

• kmh_to_ms(kmh: float) — перевод скорости из километров в час в метры в секунду.
  Формула: m/s = km/h ÷ 3.6
  Пример: 72 км/ч → 20 м/с

• ms_to_kmh(ms: float) — обратное преобразование из метров в секунду в километры в час.
  Формула: km/h = m/s × 3.6
  Пример: 20 м/с → 72 км/ч

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

from XTools import UnitConverter

print(UnitConverter.celsius_to_fahrenheit(0))     # 32.0
print(UnitConverter.fahrenheit_to_celsius(32))    # 0.0
print(UnitConverter.meters_to_kilometers(1500))   # 1.5
print(UnitConverter.grams_to_kilograms(2500))     # 2.5
print(UnitConverter.kmh_to_ms(36))  # 10.0 м/с
print(UnitConverter.ms_to_kmh(10))  # 36.0 км/ч

Шифрование и Дешифрование

Класс EncryptionUtils предназначен для безопасного шифрования и дешифрования данных с использованием библиотеки cryptography.fernet. Методы работают с симметричным ключом, который обязателен как для процесса шифрования, так и для обратной операции расшифровки.

Функционал класса

1. Генерация ключа

• generate_key() — создает новый криптографически безопасный ключ, который будет использоваться для шифрования и дешифрования данных.
  Пример:

  key = EncryptionUtils.generate_key()

2. Шифрование данных

• encrypt(data: str, key: bytes) — принимает исходную строку и ключ, возвращает зашифрованную строку в кодировке UTF-8.
  Пример:

  encrypted = EncryptionUtils.encrypt("Hello World", key)

3. Дешифрование данных

• decrypt(data: str, key: bytes) — принимает зашифрованную строку и ключ, возвращает исходный текст в виде строки.
  Пример:

  decrypted = EncryptionUtils.decrypt(encrypted, key)

Принцип работы

• Используется Fernet — реализация симметричного шифрования с гарантией целостности данных.

• Ключ генерируется один раз и должен храниться в защищенном месте (например, в переменных окружения).

• Без правильного ключа расшифровка невозможна.

Работа с S3-хранилищами

Классы S3Storage (синхронная версия) и AsyncS3Storage (асинхронная версия) предоставляют удобный интерфейс для работы с AWS S3 и S3-совместимыми облачными хранилищами (например, MinIO, Yandex Object Storage, DigitalOcean Spaces). Они поддерживают полный набор базовых операций с файлами: загрузка, скачивание, удаление и получение списка объектов в бакете.

Возможности:

1. Загрузка файлов

   • upload_file(file_path, s3_key) — загружает локальный файл в указанный бакет с заданным ключом (путем в хранилище).

2. Скачивание файлов

   • download_file(s3_key, file_path) — скачивает файл из хранилища по ключу и сохраняет его локально.

3. Удаление файлов

   • delete_file(s3_key) — удаляет объект по ключу.

4. Список файлов

   • list_files() — возвращает список всех файлов в бакете.

Поддержка асинхронности

• AsyncS3Storage использует aioboto3, что позволяет интегрировать работу с хранилищем в асинхронные приложения (например, FastAPI, aiohttp).

• Синхронный S3Storage подходит для скриптов, утилит и приложений без async/await.

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

s3 = S3Storage("my-bucket", "ACCESS_KEY", "SECRET_KEY")

# Загрузка
s3.upload_file("local.txt", "folder/remote.txt")

# Скачивание
s3.download_file("folder/remote.txt", "downloaded.txt")

# Удаление
s3.delete_file("folder/remote.txt")

# Получение списка файлов
print(s3.list_files())

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

import asyncio

async def main():
    s3 = AsyncS3Storage("my-bucket", "ACCESS_KEY", "SECRET_KEY")

    # Загрузка
    await s3.upload_file("local.txt", "folder/remote.txt")

    # Скачивание
    await s3.download_file("folder/remote.txt", "downloaded.txt")

    # Удаление
    await s3.delete_file("folder/remote.txt")

    # Список файлов
    files = await s3.list_files()
    print(files)

asyncio.run(main())

? Roadmap

• Поддержка Redis для кеша.

• Расширенная валидация.

• Новые математические функции.

? Полезные ссылки

• ? PyPI: XTools-py

• ? GitHub: SikWeet/XTools-py