grusher-lib

Версія 0.1.0 — alpha. Бібліотека активно розробляється.

Python бібліотека для роботи з Grusher API — системою управління мережею ISP.

Встановлення

git clone https://github.com/RodOpsOK/grusher-lib.git
cd grusher-lib
pip install -e .

Залежності

• Python 3.10+
• requests >= 2.28
• pydantic >= 2.0

Швидкий старт

from grusher import GrusherAPI

api = GrusherAPI(
    host="http://your-grusher-server.com",
    api_key="your_api_key"
)

API ключ налаштовується в Grusher: Налаштування → API.

---

Модуль billing

Користувачі (api.billing.user)

# Створити користувача
user = api.billing.user.create_user(
    user_name="Іван Петренко",
    login="ivanp",
    mac="AA:BB:CC:DD:EE:FF",  # автоматично нормалізується → AABBCCDDEEFF
    tariff_id=1,
    building_id=5,
    billing_id=0
)

# Оновити користувача
user = api.billing.user.update_user(user_id=1, user_name="Іван Петренко (оновлено)")

# Отримати за ID
user = api.billing.user.get_user_by_id(user_id=1)
user = api.billing.user.get_user_by_id(user_id=1, billing_id=2)

# Пошук (повний об'єкт користувача)
user = api.billing.user.find_user_by_login("ivanp")
user = api.billing.user.find_user_by_mac("AA:BB:CC:DD:EE:FF")
user = api.billing.user.find_user_by_onu_name("ONU-01")

# Пошук (id, billing_id, billing_user_id)
find_result = api.billing.user.find_user_id_by_login("ivanp")
find_result = api.billing.user.find_user_id_by_mac("AA:BB:CC:DD:EE:FF")
find_result = api.billing.user.find_user_id_by_onu_name("ONU-01")
print(find_result.id)

result = api.billing.user.find_user_by_phone(
    "380501234567",
    only_full_info=True,
    only_first=True
)

Телефони

# Додати телефон
phone = api.billing.user.add_user_phone(user_id=1, phone="380501234567")

# Видалити телефон → bool
success = api.billing.user.delete_user_phone(user_id=1, phone="380501234567")

Тарифи

from grusher.models import UserTariffPayType

# Створити тариф
tariff = api.billing.user.create_tariff(
    title="Базовий 100",
    speed=100,
    pay_type=UserTariffPayType.pay_30_day_no_daily,
    pay_for_period=200
)

# Оновити тариф
tariff = api.billing.user.update_tariff(tariff_id=1, speed=200)

# Видалити тариф
api.billing.user.delete_tariff(tariff_id=1)

MAC-адреси приймаються в будь-якому форматі (AA:BB:CC:DD:EE:FF, AA-BB-CC-DD-EE-FF, AABBCCDDEEFF) — бібліотека нормалізує автоматично.

---

Адреси (api.billing.address)

Регіони

regions = api.billing.address.get_regions()
region  = api.billing.address.get_region(region_id=1)
region  = api.billing.address.add_region(name="Київська область")
region  = api.billing.address.update_region(region_id=1, name="Київська область")
success = api.billing.address.delete_region(region_id=1)  # bool

Райони

districts = api.billing.address.get_districts(with_parents=True)
district  = api.billing.address.get_district(district_id=1, with_parents=True)
district  = api.billing.address.add_district(region_id=1, name="Бориспільський район")
district  = api.billing.address.update_district(district_id=1, name="Бориспільський район")
success   = api.billing.address.delete_district(district_id=1)

Міста / Населені пункти

cities  = api.billing.address.get_cities(with_parents=True)
city    = api.billing.address.get_city(city_id=1, with_parents=True)
city    = api.billing.address.add_city(district_id=1, name="Бориспіль")
city    = api.billing.address.update_city(city_id=1, name="Бориспіль")
success = api.billing.address.delete_city(city_id=1)

Вулиці

streets = api.billing.address.get_streets(with_parents=True)
street  = api.billing.address.get_street(street_id=1, with_parents=True)
street  = api.billing.address.add_street(city_id=1, name="вул. Центральна")
street  = api.billing.address.update_street(street_id=1, name="вул. Центральна")
success = api.billing.address.delete_street(street_id=1)

Будинки

buildings = api.billing.address.get_buildings(with_parents=True)
building  = api.billing.address.get_building(building_id=1, with_parents=True)

building = api.billing.address.add_building(
    street_id=1,
    name="10А",
    description="Житловий будинок",
    entrances_count=4,
    floors_count=9,
    lat=50.3456,
    lon=30.9123
)

building = api.billing.address.update_building(building_id=1, name="10Б")
success  = api.billing.address.delete_building(building_id=1)

---

Заявки (api.billing.ticket)

from grusher.models import TicketType, TicketPriority, TicketFilterStatus

# Список заявок
tickets = api.billing.ticket.get_tickets(status=TicketFilterStatus.OPEN)

# Одна заявка (з повідомленнями)
ticket = api.billing.ticket.get_ticket(ticket_id=1)
for msg in ticket.messages:
    print(msg.message)

# Створити заявку
ticket = api.billing.ticket.create_ticket(
    theme="Немає інтернету",
    type=TicketType.TECHNICAL,
    priority=TicketPriority.HIGH,
    user_id=42
)

# Оновити
ticket = api.billing.ticket.update_ticket(ticket_id=1, priority=TicketPriority.CRITICAL)

# Закрити
ticket = api.billing.ticket.close_ticket(ticket_id=1, closed_by_user_id=42)

# Повідомлення
message = api.billing.ticket.create_message(ticket_id=1, message="Проблему вирішено")
message = api.billing.ticket.update_message(message_id=1, message="Оновлений текст")

Клас	Значення
TicketFilterStatus	OPEN=1, CLOSED=2, ALL=3
TicketType	NOT_SPECIFY=0, TECHNICAL=1, CLIENTS=2, OTHER=10
TicketPriority	NO_PRIORITY=0, LOW=1, MIDDLE=2, HIGH=3, CRITICAL=4

---

GPS (api.billing.gps)

from grusher.models import GPSProtocol
from datetime import datetime

api.billing.gps.set_gps(
    tracker_id="123456789012345",
    lat=50.4501,
    lon=30.5234,
    speed=60.0,
    protocol_name=GPSProtocol.TELTONIKA,
    last_alive=datetime.now()
)

Підтримувані протоколи: OSMAND, TELTONIKA, GPS103, GT06, GT02A, H02, TK103.

---

Обробка помилок

from grusher.exceptions import (
    GrusherAPIError,
    GrusherConnectionError,
    GrusherAuthenticationError
)

try:
    ticket = api.billing.ticket.get_ticket(999)
except GrusherAuthenticationError:
    print("Невірний API ключ")
except GrusherConnectionError as e:
    print(f"Помилка з'єднання: {e}")
except GrusherAPIError as e:
    print(f"Помилка API: {e}")

---

Структура проекту

grusher/
├── api.py              # Точка входу GrusherAPI
├── net.py              # HTTP сесія
├── exceptions.py       # Винятки
├── entities/           # Логіка API методів
│   ├── billing.py
│   ├── address.py
│   ├── ticket.py
│   ├── user.py
│   └── gps.py
└── models/             # Pydantic моделі
    ├── address.py
    ├── ticket.py
    ├── user.py
    ├── gps.py
    └── timestamp.py

Реалізовано / Заплановано

Модуль	Статус
billing.address	✅ Реалізовано
billing.ticket	✅ Реалізовано
billing.user	✅ Реалізовано
billing.gps	✅ Реалізовано (beta)
billing.scheduler	🔜 Планується
db	🔜 Планується
device	🔜 Планується
inventory	🔜 Планується
tasks	🔜 Планується
reports	🔜 Планується
system	🔜 Планується

Ліцензія

MIT