loopix-sdk 2.30.0__py3-none-any.whl

loopix/volume/client_async/__init__.py

@@ -0,0 +1,88 @@
+import asyncio
+import os
+import weakref
+from typing import Dict, Optional
+
+import httpx
+from httpx import Limits
+from httpx._types import ProxyTypes
+
+from loopix.api import make_async_logging_event_hooks
+from loopix.api.metadata import default_headers
+from loopix.exceptions import AuthenticationException
+from loopix.volume.client.client import AuthenticatedClient as AsyncVolumeApiClient
+from loopix.volume.connection_config import VolumeConnectionConfig
+
+limits = Limits(
+    max_keepalive_connections=int(os.getenv("LOOPIX_MAX_KEEPALIVE_CONNECTIONS", "20")),
+    max_connections=int(os.getenv("LOOPIX_MAX_CONNECTIONS", "2000")),
+    keepalive_expiry=int(os.getenv("LOOPIX_KEEPALIVE_EXPIRY", "300")),
+)
+
+TransportKey = Optional[ProxyTypes]
+
+
+def get_api_client(config: VolumeConnectionConfig, **kwargs) -> AsyncVolumeApiClient:
+    if config.access_token is None:
+        raise AuthenticationException(
+            "Volume token is required for volume content operations. "
+            "Use `AsyncVolume.create`/`AsyncVolume.connect` to obtain it "
+            "or pass `token` in options.",
+        )
+
+    headers = {
+        **default_headers,
+        **(config.headers or {}),
+    }
+
+    request_timeout = config.request_timeout
+
+    return AsyncVolumeApiClient(
+        base_url=config.api_url,
+        token=config.access_token,
+        auth_header_name="Authorization",
+        prefix="Bearer",
+        headers=headers,
+        timeout=(
+            httpx.Timeout(request_timeout) if request_timeout is not None else None
+        ),
+        httpx_args={
+            "proxy": config.proxy,
+            "transport": get_transport(config),
+            "event_hooks": make_async_logging_event_hooks(config.logger),
+        },
+        **kwargs,
+    )
+
+
+class AsyncTransportWithLogger(httpx.AsyncHTTPTransport):
+    # Keyed weakly by the event loop object itself, not id(loop) — CPython
+    # reuses object ids, so a new loop could otherwise inherit a transport
+    # bound to a previous, closed loop.
+    _instances: weakref.WeakKeyDictionary[
+        asyncio.AbstractEventLoop,
+        Dict[TransportKey, "AsyncTransportWithLogger"],
+    ] = weakref.WeakKeyDictionary()
+
+    @property
+    def pool(self):
+        return self._pool
+
+
+def get_transport(config: VolumeConnectionConfig) -> AsyncTransportWithLogger:
+    loop = asyncio.get_running_loop()
+    loop_instances = AsyncTransportWithLogger._instances.get(loop)
+    if loop_instances is None:
+        loop_instances = {}
+        AsyncTransportWithLogger._instances[loop] = loop_instances
+
+    key: TransportKey = config.proxy
+    transport = loop_instances.get(key)
+    if transport is None:
+        transport = AsyncTransportWithLogger(
+            limits=limits,
+            proxy=config.proxy,
+        )
+        loop_instances[key] = transport
+
+    return transport

loopix/volume/client_sync/__init__.py

@@ -0,0 +1,80 @@
+import os
+import threading
+from typing import Dict, Optional
+
+import httpx
+from httpx import Limits
+from httpx._types import ProxyTypes
+
+from loopix.api import make_logging_event_hooks
+from loopix.api.metadata import default_headers
+from loopix.exceptions import AuthenticationException
+from loopix.volume.client.client import AuthenticatedClient as VolumeApiClient
+from loopix.volume.connection_config import VolumeConnectionConfig
+
+limits = Limits(
+    max_keepalive_connections=int(os.getenv("LOOPIX_MAX_KEEPALIVE_CONNECTIONS", "20")),
+    max_connections=int(os.getenv("LOOPIX_MAX_CONNECTIONS", "2000")),
+    keepalive_expiry=int(os.getenv("LOOPIX_KEEPALIVE_EXPIRY", "300")),
+)
+
+TransportKey = Optional[ProxyTypes]
+
+
+def get_api_client(config: VolumeConnectionConfig, **kwargs) -> VolumeApiClient:
+    if config.access_token is None:
+        raise AuthenticationException(
+            "Volume token is required for volume content operations. "
+            "Use `Volume.create`/`Volume.connect` to obtain it "
+            "or pass `token` in options.",
+        )
+
+    headers = {
+        **default_headers,
+        **(config.headers or {}),
+    }
+
+    request_timeout = config.request_timeout
+
+    return VolumeApiClient(
+        base_url=config.api_url,
+        token=config.access_token,
+        auth_header_name="Authorization",
+        prefix="Bearer",
+        headers=headers,
+        timeout=(
+            httpx.Timeout(request_timeout) if request_timeout is not None else None
+        ),
+        httpx_args={
+            "proxy": config.proxy,
+            "transport": get_transport(config),
+            "event_hooks": make_logging_event_hooks(config.logger),
+        },
+        **kwargs,
+    )
+
+
+class TransportWithLogger(httpx.HTTPTransport):
+    _thread_local = threading.local()
+
+    @property
+    def pool(self):
+        return self._pool
+
+
+def get_transport(config: VolumeConnectionConfig) -> TransportWithLogger:
+    instances: Dict[TransportKey, TransportWithLogger] = getattr(
+        TransportWithLogger._thread_local, "instances", {}
+    )
+    key: TransportKey = config.proxy
+    cached = instances.get(key)
+    if cached is not None:
+        return cached
+
+    transport = TransportWithLogger(
+        limits=limits,
+        proxy=config.proxy,
+    )
+    instances[key] = transport
+    TransportWithLogger._thread_local.instances = instances
+    return transport

loopix/volume/connection_config.py

@@ -0,0 +1,145 @@
+import logging
+import os
+
+from typing import Dict, Optional, TypedDict
+
+from httpx._types import ProxyTypes
+from typing_extensions import Unpack
+
+from loopix.api.metadata import package_version
+
+REQUEST_TIMEOUT: float = 60.0  # 60 seconds
+
+# Timeout for volume file transfers, which stream large bodies and so must not
+# inherit the short REQUEST_TIMEOUT. (Sandbox filesystem streaming instead
+# bounds each chunk by the request timeout and leaves the total to the server.)
+FILE_TIMEOUT: float = 3600.0  # 1 hour
+
+
+class VolumeApiParams(TypedDict, total=False):
+    """
+    Parameters for requests made to the volume content API.
+    """
+
+    domain: Optional[str]
+    """Domain to use for the volume API, defaults to `LOOPIX_DOMAIN` or `vm.betmandu.net`."""
+
+    debug: Optional[bool]
+    """Whether to use debug mode, defaults to `LOOPIX_DEBUG` environment variable."""
+
+    request_timeout: Optional[float]
+    """Timeout for the request in **seconds**, defaults to 60 seconds."""
+
+    headers: Optional[Dict[str, str]]
+    """Additional headers to send with the request."""
+
+    token: Optional[str]
+    """Volume auth token used for `Authorization: Bearer <token>`."""
+
+    api_url: Optional[str]
+    """URL to use for the volume API, defaults to `LOOPIX_VOLUME_API_URL` or `https://<domain>/api`."""
+
+    proxy: Optional[ProxyTypes]
+    """Proxy to use for the request."""
+
+    logger: Optional[logging.Logger]
+    """Logger used for request and response logging. Accepts a standard library `logging.Logger`."""
+
+
+class VolumeConnectionConfig:
+    """
+    Configuration for the volume content API.
+
+    Uses bearer token authentication and defaults to the volume content host.
+    """
+
+    @staticmethod
+    def _domain():
+        return os.getenv("LOOPIX_DOMAIN") or "vm.betmandu.net"
+
+    @staticmethod
+    def _debug():
+        return os.getenv("LOOPIX_DEBUG", "false").lower() == "true"
+
+    @staticmethod
+    def _volume_api_url():
+        return os.getenv("LOOPIX_VOLUME_API_URL")
+
+    @staticmethod
+    def _get_request_timeout(
+        default_timeout: Optional[float],
+        request_timeout: Optional[float],
+    ):
+        if request_timeout == 0:
+            return None
+        elif request_timeout is not None:
+            return request_timeout
+        else:
+            return default_timeout
+
+    def __init__(
+        self,
+        domain: Optional[str] = None,
+        debug: Optional[bool] = None,
+        token: Optional[str] = None,
+        api_url: Optional[str] = None,
+        request_timeout: Optional[float] = None,
+        headers: Optional[Dict[str, str]] = None,
+        proxy: Optional[ProxyTypes] = None,
+        logger: Optional[logging.Logger] = None,
+    ):
+        self.logger = logger
+        self.domain = domain or self._domain()
+        self.debug = debug if debug is not None else self._debug()
+
+        self.api_url = (
+            api_url
+            or self._volume_api_url()
+            or ("http://localhost:8080" if self.debug else f"https://{self.domain}/api")
+        )
+        self.access_token = token
+        self.token = self.access_token
+        self.proxy = proxy
+
+        self.headers = dict(headers) if headers else {}
+        self.headers["User-Agent"] = f"loopix-python-sdk/{package_version}"
+
+        self.request_timeout = self._get_request_timeout(
+            REQUEST_TIMEOUT, request_timeout
+        )
+
+    def get_request_timeout(self, request_timeout: Optional[float] = None):
+        return self._get_request_timeout(self.request_timeout, request_timeout)
+
+    def get_api_params(
+        self,
+        **opts: Unpack[VolumeApiParams],
+    ) -> dict:
+        """
+        Get request parameters for the volume content API.
+        """
+        domain = opts.get("domain")
+        debug = opts.get("debug")
+        headers = opts.get("headers")
+        request_timeout = opts.get("request_timeout")
+        token = opts.get("token")
+        api_url = opts.get("api_url")
+        proxy = opts.get("proxy")
+        logger = opts.get("logger")
+
+        req_headers = self.headers.copy()
+        if headers is not None:
+            req_headers.update(headers)
+
+        return dict(
+            VolumeApiParams(
+                domain=domain if domain is not None else self.domain,
+                debug=debug if debug is not None else self.debug,
+                token=token if token is not None else self.token,
+                api_url=api_url if api_url is not None else self.api_url,
+                request_timeout=self.get_request_timeout(request_timeout),
+                headers=req_headers,
+                proxy=proxy if proxy is not None else self.proxy,
+                logger=logger if logger is not None else self.logger,
+            )
+        )

loopix/volume/types.py

@@ -0,0 +1,62 @@
+import datetime
+from dataclasses import dataclass
+from typing import Optional
+
+from loopix.volume.client.models.volume_entry_stat_type import VolumeEntryStatType
+
+# Type alias for file type enum
+VolumeFileType = VolumeEntryStatType
+
+
+@dataclass
+class VolumeInfo:
+    """Information about a volume."""
+
+    volume_id: str
+    """Volume ID."""
+    name: str
+    """Volume name."""
+
+
+@dataclass
+class VolumeAndToken(VolumeInfo):
+    """Information about a volume and its auth token."""
+
+    token: str
+    """Volume auth token."""
+
+
+@dataclass
+class VolumeEntryStat:
+    """Volume entry stat information."""
+
+    name: str
+    """Name of the filesystem object."""
+    type: VolumeFileType
+    """Type of the filesystem object."""
+    path: str
+    """Path to the filesystem object."""
+    size: int
+    """Size of the filesystem object."""
+    mode: int
+    """Mode of the filesystem object."""
+    uid: int
+    """User ID of the filesystem object."""
+    gid: int
+    """Group ID of the filesystem object."""
+    atime: datetime.datetime
+    """Access time."""
+    mtime: datetime.datetime
+    """Modification time."""
+    ctime: datetime.datetime
+    """Creation time."""
+    target: Optional[str] = None
+    """Target path for symlinks."""
+
+
+__all__ = [
+    "VolumeInfo",
+    "VolumeAndToken",
+    "VolumeEntryStat",
+    "VolumeFileType",
+]

loopix/volume/utils.py

@@ -0,0 +1,52 @@
+import datetime
+from typing import Optional
+
+from loopix.volume.client.models import VolumeEntryStat as VolumeEntryStatApi
+from loopix.volume.client.types import UNSET
+from loopix.volume.types import VolumeEntryStat
+
+
+def _ensure_utc(dt: datetime.datetime) -> datetime.datetime:
+    """Mark a timezone-naive datetime as UTC (API timestamps are UTC)."""
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=datetime.timezone.utc)
+    return dt
+
+
+def convert_volume_entry_stat(api_stat: VolumeEntryStatApi) -> VolumeEntryStat:
+    """Convert API VolumeEntryStat to SDK VolumeEntryStat."""
+    target: Optional[str] = None
+    if api_stat.target is not UNSET and api_stat.target is not None:
+        target = str(api_stat.target)
+
+    return VolumeEntryStat(
+        name=api_stat.name,
+        type=api_stat.type_,
+        path=api_stat.path,
+        size=api_stat.size,
+        mode=api_stat.mode,
+        uid=api_stat.uid,
+        gid=api_stat.gid,
+        atime=_ensure_utc(api_stat.atime),
+        mtime=_ensure_utc(api_stat.mtime),
+        ctime=_ensure_utc(api_stat.ctime),
+        target=target,
+    )
+
+
+class DualMethod:
+    """Descriptor enabling the same name for a static (class-level) and instance method.
+
+    When accessed on the class (e.g. ``Volume.get_info``), the static function
+    is returned.  When accessed on an instance (e.g. ``vol.get_info``), the
+    instance method is returned as a bound method.
+    """
+
+    def __init__(self, static_fn, instance_fn):
+        self._static_fn = static_fn
+        self._instance_fn = instance_fn
+
+    def __get__(self, obj, objtype=None):
+        if obj is None:
+            return self._static_fn
+        return self._instance_fn.__get__(obj, objtype)