pymlsapi 0.1.0__py3-none-any.whl

pymlsapi/__init__.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from pymlsapi.async_client import AsyncMLS, AsyncMlsApiClient
+from pymlsapi.client import MLS, MlsApiClient
+from pymlsapi.config import ClientConfig
+from pymlsapi.errors import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidRequestError,
+    JobTimeoutError,
+    MlsApiError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    StudioJobFailedError,
+)
+from pymlsapi.models import (
+    AdCreativesResult,
+    Address,
+    ArchitecturalRenderResult,
+    BaseListing,
+    ContentGenerationResponse,
+    Coordinates,
+    CustomStudioResult,
+    DeclutterResult,
+    DeStageEmptyResult,
+    ExteriorEnhanceResult,
+    FloorPlanAnalysisResponse,
+    HouseTourResult,
+    IngestJob,
+    InteriorStyle,
+    JobStatus,
+    PropertyIntelligence,
+    PropertySpecifications,
+    Render3dResult,
+    ReplaceFurnitureResult,
+    ReplaceMaterialResult,
+    RestyleResult,
+    RoomType,
+    SocialPlatform,
+    SocialPublishResult,
+    StagingResult,
+    StudioJob,
+    TwilightResult,
+    UploadResult,
+    UpscaleResult,
+    VideoEnhanceResult,
+    VideoTransitionResult,
+    VideoWalkthroughResult,
+    WallColorsResult,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MLS",
+    "AdCreativesResult",
+    "Address",
+    "ArchitecturalRenderResult",
+    "AsyncMLS",
+    "AsyncMlsApiClient",
+    "AuthenticationError",
+    "BaseListing",
+    "ClientConfig",
+    "ContentGenerationResponse",
+    "Coordinates",
+    "CustomStudioResult",
+    "DeStageEmptyResult",
+    "DeclutterResult",
+    "ExteriorEnhanceResult",
+    "FloorPlanAnalysisResponse",
+    "HouseTourResult",
+    "IngestJob",
+    "InsufficientCreditsError",
+    "InteriorStyle",
+    "InvalidRequestError",
+    "JobStatus",
+    "JobTimeoutError",
+    "MlsApiClient",
+    "MlsApiError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "PropertyIntelligence",
+    "PropertySpecifications",
+    "RateLimitError",
+    "Render3dResult",
+    "ReplaceFurnitureResult",
+    "ReplaceMaterialResult",
+    "RestyleResult",
+    "RoomType",
+    "SocialPlatform",
+    "SocialPublishResult",
+    "StagingResult",
+    "StudioJob",
+    "StudioJobFailedError",
+    "TwilightResult",
+    "UploadResult",
+    "UpscaleResult",
+    "VideoEnhanceResult",
+    "VideoTransitionResult",
+    "VideoWalkthroughResult",
+    "WallColorsResult",
+]

pymlsapi/async_client.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.config import (
+    DEFAULT_JOB_TIMEOUT_SECONDS,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_POLL_INTERVAL_SECONDS,
+    DEFAULT_TIMEOUT_SECONDS,
+    ClientConfig,
+)
+from pymlsapi.resources.account import AsyncAccountResource
+from pymlsapi.resources.content import AsyncContentResource
+from pymlsapi.resources.intelligence import AsyncIntelligenceResource
+from pymlsapi.resources.listings import AsyncListingsResource
+from pymlsapi.resources.studio import AsyncStudioResource
+
+
+class AsyncMlsApiClient:
+    """Official asynchronous Python client for mlsapi.dev.
+
+    High-concurrency asyncio client for real-time MLS listings, property intelligence,
+    marketing copy, and the complete suite of Studio Visual AI generative tools.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        environment: str = "live",
+        base_url: Optional[str] = None,
+        timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        poll_interval: float = DEFAULT_POLL_INTERVAL_SECONDS,
+        job_timeout_seconds: float = DEFAULT_JOB_TIMEOUT_SECONDS,
+    ) -> None:
+        self.config = ClientConfig.create(
+            api_key=api_key,
+            environment=environment,
+            base_url=base_url,
+            timeout_seconds=timeout_seconds,
+            max_retries=max_retries,
+            poll_interval=poll_interval,
+            job_timeout_seconds=job_timeout_seconds,
+        )
+        self._http = AsyncHttpClient(self.config)
+
+        # Namespaced resources
+        self.listings = AsyncListingsResource(self._http)
+        self.intelligence = AsyncIntelligenceResource(self._http)
+        self.content = AsyncContentResource(self._http)
+        self.studio = AsyncStudioResource(self._http)
+        self.account = AsyncAccountResource(self._http)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client transport."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncMlsApiClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+
+# Convenient alias
+AsyncMLS = AsyncMlsApiClient

pymlsapi/async_http.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import asyncio
+import random
+from typing import Any, Dict, Optional
+
+import httpx
+
+from pymlsapi.config import ClientConfig
+from pymlsapi.errors import MlsApiError
+from pymlsapi.http import _handle_error_response
+
+
+class AsyncHttpClient:
+    """Asynchronous HTTP transport engine with automatic retries and exponential backoff."""
+
+    def __init__(self, config: ClientConfig) -> None:
+        self.config = config
+        headers = {
+            "Authorization": f"Bearer {config.api_key}",
+            "x-api-key": config.api_key,
+            "User-Agent": "pymlsapi/0.1.0",
+            "Accept": "application/json",
+        }
+        self._client = httpx.AsyncClient(
+            base_url=config.base_url,
+            headers=headers,
+            timeout=config.timeout_seconds,
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncHttpClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Any] = None,
+        files: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = path if path.startswith("http") else path.lstrip("/")
+        attempts = 0
+        max_retries = self.config.max_retries
+
+        while True:
+            attempts += 1
+            try:
+                response = await self._client.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    json=json,
+                    files=files,
+                    data=data,
+                )
+
+                if response.status_code in (429, 500, 502, 503, 504) and attempts <= max_retries:
+                    backoff = (2 ** (attempts - 1)) * 0.5 + random.uniform(0.1, 0.4)
+                    await asyncio.sleep(backoff)
+                    continue
+
+                if response.is_error:
+                    _handle_error_response(response)
+
+                if response.status_code == 204:
+                    return None
+
+                return response.json()
+
+            except (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout) as exc:
+                if attempts <= max_retries:
+                    backoff = (2 ** (attempts - 1)) * 0.5 + random.uniform(0.1, 0.4)
+                    await asyncio.sleep(backoff)
+                    continue
+                raise MlsApiError(f"Network error during {method} {url}: {exc}") from exc
+
+    async def get(self, path: str, *, params: Optional[Dict[str, Any]] = None) -> Any:
+        return await self.request("GET", path, params=params)
+
+    async def post(
+        self,
+        path: str,
+        *,
+        json: Optional[Any] = None,
+        files: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        return await self.request("POST", path, json=json, files=files, data=data, params=params)
+
+    async def put(self, path: str, *, json: Optional[Any] = None) -> Any:
+        return await self.request("PUT", path, json=json)
+
+    async def delete(self, path: str, *, params: Optional[Dict[str, Any]] = None) -> Any:
+        return await self.request("DELETE", path, params=params)

pymlsapi/client.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from pymlsapi.config import (
+    DEFAULT_JOB_TIMEOUT_SECONDS,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_POLL_INTERVAL_SECONDS,
+    DEFAULT_TIMEOUT_SECONDS,
+    ClientConfig,
+)
+from pymlsapi.http import HttpClient
+from pymlsapi.resources.account import AccountResource
+from pymlsapi.resources.content import ContentResource
+from pymlsapi.resources.intelligence import IntelligenceResource
+from pymlsapi.resources.listings import ListingsResource
+from pymlsapi.resources.studio import StudioResource
+
+
+class MlsApiClient:
+    """Official synchronous Python client for mlsapi.dev.
+
+    Access real-time MLS listings, property intelligence, marketing copy,
+    and the complete suite of Studio Visual AI generative tools.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        environment: str = "live",
+        base_url: Optional[str] = None,
+        timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        poll_interval: float = DEFAULT_POLL_INTERVAL_SECONDS,
+        job_timeout_seconds: float = DEFAULT_JOB_TIMEOUT_SECONDS,
+    ) -> None:
+        self.config = ClientConfig.create(
+            api_key=api_key,
+            environment=environment,
+            base_url=base_url,
+            timeout_seconds=timeout_seconds,
+            max_retries=max_retries,
+            poll_interval=poll_interval,
+            job_timeout_seconds=job_timeout_seconds,
+        )
+        self._http = HttpClient(self.config)
+
+        # Namespaced resources
+        self.listings = ListingsResource(self._http)
+        self.intelligence = IntelligenceResource(self._http)
+        self.content = ContentResource(self._http)
+        self.studio = StudioResource(self._http)
+        self.account = AccountResource(self._http)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client transport."""
+        self._http.close()
+
+    def __enter__(self) -> MlsApiClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+# Convenient alias
+MLS = MlsApiClient

pymlsapi/config.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+DEFAULT_LIVE_URL = "https://mlsapi.dev"
+DEFAULT_TEST_URL = "https://api.mlsapi.dev"
+DEFAULT_TIMEOUT_SECONDS = 60.0
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_POLL_INTERVAL_SECONDS = 2.0
+DEFAULT_JOB_TIMEOUT_SECONDS = 90.0
+
+
+@dataclass
+class ClientConfig:
+    """Configuration options for the MLS API Client."""
+
+    api_key: str
+    environment: str = "live"
+    base_url: str = DEFAULT_LIVE_URL
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS
+    max_retries: int = DEFAULT_MAX_RETRIES
+    poll_interval: float = DEFAULT_POLL_INTERVAL_SECONDS
+    job_timeout_seconds: float = DEFAULT_JOB_TIMEOUT_SECONDS
+
+    @classmethod
+    def create(
+        cls,
+        api_key: Optional[str] = None,
+        environment: str = "live",
+        base_url: Optional[str] = None,
+        timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        poll_interval: float = DEFAULT_POLL_INTERVAL_SECONDS,
+        job_timeout_seconds: float = DEFAULT_JOB_TIMEOUT_SECONDS,
+    ) -> ClientConfig:
+        resolved_key = api_key or os.environ.get("MLSAPI_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "MLS API key is required. Pass `api_key` to client or set MLSAPI_KEY environment variable."
+            )
+
+        if base_url is None:
+            base_url = DEFAULT_LIVE_URL if environment == "live" else DEFAULT_TEST_URL
+
+        # Strip trailing slashes
+        base_url = base_url.rstrip("/")
+
+        return cls(
+            api_key=resolved_key,
+            environment=environment,
+            base_url=base_url,
+            timeout_seconds=timeout_seconds,
+            max_retries=max_retries,
+            poll_interval=poll_interval,
+            job_timeout_seconds=job_timeout_seconds,
+        )

pymlsapi/errors.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class MlsApiError(Exception):
+    """Base exception for all mlsapi.dev SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+        raw_response: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code or "UNKNOWN_ERROR"
+        self.raw_response = raw_response
+
+    def __str__(self) -> str:
+        parts = []
+        if self.status_code:
+            parts.append(f"HTTP {self.status_code}")
+        if self.code and self.code != "UNKNOWN_ERROR":
+            parts.append(f"[{self.code}]")
+        parts.append(self.message)
+        return " - ".join(parts)
+
+
+class AuthenticationError(MlsApiError):
+    """Raised on HTTP 401 when the provided API key is invalid, missing, or revoked."""
+
+
+class PermissionDeniedError(MlsApiError):
+    """Raised on HTTP 403 when the API key lacks necessary permissions or plan tier."""
+
+
+class NotFoundError(MlsApiError):
+    """Raised on HTTP 404 when the requested MLS listing, job, or resource is not found."""
+
+
+class InvalidRequestError(MlsApiError):
+    """Raised on HTTP 400 when request parameters are malformed or missing."""
+
+
+class InsufficientCreditsError(MlsApiError):
+    """Raised on HTTP 402 when workspace credit balance is insufficient for the requested action."""
+
+
+class RateLimitError(MlsApiError):
+    """Raised on HTTP 429 when concurrency or rate limits have been exceeded."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 429,
+        code: str = "RATE_LIMIT_EXCEEDED",
+        retry_after_seconds: Optional[float] = None,
+        raw_response: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message, status_code, code, raw_response)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class StudioJobFailedError(MlsApiError):
+    """Raised when an asynchronous Studio AI job completes with a failed status."""
+
+    def __init__(
+        self,
+        job_id: str,
+        message: str,
+        error_details: Optional[Any] = None,
+    ) -> None:
+        super().__init__(
+            f"Studio job '{job_id}' failed: {message}",
+            status_code=500,
+            code="JOB_FAILED",
+            raw_response=error_details,
+        )
+        self.job_id = job_id
+
+
+class JobTimeoutError(MlsApiError):
+    """Raised when polling for an asynchronous job exceeds the configured timeout."""
+
+    def __init__(self, job_id: str, timeout_seconds: float) -> None:
+        super().__init__(
+            f"Job '{job_id}' did not complete within {timeout_seconds:.1f} seconds",
+            status_code=408,
+            code="JOB_TIMEOUT",
+        )
+        self.job_id = job_id
+        self.timeout_seconds = timeout_seconds

pymlsapi/http.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import random
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from pymlsapi.config import ClientConfig
+from pymlsapi.errors import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidRequestError,
+    MlsApiError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+
+
+def _handle_error_response(response: httpx.Response) -> None:
+    status = response.status_code
+    try:
+        body = response.json()
+    except Exception:
+        body = {"message": response.text}
+
+    msg = body.get("error", {})
+    if isinstance(msg, dict):
+        message = msg.get("message") or str(body)
+        code = msg.get("code", "API_ERROR")
+    else:
+        message = str(msg) if msg else body.get("message", response.text or "Unknown error")
+        code = body.get("code", "API_ERROR")
+
+    if status == 401:
+        raise AuthenticationError(message, status_code=status, code=code, raw_response=body)
+    elif status == 402:
+        raise InsufficientCreditsError(message, status_code=status, code=code, raw_response=body)
+    elif status == 403:
+        raise PermissionDeniedError(message, status_code=status, code=code, raw_response=body)
+    elif status == 404:
+        raise NotFoundError(message, status_code=status, code=code, raw_response=body)
+    elif status == 400:
+        raise InvalidRequestError(message, status_code=status, code=code, raw_response=body)
+    elif status == 429:
+        retry_after = None
+        if "retry-after" in response.headers:
+            try:
+                retry_after = float(response.headers["retry-after"])
+            except ValueError:
+                pass
+        raise RateLimitError(
+            message,
+            status_code=status,
+            code=code,
+            retry_after_seconds=retry_after,
+            raw_response=body,
+        )
+    else:
+        raise MlsApiError(message, status_code=status, code=code, raw_response=body)
+
+
+class HttpClient:
+    """Synchronous HTTP transport engine with automatic retries and exponential backoff."""
+
+    def __init__(self, config: ClientConfig) -> None:
+        self.config = config
+        headers = {
+            "Authorization": f"Bearer {config.api_key}",
+            "x-api-key": config.api_key,
+            "User-Agent": "pymlsapi/0.1.0",
+            "Accept": "application/json",
+        }
+        self._client = httpx.Client(
+            base_url=config.base_url,
+            headers=headers,
+            timeout=config.timeout_seconds,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Any] = None,
+        files: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = path if path.startswith("http") else path.lstrip("/")
+        attempts = 0
+        max_retries = self.config.max_retries
+
+        while True:
+            attempts += 1
+            try:
+                response = self._client.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    json=json,
+                    files=files,
+                    data=data,
+                )
+
+                if response.status_code in (429, 500, 502, 503, 504) and attempts <= max_retries:
+                    # Exponential backoff with jitter
+                    backoff = (2 ** (attempts - 1)) * 0.5 + random.uniform(0.1, 0.4)
+                    time.sleep(backoff)
+                    continue
+
+                if response.is_error:
+                    _handle_error_response(response)
+
+                if response.status_code == 204:
+                    return None
+
+                return response.json()
+
+            except (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout) as exc:
+                if attempts <= max_retries:
+                    backoff = (2 ** (attempts - 1)) * 0.5 + random.uniform(0.1, 0.4)
+                    time.sleep(backoff)
+                    continue
+                raise MlsApiError(f"Network error during {method} {url}: {exc}") from exc
+
+    def get(self, path: str, *, params: Optional[Dict[str, Any]] = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: Optional[Any] = None,
+        files: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        return self.request("POST", path, json=json, files=files, data=data, params=params)
+
+    def put(self, path: str, *, json: Optional[Any] = None) -> Any:
+        return self.request("PUT", path, json=json)
+
+    def delete(self, path: str, *, params: Optional[Dict[str, Any]] = None) -> Any:
+        return self.request("DELETE", path, params=params)