Клиент к API облака REG.RU

Обёртка над api.cloudvps.reg.ru. Само API несложное, но у него есть неочевидные
места, на которые мы наступили на живых машинах, и которые тут обойдены.

- адрес машины лежит в поле ip, networks всегда пустое
- снимок нельзя снять с остановленной машины, API останавливает её сам
- после снимка машина сидит в locked и не удаляется, удаление настойчивое
- тарифы с картами метод sizes не показывает, их список в docs_slugs.md
- тарификация идёт от часа, короткие запуски невыгодны

Claude-Session: https://claude.ai/code/session_01Loz5stgQZH6ofBdMqTxiJu

README.md

@@ -0,0 +1,89 @@
+# regcloud-api
+
+Клиент к API облака REG.RU (Рег.облако), точка входа `https://api.cloudvps.reg.ru`.
+
+Само API устроено как у DigitalOcean и особой сложности не представляет. Обёртка нужна
+из-за неочевидных мест, на которые мы уже наступили в бою, и которые тут обойдены.
+
+## Что тут учтено
+
+**Адрес машины лежит в поле `ip`.** Поле `networks`, которое по документации должно
+его содержать, всегда пустое. Метод `ip_of()` знает про это.
+
+**Снимок нельзя снять с остановленной машины.** API отвечает `SERVER_IS_STOPPED`.
+Останавливать её должен он сам, для этого есть параметр `offline`.
+
+**Сразу после снимка машина сидит в `locked` и удаляться отказывается**, отвечая
+`RESOURCE_DELETE_ERROR`. Отпускает примерно через полминуты. `destroy()` по умолчанию
+долбится, пока не поддастся, потому что забытая машина продолжает тикать по деньгам.
+
+**Тарифы с видеокартами метод `sizes()` не показывает вообще**, хотя создание с ними
+прекрасно работает. Их список лежит в [docs_slugs.md](docs_slugs.md), там же образы,
+регионы и правила составления slug'ов.
+
+**Тарификация идёт от часа.** Двадцать минут работы списываются как полный час,
+проверено на живой машине. Поднимать машину на короткие задачи невыгодно.
+
+## Установка
+
+```bash
+pip install git+https://git.stackworks.ru/viktor/regcloud-api.git
+```
+
+Токен берётся в личном кабинете и кладётся в `REGRU_CLOUD_TOKEN`.
+
+## Как пользоваться
+
+```python
+from regcloud_api import RegCloud
+
+api = RegCloud()
+
+for s in api.list():
+    print(s["id"], s["name"], s["status"], RegCloud.ip_of(s))
+
+print(api.balance())
+```
+
+Поднять машину с видеокартой, снять с неё образ и удалить.
+
+```python
+srv = api.create(size="c8-m32-d128-g1-a4000-gpu",
+                 image="ubuntu-24-04-amd64-gpu",
+                 name="worker",
+                 ssh_keys=["d7:3a:..."],
+                 region="openstack-spb1")
+
+info = api.wait_active(srv["id"])
+print("адрес", RegCloud.ip_of(info))
+
+api.snapshot(srv["id"], "worker-base", offline=True)   # машину остановит сам
+api.destroy(srv["id"])                                  # дождётся снятия locked
+```
+
+Дальше машину можно поднимать уже из снимка, передав его номер вместо имени образа.
+
+```python
+api.create(size="c8-m32-d128-g1-a4000-gpu", image=7887485, region="openstack-spb1")
+```
+
+## Что умеет
+
+| Метод | Что делает |
+|---|---|
+| `list()`, `get(id)` | машины на аккаунте |
+| `create(...)` | поднять машину, из образа или из снимка |
+| `destroy(id)` | удалить, настойчиво |
+| `stop(id)`, `start(id)` | выключить и включить |
+| `action(id, type, **kw)` | любое действие из списка API |
+| `snapshot(id, name)` | снять образ |
+| `wait_active(id)`, `wait_action(id)` | дождаться готовности |
+| `sizes()`, `gpu_sizes()` | тарифы |
+| `images()`, `snapshots()` | образы и снимки |
+| `ssh_keys()` | ключи доступа |
+| `balance()`, `prices()` | деньги |
+
+## Полезное рядом
+
+- [docs_slugs.md](docs_slugs.md) — тарифы с картами, образы, регионы, правила slug'ов
+- [openapi_v1.json](openapi_v1.json) — спецификация API, снятая с их сервера