cloudtips 0.3.1__tar.gz → 0.4.1__tar.gz

cloudtips-0.4.1/.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install mkdocs-material
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

cloudtips-0.4.1/.gitignore

@@ -0,0 +1,4 @@
+site/
+__pycache__/
+*.pyc
+.DS_Store

cloudtips-0.4.1/CNAME

@@ -0,0 +1 @@
+docs.cloudtips.irring.ru

cloudtips-0.4.1/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: cloudtips
+Version: 0.4.1
+Summary: Неофициальная асинхронная Python-библиотека для CloudTips (получение донатов, поллинг, обновление токенов)
+Project-URL: Repository, https://github.com/IRRatium/cloudtips-api
+Project-URL: Issues, https://github.com/IRRatium/cloudtips-api/issues
+License: MIT
+License-File: LICENSE
+Keywords: api,async,asyncio,cloudtips,donations,payments,tips
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Requires-Dist: aiohttp>=3.9
+Description-Content-Type: text/markdown
+
+# CloudtipsAPI
+<p align="center">
+  <img src="https://static.tildacdn.com/tild3431-6231-4938-b464-663831306266/Horiz.svg" alt="CloudTips" height="120">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/cloudtips/"><img src="https://img.shields.io/pypi/v/cloudtips?color=blue&label=PyPI" alt="PyPI"></a>
+  <a href="https://pepy.tech/project/cloudtips"><img src="https://static.pepy.tech/badge/cloudtips" alt="Downloads"></a>
+  <a href="https://github.com/IRRatium/cloudtips-api/blob/main/LICENSE"><img src="https://img.shields.io/github/license/IRRatium/cloudtips-api" alt="License"></a>
+  <img src="https://img.shields.io/badge/python-3.9+-blue" alt="Python 3.9+">
+  <a href="https://docs.cloudtips.irring.ru"><img src="https://img.shields.io/badge/docs-docs.cloudtips.irring.ru-blue" alt="Docs"></a>
+</p>
+
+Неофициальная асинхронная Python-библиотека для [CloudTips](https://cloudtips.ru) — получение донатов, поллинг новых поступлений и автоматическое обновление токенов.
+
+## Установка
+
+```bash
+pip install cloudtips
+```
+
+## Быстрый старт
+
+```python
+import asyncio
+import json
+from cloudtips import CloudTipsAuth, CloudTipsClient, TokenData
+
+with open("donate.json") as f:
+    config = json.load(f)
+
+# Колбэк вызывается каждый раз при обновлении токенов.
+# Поддерживаются как async, так и обычные функции.
+# Refresh-токен одноразовый — обязательно сохраняйте новые!
+async def on_token_refresh(token_data: TokenData):
+    config["cloudtips_token"] = token_data.access_token
+    config["cloudtips_refresh_token"] = token_data.refresh_token
+    config["cloudtips_expires_at"] = token_data.expires_at
+    with open("donate.json", "w") as f:
+        json.dump(config, f, ensure_ascii=False, indent=2)
+
+auth = CloudTipsAuth(
+    token=config["cloudtips_token"],
+    refresh_token=config["cloudtips_refresh_token"],
+    expires_at=config["cloudtips_expires_at"],
+    on_token_refresh=on_token_refresh,
+)
+
+async def main():
+    async with CloudTipsClient(auth) as client:
+        donations = await client.get_all_donations()
+        for d in donations:
+            print(d)
+        # [2024-01-15 14:30] Антон → 100₽ — "спасибо за контент"
+
+asyncio.run(main())
+
+```
+
+## Получение донатов
+
+```python
+async with CloudTipsClient(auth) as client:
+    # Все донаты за последние 24 часа
+    donations = await client.get_all_donations()
+    for d in donations:
+        print(d.name)     # Антон
+        print(d.amount)   # 50.0
+        print(d.comment)  # спасибо за сервис
+        print(d.date)     # 2026-04-10 20:44:00+03:00
+
+    # За конкретный период
+    from datetime import datetime, timedelta, timezone
+
+    week_ago = datetime.now(tz=timezone.utc) - timedelta(days=7)
+    weekly = await client.get_all_donations(since=week_ago)
+    print(f"Всего за неделю: {len(weekly)} донатов")
+    print(f"Сумма: {sum(d.amount for d in weekly)}₽")
+
+```
+
+## Поллинг новых донатов
+
+### Вариант 1 — async-генератор
+
+```python
+async with CloudTipsClient(auth) as client:
+    async for donation in client.poll(interval=30):
+        print(f"💰 {donation.name} задонатил {donation.amount}₽")
+        if donation.comment:
+            print(f"   Комментарий: {donation.comment}")
+
+```
+
+### Вариант 2 — async-колбэк
+
+```python
+async def handle_donation(donation):
+    print(f"Новый донат от {donation.name}: {donation.amount}₽")
+    # await bot.send_message(...)
+
+async with CloudTipsClient(auth) as client:
+    async for _ in client.poll(interval=15, callback=handle_donation):
+        pass
+
+```
+
+### Вариант 3 — фоновая задача asyncio
+
+```python
+async def poll_task(client):
+    async for donation in client.poll(interval=30):
+        print(f"Новый донат: {donation}")
+
+async def main():
+    async with CloudTipsClient(auth) as client:
+        task = asyncio.create_task(poll_task(client))
+        await asyncio.sleep(3600)  # работаем час
+        task.cancel()
+
+asyncio.run(main())
+
+```
+
+## Профиль, карты и баланс
+
+```python
+async with CloudTipsClient(auth) as client:
+    # Профиль пользователя
+    me = await client.get_me()
+    print(me.full_name)       # Иван Иванов
+    print(me.payout_method)   # Accumulation
+
+    # Привязанные карты
+    for card in await client.get_cards():
+        print(card)  # MIR *0000 (T-BANK, до 00/00) [по умолчанию]
+
+    # Баланс к выводу
+    s = await client.get_accumulation_summary()
+    print(f"Накоплено: {s.accumulated_amount}₽")
+    print(f"Комиссия: {s.commission_percent}%")
+    print(f"Следующая выплата: {s.next_payout_date or 'не запланирована'}")
+
+    # Информация о комиссиях
+    fee = await client.get_payout_fee_info()
+    print(fee.text)
+
+    # Смена метода выплат
+    await client.set_payout_method("Instant")       # мгновенно
+    await client.set_payout_method("Accumulation")  # накопительно
+
+    # Удаление карты
+    for card in await client.get_cards():
+        if not card.is_default:
+            await client.delete_card(card.token)
+
+```
+
+## Обработка ошибок
+
+```python
+from cloudtips import CloudTipsAuthError, CloudTipsAPIError
+
+try:
+    async with CloudTipsClient(auth) as client:
+        donations = await client.get_all_donations()
+except CloudTipsAuthError as e:
+    print(f"Проблема с аутентификацией: {e}")
+except CloudTipsAPIError as e:
+    print(f"Ошибка API (HTTP {e.status_code}): {e.detail}")
+
+```
+
+## Примечания
+
+* **Refresh-токен одноразовый.** После каждого обновления старый токен становится недействительным. Всегда передавайте `on_token_refresh` и сохраняйте новые токены.
+* `on_token_refresh` поддерживает как обычные (`def`), так и async-функции (`async def`).
+* Библиотека автоматически обновляет токен за 2 минуты до истечения.
+* Поллинг отслеживает уже виденные `transaction_id`, поэтому дублей не будет.
+* Клиент — контекстный менеджер (`async with`), это рекомендуемый способ использования.
+* Для логирования внутренних процессов и ошибок сети библиотека использует стандартный модуль `logging`. Настройте ваш логгер для отображения сообщений: `logging.basicConfig(level=logging.INFO)`.
+
+## Лицензия
+
+MIT

cloudtips-0.4.1/README.md

@@ -0,0 +1,185 @@
+# CloudtipsAPI
+<p align="center">
+  <img src="https://static.tildacdn.com/tild3431-6231-4938-b464-663831306266/Horiz.svg" alt="CloudTips" height="120">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/cloudtips/"><img src="https://img.shields.io/pypi/v/cloudtips?color=blue&label=PyPI" alt="PyPI"></a>
+  <a href="https://pepy.tech/project/cloudtips"><img src="https://static.pepy.tech/badge/cloudtips" alt="Downloads"></a>
+  <a href="https://github.com/IRRatium/cloudtips-api/blob/main/LICENSE"><img src="https://img.shields.io/github/license/IRRatium/cloudtips-api" alt="License"></a>
+  <img src="https://img.shields.io/badge/python-3.9+-blue" alt="Python 3.9+">
+  <a href="https://docs.cloudtips.irring.ru"><img src="https://img.shields.io/badge/docs-docs.cloudtips.irring.ru-blue" alt="Docs"></a>
+</p>
+
+Неофициальная асинхронная Python-библиотека для [CloudTips](https://cloudtips.ru) — получение донатов, поллинг новых поступлений и автоматическое обновление токенов.
+
+## Установка
+
+```bash
+pip install cloudtips
+```
+
+## Быстрый старт
+
+```python
+import asyncio
+import json
+from cloudtips import CloudTipsAuth, CloudTipsClient, TokenData
+
+with open("donate.json") as f:
+    config = json.load(f)
+
+# Колбэк вызывается каждый раз при обновлении токенов.
+# Поддерживаются как async, так и обычные функции.
+# Refresh-токен одноразовый — обязательно сохраняйте новые!
+async def on_token_refresh(token_data: TokenData):
+    config["cloudtips_token"] = token_data.access_token
+    config["cloudtips_refresh_token"] = token_data.refresh_token
+    config["cloudtips_expires_at"] = token_data.expires_at
+    with open("donate.json", "w") as f:
+        json.dump(config, f, ensure_ascii=False, indent=2)
+
+auth = CloudTipsAuth(
+    token=config["cloudtips_token"],
+    refresh_token=config["cloudtips_refresh_token"],
+    expires_at=config["cloudtips_expires_at"],
+    on_token_refresh=on_token_refresh,
+)
+
+async def main():
+    async with CloudTipsClient(auth) as client:
+        donations = await client.get_all_donations()
+        for d in donations:
+            print(d)
+        # [2024-01-15 14:30] Антон → 100₽ — "спасибо за контент"
+
+asyncio.run(main())
+
+```
+
+## Получение донатов
+
+```python
+async with CloudTipsClient(auth) as client:
+    # Все донаты за последние 24 часа
+    donations = await client.get_all_donations()
+    for d in donations:
+        print(d.name)     # Антон
+        print(d.amount)   # 50.0
+        print(d.comment)  # спасибо за сервис
+        print(d.date)     # 2026-04-10 20:44:00+03:00
+
+    # За конкретный период
+    from datetime import datetime, timedelta, timezone
+
+    week_ago = datetime.now(tz=timezone.utc) - timedelta(days=7)
+    weekly = await client.get_all_donations(since=week_ago)
+    print(f"Всего за неделю: {len(weekly)} донатов")
+    print(f"Сумма: {sum(d.amount for d in weekly)}₽")
+
+```
+
+## Поллинг новых донатов
+
+### Вариант 1 — async-генератор
+
+```python
+async with CloudTipsClient(auth) as client:
+    async for donation in client.poll(interval=30):
+        print(f"💰 {donation.name} задонатил {donation.amount}₽")
+        if donation.comment:
+            print(f"   Комментарий: {donation.comment}")
+
+```
+
+### Вариант 2 — async-колбэк
+
+```python
+async def handle_donation(donation):
+    print(f"Новый донат от {donation.name}: {donation.amount}₽")
+    # await bot.send_message(...)
+
+async with CloudTipsClient(auth) as client:
+    async for _ in client.poll(interval=15, callback=handle_donation):
+        pass
+
+```
+
+### Вариант 3 — фоновая задача asyncio
+
+```python
+async def poll_task(client):
+    async for donation in client.poll(interval=30):
+        print(f"Новый донат: {donation}")
+
+async def main():
+    async with CloudTipsClient(auth) as client:
+        task = asyncio.create_task(poll_task(client))
+        await asyncio.sleep(3600)  # работаем час
+        task.cancel()
+
+asyncio.run(main())
+
+```
+
+## Профиль, карты и баланс
+
+```python
+async with CloudTipsClient(auth) as client:
+    # Профиль пользователя
+    me = await client.get_me()
+    print(me.full_name)       # Иван Иванов
+    print(me.payout_method)   # Accumulation
+
+    # Привязанные карты
+    for card in await client.get_cards():
+        print(card)  # MIR *0000 (T-BANK, до 00/00) [по умолчанию]
+
+    # Баланс к выводу
+    s = await client.get_accumulation_summary()
+    print(f"Накоплено: {s.accumulated_amount}₽")
+    print(f"Комиссия: {s.commission_percent}%")
+    print(f"Следующая выплата: {s.next_payout_date or 'не запланирована'}")
+
+    # Информация о комиссиях
+    fee = await client.get_payout_fee_info()
+    print(fee.text)
+
+    # Смена метода выплат
+    await client.set_payout_method("Instant")       # мгновенно
+    await client.set_payout_method("Accumulation")  # накопительно
+
+    # Удаление карты
+    for card in await client.get_cards():
+        if not card.is_default:
+            await client.delete_card(card.token)
+
+```
+
+## Обработка ошибок
+
+```python
+from cloudtips import CloudTipsAuthError, CloudTipsAPIError
+
+try:
+    async with CloudTipsClient(auth) as client:
+        donations = await client.get_all_donations()
+except CloudTipsAuthError as e:
+    print(f"Проблема с аутентификацией: {e}")
+except CloudTipsAPIError as e:
+    print(f"Ошибка API (HTTP {e.status_code}): {e.detail}")
+
+```
+
+## Примечания
+
+* **Refresh-токен одноразовый.** После каждого обновления старый токен становится недействительным. Всегда передавайте `on_token_refresh` и сохраняйте новые токены.
+* `on_token_refresh` поддерживает как обычные (`def`), так и async-функции (`async def`).
+* Библиотека автоматически обновляет токен за 2 минуты до истечения.
+* Поллинг отслеживает уже виденные `transaction_id`, поэтому дублей не будет.
+* Клиент — контекстный менеджер (`async with`), это рекомендуемый способ использования.
+* Для логирования внутренних процессов и ошибок сети библиотека использует стандартный модуль `logging`. Настройте ваш логгер для отображения сообщений: `logging.basicConfig(level=logging.INFO)`.
+
+## Лицензия
+
+MIT

{cloudtips-0.3.1 → cloudtips-0.4.1}/cloudtips/__init__.py

@@ -1,12 +1,12 @@
 """
-cloudtips — неофициальная Python-библиотека для CloudTips.
+cloudtips — неофициальная асинхронная Python-библиотека для CloudTips.
 """
 
 from .auth import CloudTipsAuth, CloudTipsAuthError
 from .client import CloudTipsAPIError, CloudTipsClient
 from .models import AccumulationSummary, Card, Donation, PayoutFeeInfo, ReceiverProfile, TokenData
 
-__version__ = "0.3.1"
+__version__ = "0.4.1"
 __all__ = [
     "CloudTipsAuth",
     "CloudTipsAuthError",

{cloudtips-0.3.1 → cloudtips-0.4.1}/cloudtips/auth.py

@@ -1,7 +1,11 @@
+"""
+Аутентификация CloudTips — управление access/refresh токенами.
+"""
+import asyncio
 import time
 from typing import Callable, Optional
 
-import requests
+import aiohttp
 
 from .models import TokenData
 
@@ -14,21 +18,21 @@ class CloudTipsAuth:
     """
     Управляет access/refresh токенами CloudTips.
 
-    Параметр `on_token_refresh` — это колбэк, который вызывается каждый раз
-    после успешного обновления токенов. Используйте его, чтобы сохранить
-    новые токены в файл/БД/переменные окружения — refresh-токен одноразовый!
+    Параметр ``on_token_refresh`` — колбэк, вызываемый после каждого
+    успешного обновления токенов. Refresh-токен одноразовый, поэтому
+    обязательно сохраняйте новые значения.
 
     Пример::
 
-        def save_tokens(token_data: TokenData):
+        async def save_tokens(token_data: TokenData):
             config["cloudtips_token"] = token_data.access_token
             config["cloudtips_refresh_token"] = token_data.refresh_token
             config["cloudtips_expires_at"] = token_data.expires_at
-            save_config(config)
+            await write_config(config)
 
         auth = CloudTipsAuth(
-            token="...",
-            refresh_token="...",
+            token="eyJ...",
+            refresh_token="abc123...",
             expires_at=1776099728.0,
             on_token_refresh=save_tokens,
         )
@@ -45,36 +49,40 @@ class CloudTipsAuth:
         self._refresh_token = refresh_token
         self._expires_at = expires_at
         self._on_token_refresh = on_token_refresh
+        self._lock = asyncio.Lock()  # Защита от Race Condition при параллельных запросах
 
     # ------------------------------------------------------------------
     # Public
     # ------------------------------------------------------------------
 
-    @property
-    def token(self) -> str:
+    async def get_token(self) -> str:
         """Возвращает актуальный access-токен, автоматически обновляя при необходимости."""
         if self._is_expired():
-            self.refresh()
+            async with self._lock:
+                # Повторная проверка: пока текущий таск ждал лока, другой таск уже мог обновить токен
+                if self._is_expired():
+                    await self.refresh()
         return self._token
 
     @property
     def expires_at(self) -> float:
         return self._expires_at
 
-    def refresh(self) -> TokenData:
+    async def refresh(self) -> TokenData:
         """Принудительно обновляет токены через CloudTips Identity Server."""
-        response = requests.post(
-            _TOKEN_URL,
-            data={
-                "grant_type": "refresh_token",
-                "refresh_token": self._refresh_token,
-                "client_id": _CLIENT_ID,
-            },
-            timeout=10,
-        )
-        _raise_for_status(response)
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                _TOKEN_URL,
+                data={
+                    "grant_type":    "refresh_token",
+                    "refresh_token": self._refresh_token,
+                    "client_id":     _CLIENT_ID,
+                },
+                timeout=aiohttp.ClientTimeout(total=10),
+            ) as response:
+                await _raise_for_status(response)
+                data = await response.json()
 
-        data = response.json()
         token_data = TokenData(
             access_token=data["access_token"],
             refresh_token=data["refresh_token"],
@@ -86,15 +94,17 @@ class CloudTipsAuth:
         self._expires_at = token_data.expires_at
 
         if self._on_token_refresh:
-            self._on_token_refresh(token_data)
+            result = self._on_token_refresh(token_data)
+            if asyncio.iscoroutine(result):
+                await result
 
         return token_data
 
-    def headers(self) -> dict:
+    async def headers(self) -> dict:
         """Готовые Authorization-заголовки для запросов."""
         return {
-            "Authorization": f"Bearer {self.token}",
-            "Content-Type": "application/json",
+            "Authorization": f"Bearer {await self.get_token()}",
+            "Content-Type":  "application/json",
         }
 
     # ------------------------------------------------------------------
@@ -105,18 +115,17 @@ class CloudTipsAuth:
         return time.time() >= self._expires_at - _EXPIRE_BUFFER
 
 
-def _raise_for_status(response: requests.Response) -> None:
-    try:
-        response.raise_for_status()
-    except requests.HTTPError as e:
+async def _raise_for_status(response: aiohttp.ClientResponse) -> None:
+    if not response.ok:
         try:
-            detail = response.json()
+            detail = await response.json()
         except Exception:
-            detail = response.text
+            detail = await response.text()
         raise CloudTipsAuthError(
-            f"Ошибка при обновлении токена: {response.status_code} — {detail}"
-        ) from e
+            f"Ошибка при обновлении токена: {response.status} — {detail}"
+        )
 
 
 class CloudTipsAuthError(Exception):
     """Ошибка аутентификации CloudTips."""
+    pass