MiCloud SDK - Python библиотека

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

MiCloud SDK - это официальная Python библиотека для удобной работы с API облачного хранилища MiCloud. Библиотека предоставляет простой и интуитивный интерфейс для всех операций с файлами, папками, репозиториями и публичными ссылками.

✓ Основные возможности:

Полная поддержка всех API методов
Работа как в синхронном, так и асинхронном режиме
Типизированные данные (pydantic models)
Удобная обработка ошибок
Контекстные менеджеры для управления ресурсами

📦 Установка

Установите MiCloud SDK через pip:

pip install micloud-sdk

📋 Требования

Python: 3.8+
requests: для синхронных операций
aiohttp: для асинхронных операций

pip install requests aiohttp

✨ Основные возможности

📁 Управление файлами

Загрузка, скачивание, переименование и удаление файлов

📂 Организация папок

Создание, переименование и удаление папок с древовидной структурой

🔗 Публичные ссылки

Создание защищенных ссылок для шаринга файлов с паролями и сроками

📚 Репозитории

Управление репозиториями с системой версионирования (коммиты)

🌐 Веб-публикация

Публикация репозиториев как веб-сайтов с автоматической генерацией URL

🔐 Безопасность

API ключ в заголовках, защита от rata limit, обработка ошибок

🔐 Аутентификация

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

Откройте бота MiCloud
Введите команду /api_key
Нажмите "Сгенерировать новый ключ"
Скопируйте полученный ключ

Инициализация клиента

            from micloud_sdk
            import MiCloudClient

            # Просто передайте API ключ
            client = MiCloudClient(api_key="your_api_key_here")
          

📖 Документация API

👤 Методы аутентификации

MiCloudClient auth.get_current_user()

Описание: Получить информацию о текущем пользователе

Возвращает: User

              user = client.auth.get_current_user()
              print(f"Пользователь: {user.username}") print(f"Premium: {user.is_premium}") print(f"Хранилище: {user.used_storage}/{user.max_storage}")
            

MiCloudClient Async auth.get_current_user_async()

Описание: Асинхронная версия

              user =
              await
              client.auth.get_current_user_async()
            

MiCloudClient auth.get_full_user()

Описание: Получить полную информацию о пользователе со статистикой

Возвращает: User с полной информацией

              user = client.auth.get_full_user()
              print(f"Хранилище: {user.used_storage}/{user.max_storage}")
            

MiCloudClient auth.get_stats()

Описание: Получить статистику пользователя

              stats = client.auth.get_stats()
              print(stats)
            

MiCloudClient auth.get_api_key()

Описание: Получить текущий API ключ

              api_key = client.auth.get_api_key()
              print(f"Ключ активен: {api_key.is_active}")
            

MiCloudClient auth.regenerate_api_key()

Описание: Переоформить API ключ (предыдущий станет невалидным)

              new_key = client.auth.regenerate_api_key()
              print(f"Новый ключ: {new_key.key}")
            

📄 Методы работы с файлами

MiCloudClient files.list_tree()

Описание: Получить полное дерево файлов и папок с корня

Возвращает: TreeNode

              tree = client.files.list_tree()
              def print_tree(node, indent=0): print(" "
              * indent + f"{node.icon} {node.name}")
              for child
              in node.children: print_tree(child,
              indent + 1) print_tree(tree)
            

MiCloudClient files.get_tree_by_id(folder_id)

Описание: Получить дерево файлов и папок по ID папки

Параметры:

folder_id (str) - ID папки для получения содержимого

Возвращает: TreeNode

              # Получить содержимое папки по ID
              folder_tree = client.files.get_tree_by_id("89") for child
              in folder_tree.children:
              print(f"{child.icon} {child.name}")
            

MiCloudClient files.list_folder(folder_id=None)

Описание: Получить содержимое папки в виде словаря (raw API ответ)

Параметры:

folder_id (str, optional) - ID папки (если None - корневая папка)

Возвращает: Dict с файлами и папками

              # Получить содержимое корневой папки
              content = client.files.list_folder()
              print(content["tree"])
            

MiCloudClient files.upload(file_path, parent_folder_id=None)

Описание: Загрузить файл

Параметры:

file_path (str) - путь к файлу для загрузки
parent_folder_id (str, optional) - ID папки назначения

Возвращает: FileInfo

              file_info = client.files.upload("path/to/file.txt") print(f"Загружено: {file_info.name} ({file_info.size} bytes)")

              # В определенную папку
              file_info = client.files.upload("path/to/file.txt", parent_folder_id="folder_id")
            

MiCloudClient files.download(file_id, save_path=None)

Описание: Скачать файл

Параметры:

file_id (str) - ID файла
save_path (str, optional) - путь для сохранения (если None - вернет bytes)

              # Сохранить на диск
              client.files.download("file_id_here",
              save_path="local_file.txt")

              # Получить в памяти
              content = client.files.download("file_id_here") print(f"Размер: {len(content)} bytes")
            

MiCloudClient files.rename(file_id, new_name)

Описание: Переименовать файл

renamed = client.files.rename("file_id", "новое_имя.txt")

MiCloudClient files.delete(file_id)

Описание: Удалить файл

client.files.delete("file_id")

📁 Методы работы с папками

MiCloudClient folders.create(name, parent_folder_id=None)

Описание: Создать новую папку

              folder = client.folders.create("Моя папка") subfolder = client.folders.create("Подпапка", parent_folder_id=folder.id)
            

MiCloudClient folders.rename(folder_id, new_name)

Описание: Переименовать папку

folder = client.folders.rename("folder_id", "Новое имя")

MiCloudClient folders.delete(folder_id)

Описание: Удалить папку со всем содержимым

client.folders.delete("folder_id")

MiCloudClient shares.create(file_id, is_anonymous=False, password=None, expires_in_days=None, max_accesses=None)

Описание: Создать публичную ссылку на файл

              share = client.shares.create( file_id="file_id", is_anonymous=False, password="secret123", expires_in_days=7, )
              print(f"Ссылка: {share.share_url}")
            

MiCloudClient shares.get(share_id)

Описание: Получить информацию о ссылке

              share = client.shares.get("share_id")
              print(f"Доступов: {share.access_count}")
            

MiCloudClient shares.update(share_id, is_anonymous=None, password=None, max_accesses=None)

Описание: Обновить параметры публичной ссылки

Параметры:

share_id (str) - ID ссылки
is_anonymous (bool, optional) - скрыть имя автора
password (str, optional) - новый пароль
max_accesses (int, optional) - максимальное количество доступов

              # Изменить пароль на ссылке
              share = client.shares.update("share_id", password="new_secret123",
              max_accesses=100)
            

MiCloudClient shares.delete(share_id)

Описание: Удалить публичную ссылку

client.shares.delete("share_id")

📚 Методы репозиториев

MiCloudClient repos.list()

Описание: Получить список всех репозиториев

              repos = client.repos.list()
              for repo
              in repos:
              print(f"{repo.name} (приватное: {repo.is_private})")
            

MiCloudClient repos.get(repo_id)

Описание: Получить информацию о репозитории

Параметры:

repo_id (str) - ID репозитория

Возвращает: Repository

              repo = client.repos.get("repo_id")
              print(f"Репо: {repo.name}") print(f"Использовано: {repo.used_storage} байт")
            

MiCloudClient repos.create(name, description="", is_private=True)

Описание: Создать новый репозиторий

              repo = client.repos.create( name="Мой проект", description="Описание проекта",
              is_private=True
              )
            

MiCloudClient repos.update(repo_id, name=None, description=None, is_private=None)

Описание: Обновить информацию о репозитории

Параметры:

repo_id (str) - ID репозитория
name (str, optional) - новое имя
description (str, optional) - новое описание
is_private (bool, optional) - изменить статус приватности

              # Обновить название и сделать публичным
              repo = client.repos.update("repo_id",
              name="Новое название",
              is_private=False)
            

MiCloudClient repos.add_file(repo_id, file_id)

Описание: Добавить файл в репозиторий

              client.repos.add_file("repo_id",
              "file_id")
            

MiCloudClient repos.get_commits(repo_id)

Описание: Получить историю коммитов

              commits = client.repos.get_commits("repo_id") for commit
              in commits:
              print(f"{commit.message} ({commit.created_at})")
            

MiCloudClient repos.deploy(repo_id)

Описание: Опубликовать репозиторий как веб-сайт

              deploy = client.repos.deploy("repo_id") print(f"Сайт опубликован: {deploy.deploy_url}")
            

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

SDK предоставляет специальные исключения для разных ситуаций:

Исключение	Описание	HTTP статус
`AuthenticationError`	Неверный API ключ	401
`PermissionDeniedError`	Отказано в доступе	403
`NotFoundError`	Ресурс не найден	404
`RateLimitError`	Превышено ограничение запросов	429
`ValidationError`	Ошибка валидации данных	400, 413
`QuotaExceededError`	Превышена квота хранилища	507

            from micloud_sdk
            import ( MiCloudClient,
            AuthenticationError, RateLimitError, QuotaExceededError )

            try: user =
            client.auth.get_current_user()
            print(f"Пользователь: {user.username}") except AuthenticationError:
            print("Ошибка: неверный API ключ") except RateLimitError
            as e:
            print(f"Ограничение запросов. Повторите через {e.retry_after} сек") except QuotaExceededError:
            print("Превышена квота хранилища") except Exception
            as e:
            print(f"Ошибка: {e}")
          

🔄 Синхронный vs Асинхронный код

Все методы доступны в двух версиях: синхронной и асинхронной.

Синхронное использование

            # Синхронные методы (блокируют выполнение)
            user = client.auth.get_current_user() files =
            client.files.list_tree() repo = client.repos.create("Мой проект")
          

Асинхронное использование

Все методы имеют асинхронные версии с суффиксом _async():

            async def main():
            # Асинхронные методы (не блокируют)
            user =
            await
            client.auth.get_current_user_async() files =
            await client.files.list_tree_async()
            folder_content =
            await
            client.files.get_tree_by_id_async("89")
            repo =
            await client.repos.create_async("Мой проект")

            # Несколько операций параллельно
            tasks = [ client.repos.create_async("Проект 1"), client.repos.create_async("Проект 2"), client.repos.create_async("Проект 3"), ] results =
            await asyncio.gather(*tasks)
          

💡 Совет: Для всех методов доступны асинхронные версии: get_current_user() → get_current_user_async(), files.upload() → files.upload_async() и т.д.

💻 Примеры использования

Пример 1: Полный workflow

            from micloud_sdk
            import MiCloudClient

            # Инициализация
            client = MiCloudClient(api_key="your_api_key")

            # 1. Проверить аутентификацию
            user = client.auth.get_current_user()
            print(f"✓ Аутентифицирован как {user.username}")

            # 2. Создать папку
            folder = client.folders.create("Мои файлы") print(f"✓ Папка создана: {folder.name}")

            # 3. Загрузить файл
            file_info = client.files.upload("document.pdf", parent_folder_id=folder.id)
            print(f"✓ Файл загружен: {file_info.name}")

            # 4. Создать публичную ссылку
            share = client.shares.create(file_id=file_info.id, password="secret123") print(f"✓ Ссылка создана: {share.share_url}")
          

Пример 2: Асинхронная загрузка нескольких файлов

            import asyncio
            from micloud_sdk
            import MiCloudClient

            async def upload_multiple_files():
            async with MiCloudClient(api_key="your_api_key") as client: files = ["file1.pdf", "file2.pdf",
            "file3.pdf"]

            # Загрузить параллельно
            tasks = [client.files.upload_async(f)
            for f
            in files] results =
            await asyncio.gather(*tasks)

            for result
            in results:
            print(f"✓ Загружено: {result.name}")

            # Запуск
            asyncio.run(upload_multiple_files())
          

Пример 3: Создание и публикация веб-сайта

            client = MiCloudClient(api_key="your_api_key")

            # Создать репозиторий
            repo = client.repos.create( name="Мой веб-сайт", description="HTML сайт",
            is_private=False
            )

            # Загрузить HTML файлы
            html_files = ["index.html",
            "style.css",
            "script.js"]
            for file_path
            in html_files: file_info =
            client.files.upload(file_path) client.repos.add_file(repo.id,
            file_info.id)

            # Опубликовать
            deploy = client.repos.deploy(repo.id)
            print(f"✓ Сайт доступен по адресу: {deploy.deploy_url}")
          

❓ Часто задаваемые вопросы

Q: Как получить API ключ?

A: Откройте приложение MiCloud, перейдите в Настройки → API и нажмите "Сгенерировать новый ключ". Используйте этот ключ при инициализации клиента.

Q: Какой лимит на размер файла?

A: Максимальный размер одного файла - 500 МБ. Для файлов больше 10 МБ рекомендуется использовать асинхронную загрузку.

Q: Как работает rate limiting?

A: API ограничен на 100 запросов в 60 секунд. При превышении вы получите исключение RateLimitError с информацией о времени ожидания.

Q: Могу ли я использовать оба режима (sync и async) одновременно?

A: Да, один экземпляр клиента можно использовать для обоих режимов. Просто вызывайте нужные методы.

Q: Как закрыть асинхронную сессию?

A: Используйте контекстный менеджер async with или вызовите await client.close()

🐍 MiCloud SDK

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

📦 Установка

📋 Требования

✨ Основные возможности

📁 Управление файлами

📂 Организация папок

🔗 Публичные ссылки

📚 Репозитории

🌐 Веб-публикация

🔐 Безопасность

🔐 Аутентификация

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

Инициализация клиента

📖 Документация API

👤 Методы аутентификации

📄 Методы работы с файлами

📁 Методы работы с папками

🔗 Методы публичных ссылок

📚 Методы репозиториев

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

🔄 Синхронный vs Асинхронный код

Синхронное использование

Асинхронное использование

💻 Примеры использования

Пример 1: Полный workflow

Пример 2: Асинхронная загрузка нескольких файлов

Пример 3: Создание и публикация веб-сайта

❓ Часто задаваемые вопросы

Q: Как получить API ключ?

Q: Какой лимит на размер файла?

Q: Как работает rate limiting?

Q: Могу ли я использовать оба режима (sync и async) одновременно?

Q: Как закрыть асинхронную сессию?