Metadata-Version: 2.4
Name: simpleworkernet
Version: 0.0.3b30
Summary: Python клиент для API WorkerNet
Author-email: BusyBeaver <busybeaver.bb@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Андрей Литвинов
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# SimpleWorkerNet

Высокопроизводительный Python клиент для REST API системы WorkerNet с интеллектуальной системой трансформации и типизации сложных JSON структур

---

## 📋 Содержание

- [SimpleWorkerNet](#simpleworkernet)
  - [📋 Содержание](#-содержание)
  - [🌟 Особенности](#-особенности)
    - [🚀 SmartData Framework](#-smartdata-framework)
    - [🔧 BaseModel Engine](#-basemodel-engine)
    - [🎯 Умный клиент API](#-умный-клиент-api)
    - [📊 Продвинутое логирование через ConfigManager](#-продвинутое-логирование-через-configmanager)
    - [🗄️ Кэширование через ConfigManager](#️-кэширование-через-configmanager)
  - [📦 Установка](#-установка)
  - [🚀 Быстрый старт](#-быстрый-старт)
  - [🔧 Конфигурация](#-конфигурация)
    - [Группы настроек](#группы-настроек)
  - [📚 Основные компоненты](#-основные-компоненты)
    - [WorkerNetClient](#workernetclient)
    - [BaseModel и smart\_model](#basemodel-и-smart_model)
    - [SmartData Framework](#smartdata-framework)
    - [Метаданные и CollapsedField](#метаданные-и-collapsedfield)
    - [Примитивные типы](#примитивные-типы)
  - [📊 Логирование через ConfigManager](#-логирование-через-configmanager)
  - [💾 Кэширование через ConfigManager](#-кэширование-через-configmanager)
  - [🎨 Примеры использования](#-примеры-использования)
  - [🧹 Очистка данных](#-очистка-данных)
  - [✒️ Автор](#️-автор)
---

## <a name="features"></a>🌟 Особенности

### 🚀 SmartData Framework

Интеллектуальная обработка API-ответов с автоматическим приведением типов, сохранением метаданных и глубоким поиском по любым уровням вложенности.

### 🔧 BaseModel Engine

Мощная система рекурсивного кастинга типов с поддержкой Union, Optional, List и вложенных моделей.

### 🎯 Умный клиент API

    Автоматическое управление сессиями

    Интеллектуальный выбор метода (GET/POST) при превышении лимита URL

    Автоматические повторы при таймаутах

    Кэширование для оптимизации производительности

### 📊 Продвинутое логирование через ConfigManager

    Централизованное управление через единый менеджер конфигурации

    Сессионные логи с временными метками

    Автоматическая ротация файлов

    Кросс-платформенность (Windows, macOS, Linux)

### 🗄️ Кэширование через ConfigManager

    Двухуровневое кэширование полей моделей

    Автоматическая очистка при достижении лимита

    Сохранение на диск и загрузка при инициализации

    Предзагрузка из моделей

## <a name="installation"></a>📦 Установка
```bash

pip install simpleworkernet
```

## <a name="quick-start"></a>🚀 Быстрый старт

Минимальный пример
```python

from simpleworkernet import WorkerNetClient

# Создаем клиент
client = WorkerNetClient(
    host="my.workernet.ru",
    apikey="your-secret-api-key"
)

# Получаем данные
cables = client.Fiber.catalog_cables_get()
print(f"Найдено кабелей в каталоге: {len(cables)}")
```

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

from simpleworkernet import WorkerNetClient

with WorkerNetClient("my.workernet.ru", "your-api-key") as client:
    customers = client.Module.get_user_list()
    addresses = client.Address.get_city()
    
    print(f"Абонентов: {len(customers)}")
    print(f"Городов: {len(addresses)}")
```

Поиск и фильтрация
```python

from simpleworkernet import WorkerNetClient, Where, Operator

client = WorkerNetClient("my.workernet.ru", "your-api-key")

# Получаем данные
customers = client.Module.get_user_list()

# Создаем условия поиска
conditions = [
    Where('state_id', 2),                    # активные абоненты
    Where('balance', 1000, Operator.GT),     # с балансом > 1000
    Where('full_name', 'Иван', Operator.LIKE) # имя содержит 'Иван'
]

# Фильтруем
filtered = customers.filter(*conditions, join='AND')
print(f"Найдено: {filtered.count()}")

# Или через where для простых условий
active_customers = customers.where('state_id', 2)
```

## <a name="configuration"></a>🔧 Конфигурация

ConfigManager - центральный элемент управления всеми настройками библиотеки. Он предоставляет групповой доступ к различным категориям настроек.

Просмотр текущей конфигурации
```python

from simpleworkernet import ConfigManager

# Просмотр в лог
ConfigManager.show_config()

# Получение как строки
config_str = ConfigManager.show_config(return_string=True)
print(config_str)
```

### Группы настроек

Изменение настроек через группы
```python

from simpleworkernet import ConfigManager

# Настройка логирования
ConfigManager.Log.level = "DEBUG"
ConfigManager.Log.to_file = True
ConfigManager.Log.console = True
ConfigManager.Log.max_files = 20

# Настройка кэширования
ConfigManager.Cache.enabled = True
ConfigManager.Cache.max_size = 100000
ConfigManager.Cache.auto_save = True
ConfigManager.Cache.evict_strategy = "lru"

# Настройка клиента
ConfigManager.Client.timeout = 60
ConfigManager.Client.max_retries = 5

# Настройка SmartData
ConfigManager.SmartData.max_depth = 200
ConfigManager.SmartData.mode = "aggressive"
ConfigManager.SmartData.debug = False

# Сохранение изменений в файл
ConfigManager.save()
```

Массовое обновление через update()
```python

from simpleworkernet import ConfigManager

ConfigManager.update(
    log_level="DEBUG",
    log_to_file=True,
    console_output=True,
    cache_enabled=True,
    cache_max_size=100000,
    default_timeout=60,
    max_retries=5,
    smartdata_max_depth=200,
    save=True  # сразу сохранить в файл
)
```

Создание пользовательской конфигурации
```python

from simpleworkernet import ConfigManager, WorkerNetConfig

# Создание своей конфигурации
custom_config = WorkerNetConfig(
    log_level="INFO",
    log_to_file=True,
    log_file="/custom/path/workernet.log",
    cache_enabled=True,
    cache_max_size=50000,
    default_timeout=60,
    max_retries=5,
    smartdata_max_depth=200
)

# Применение
ConfigManager.update(**custom_config.to_dict(), save=True)
```

Интерактивная настройка
```python

from simpleworkernet import ConfigManager

# Запуск интерактивного режима с выбором из доступных вариантов
ConfigManager.interactive_configure(save=True)
```

Сброс на значения по умолчанию
```python

from simpleworkernet import ConfigManager

ConfigManager.reset(save=True)
```

## <a name="core-components"></a>📚 Основные компоненты


### <a name="workernetclient"></a>WorkerNetClient

Основной класс для взаимодействия с API WorkerNet.

Доступные категории (в разработке):

Address, Customer, Device, Employee, Fiber, Map, Module, Additional_data, Advertising, Attach, Billing, Cable_route, Call, Commutation, Cross, Cwdm, Gps, Inventory, Key, Node

### <a name="basemodel-and-smartmodel"></a>BaseModel и smart_model

Базовый класс для всех моделей с автоматическим кастингом типов.
```python

from simpleworkernet import smart_model, BaseModel, CollapsedField, vStr, GeoPoint, vPhoneNumber
from simpleworkernet.smartdata.metadata import SegmentType
from typing import List, Optional

@smart_model
class Contact(BaseModel):
    """Контактная информация"""
    email: Optional[str]
    phone: Optional[vPhoneNumber]
    telegram: Optional[str]

@smart_model
class Address(BaseModel):
    """Модель адреса"""
    id: int
    city: vStr
    street: vStr
    house: str
    apartment: Optional[int]
    coordinates: GeoPoint
    contacts: Optional[Contact]

@smart_model
class Traffic(BaseModel):
    """Трафик абонента"""
    up: int
    down: int
    # Доступ к схлопнутому ключу 'month' из метаданных
    period = CollapsedField(type_filter=SegmentType.FLD)

# Автоматическое создание из словаря
addr = Address(
    id=1,
    city="Москва",
    street="Ленина",
    house="10",
    apartment=42,
    coordinates=[55.75, 37.62],
    contacts={"phone": "+7-999-123-45-67"}
)
```

### <a name="smartdata-framework"></a>SmartData Framework

Контейнер для интеллектуальной обработки JSON-структур с fluent-интерфейсом.
```python

from simpleworkernet import SmartData, Where, Operator

# Из ответа API (автоматически)
customers = client.Module.get_user_list()  # уже SmartData

# Цепочка операций
result = (customers
    .where('balance', 0, Operator.GT)
    .where('state_id', 2)
    .sort(key=lambda x: x.balance, reverse=True)
    .limit(10)
    .map(lambda x: x.full_name))

# Группировка и агрегация
by_state = customers.group_by(lambda x: x.state_id)
for state, group in by_state.items():
    avg_balance = group.avg(lambda x: x.balance)
    print(f"Статус {state}: {group.count()} абонентов, средний баланс {avg_balance}")
```

### <a name="metadata-and-collapsedfield"></a>Метаданные и CollapsedField

Каждый объект хранит метаданные о своем положении в исходной структуре.
```python

from simpleworkernet import SmartData, CollapsedField
from simpleworkernet.smartdata.metadata import SegmentType

# Получение данных от API
customers = client.Customer.get_data(customer_id='1,2')

for customer in customers:
    # Доступ к метаданным
    if customer.meta:
        print(f"Путь к объекту: {customer.meta.get_path_string()}")
        print(f"Схлопнутые ключи: {customer.get_collapsed_keys()}")
    
    # Доступ к схлопнутым полям через CollapsedField
    if customer.tariff:
        print(f"container_name: {customer.tariff.container_name}")  # 'current'
```

### <a name="primitive-types"></a>Примитивные типы

Библиотека предоставляет богатый набор примитивных типов с дополнительной логикой:
```python

from simpleworkernet import vStr, vFlag, GeoPoint, vPhoneNumber, vMoney, vPercent, vINN, vKPP, vSNILS, vOGRN

# Декодирование строк
text = vStr("Hello%20World&amp;Co")  # "Hello World&Co"

# Геокоординаты
point = GeoPoint(55.75, 37.62)
print(point)  # "55.75,37.62"
print(point.distance_to(GeoPoint("55.76,37.63")))  # расстояние в км

# Телефонные номера
phone = vPhoneNumber("+7 (123) 456-78-90")
print(phone.normalized)  # "71234567890"
print(phone.international)  # "+71234567890"

# Денежные суммы
money = vMoney(100.50, "RUB")
money2 = money + 50.25
print(money2)  # "150.75 RUB"

# Проценты
p = vPercent(15.5)
print(p.of(1000))  # 155.0
```

## <a name="logging"></a>📊 Логирование через ConfigManager

Управление логированием осуществляется через ConfigManager.Log.

Настройка логирования
```python

from simpleworkernet import ConfigManager

# Базовая настройка
ConfigManager.Log.level = "DEBUG"
ConfigManager.Log.to_file = True
ConfigManager.Log.console = True
ConfigManager.Log.max_files = 20

# Изменение пути к файлу логов
ConfigManager.Log.file = "/custom/path/workernet.log"

# Применение изменений и сохранение
ConfigManager.save()
```

Работа с сессионными логами

Логгер автоматически создает отдельные файлы для каждого запуска с уникальным ID сессии. Информация о сессиях доступна через методы логгера.
```python

from simpleworkernet import log

# Информация о текущей сессии
current_log = log.get_session_log_path()
session_id = log.get_session_id()
print(f"Сессия: {session_id}, лог: {current_log}")

# Список всех сессий
for log_file in log.list_session_logs(sort_by='newest')[:5]:
    info = log.get_session_info(log_file)
    created = info['created'].strftime("%Y-%m-%d %H:%M:%S")
    print(f"{info['session_id']} - {created} - {info['size_kb']:.1f} KB")

# Начать новую сессию вручную
new_session = log.new_session("my_custom_session")
```

Структура файлов логов
```text

~/.local/share/simpleworkernet/logs/scriptname_hash/
├── scriptname_hash_workernet_20250220_091233.log
├── scriptname_hash_workernet_20250220_143022.log
└── scriptname_hash_workernet_20250220_163502.log
```

Уровни логирования: DEBUG, INFO, WARNING, ERROR, CRITICAL

## <a name="caching"></a>💾 Кэширование через ConfigManager

Управление кэшированием осуществляется через ConfigManager.Cache.

Настройка кэша
```python

from simpleworkernet import ConfigManager

# Базовая настройка
ConfigManager.Cache.enabled = True
ConfigManager.Cache.max_size = 100000
ConfigManager.Cache.auto_save = True
ConfigManager.Cache.evict_strategy = "lru"  # 'lru', 'lfu', 'fifo'
ConfigManager.Cache.evict_threshold = 0.9    # порог очистки (90%)
ConfigManager.Cache.evict_percent = 0.2      # процент удаляемых записей

# Изменение директории кэша
ConfigManager.Cache.directory = "/custom/cache/path"

# Применение изменений и сохранение
ConfigManager.save()
```

Управление кэшем через SmartData
```python

from simpleworkernet import SmartData

# Сохранение и загрузка
SmartData.save_cache(force=True)
SmartData.load_cache()

# Очистка
SmartData.clear_cache()

# Статистика
stats = SmartData.get_cache_stats()
print(f"Попаданий: {stats['hits']} ({stats['hit_rate']:.1f}%)")
print(f"Размер кэша: {stats['field_cache_size']} полей")
```

Предзагрузка кэша из моделей
```python

from simpleworkernet import SmartData
from simpleworkernet.models.categories.customer import Customer

# Предварительная загрузка полей моделей
SmartData.preload_from_models(
    Customer.Get_data,
    Customer.Get_data.Address,
    Customer.Get_data.Tariff,
    recursive=True
)
```

## <a name="examples"></a>🎨 Примеры использования

Базовые операции с API
```python

from simpleworkernet import WorkerNetClient, ConfigManager

# Настройка через ConfigManager
ConfigManager.Log.level = "DEBUG"
ConfigManager.Log.to_file = True
ConfigManager.save()

with WorkerNetClient("my.workernet.ru", "your-api-key") as client:
    # Различные запросы
    customers = client.Module.get_user_list()
    customer = client.Customer.get_data(customer_id=123)
    addresses = client.Address.get(city_id=1)
    cables = client.Fiber.catalog_cables_get()
```

Фильтрация данных
```python

from simpleworkernet import SmartData, Where, Operator

customers = client.Customer.get_data()

# Простая фильтрация
active = customers.where('state_id', 2)
positive_balance = customers.where('balance', 0, Operator.GT)

# Составные условия
filtered = customers.filter(
    Where('state_id', 2),
    Where('balance', 1000, Operator.GT),
    Where('city', 'Москва', Operator.LIKE),
    join='AND'
)

# Диапазон и вхождение
middle_age = customers.where('age', [25, 35], Operator.BETWEEN)
cities = customers.where('city', ['Москва', 'СПб'], Operator.IN)
```

Глубокий поиск по структуре
```python

complex_data = [{
    "id": 1,
    "name": "Иван",
    "contacts": {
        "email": "ivan@example.com",
        "phone": "+7-999-123-45-67"
    }
}]

sd = SmartData(complex_data)

# Поиск по email в любой вложенности
results = sd.find_all('email', 'ivan@example.com')
print(f"Найдено объектов: {len(results)}")
```

Создание пользовательских моделей
```python

from simpleworkernet import smart_model, BaseModel, vStr, vMoney
from typing import List, Optional

@smart_model
class Service(BaseModel):
    id: int
    name: vStr
    price: vMoney
    active: bool

@smart_model
class User(BaseModel):
    id: int
    login: str
    full_name: vStr
    balance: vMoney
    services: List[Service]

# Использование
user = User(**api_response)
```

Агрегация и статистика
```python

data = [
    {"name": "Иван", "age": 30, "salary": 50000, "dept": "IT"},
    {"name": "Петр", "age": 25, "salary": 45000, "dept": "IT"},
]

sd = SmartData(data)

# Статистика
total = sd.count()  # 2
avg_age = sd.avg(lambda x: x['age'])  # 27.5
max_salary = sd.max(lambda x: x['salary'])  # 50000

# Группировка
by_dept = sd.group_by(lambda x: x['dept'])
for dept, employees in by_dept.items():
    print(f"{dept}: {employees.count()} сотрудников")

# Трансформация
names = sd.map(lambda x: x['name'].upper())
```

Сериализация
```python

from simpleworkernet import SmartData

sd = SmartData(data)

# Сохранение в различных форматах
sd.to_file("data.json")           # JSON
sd.to_file("data.pkl", format="pkl")  # Pickle
sd.to_file("data.gz", format="gz")    # Gzip

# Загрузка
loaded = SmartData.from_file("data.json")
```

## <a name="cleanup"></a>🧹 Очистка данных

Консольная команда
```bash

# Запуск очистки с подтверждением
cleanup-simpleworkernet

# Принудительная очистка без подтверждения
cleanup-simpleworkernet --force

# Просмотр того, что будет удалено (без удаления)
cleanup-simpleworkernet --dry-run

# Просмотр установленных приложений
cleanup-simpleworkernet --list

# Очистка конкретного приложения
cleanup-simpleworkernet --app myapp_abc123

# Очистка только логов
cleanup-simpleworkernet --logs-only

# Очистка только кэша
cleanup-simpleworkernet --cache-only

# Очистка только конфигурации
cleanup-simpleworkernet --config-only

# Показать версию
cleanup-simpleworkernet --version
```

Из кода Python
```python

from simpleworkernet import cleanup

# С подтверждением
cleanup()

# Без подтверждения
cleanup(force=True)

# Очистка конкретного приложения
cleanup(force=True, app_name="myapp_abc123")
```

Полное удаление пакета
```bash

# 1. Очистить данные
cleanup-simpleworkernet --force

# 2. Удалить пакет
pip uninstall simpleworkernet
```

## <a name="author"></a>✒️ Автор

 - [Андрей Литвинов](https://t.me/busy4beaver)
