pydomi 0.1.0__py3-none-any.whl

pydomi/__init__.py

@@ -0,0 +1,53 @@
+"""``pydomi`` — Python SDK for DOM.Inventory CMDB.
+
+Quick start::
+
+    import pydomi
+
+    api = pydomi.Api("http://127.0.0.1:8000", token="…")
+    for site in api.dcim.sites.all():
+        print(site.id, site.name)
+
+The full client API is documented on :class:`~pydomi.api.Api`.
+"""
+
+from __future__ import annotations
+
+from . import generated  # cheap — pure-data module, see generated/__init__.py
+from .api import Api
+
+
+# Lazy: AsyncApi requires httpx, which is an optional extra. Don't import
+# at top-level — pull it from ``pydomi.async_api`` when needed.
+def __getattr__(name):  # PEP 562
+    if name == "AsyncApi":
+        from .async_api import AsyncApi
+        return AsyncApi
+    raise AttributeError(name)
+
+
+from .exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    DomiError,
+    NotFoundError,
+    RequestError,
+    ThrottledError,
+    ValidationError,
+)
+from .record import Record
+
+__all__ = [
+    "Api",
+    "Record",
+    # exceptions
+    "DomiError",
+    "ConfigurationError",
+    "RequestError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ValidationError",
+    "ThrottledError",
+]
+
+__version__ = "0.1.0"

pydomi/__main__.py

@@ -0,0 +1,10 @@
+"""Allow ``python -m pydomi`` to work the same as ``python -m pydomi.cli``."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

pydomi/api.py

@@ -0,0 +1,483 @@
+"""Top-level :class:`Api` — the entry point clients import.
+
+Usage
+-----
+::
+
+    import pydomi
+
+    api = pydomi.Api("http://127.0.0.1:8000", token="abc123")
+    for device in api.dcim.devices.filter(site=1):
+        print(device.name, device.serial)
+
+    new = api.dcim.sites.create(name="DC-North", slug="dc-north")
+    new.description = "Primary RU-NORTH site"
+    new.save()
+    new.delete()
+"""
+
+from __future__ import annotations
+
+import json as _json
+import logging
+from typing import Any
+from urllib.parse import urljoin
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from .app import App
+from .exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    NotFoundError,
+    RequestError,
+    ThrottledError,
+    ValidationError,
+)
+from .registry import REGISTRY, app_names
+
+logger = logging.getLogger("pydomi")
+
+DEFAULT_TIMEOUT = 30  # seconds — overridable per Api instance
+DEFAULT_RETRIES = 3   # retries on 5xx / connection errors
+DEFAULT_BACKOFF = 0.3  # urllib3 Retry backoff_factor
+DEFAULT_CACHE_TTL = 0.0  # seconds — 0 disables the reference-data cache
+
+
+def _build_retry_adapter(retries: int, backoff: float) -> HTTPAdapter:
+    """urllib3-based retry adapter: 5xx + connection errors + 429.
+
+    DRF returns 429 with ``Retry-After`` for throttling. urllib3 honours
+    that header automatically when 429 is in the ``status_forcelist`` —
+    so we get exponential backoff *and* server-prescribed delays from one
+    place.
+    """
+    return HTTPAdapter(max_retries=Retry(
+        total=retries,
+        connect=retries,
+        read=retries,
+        status=retries,
+        status_forcelist=(429, 500, 502, 503, 504),
+        allowed_methods=("HEAD", "GET", "OPTIONS", "PUT", "PATCH", "POST", "DELETE"),
+        backoff_factor=backoff,
+        respect_retry_after_header=True,
+        raise_on_status=False,
+    ))
+
+
+class Api:
+    """Top-level handle for a DOM.Inventory server.
+
+    Parameters
+    ----------
+    url : str
+        Base URL of the server, e.g. ``http://127.0.0.1:8000``. The
+        ``/api/`` prefix is appended by the SDK — do **not** include it.
+    token : str | None
+        API token (created in the DOM.Inventory ``/auth/tokens/`` UI or via
+        ``apps.core.models.APIToken``). Sent as ``Authorization: Token <key>``.
+    session : requests.Session | None
+        Reuse an existing session (lets you pin custom adapters, retries,
+        TLS verification, etc.). A fresh one is created if omitted.
+    timeout : float
+        Per-request timeout in seconds (default 30).
+    verify : bool | str
+        Forwarded to ``requests`` — set to ``False`` to skip TLS check,
+        or pass a CA-bundle path.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        token: str | None = None,
+        session: requests.Session | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        verify: bool | str = True,
+        user_agent: str = "pydomi-sdk/0.1",
+        retries: int = DEFAULT_RETRIES,
+        backoff_factor: float = DEFAULT_BACKOFF,
+        cache_ttl: float = DEFAULT_CACHE_TTL,
+        dry_run: bool = False,
+    ):
+        if not url or not url.startswith(("http://", "https://")):
+            raise ConfigurationError(
+                f"`url` must start with http:// or https:// — got {url!r}"
+            )
+        self.base_url = url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self.verify = verify
+
+        self._session = session or requests.Session()
+        self._session.headers.update({
+            "Accept": "application/json",
+            "User-Agent": user_agent,
+        })
+        if token:
+            self._session.headers["Authorization"] = f"Token {token}"
+
+        # Mount retry adapter unless the caller supplied their own session
+        # with adapters already wired up. ``retries=0`` opts out cleanly.
+        if session is None and retries > 0:
+            adapter = _build_retry_adapter(retries, backoff_factor)
+            self._session.mount("http://", adapter)
+            self._session.mount("https://", adapter)
+
+        self._apps: dict[str, App] = {name: App(self, name) for name in app_names()}
+        # Lazy cache for /api/contenttypes/ — populated on first call.
+        self._ct_cache: dict[tuple[str, str], int] | None = None
+        # Token management namespace — ``api.tokens.create(...)`` etc.
+        from .tokens import _TokenManager
+        self.tokens = _TokenManager(self)
+        # Reference-data cache (Tag/Status/Site/AS/...). Opt-in.
+        from .cache import _TTLCache
+        self._cache = _TTLCache(ttl=cache_ttl)
+        # When True, mutating verbs (POST/PUT/PATCH/DELETE) are logged
+        # and skipped — returning a synthetic stub. Reads still go to
+        # the server so chained scripts keep working.
+        self.dry_run = dry_run
+
+    # ── public attribute access (api.dcim, api.network, …) ──────────────
+    def __getattr__(self, item: str) -> App:
+        # __getattr__ is consulted only when normal lookup fails, so
+        # internal attrs like ``base_url`` are NOT routed here.
+        try:
+            return self._apps[item]
+        except KeyError as exc:
+            raise AttributeError(
+                f"DOM.Inventory has no app {item!r}. Known apps: {sorted(self._apps)}"
+            ) from exc
+
+    def __dir__(self) -> list[str]:
+        return sorted(set(self._apps) | set(super().__dir__()))
+
+    # ── meta helpers ─────────────────────────────────────────────────────
+    def apps(self) -> list[str]:
+        """List of known app namespaces."""
+        return list(self._apps)
+
+    def endpoints(self) -> dict[str, list[str]]:
+        """Map ``{app: [endpoint_attr, ...]}`` — useful for introspection."""
+        return {a: sorted(eps) for a, eps in REGISTRY.items()}
+
+    # ── parallel fetch / global search ─────────────────────────────────
+    def gather(self, callables, *, max_workers: int = 8) -> list:
+        """Run *callables* concurrently in a thread pool and return their
+        results in the original order. Exceptions are re-raised in the
+        position of the failing callable when iterating the result list
+        (via ``concurrent.futures``).
+
+        Example::
+
+            sites, devices = api.gather([
+                lambda: list(api.dcim.sites.all()),
+                lambda: list(api.dcim.devices.all()),
+            ])
+        """
+        import concurrent.futures
+        results: list = [None] * len(callables)
+        with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as pool:
+            future_to_idx = {pool.submit(fn): i for i, fn in enumerate(callables)}
+            for fut in concurrent.futures.as_completed(future_to_idx):
+                results[future_to_idx[fut]] = fut.result()
+        return results
+
+    def fetch_many(self, refs, *, max_workers: int = 8) -> list:
+        """Fetch many objects in parallel.
+
+        *refs* is a list of ``(endpoint_segment, pk)`` tuples — e.g.
+        ``[("sites", 1), ("devices", 7), ("tags", 4)]``. Returns Records
+        in the same order, ``None`` if any single GET fails with 404.
+        Other errors raise normally (so a 500 still surfaces).
+        """
+        def _one(seg, pk):
+            ep = self._lookup_endpoint(seg)
+            if ep is None:
+                return None
+            try:
+                return ep.get(pk)
+            except (NotFoundError,):
+                return None
+        return self.gather([
+            (lambda s=s, p=p: _one(s, p)) for s, p in refs
+        ], max_workers=max_workers)
+
+    def _lookup_endpoint(self, url_segment: str):
+        for app in self._apps.values():
+            for ep in app._endpoints.values():
+                if ep.url_segment == url_segment:
+                    return ep
+        return None
+
+    def search(
+        self,
+        query: str,
+        *,
+        endpoints: list[str] | None = None,
+        max_per: int = 25,
+        max_workers: int = 8,
+    ) -> dict[str, list]:
+        """Run DRF ``?search=<query>`` against every applicable endpoint
+        in parallel; return ``{endpoint_segment: [Record, ...]}``.
+
+        *endpoints* — restrict to specific URL segments (default: every
+        endpoint registered in :data:`REGISTRY`). *max_per* caps the
+        result count per endpoint to avoid surprising responses.
+
+        Use this for «найти 'router' где угодно» — UI search bars,
+        ad-hoc REPL exploration.
+        """
+        from .registry import REGISTRY
+        targets = endpoints or sorted({
+            seg for app in REGISTRY.values() for seg in app.values()
+        })
+
+        def _run(seg: str) -> list:
+            ep = self._lookup_endpoint(seg)
+            if ep is None:
+                return []
+            try:
+                return [r for _, r in zip(range(max_per),
+                                          ep.search(query))]
+            except RequestError:
+                return []  # endpoint doesn't accept ?search=
+
+        results = self.gather(
+            [(lambda s=s: _run(s)) for s in targets],
+            max_workers=max_workers,
+        )
+        return {seg: hits for seg, hits in zip(targets, results) if hits}
+
+    def content_types(self, *, refresh: bool = False) -> dict[tuple[str, str], int]:
+        """Map ``(app_label, model) → content_type_id`` for the whole project.
+
+        Cached after the first call (CT ids don't change at runtime — they
+        only shift if the DB is wiped). Pass ``refresh=True`` to force a
+        re-fetch.
+
+        Use it whenever you create an object that uses a GenericFK::
+
+            ct = api.content_types()[("dcim", "device")]
+            api.agents.agents.create(
+                content_type=ct, object_id=device.id, type=osquery_type.id,
+                name="OSQuery", config={...},
+            )
+        """
+        if refresh or self._ct_cache is None:
+            data = self._request("GET", f"{self.base_url}/api/contenttypes/")
+            self._ct_cache = {
+                (row["app_label"], row["model"]): row["id"] for row in data
+            }
+        return self._ct_cache
+
+    def content_type_id(self, app_label: str, model: str) -> int:
+        """Convenience: ``api.content_type_id("dcim", "device")``."""
+        try:
+            return self.content_types()[(app_label, model)]
+        except KeyError as exc:
+            raise ConfigurationError(
+                f"No ContentType for ({app_label!r}, {model!r}). "
+                f"Known: {sorted(self.content_types())[:5]}…"
+            ) from exc
+
+    def login(
+        self,
+        username: str,
+        password: str,
+        *,
+        login_path: str = "/auth/login/",
+    ) -> None:
+        """Authenticate via Django's session login (CSRF + form POST).
+
+        After this call, subsequent requests carry the session cookie
+        and you can omit the API token entirely. Useful when token
+        management is locked down to admins.
+
+        The flow is the standard one for Django auth views:
+
+        1. ``GET <login_path>`` to obtain the CSRF cookie.
+        2. ``POST`` username/password/csrfmiddlewaretoken back, with
+           ``Referer`` pointing at the GET URL (CSRF middleware will
+           reject otherwise).
+
+        Raises :class:`AuthenticationError` if the server returns a
+        non-redirect / non-200 (which Django does for bad credentials).
+        """
+        login_url = f"{self.base_url}{login_path}"
+
+        # 1. GET to seed the csrftoken cookie.
+        get_resp = self._session.get(
+            login_url, timeout=self.timeout, verify=self.verify,
+        )
+        if get_resp.status_code >= 400:
+            raise AuthenticationError(
+                get_resp.status_code, login_url, get_resp.text[:200],
+                message=f"login page unreachable: HTTP {get_resp.status_code}",
+            )
+        csrf = self._session.cookies.get("csrftoken")
+        if not csrf:
+            raise AuthenticationError(
+                0, login_url, "no csrftoken cookie",
+                message="Server did not set a csrftoken cookie on the login GET.",
+            )
+
+        # 2. Form-encoded POST with Referer header (Django CSRF check).
+        post = self._session.post(
+            login_url,
+            data={
+                "username": username,
+                "password": password,
+                "csrfmiddlewaretoken": csrf,
+            },
+            headers={"Referer": login_url},
+            allow_redirects=False,
+            timeout=self.timeout, verify=self.verify,
+        )
+        # Django returns 302 on success (to LOGIN_REDIRECT_URL) and 200
+        # (re-rendered form) on failure.
+        if post.status_code not in (302, 303):
+            raise AuthenticationError(
+                post.status_code, login_url,
+                post.text[:200] if post.text else "(empty body)",
+                message=f"Login failed (HTTP {post.status_code}); "
+                        f"check username/password.",
+            )
+
+    def logout(self, *, logout_path: str = "/auth/logout/") -> None:
+        """End the session. Best-effort — no exception on already-logged-out."""
+        try:
+            self._session.post(
+                f"{self.base_url}{logout_path}",
+                timeout=self.timeout, verify=self.verify,
+                allow_redirects=False,
+            )
+        finally:
+            self._session.cookies.clear()
+
+    def status(self) -> dict[str, Any]:
+        """Lightweight reachability probe.
+
+        Fetches ``/api/schema/?format=json`` (drf-spectacular), since DOM.
+        Inventory does not expose a dedicated ``/api/status/`` route. If
+        you only need to confirm the server is up and the token is valid,
+        this is the cheapest call available.
+        """
+        url = f"{self.base_url}/api/schema/?format=json"
+        data = self._request("GET", url)
+        if isinstance(data, dict):
+            info = data.get("info", {})
+            return {"title": info.get("title"), "version": info.get("version")}
+        return {"raw": data}
+
+    # ── public HTTP helper (low-level escape hatch) ──────────────────────
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        expect_json: bool = True,
+    ) -> Any:
+        """Public hook for non-CRUD endpoints (``/api/changelog/``, custom
+        views from third-party apps, etc.).
+
+        *path* may be absolute (``"http://..."``) or relative
+        (``"/api/changelog/"`` or even ``"changelog/"``). The token /
+        session / retry adapter / typed exceptions all apply just like
+        for built-in calls."""
+        if not path.startswith(("http://", "https://", "/")):
+            path = "/" + path
+        return self._request(method, path, params=params, json=json,
+                             expect_json=expect_json)
+
+    # ── HTTP plumbing ────────────────────────────────────────────────────
+    def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        expect_json: bool = True,
+    ) -> Any:
+        """Send a single request and translate errors into typed exceptions."""
+        full_url = url if url.startswith("http") else urljoin(self.base_url + "/", url.lstrip("/"))
+        logger.debug("HTTP %s %s params=%s body=%s", method, full_url, params, json)
+
+        # Dry-run short-circuit for mutating verbs.
+        if self.dry_run and method.upper() in ("POST", "PUT", "PATCH", "DELETE"):
+            logger.info("DRY-RUN  %s %s body=%s", method.upper(), full_url, json)
+            # Return something Endpoint/Record can consume without crashing.
+            stub = dict(json) if isinstance(json, dict) else {}
+            stub.setdefault("id", -1)
+            return stub
+
+        try:
+            resp = self._session.request(
+                method, full_url,
+                params=params, json=json,
+                timeout=self.timeout, verify=self.verify,
+            )
+        except requests.RequestException as exc:
+            raise RequestError(
+                status_code=0, url=full_url, body=str(exc),
+                message=f"Network error talking to {full_url}: {exc}",
+            ) from exc
+
+        return self._handle_response(resp, expect_json=expect_json)
+
+    @staticmethod
+    def _handle_response(resp: requests.Response, *, expect_json: bool) -> Any:
+        """Lift a requests.Response into a Python value or a typed exception."""
+        if 200 <= resp.status_code < 300:
+            if resp.status_code == 204 or not resp.content:
+                return None
+            if not expect_json:
+                return None
+            try:
+                return resp.json()
+            except _json.JSONDecodeError as exc:
+                raise RequestError(
+                    status_code=resp.status_code, url=resp.url,
+                    body=resp.text[:400],
+                    message=f"Server returned non-JSON: {exc}",
+                ) from exc
+
+        # Error path. DRF replies with JSON about 99% of the time;
+        # fall back to text otherwise.
+        try:
+            body: Any = resp.json()
+        except _json.JSONDecodeError:
+            body = resp.text
+
+        if resp.status_code in (401, 403):
+            raise AuthenticationError(resp.status_code, resp.url, body)
+        if resp.status_code == 404:
+            raise NotFoundError(resp.status_code, resp.url, body)
+        if resp.status_code == 400:
+            raise ValidationError(resp.status_code, resp.url, body)
+        if resp.status_code == 429:
+            retry = resp.headers.get("Retry-After")
+            try:
+                retry_f = float(retry) if retry is not None else None
+            except ValueError:
+                retry_f = None
+            raise ThrottledError(resp.status_code, resp.url, body, retry_after=retry_f)
+        raise RequestError(resp.status_code, resp.url, body)
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> "Api":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        masked = "set" if self.token else "none"
+        return f"<Api {self.base_url} token={masked}>"

pydomi/app.py

@@ -0,0 +1,42 @@
+"""Domain-app namespace — groups endpoints under ``api.<app>.<endpoint>``."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .endpoint import Endpoint
+from .registry import READ_ONLY_ENDPOINTS, endpoints_for
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .api import Api
+
+
+class App:
+    """Lazy container for endpoints belonging to one DOM.Inventory app."""
+
+    def __init__(self, api: "Api", name: str):
+        self._api = api
+        self.name = name
+        self._endpoints: dict[str, Endpoint] = {}
+        for attr, segment in endpoints_for(name).items():
+            self._endpoints[attr] = Endpoint(
+                api,
+                segment,
+                read_only=(name, attr) in READ_ONLY_ENDPOINTS,
+            )
+
+    # Attribute access exposes endpoints by their python identifier.
+    def __getattr__(self, item: str) -> Endpoint:
+        try:
+            return self._endpoints[item]
+        except KeyError as exc:
+            raise AttributeError(
+                f"App {self.name!r} has no endpoint {item!r}. "
+                f"Available: {sorted(self._endpoints)}"
+            ) from exc
+
+    def __dir__(self) -> list[str]:
+        return sorted(set(list(self._endpoints)) | set(super().__dir__()))
+
+    def __repr__(self) -> str:
+        return f"<App {self.name} endpoints={sorted(self._endpoints)}>"