# aiovmmanager
Async lib based on aiohttp for working with the VMmanager6 API
## What is it?
A small library that contains several public classes for working with the VMmanager 6 API
- AuthSession
- DnsProxySession
- IpSession
- VmSession
Each class inherits from a base class, BaseSession,
which wraps aiohttp.ClientSession and acts as a context manager.
The library already implements the formation of convenient endpoints,
decodes JSON responses, and also raises a `ClientResponseError` exception
if the response status is 400 or higher.
### There are also several ready-made methods for basic actions:
**AuthSession**
- get_token
- get_key
- whoami
**VmSession**
- get_task
- get_task_by_consul_id
- host_create
- host_delete
- host_edit
## How to use it?
Each available direction of the VMmanager 6 API has its own class.
When initializing the class, you can specify the base url and SSL certificate verification.
All other parameters override the behavior of `aiohttp.ClientSession`
You can read more in the official documentation
[aiohttp](https://docs.aiohttp.org/en/stable/client_reference.html)
Each class has methods that make it easier to generate API requests
Their names are the same as the `aiohttp.ClientSession` methods.
Methods currently implemented:
- get
- post
- delete
To start generating queries, import the required class
and use the context manager syntax
## Installation
### Requirements
- python = `^3.9`
### Manual
- install dependency `pip install aiohttp`
- copy the aiovmmanager package to your project
### Use pip
- `pip install iovmmanager`
## Examples
- **get an authorization token**
this token will need to be added to the header of each request in the future
```python
import asyncio
from aiovmmanager import AuthSession
async def main():
url = 'https://vm6.example.com'
headers = {}
# pass to AuthSession ssl=False if you have a self-signed or invalid certificate
async with AuthSession(url=url) as session:
response = await session.get_token(
email='admin@example.com',
password='password',
)
# set x-xsrf-token header:
headers['x-xsrf-token'] = response.get('token', '')
print(headers)
if __name__ == "__main__":
asyncio.run(main())
```
- **end-to-end authorization by key**
```python
import asyncio
from aiovmmanager import AuthSession
async def main():
url = 'https://vm6.example.com'
headers = {'x-xsrf-token': 'the token can be obtained in the example above'}
# pass to AuthSession ssl=False if you have a self-signed or invalid certificate
async with AuthSession(url=url, headers=headers) as session:
response = await session.get_key(email_or_id='admin@example.com')
print(response)
if __name__ == "__main__":
asyncio.run(main())
```
- **Create 3 virtual machines asynchronously**
```python
import asyncio
from aiovmmanager import VmSession
vm_template = {
"name": "aiovmmgr",
"os": 8211,
"password": "root-password",
"send_email_mode": "default",
"cluster": 27,
"preset": 1,
"disks": [
{
"boot_order": 1,
"size_mib": 10240,
"tags": [],
"storage": 61
}
],
"comment": "test vm from aiovmmgr",
"account": 124,
"node": 64,
"custom_interfaces": [
{
"model": "virtio",
"is_main_network": True,
"bridge_id": 97,
"ip_count": 1,
"ippool": 111
}
],
"domain": "aiovmmgr.example.com"
}
async def main():
url = 'https://vm6.example.com'
headers = {'x-xsrf-token': 'the token can be obtained in the first example'}
async with VmSession(url=url, headers=headers) as session:
# create a list of three coroutines
# of course in a real example host_params contains three different vms
tasks = [session.host_create(host_params=vm_template) for _ in range(3)]
# send a request to create virtual machines asynchronously
results = await asyncio.gather(*tasks)
for result in results:
print(result)
if __name__ == "__main__":
asyncio.run(main())
```
- **get task by consul id**
All tasks that are performed by the platform for a long time fall into the consul.
The response comes with the id of such a task. Subsequently, the task
will go to the task manager and will be processed and completed
You can find the task number in the task manager by requesting information by consul id.
The method is configured with an exact match filter by consul id
```python
import asyncio
from aiovmmanager import VmSession
async def main():
url = 'https://vm6.example.com'
headers = {'x-xsrf-token': 'the token can be obtained in the first example'}
consul_id = 1488228 # example consul_id
async with VmSession(url=url, headers=headers) as session:
response = await session.get_task_by_consul_id(consul_id=consul_id)
print(response)
if __name__ == "__main__":
asyncio.run(main())
```
- **any request in accordance with the VMmanager 6 API documentation**
Since all classes inherit from `BaseSession` which is a
wrapper of `aiohttp.ClientSession` you can make requests for any handlers.
```python
import asyncio
from aiovmmanager import AuthSession, VmSession
async def main():
url = 'https://vm6.example.com'
headers = {'x-xsrf-token': 'the token can be obtained in the first example'}
# -- Snip
async with AuthSession(url=url, headers=headers) as session:
# show active admins:
list_admins = await session.get(
url='/user',
params={"where": "((roles+CP+'%@admin%')+AND+(state+EQ+'active'))"}
)
print(list_admins)
# -- Snip
# -- Snip
async with VmSession(url=url, headers=headers) as session:
# force restart vm by id:
host_id = 228
restart_vm = await session.post(
url=f'/host/{host_id}/restart',
json={'force': True}
)
print(restart_vm)
# -- Snip
if __name__ == "__main__":
asyncio.run(main())
```
Raw data
{
"_id": null,
"home_page": "https://github.com/MOIS3Y/aiovmmanager",
"name": "aiovmmanager",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "vmmanager, ispsystem, kvm, virtualisation",
"author": "MOIS3Y",
"author_email": "stepan@zhukovsky.me",
"download_url": "https://files.pythonhosted.org/packages/5a/7e/a6a144132d9cdf4ca542ab3a291d5d191707177176cecb84195666f20bb9/aiovmmanager-0.1.1.tar.gz",
"platform": null,
"description": "# aiovmmanager\nAsync lib based on aiohttp for working with the VMmanager6 API\n\n\n## What is it?\n\nA small library that contains several public classes for working with the VMmanager 6 API\n- AuthSession\n- DnsProxySession\n- IpSession\n- VmSession\n\nEach class inherits from a base class, BaseSession,\nwhich wraps aiohttp.ClientSession and acts as a context manager.\n\nThe library already implements the formation of convenient endpoints,\ndecodes JSON responses, and also raises a `ClientResponseError` exception\nif the response status is 400 or higher.\n\n\n### There are also several ready-made methods for basic actions:\n\n**AuthSession**\n\n- get_token\n- get_key\n- whoami\n\n\n**VmSession**\n\n- get_task\n- get_task_by_consul_id\n- host_create\n- host_delete\n- host_edit\n\n## How to use it?\n\nEach available direction of the VMmanager 6 API has its own class.\nWhen initializing the class, you can specify the base url and SSL certificate verification.\nAll other parameters override the behavior of `aiohttp.ClientSession`\nYou can read more in the official documentation \n[aiohttp](https://docs.aiohttp.org/en/stable/client_reference.html)\n\nEach class has methods that make it easier to generate API requests\nTheir names are the same as the `aiohttp.ClientSession` methods.\nMethods currently implemented:\n\n- get\n- post\n- delete\n\nTo start generating queries, import the required class\nand use the context manager syntax\n\n\n## Installation\n\n### Requirements\n- python = `^3.9`\n\n### Manual\n- install dependency `pip install aiohttp`\n- copy the aiovmmanager package to your project\n\n### Use pip\n\n- `pip install iovmmanager`\n\n\n## Examples\n\n- **get an authorization token** \nthis token will need to be added to the header of each request in the future\n\n```python\nimport asyncio\nfrom aiovmmanager import AuthSession\n\n\nasync def main():\n url = 'https://vm6.example.com'\n headers = {}\n\n # pass to AuthSession ssl=False if you have a self-signed or invalid certificate\n async with AuthSession(url=url) as session:\n response = await session.get_token(\n email='admin@example.com',\n password='password',\n )\n # set x-xsrf-token header:\n headers['x-xsrf-token'] = response.get('token', '')\n print(headers)\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n\n```\n\n- **end-to-end authorization by key**\n\n```python\nimport asyncio\nfrom aiovmmanager import AuthSession\n\n\nasync def main():\n url = 'https://vm6.example.com'\n headers = {'x-xsrf-token': 'the token can be obtained in the example above'}\n\n # pass to AuthSession ssl=False if you have a self-signed or invalid certificate\n async with AuthSession(url=url, headers=headers) as session:\n response = await session.get_key(email_or_id='admin@example.com')\n print(response)\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n\n```\n\n- **Create 3 virtual machines asynchronously**\n\n```python\nimport asyncio\nfrom aiovmmanager import VmSession\n\n\nvm_template = {\n \"name\": \"aiovmmgr\",\n \"os\": 8211,\n \"password\": \"root-password\",\n \"send_email_mode\": \"default\",\n \"cluster\": 27,\n \"preset\": 1,\n \"disks\": [\n {\n \"boot_order\": 1,\n \"size_mib\": 10240,\n \"tags\": [],\n \"storage\": 61\n }\n ],\n \"comment\": \"test vm from aiovmmgr\",\n \"account\": 124,\n \"node\": 64,\n \"custom_interfaces\": [\n {\n \"model\": \"virtio\",\n \"is_main_network\": True,\n \"bridge_id\": 97,\n \"ip_count\": 1,\n \"ippool\": 111\n }\n ],\n \"domain\": \"aiovmmgr.example.com\"\n}\n\n\nasync def main():\n url = 'https://vm6.example.com'\n headers = {'x-xsrf-token': 'the token can be obtained in the first example'}\n\n async with VmSession(url=url, headers=headers) as session:\n # create a list of three coroutines\n # of course in a real example host_params contains three different vms\n tasks = [session.host_create(host_params=vm_template) for _ in range(3)]\n # send a request to create virtual machines asynchronously\n results = await asyncio.gather(*tasks)\n\n for result in results:\n print(result)\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n- **get task by consul id**\n\nAll tasks that are performed by the platform for a long time fall into the consul.\nThe response comes with the id of such a task. Subsequently, the task\nwill go to the task manager and will be processed and completed\nYou can find the task number in the task manager by requesting information by consul id.\nThe method is configured with an exact match filter by consul id\n\n```python\nimport asyncio\nfrom aiovmmanager import VmSession\n\n\nasync def main():\n url = 'https://vm6.example.com'\n headers = {'x-xsrf-token': 'the token can be obtained in the first example'}\n\n consul_id = 1488228 # example consul_id\n\n async with VmSession(url=url, headers=headers) as session:\n response = await session.get_task_by_consul_id(consul_id=consul_id)\n print(response)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n- **any request in accordance with the VMmanager 6 API documentation**\n\nSince all classes inherit from `BaseSession` which is a\nwrapper of `aiohttp.ClientSession` you can make requests for any handlers.\n\n\n```python\nimport asyncio\nfrom aiovmmanager import AuthSession, VmSession\n\n\nasync def main():\n url = 'https://vm6.example.com'\n headers = {'x-xsrf-token': 'the token can be obtained in the first example'}\n\n # -- Snip\n async with AuthSession(url=url, headers=headers) as session:\n # show active admins:\n list_admins = await session.get(\n url='/user',\n params={\"where\": \"((roles+CP+'%@admin%')+AND+(state+EQ+'active'))\"}\n )\n print(list_admins)\n # -- Snip\n\n # -- Snip\n async with VmSession(url=url, headers=headers) as session:\n # force restart vm by id:\n host_id = 228\n restart_vm = await session.post(\n url=f'/host/{host_id}/restart',\n json={'force': True}\n )\n print(restart_vm)\n # -- Snip\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Async lib based on aiohttp for working with the VMmanager6 API",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/MOIS3Y/aiovmmanager",
"Repository": "https://github.com/MOIS3Y/aiovmmanager"
},
"split_keywords": [
"vmmanager",
" ispsystem",
" kvm",
" virtualisation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9cd8b33658a0f02f699bf9a27b9cdc3c58d067ea45bb3e50d7a100b2e10d149b",
"md5": "1666631e2f2cbc3ea47622884532a72b",
"sha256": "7dc5b748fadec555f6f730a4494209dee912d875985a6019ace09698420226ba"
},
"downloads": -1,
"filename": "aiovmmanager-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1666631e2f2cbc3ea47622884532a72b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 7482,
"upload_time": "2024-09-11T06:45:23",
"upload_time_iso_8601": "2024-09-11T06:45:23.402298Z",
"url": "https://files.pythonhosted.org/packages/9c/d8/b33658a0f02f699bf9a27b9cdc3c58d067ea45bb3e50d7a100b2e10d149b/aiovmmanager-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5a7ea6a144132d9cdf4ca542ab3a291d5d191707177176cecb84195666f20bb9",
"md5": "2956203ee8815f87ee2d064b31a2f36a",
"sha256": "7dfe2197ae5beb9bd039a7b26c6e7357ea3174d0b34c29fe083aceece25d36d9"
},
"downloads": -1,
"filename": "aiovmmanager-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "2956203ee8815f87ee2d064b31a2f36a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 6171,
"upload_time": "2024-09-11T06:45:25",
"upload_time_iso_8601": "2024-09-11T06:45:25.272458Z",
"url": "https://files.pythonhosted.org/packages/5a/7e/a6a144132d9cdf4ca542ab3a291d5d191707177176cecb84195666f20bb9/aiovmmanager-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-11 06:45:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MOIS3Y",
"github_project": "aiovmmanager",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "aiovmmanager"
}
JSON
