spatialflow 0.1.0__py3-none-any.whl

spatialflow/_generated/spatialflow_generated/rest.py

@@ -0,0 +1,215 @@
+# coding: utf-8
+
+"""
+    SpatialFlow API
+
+    Real-time geospatial automation platform API.  ## Authentication  **API Key:** Include `X-API-Key` header **JWT Token:** Include `Authorization: Bearer <token>` header  ## Rate Limits  - Per API Key: 200 rps sustained, 1,000 rps burst - Per Organization: 1,000 rps aggregate  ## Webhook Verification  Outbound webhooks include HMAC-SHA256 signatures in `X-SF-Signature` header.  ## Support  - Documentation: https://docs.spatialflow.io - GitHub: https://github.com/spatialflow/spatialflow - Email: support@spatialflow.io     
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+import io
+import json
+import re
+import ssl
+from typing import Optional, Union
+
+import aiohttp
+import aiohttp_retry
+
+from .exceptions import ApiException, ApiValueError
+
+RESTResponseType = aiohttp.ClientResponse
+
+ALLOW_RETRY_METHODS = frozenset({'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PUT', 'TRACE'})
+
+class RESTResponse(io.IOBase):
+
+    def __init__(self, resp) -> None:
+        self.response = resp
+        self.status = resp.status
+        self.reason = resp.reason
+        self.data = None
+
+    async def read(self):
+        if self.data is None:
+            self.data = await self.response.read()
+        return self.data
+
+    def getheaders(self):
+        """Returns a CIMultiDictProxy of the response headers."""
+        return self.response.headers
+
+    def getheader(self, name, default=None):
+        """Returns a given response header."""
+        return self.response.headers.get(name, default)
+
+
+class RESTClientObject:
+
+    def __init__(self, configuration) -> None:
+
+        # maxsize is number of requests to host that are allowed in parallel
+        maxsize = configuration.connection_pool_maxsize
+
+        ssl_context = ssl.create_default_context(
+            cafile=configuration.ssl_ca_cert
+        )
+        if configuration.cert_file:
+            ssl_context.load_cert_chain(
+                configuration.cert_file, keyfile=configuration.key_file
+            )
+
+        if not configuration.verify_ssl:
+            ssl_context.check_hostname = False
+            ssl_context.verify_mode = ssl.CERT_NONE
+
+        connector = aiohttp.TCPConnector(
+            limit=maxsize,
+            ssl=ssl_context
+        )
+
+        self.proxy = configuration.proxy
+        self.proxy_headers = configuration.proxy_headers
+
+        # https pool manager
+        self.pool_manager = aiohttp.ClientSession(
+            connector=connector,
+            trust_env=True
+        )
+
+        retries = configuration.retries
+        self.retry_client: Optional[aiohttp_retry.RetryClient]
+        if retries is not None:
+            self.retry_client = aiohttp_retry.RetryClient(
+                client_session=self.pool_manager,
+                retry_options=aiohttp_retry.ExponentialRetry(
+                    attempts=retries,
+                    factor=2.0,
+                    start_timeout=0.1,
+                    max_timeout=120.0
+                )
+            )
+        else:
+            self.retry_client = None
+
+    async def close(self):
+        await self.pool_manager.close()
+        if self.retry_client is not None:
+            await self.retry_client.close()
+
+    async def request(
+        self,
+        method,
+        url,
+        headers=None,
+        body=None,
+        post_params=None,
+        _request_timeout=None
+    ):
+        """Execute request
+
+        :param method: http request method
+        :param url: http request url
+        :param headers: http request headers
+        :param body: request json body, for `application/json`
+        :param post_params: request post parameters,
+                            `application/x-www-form-urlencoded`
+                            and `multipart/form-data`
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        """
+        method = method.upper()
+        assert method in [
+            'GET',
+            'HEAD',
+            'DELETE',
+            'POST',
+            'PUT',
+            'PATCH',
+            'OPTIONS'
+        ]
+
+        if post_params and body:
+            raise ApiValueError(
+                "body parameter cannot be used with post_params parameter."
+            )
+
+        post_params = post_params or {}
+        headers = headers or {}
+        # url already contains the URL query string
+        timeout = _request_timeout or 5 * 60
+
+        if 'Content-Type' not in headers:
+            headers['Content-Type'] = 'application/json'
+
+        args = {
+            "method": method,
+            "url": url,
+            "timeout": timeout,
+            "headers": headers
+        }
+
+        if self.proxy:
+            args["proxy"] = self.proxy
+        if self.proxy_headers:
+            args["proxy_headers"] = self.proxy_headers
+
+        # For `POST`, `PUT`, `PATCH`, `OPTIONS`, `DELETE`
+        if method in ['POST', 'PUT', 'PATCH', 'OPTIONS', 'DELETE']:
+            if re.search('json', headers['Content-Type'], re.IGNORECASE):
+                if body is not None:
+                    body = json.dumps(body)
+                args["data"] = body
+            elif headers['Content-Type'] == 'application/x-www-form-urlencoded':
+                args["data"] = aiohttp.FormData(post_params)
+            elif headers['Content-Type'] == 'multipart/form-data':
+                # must del headers['Content-Type'], or the correct
+                # Content-Type which generated by aiohttp
+                del headers['Content-Type']
+                data = aiohttp.FormData()
+                for param in post_params:
+                    k, v = param
+                    if isinstance(v, tuple) and len(v) == 3:
+                        data.add_field(
+                            k,
+                            value=v[1],
+                            filename=v[0],
+                            content_type=v[2]
+                        )
+                    else:
+                        # Ensures that dict objects are serialized
+                        if isinstance(v, dict):
+                            v = json.dumps(v)
+                        elif isinstance(v, int):
+                            v = str(v)
+                        data.add_field(k, v)
+                args["data"] = data
+
+            # Pass a `bytes` or `str` parameter directly in the body to support
+            # other content types than Json when `body` argument is provided
+            # in serialized form
+            elif isinstance(body, str) or isinstance(body, bytes):
+                args["data"] = body
+            else:
+                # Cannot generate the request from given parameters
+                msg = """Cannot prepare a request message for provided
+                         arguments. Please check that your arguments match
+                         declared content type."""
+                raise ApiException(status=0, reason=msg)
+
+        pool_manager: Union[aiohttp.ClientSession, aiohttp_retry.RetryClient]
+        if self.retry_client is not None and method in ALLOW_RETRY_METHODS:
+            pool_manager = self.retry_client
+        else:
+            pool_manager = self.pool_manager
+
+        r = await pool_manager.request(**args)
+
+        return RESTResponse(r)

spatialflow/_generated/test-requirements.txt

@@ -0,0 +1,6 @@
+pytest >= 7.2.1
+pytest-cov >= 2.8.1
+tox >= 3.9.0
+flake8 >= 4.0.0
+types-python-dateutil >= 2.8.19.14
+mypy >= 1.5

spatialflow/_generated/tox.ini

@@ -0,0 +1,9 @@
+[tox]
+envlist = py3
+
+[testenv]
+deps=-r{toxinidir}/requirements.txt
+     -r{toxinidir}/test-requirements.txt
+
+commands=
+   pytest --cov=spatialflow_generated

spatialflow/client.py

@@ -0,0 +1,137 @@
+"""
+SpatialFlow Python SDK Client
+
+The main entry point for the SpatialFlow API.
+"""
+
+from typing import Optional
+
+# Import from the generated package using relative imports
+# The generated code now uses relative imports internally
+from ._generated.spatialflow_generated.api_client import ApiClient
+from ._generated.spatialflow_generated.configuration import Configuration
+from ._generated.spatialflow_generated.api.geofences_api import GeofencesApi
+from ._generated.spatialflow_generated.api.workflows_api import WorkflowsApi
+from ._generated.spatialflow_generated.api.webhooks_api import WebhooksApi
+from ._generated.spatialflow_generated.api.devices_api import DevicesApi
+from ._generated.spatialflow_generated.api.account_api import AccountApi
+
+__all__ = ["SpatialFlow"]
+
+# Host only - generated paths include /api/v1 prefix
+DEFAULT_BASE_URL = "https://api.spatialflow.io"
+DEFAULT_TIMEOUT = 30  # seconds
+DEFAULT_MAX_RETRIES = 3
+VERSION = "0.1.0"
+
+
+class SpatialFlow:
+    """
+    SpatialFlow API client.
+
+    Provides access to geofences, workflows, webhooks, and devices.
+
+    Example:
+        >>> client = SpatialFlow(api_key="sf_xxx")
+        >>> geofences = await client.geofences.apps_geofences_api_list_geofences()
+
+    Args:
+        api_key: SpatialFlow API key (starts with "sf_")
+        access_token: JWT access token (alternative to api_key)
+        base_url: API base URL (default: https://api.spatialflow.io)
+        timeout: Request timeout in seconds (default: 30)
+        max_retries: Maximum retry attempts for failed requests (default: 3)
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        access_token: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        if not api_key and not access_token:
+            raise ValueError("Either api_key or access_token must be provided")
+
+        if api_key and access_token:
+            raise ValueError("Provide either api_key or access_token, not both")
+
+        # Build configuration
+        config = Configuration(host=base_url)
+
+        # Configure authentication
+        if api_key:
+            config.api_key = {"APIKeyBearer": api_key}
+        elif access_token:
+            config.access_token = access_token
+
+        # Configure timeouts and retries
+        config.retries = max_retries
+
+        # Create API client
+        self._api_client = ApiClient(configuration=config)
+
+        # Set User-Agent
+        self._api_client.user_agent = f"spatialflow-python/{VERSION}"
+
+        # Store config for reference
+        self._base_url = base_url
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+        # Initialize resource APIs (lazy initialization)
+        self._geofences: Optional[GeofencesApi] = None
+        self._workflows: Optional[WorkflowsApi] = None
+        self._webhooks: Optional[WebhooksApi] = None
+        self._devices: Optional[DevicesApi] = None
+        self._account: Optional[AccountApi] = None
+
+    @property
+    def geofences(self) -> GeofencesApi:
+        """Access geofence operations."""
+        if self._geofences is None:
+            self._geofences = GeofencesApi(self._api_client)
+        return self._geofences
+
+    @property
+    def workflows(self) -> WorkflowsApi:
+        """Access workflow operations."""
+        if self._workflows is None:
+            self._workflows = WorkflowsApi(self._api_client)
+        return self._workflows
+
+    @property
+    def webhooks(self) -> WebhooksApi:
+        """Access webhook operations."""
+        if self._webhooks is None:
+            self._webhooks = WebhooksApi(self._api_client)
+        return self._webhooks
+
+    @property
+    def devices(self) -> DevicesApi:
+        """Access device operations."""
+        if self._devices is None:
+            self._devices = DevicesApi(self._api_client)
+        return self._devices
+
+    @property
+    def account(self) -> AccountApi:
+        """Access account operations."""
+        if self._account is None:
+            self._account = AccountApi(self._api_client)
+        return self._account
+
+    async def close(self) -> None:
+        """Close the API client and release resources."""
+        if self._api_client:
+            await self._api_client.close()
+
+    async def __aenter__(self) -> "SpatialFlow":
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Async context manager exit."""
+        await self.close()

spatialflow/exceptions.py

@@ -0,0 +1,234 @@
+"""
+SpatialFlow SDK Exceptions
+
+Provides a clean exception hierarchy for handling API errors.
+These wrap the generated exceptions with more user-friendly interfaces.
+"""
+
+from typing import Any, Optional
+
+
+class SpatialFlowError(Exception):
+    """Base exception for all SpatialFlow SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        detail: Optional[str] = None,
+        error_code: Optional[str] = None,
+        headers: Optional[dict[str, str]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.detail = detail
+        self.error_code = error_code
+        self.headers = headers or {}
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.status_code:
+            parts.insert(0, f"[{self.status_code}]")
+        if self.detail and self.detail != self.message:
+            parts.append(f"- {self.detail}")
+        return " ".join(parts)
+
+
+class AuthenticationError(SpatialFlowError):
+    """
+    Raised when authentication fails (401 Unauthorized).
+
+    This typically means:
+    - API key is invalid or expired
+    - JWT token is invalid or expired
+    - No authentication credentials provided
+    """
+
+    pass
+
+
+class PermissionError(SpatialFlowError):
+    """
+    Raised when the authenticated user lacks permission (403 Forbidden).
+
+    This typically means:
+    - User doesn't have access to this resource
+    - API key doesn't have the required scope
+    - Organization limits exceeded
+    """
+
+    pass
+
+
+class NotFoundError(SpatialFlowError):
+    """
+    Raised when a resource is not found (404 Not Found).
+
+    Check that:
+    - The resource ID is correct
+    - The resource hasn't been deleted
+    - You have access to the resource
+    """
+
+    pass
+
+
+class ValidationError(SpatialFlowError):
+    """
+    Raised when request validation fails (400 Bad Request or 422 Unprocessable Entity).
+
+    Check that:
+    - Required fields are provided
+    - Field values match expected types/formats
+    - Geometry is valid GeoJSON
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        detail: Optional[str] = None,
+        error_code: Optional[str] = None,
+        headers: Optional[dict[str, str]] = None,
+        errors: Optional[list[dict[str, Any]]] = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            detail=detail,
+            error_code=error_code,
+            headers=headers,
+        )
+        self.errors = errors or []
+
+
+class RateLimitError(SpatialFlowError):
+    """
+    Raised when rate limit is exceeded (429 Too Many Requests).
+
+    The `retry_after` property indicates when you can retry.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int = 429,
+        detail: Optional[str] = None,
+        error_code: Optional[str] = None,
+        headers: Optional[dict[str, str]] = None,
+        retry_after: Optional[int] = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            detail=detail,
+            error_code=error_code,
+            headers=headers,
+        )
+        self.retry_after = retry_after or self._parse_retry_after(headers)
+
+    def _parse_retry_after(self, headers: Optional[dict[str, str]]) -> Optional[int]:
+        if not headers:
+            return None
+        retry_after = headers.get("Retry-After") or headers.get("retry-after")
+        if retry_after:
+            try:
+                return int(retry_after)
+            except ValueError:
+                pass
+        return None
+
+
+class ServerError(SpatialFlowError):
+    """
+    Raised when the server encounters an error (5xx status codes).
+
+    This is typically a temporary issue. Retry with exponential backoff.
+    """
+
+    pass
+
+
+class ConflictError(SpatialFlowError):
+    """
+    Raised when there's a resource conflict (409 Conflict).
+
+    This typically means:
+    - Resource already exists with that name/identifier
+    - Concurrent modification conflict
+    """
+
+    pass
+
+
+class TimeoutError(SpatialFlowError):
+    """Raised when a request times out."""
+
+    pass
+
+
+class ConnectionError(SpatialFlowError):
+    """Raised when unable to connect to the API."""
+
+    pass
+
+
+def raise_for_status(
+    status_code: int,
+    message: str = "API request failed",
+    *,
+    detail: Optional[str] = None,
+    error_code: Optional[str] = None,
+    headers: Optional[dict[str, str]] = None,
+    body: Optional[Any] = None,
+) -> None:
+    """
+    Raise the appropriate exception based on HTTP status code.
+
+    Args:
+        status_code: HTTP status code
+        message: Error message
+        detail: Additional error detail
+        error_code: Machine-readable error code
+        headers: Response headers
+        body: Response body (for extracting validation errors)
+    """
+    # Extract detail from body if not provided
+    if body and not detail:
+        if isinstance(body, dict):
+            detail = body.get("detail")
+            if isinstance(detail, list):
+                # Django Ninja validation error format
+                detail = "; ".join(str(e) for e in detail)
+            error_code = error_code or body.get("error_code")
+
+    kwargs = {
+        "status_code": status_code,
+        "detail": detail,
+        "error_code": error_code,
+        "headers": headers,
+    }
+
+    if status_code == 400 or status_code == 422:
+        errors = []
+        if isinstance(body, dict) and isinstance(body.get("detail"), list):
+            errors = body["detail"]
+        raise ValidationError(message, errors=errors, **kwargs)
+    elif status_code == 401:
+        raise AuthenticationError(message, **kwargs)
+    elif status_code == 403:
+        raise PermissionError(message, **kwargs)
+    elif status_code == 404:
+        raise NotFoundError(message, **kwargs)
+    elif status_code == 409:
+        raise ConflictError(message, **kwargs)
+    elif status_code == 429:
+        raise RateLimitError(message, **kwargs)
+    elif 500 <= status_code < 600:
+        raise ServerError(message, **kwargs)
+    elif status_code >= 400:
+        raise SpatialFlowError(message, **kwargs)