micloud-sdk 1.0.3
Professional Python SDK for MiCloud API
License: MIT
Requires Python: >=3.8
Keywords: micloud api sdk cloud storage

# MiCloud SDK

Python библиотека для работы с MiCloud API. 

## Особенности

- 🔐 Безопасная аутентификация через API ключи
- 📦 Загрузка и управление файлами
- 📁 Работа с папками и структурой файлов
- 🔗 Создание публичных ссылок для шаринга
- 📊 Получение статистики использования
- 🔄 Поддержка асинхронных операций

## Установка

```bash
pip install micloud-sdk
```

## Быстрый старт

### Инициализация клиента

```python
from micloud_sdk import MiCloudClient

# Просто передайте API ключ - всё остальное настроено
client = MiCloudClient(api_key="ваш_api_ключ")
```

### Получение информации о пользователе

```python
# Базовая информация (user_id, username, full_name)
user_info = client.auth.get_current_user()
print(f"Пользователь: {user_info.username} (ID: {user_info.user_id})")

# Полная информация со статистикой (используйте эту для storage и premium статуса)
full_user = client.auth.get_full_user()
print(f"Всего файлов: {full_user.files_count}")
print(f"Используется: {full_user.used_storage / 1024 / 1024} MB")
print(f"Лимит: {full_user.max_storage / 1024 / 1024} MB")
print(f"Премиум: {full_user.is_premium}")
```

**Важно**: `/me` возвращает только базовую информацию. Для полной статистики используйте `get_full_user()` которая вызывает `/me/stats`.

### Загрузка файла

```python
# Загрузить файл
file_info = client.files.upload("path/to/file.txt")
print(f"Файл загружен: {file_info.name}")
print(f"Размер: {file_info.size} байт")
```

### Создание репозитория

```python
# Создать репозиторий
repo = client.repos.create("Мой проект", "Описание проекта")
print(f"Репо создано: {repo.name}")
```

## Асинхронное использование

```python
import asyncio

async def main():
    client = MiCloudClient(api_key="ваш_api_ключ")
    
    # Базовая информация
    user = await client.auth.get_current_user_async()
    print(f"Пользователь: {user.username}")
    
    # Полная информация со статистикой
    full_user = await client.auth.get_full_user_async()
    print(f"Статистика: {full_user.files_count} файлов")
    
    await client.close()

asyncio.run(main())
```

### С контекстным менеджером

```python
async with MiCloudClient(api_key="ваш_api_ключ") as client:
    user = await client.auth.get_current_user_async()
    print(f"Пользователь: {user.username}")
```

## API Referece

### Аутентификация

- `client.auth.get_current_user()` - Получить базовую информацию о пользователе
- `client.auth.get_full_user()` - Получить полную информацию с статистикой
- `client.auth.get_stats()` - Получить статистику использования

### Файлы

- `client.files.upload(file_path)` - Загрузить файл
- `client.files.list_tree()` - Получить дерево файлов
- `client.files.download(file_id)` - Скачать файл
- `client.files.delete(file_id)` - Удалить файл

### Папки

- `client.folders.create(name, parent_id)` - Создать папку
- `client.folders.list(parent_id)` - Список папок
- `client.folders.delete(folder_id)` - Удалить папку

### Репозитории

- `client.repos.create(name, description)` - Создать репозиторий
- `client.repos.list()` - Список репозиториев
- `client.repos.delete(repo_id)` - Удалить репозиторий

## Конфигурация

API подключается к `https://api.micloud.website` по умолчанию. Убедитесь что у вас есть действительный API ключ.

## Обработка ошибок

```python
from micloud_sdk import (
    MiCloudClient,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    ValidationError,
)

try:
    client = MiCloudClient(api_key="invalid_key")
    user = client.auth.get_current_user()
except AuthenticationError:
    print("Неверный API ключ")
except RateLimitError as e:
    print(f"Превышено ограничение. Повторите через {e.retry_after} сек")
except NotFoundError:
    print("Ресурс не найден")
except ValidationError as e:
    print(f"Ошибка валидации: {e}")
```

## Версионирование

Версия SDK: 1.0.0
API версия: v1

## Лицензия

MIT