async-xenapi 1.0.1__tar.gz

async_xenapi-1.0.1/.gitignore

@@ -0,0 +1,7 @@
+**/.env
+**/node_modules/
+**/dist/
+**/__pycache__/
+**/*.egg-info/
+**/.venv/
+**/.pytest_cache/

async_xenapi-1.0.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: async-xenapi
+Version: 1.0.1
+Summary: Async XenAPI session via JSON-RPC
+Project-URL: Homepage, https://github.com/acefei/async-xenapi
+Project-URL: Repository, https://github.com/acefei/async-xenapi
+Author-email: Su Fei <acefei@163.com>
+License: LGPL-2.1-only
+Keywords: async,xen-api,xenserver
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v2 (LGPLv2)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: aiohttp>=3.9
+Description-Content-Type: text/markdown
+
+# async-xenapi (Python)
+
+An async Python library for [XenAPI](https://xapi-project.github.io/xen-api).
+
+## Install
+
+Requires **Python 3.14+**.
+
+```
+pip install async-xenapi
+```
+
+Or with `uv`:
+
+```
+uv add async-xenapi
+```
+
+## Usage
+
+```python
+import asyncio
+from async_xenapi import AsyncXenAPISession
+
+async def main():
+    session = AsyncXenAPISession("https://xen-host")
+    await session.login_with_password("root", "password")
+    try:
+        vms = await session.xenapi.VM.get_all()
+        for vm in vms:
+            record = await session.xenapi.VM.get_record(vm)
+            print(record["name_label"])
+    finally:
+        await session.logout()
+
+asyncio.run(main())
+```
+
+Any dotted method path under `session.xenapi` maps directly to the corresponding JSON-RPC call.
+See the [XenAPI Reference](https://xapi-project.github.io/xen-api) for all available classes and fields.
+
+## Best Practices
+
+### 1. Use `get_all_records()` instead of N+1 queries
+
+The single biggest performance win. Instead of fetching a list of refs then querying each one individually, fetch everything in one call:
+
+```python
+# SLOW — N+1 round-trips (1 for get_all + N for each get_name_label)
+vms = await session.xenapi.VM.get_all()
+for vm in vms:
+    name = await session.xenapi.VM.get_name_label(vm)
+    print(name)
+
+# FAST — 1 round-trip, returns {ref: {field: value, ...}, ...}
+records = await session.xenapi.VM.get_all_records()
+for ref, rec in records.items():
+    if not rec["is_a_template"] and not rec["is_a_snapshot"]:
+        print(f"{rec['name_label']} ({rec['power_state']})")
+```
+
+This applies to every XenAPI class: `host`, `SR`, `network`, `VM`, `pool`, etc.
+
+### 2. Use `asyncio.gather()` for independent calls
+
+When you need results from multiple independent API calls, run them concurrently:
+
+```python
+# SLOW — sequential, each awaits the previous
+major = await session.xenapi.host.get_API_version_major(host)
+minor = await session.xenapi.host.get_API_version_minor(host)
+
+# FAST — concurrent, both requests in flight at the same time
+major, minor = await asyncio.gather(
+    session.xenapi.host.get_API_version_major(host),
+    session.xenapi.host.get_API_version_minor(host),
+)
+```
+
+You can also gather across different classes:
+
+```python
+hosts, vms, networks = await asyncio.gather(
+    session.xenapi.host.get_all_records(),
+    session.xenapi.VM.get_all_records(),
+    session.xenapi.network.get_all_records(),
+)
+```
+
+### 3. Always clean up the session
+
+Use `try/finally` to ensure `logout()` is called, which closes both the server-side session and the underlying HTTP connection:
+
+```python
+session = AsyncXenAPISession("https://xen-host")
+await session.login_with_password("root", "password")
+try:
+    # ... your code ...
+finally:
+    await session.logout()
+```
+
+### Key Takeaways
+
+| Pattern                      | Calls        | Approach             |
+|------------------------------|--------------|----------------------|
+| List objects with fields     | 1            | `get_all_records()`  |
+| Multiple independent values  | N concurrent | `asyncio.gather()`   |
+| Lookup one field for one ref | 1            | `get_<field>(ref)`   |
+
+## Run Tests
+
+```
+git clone git@github.com:acefei/async-xenapi.git
+cd async-xenapi
+cp .env.example .env  # then edit .env with your credentials
+cd python
+uv sync
+uv run pytest tests/test_get_xapi_version.py -v
+```
+
+## License
+
+LGPL-2.1-only

async_xenapi-1.0.1/README.md

@@ -0,0 +1,124 @@
+# async-xenapi (Python)
+
+An async Python library for [XenAPI](https://xapi-project.github.io/xen-api).
+
+## Install
+
+Requires **Python 3.14+**.
+
+```
+pip install async-xenapi
+```
+
+Or with `uv`:
+
+```
+uv add async-xenapi
+```
+
+## Usage
+
+```python
+import asyncio
+from async_xenapi import AsyncXenAPISession
+
+async def main():
+    session = AsyncXenAPISession("https://xen-host")
+    await session.login_with_password("root", "password")
+    try:
+        vms = await session.xenapi.VM.get_all()
+        for vm in vms:
+            record = await session.xenapi.VM.get_record(vm)
+            print(record["name_label"])
+    finally:
+        await session.logout()
+
+asyncio.run(main())
+```
+
+Any dotted method path under `session.xenapi` maps directly to the corresponding JSON-RPC call.
+See the [XenAPI Reference](https://xapi-project.github.io/xen-api) for all available classes and fields.
+
+## Best Practices
+
+### 1. Use `get_all_records()` instead of N+1 queries
+
+The single biggest performance win. Instead of fetching a list of refs then querying each one individually, fetch everything in one call:
+
+```python
+# SLOW — N+1 round-trips (1 for get_all + N for each get_name_label)
+vms = await session.xenapi.VM.get_all()
+for vm in vms:
+    name = await session.xenapi.VM.get_name_label(vm)
+    print(name)
+
+# FAST — 1 round-trip, returns {ref: {field: value, ...}, ...}
+records = await session.xenapi.VM.get_all_records()
+for ref, rec in records.items():
+    if not rec["is_a_template"] and not rec["is_a_snapshot"]:
+        print(f"{rec['name_label']} ({rec['power_state']})")
+```
+
+This applies to every XenAPI class: `host`, `SR`, `network`, `VM`, `pool`, etc.
+
+### 2. Use `asyncio.gather()` for independent calls
+
+When you need results from multiple independent API calls, run them concurrently:
+
+```python
+# SLOW — sequential, each awaits the previous
+major = await session.xenapi.host.get_API_version_major(host)
+minor = await session.xenapi.host.get_API_version_minor(host)
+
+# FAST — concurrent, both requests in flight at the same time
+major, minor = await asyncio.gather(
+    session.xenapi.host.get_API_version_major(host),
+    session.xenapi.host.get_API_version_minor(host),
+)
+```
+
+You can also gather across different classes:
+
+```python
+hosts, vms, networks = await asyncio.gather(
+    session.xenapi.host.get_all_records(),
+    session.xenapi.VM.get_all_records(),
+    session.xenapi.network.get_all_records(),
+)
+```
+
+### 3. Always clean up the session
+
+Use `try/finally` to ensure `logout()` is called, which closes both the server-side session and the underlying HTTP connection:
+
+```python
+session = AsyncXenAPISession("https://xen-host")
+await session.login_with_password("root", "password")
+try:
+    # ... your code ...
+finally:
+    await session.logout()
+```
+
+### Key Takeaways
+
+| Pattern                      | Calls        | Approach             |
+|------------------------------|--------------|----------------------|
+| List objects with fields     | 1            | `get_all_records()`  |
+| Multiple independent values  | N concurrent | `asyncio.gather()`   |
+| Lookup one field for one ref | 1            | `get_<field>(ref)`   |
+
+## Run Tests
+
+```
+git clone git@github.com:acefei/async-xenapi.git
+cd async-xenapi
+cp .env.example .env  # then edit .env with your credentials
+cd python
+uv sync
+uv run pytest tests/test_get_xapi_version.py -v
+```
+
+## License
+
+LGPL-2.1-only

async_xenapi-1.0.1/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "async-xenapi"
+version = "1.0.1"
+description = "Async XenAPI session via JSON-RPC"
+readme = "README.md"
+license = { text = "LGPL-2.1-only" }
+authors = [{ name = "Su Fei", email = "acefei@163.com" }]
+requires-python = ">=3.14"
+dependencies = ["aiohttp>=3.9"]
+keywords = ["xenserver", "xen-api", "async"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Lesser General Public License v2 (LGPLv2)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Systems Administration",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/acefei/async-xenapi"
+Repository = "https://github.com/acefei/async-xenapi"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/async_xenapi"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/", "README.md", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["async_xenapi"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope = "class"
+asyncio_default_test_loop_scope = "class"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "python-dotenv>=1.0",
+    "ruff>=0.15.2",
+    "xenapi>=26.5.0",
+]

async_xenapi-1.0.1/src/async_xenapi/__init__.py

@@ -0,0 +1,5 @@
+"""async_xenapi — Async XenAPI session via JSON-RPC (stdlib only)."""
+
+from .session import AsyncXenAPISession
+
+__all__ = ["AsyncXenAPISession"]

async_xenapi-1.0.1/src/async_xenapi/session.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python
+"""Async XenAPI session via JSON-RPC
+
+Usage mirrors the synchronous XenAPI SDK:
+
+    session = AsyncXenAPISession("https://host-ip")
+    await session.login_with_password("root", "password")
+
+    vms = await session.xenapi.VM.get_all()
+    for vm in vms:
+        record = await session.xenapi.VM.get_record(vm)
+        print(record["name_label"])
+
+    await session.logout()
+"""
+
+import contextlib
+import ssl
+import uuid
+from typing import Any
+
+import aiohttp
+
+# ---------------------------------------------------------------------------
+# SSL / JSON-RPC helpers
+# ---------------------------------------------------------------------------
+
+
+def _create_ssl_ctx() -> ssl.SSLContext:
+    ctx = ssl.SSLContext(protocol=ssl.PROTOCOL_TLS_CLIENT)
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_NONE
+    return ctx
+
+
+_ssl_ctx = _create_ssl_ctx()
+
+
+def _jsonrpc_req(method: str, params: list[Any]) -> dict[str, Any]:
+    return {
+        "jsonrpc": "2.0",
+        "method": method,
+        "params": params,
+        "id": str(uuid.uuid4()),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Async XenAPI proxy
+# ---------------------------------------------------------------------------
+
+
+class _MethodProxy:
+    """Accumulates dotted attribute access (e.g. VM.get_all) then turns the
+    final call into an awaitable JSON-RPC request."""
+
+    def __init__(self, session: AsyncXenAPISession, name: str):
+        self._session = session
+        self._name = name
+
+    def __getattr__(self, attr: str) -> _MethodProxy:
+        return _MethodProxy(self._session, f"{self._name}.{attr}")
+
+    async def __call__(self, *args: Any) -> Any:
+        return await self._session._call(self._name, list(args))
+
+
+class _XenAPINamespace:
+    """The object returned by ``session.xenapi``."""
+
+    def __init__(self, session: AsyncXenAPISession):
+        self._session = session
+
+    def __getattr__(self, attr: str) -> _MethodProxy:
+        return _MethodProxy(self._session, attr)
+
+
+class AsyncXenAPISession:
+    """Lightweight async wrapper around XAPI's JSON-RPC endpoint using aiohttp."""
+
+    def __init__(self, url: str):
+        self._url = f"{url.rstrip('/')}/jsonrpc"
+        self._http: aiohttp.ClientSession | None = None
+        self._session_ref: str | None = None
+        self.xenapi = _XenAPINamespace(self)
+
+    def _ensure_http(self) -> aiohttp.ClientSession:
+        if self._http is None or self._http.closed:
+            connector = aiohttp.TCPConnector(ssl=_ssl_ctx)
+            self._http = aiohttp.ClientSession(connector=connector)
+        return self._http
+
+    async def _post(self, payload: dict[str, Any]) -> Any:
+        http = self._ensure_http()
+        async with http.post(self._url, json=payload) as resp:
+            return await resp.json()
+
+    async def login_with_password(self, user: str, password: str) -> str:
+        payload = _jsonrpc_req(
+            "session.login_with_password",
+            [user, password, "version", "originator"],
+        )
+        ret = await self._post(payload)
+        if "error" in ret:
+            raise RuntimeError(f"Login failed: {ret['error']}")
+        self._session_ref = ret["result"]
+        return self._session_ref
+
+    async def logout(self) -> None:
+        if self._session_ref:
+            payload = _jsonrpc_req("session.logout", [self._session_ref])
+            with contextlib.suppress(Exception):
+                await self._post(payload)
+            self._session_ref = None
+        if self._http and not self._http.closed:
+            await self._http.close()
+            self._http = None
+
+    async def _call(self, method: str, params: list[Any]) -> Any:
+        """Send an authenticated JSON-RPC call and return the result."""
+        if not self._session_ref:
+            raise RuntimeError("Not logged in")
+        payload = _jsonrpc_req(method, [self._session_ref] + params)
+        ret = await self._post(payload)
+        if "error" in ret:
+            raise RuntimeError(f"XAPI {method} failed: {ret['error']}")
+        return ret["result"]