tsf-sh 1.0.1

Асинхронная Python библиотека для работы с tsf.sh API

tsf-sh

Асинхронная Python библиотека для работы с tsf.sh API - сервисом для сокращения ссылок.

Установка

pip install tsf-sh

Требования

• Python 3.8+
• httpx 0.24.0+

Быстрый старт

import asyncio
from tsf_sh import Client

async def main():
    # Инициализация клиента
    client = Client(api_key="your-api-key")
    
    # Создание короткой ссылки
    link = await client.create_link(
        url="https://example.com",
        ttl_hours=24
    )
    print(f"Создана ссылка: {link.short_url}")
    
    # Получение информации о ссылке
    link_info = await client.get_link(link.code)
    print(f"Переходов: {link_info.clicks}")
    
    # Закрытие клиента
    await client.close()

asyncio.run(main())

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

import asyncio
from tsf_sh import Client

async def main():
    async with Client(api_key="your-api-key") as client:
        # Создание ссылки
        link = await client.create_link("https://example.com")
        print(f"Ссылка: {link.short_url}")
        
        # Получение списка всех ссылок
        links = await client.get_links()
        print(f"Всего ссылок: {len(links)}")
        
        # Получение статистики
        stats = await client.get_stats()
        print(f"Всего переходов: {stats.total_clicks}")

asyncio.run(main())

API методы

Создание ссылки

link = await client.create_link(
    url="https://example.com",
    ttl_hours=24,  # Время жизни в часах (1-24)
    password="optional_password"  # Опциональный пароль
)

Получение списка ссылок

links = await client.get_links()
# Список отсортирован по дате создания (новые первые)

Получение информации о ссылке

link = await client.get_link("abc123")
print(f"URL: {link.original_url}")
print(f"Переходов: {link.clicks}")
print(f"Истекает: {link.expires_datetime}")

Удаление ссылки

await client.delete_link("abc123")

Продление времени жизни ссылки

link = await client.extend_link("abc123", ttl_hours=24)
# TTL устанавливается от текущего момента

Установка пароля

await client.set_password("abc123", "my_password")

Удаление пароля

await client.remove_password("abc123")

Перегенерация кода ссылки

new_code = await client.reroll_code("abc123")
print(f"Новый код: {new_code}")

Получение статистики

stats = await client.get_stats()
print(f"Активных ссылок: {stats.links_count}")
print(f"Всего переходов: {stats.total_clicks}")

Проверка здоровья API

health = await client.health_check()
print(f"Статус: {health.status}")
print(f"Redis: {health.services['redis']}")

Модели данных

Link

link.code              # Код ссылки
link.short_url         # Короткая ссылка
link.original_url      # Оригинальный URL
link.clicks            # Количество переходов
link.ttl_seconds       # Время жизни в секундах
link.created_at        # Unix timestamp создания
link.expires_at        # Unix timestamp истечения
link.has_password      # Наличие пароля
link.created_datetime   # datetime объект для created_at
link.expires_datetime  # datetime объект для expires_at
link.is_expired        # Проверка истечения
link.remaining_seconds # Оставшееся время жизни

LinkStats

stats.links_count   # Количество активных ссылок
stats.total_clicks  # Всего переходов

HealthStatus

health.status      # "healthy" или "degraded"
health.services    # Словарь со статусами сервисов
health.is_healthy  # True если API здоров

Обработка ошибок

Библиотека выбрасывает специфичные исключения для разных типов ошибок:

from tsf_sh import (
    ValidationError,      # 400 - Ошибка валидации
    UnauthorizedError,     # 401 - Неверный API ключ
    ForbiddenError,        # 403 - Требуется премиум
    NotFoundError,         # 404 - Ресурс не найден
    ConflictError,         # 409 - Конфликт (ссылка уже существует)
    RateLimitError,        # 429 - Превышен лимит запросов
    InternalServerError   # 500 - Внутренняя ошибка сервера
)

try:
    link = await client.create_link("invalid-url")
except ValidationError as e:
    print(f"Ошибка валидации: {e.message}")
except ConflictError as e:
    print(f"Ссылка уже существует: {e.existing_code}")
except RateLimitError as e:
    print(f"Лимит превышен. Попробуйте через {e.reset_time} секунд")

Получение API ключа

API ключ можно получить в Telegram боте @tsf_sh_bot в разделе профиля, но только после покупки премиума. Премиум покупается навсегда.

Лицензия

MIT

Ссылки

• Документация API
• Telegram бот