diff --git a/pages/integrations/sdks/python.mdx b/pages/integrations/sdks/python.mdx new file mode 100644 index 0000000..7110dd4 --- /dev/null +++ b/pages/integrations/sdks/python.mdx @@ -0,0 +1,180 @@ +--- +title: Python SDK +navigation_icon: code +--- + +The Unikraft Cloud Python SDK is an autogenerated client library that interfaces with the Unikraft Cloud platform API, based on the public OpenAPI specification. +It's currently on the `prod-staging` branch (`v1.0.0`). + +## Installation + +```bash title="" +pip install unikraft-cloud-platform +``` + +Requires Python >=3.9. +The package name uses hyphens (`unikraft-cloud-platform`) but the import name uses underscores (`unikraft_cloud_platform`). + +## Quickstart + +```python title="list_instances.py" +import os +import sys +from unikraft_cloud_platform import AuthenticatedClient +from unikraft_cloud_platform.api.instances import get_instances + +def main(): + token = os.getenv("UKC_TOKEN") + base_url = os.getenv("UKC_METRO", "https://api.fra0.kraft.cloud") + + if not token: + print("Error: UKC_TOKEN is required", file=sys.stderr) + sys.exit(1) + + client = AuthenticatedClient(base_url=base_url, token=token) + + with client as c: + resp = get_instances.sync_detailed(client=c, body=[], details=True) + if resp.status_code == 200 and resp.parsed: + for inst in resp.parsed.data.instances: + print(f"Name: {inst.name}") + print(f"UUID: {inst.uuid}") + print(f"State: {inst.state}") + print("-" * 40) + +if __name__ == "__main__": + main() +``` + +## Authentication + +The Python SDK doesn't read environment variables automatically. +Read your token from the environment and pass it to `AuthenticatedClient`: + +```python title="" +import os +from unikraft_cloud_platform import AuthenticatedClient + +client = AuthenticatedClient( + base_url="https://api.fra0.kraft.cloud", + token=os.environ["UKC_TOKEN"], +) +``` + +An unauthenticated `Client` class is also available for public endpoints. + +## Async usage + +Every operation has both synchronous and asynchronous variants: + +```python title="" +# Synchronous +resp = get_instances.sync_detailed(client=client, body=[], details=True) + +# Asynchronous +import asyncio + +async def main(): + async with client as c: + resp = await get_instances.asyncio_detailed( + client=c, body=[], details=True + ) + +asyncio.run(main()) +``` + +## Resources + +The SDK covers the full Unikraft Cloud REST API surface: + +| Resource | Module | +|---|---| +| Instances | `api.instances` | +| Instance templates | `api.instances` | +| Service groups | `api.service_groups` | +| Autoscale | `api.autoscale` | +| Volumes | `api.volumes` | +| Certificates | `api.certificates` | +| Images | `api.images` | +| Users / quotas | `api.users` | +| System health | `api.system` | + +### Instances + +```python title="" +from unikraft_cloud_platform.api.instances import ( + create_instance, + get_instances, + get_instance_by_uuid, + start_instance_by_uuid, + stop_instance_by_uuid, + stop_instances, + update_instance_by_uuid, + update_instances, + delete_instance_by_uuid, + delete_instances, + get_instance_logs_by_uuid, + get_instance_metrics_by_uuid, + wait_instance_by_uuid, + wait_instances, +) +``` + +### Instance templates + +```python title="" +from unikraft_cloud_platform.api.instances import ( + create_template_instances, + get_template_instances, + get_template_instance_by_uuid, + update_template_instance_by_uuid, + delete_template_instance_by_uuid, + delete_template_instances, +) +``` + +### Volumes + +```python title="" +from unikraft_cloud_platform.api.volumes import ( + create_volume, + get_volumes, + get_volume_by_uuid, + attach_volume_by_uuid, + detach_volume_by_uuid, + update_volume_by_uuid, + delete_volume_by_uuid, + delete_volumes, +) +``` + +### Service groups + +```python title="" +from unikraft_cloud_platform.api.service_groups import ( + create_service_group, + get_service_groups, + get_service_group_by_uuid, + update_service_group_by_uuid, + delete_service_group_by_uuid, + delete_service_groups, +) +``` + +### Autoscale + +```python title="" +from unikraft_cloud_platform.api.autoscale import ( + create_autoscale_configuration_by_service_group_uuid, + create_autoscale_configuration_policy, + get_autoscale_configurations_by_service_group_uuid, + get_autoscale_configuration_policies, + delete_autoscale_configurations_by_service_group_uuid, + delete_autoscale_configuration_policy_by_name, +) +``` + +## Source + +The SDK source is available at +[github.com/unikraft-cloud/python-sdk](https://github.com/unikraft-cloud/python-sdk).