snipepy 0.1.0__py3-none-any.whl

snipepy/__init__.py

@@ -0,0 +1,73 @@
+"""Snipepy - Python wrapper for the SnipeIT REST API."""
+
+__version__ = "0.1.0"
+
+from snipepy._config import Config
+from snipepy._http_client import (
+    HttpClient,
+    HttpClientProtocol,
+    SnipepyAuthError,
+    SnipepyConflictError,
+    SnipepyError,
+    SnipepyForbiddenError,
+    SnipepyNotFoundError,
+    SnipepyRateLimitError,
+    SnipepyServerError,
+    SnipepyValidationError,
+)
+from snipepy.snipepy import (
+    AccessoriesService,
+    AssetMaintenancesService,
+    AssetModelsService,
+    AssetsService,
+    CategoriesService,
+    CompaniesService,
+    ComponentsService,
+    ConsumablesService,
+    CustomFieldsService,
+    DepartmentsService,
+    LicensesService,
+    LocationsService,
+    ManufacturersService,
+    ReportsService,
+    SettingsService,
+    Snipepy,
+    StatusLabelsService,
+    SuppliersService,
+    UserGroupsService,
+    UsersService,
+)
+
+__all__ = [
+    "AccessoriesService",
+    "AssetMaintenancesService",
+    "AssetModelsService",
+    "AssetsService",
+    "CategoriesService",
+    "CompaniesService",
+    "ComponentsService",
+    "Config",
+    "ConsumablesService",
+    "CustomFieldsService",
+    "DepartmentsService",
+    "HttpClient",
+    "HttpClientProtocol",
+    "LicensesService",
+    "LocationsService",
+    "ManufacturersService",
+    "ReportsService",
+    "SettingsService",
+    "Snipepy",
+    "SnipepyAuthError",
+    "SnipepyConflictError",
+    "SnipepyError",
+    "SnipepyForbiddenError",
+    "SnipepyNotFoundError",
+    "SnipepyRateLimitError",
+    "SnipepyServerError",
+    "SnipepyValidationError",
+    "StatusLabelsService",
+    "SuppliersService",
+    "UserGroupsService",
+    "UsersService",
+]

snipepy/_config.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from dotenv import load_dotenv
+
+
+@dataclass(frozen=True)
+class Config:
+    url: str
+    token: str
+    timeout: int = 30
+    verify_ssl: bool = False
+
+    @classmethod
+    def from_env(cls, dotenv_path: str | None = None) -> Config:
+        load_dotenv(dotenv_path, override=True)
+
+        url: str = os.environ.get("SNIPEPY_URL", "").rstrip("/")
+        token: str = os.environ.get("SNIPEPY_API_TOKEN", "")
+
+        # Collect names of missing required environment variables
+        missing: list[str] = [
+            name
+            for name, val in (
+                ("SNIPEPY_URL", url),
+                ("SNIPEPY_API_TOKEN", token),
+            )
+            if not val
+        ]
+        # Raise ValueError if any required environment variables are missing
+        if missing:
+            raise ValueError(
+                f"Missing required environment variables: {', '.join(missing)}"
+            )
+
+        timeout: int = int(os.environ.get("SNIPEPY_TIMEOUT", "30"))
+        verify_ssl: bool = os.environ.get(
+            "SNIPEPY_VERIFY_SSL", "false"
+        ).lower() in ("true", "1", "yes")
+
+        return cls(
+            url=url, token=token, timeout=timeout, verify_ssl=verify_ssl
+        )

snipepy/_constants.py

@@ -0,0 +1,15 @@
+"""HTTP status code constants for SnipeIT API error handling."""
+
+from __future__ import annotations
+
+# HTTP 4xx Client Error codes
+HTTP_400_BAD_REQUEST = 400
+HTTP_401_UNAUTHORIZED = 401
+HTTP_403_FORBIDDEN = 403
+HTTP_404_NOT_FOUND = 404
+HTTP_409_CONFLICT = 409
+HTTP_429_TOO_MANY_REQUESTS = 429
+
+# HTTP 5xx - 6xx Server Error codes
+HTTP_5XX_MIN = 500
+HTTP_5XX_MAX = 600

snipepy/_http_client.py

@@ -0,0 +1,382 @@
+"""HTTP client for SnipeIT API calls."""
+
+from __future__ import annotations
+
+import html
+import time
+from collections.abc import Callable
+from typing import Any, Protocol
+
+import requests
+from requests.models import Response
+
+from snipepy import Config
+from snipepy._constants import (
+    HTTP_5XX_MAX,
+    HTTP_5XX_MIN,
+    HTTP_401_UNAUTHORIZED,
+    HTTP_403_FORBIDDEN,
+    HTTP_404_NOT_FOUND,
+    HTTP_409_CONFLICT,
+    HTTP_429_TOO_MANY_REQUESTS,
+)
+
+_DEFAULT_MAX_RETRIES: int = 3
+_DEFAULT_RETRY_AFTER: int = 10
+
+
+class SnipepyError(Exception):
+    """Base exception for all Snipepy errors."""
+
+
+class SnipepyAuthError(SnipepyError):
+    """Raised when authentication fails (HTTP 401)."""
+
+
+class SnipepyForbiddenError(SnipepyError):
+    """Raised when access is forbidden (HTTP 403)."""
+
+
+class SnipepyNotFoundError(SnipepyError):
+    """Raised when a resource is not found (HTTP 404)."""
+
+
+class SnipepyConflictError(SnipepyError):
+    """Raised when there is a conflict (HTTP 409)."""
+
+
+class SnipepyValidationError(SnipepyError):
+    """Raised when SnipeIT returns status: error (validation failure)."""
+
+
+class SnipepyServerError(SnipepyError):
+    """Raised when server returns 5xx error."""
+
+    response: Response | None
+
+    def __init__(self, message: str, response: Response | None = None) -> None:
+        super().__init__(message)
+        self.response = response
+
+
+class SnipepyRateLimitError(SnipepyError):
+    """Raised when the API rate limit is exceeded and retries exhausted."""
+
+
+# OCP: map status codes to exceptions; extend by adding entries here
+_STATUS_EXCEPTIONS: dict[int, tuple[type[SnipepyError], str]] = {
+    HTTP_401_UNAUTHORIZED: (SnipepyAuthError, "Unauthorized"),
+    HTTP_403_FORBIDDEN: (SnipepyForbiddenError, "Forbidden"),
+    HTTP_404_NOT_FOUND: (SnipepyNotFoundError, "Not found"),
+    HTTP_409_CONFLICT: (SnipepyConflictError, "Conflict"),
+}
+
+
+def _is_listener_only_failure(response: Response) -> bool:
+    """Check if the 500 error is a listener-only failure.
+
+    SnipeIT's post-action event listeners (e.g., mail notifications) can
+    fail with a 500 error even when the main operation succeeded. The
+    stack trace in the error page contains ``Listeners/`` which indicates
+    the failure is in a post-action event listener.
+    """
+    return "listeners/" in response.text.lower()
+
+
+class HttpClientProtocol(Protocol):
+    """Structural interface for SnipeIT HTTP communication."""
+
+    def get(self, path: str, params: dict[str, Any] | None = ...) -> Any: ...
+
+    def post(self, path: str, json: dict[str, Any] | None = ...) -> Any: ...
+
+    def put(self, path: str, json: dict[str, Any]) -> Any: ...
+
+    def patch(self, path: str, json: dict[str, Any]) -> Any: ...
+
+    def delete(self, path: str) -> Any: ...
+
+    def upload(self, path: str, files: dict[str, Any]) -> Any: ...
+
+    def post_binary(
+        self,
+        path: str,
+        json: dict[str, Any] | None = ...,
+        accept: str = ...,
+    ) -> bytes: ...
+
+    def get_binary(
+        self,
+        path: str,
+        params: dict[str, Any] | None = ...,
+        accept: str = ...,
+    ) -> bytes: ...
+
+
+class HttpClient:
+    """HTTP client for SnipeIT API calls."""
+
+    _config: Config
+    _session: requests.Session
+    _max_retries: int
+    _retry_after: int
+
+    def __init__(
+        self,
+        config: Config,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        retry_after: int = _DEFAULT_RETRY_AFTER,
+    ) -> None:
+        self._config = config
+        self._max_retries = max_retries
+        self._retry_after = retry_after
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {config.token}",
+                "Accept": "application/json",
+            }
+        )
+
+    def _execute_request(
+        self, make_request: Callable[[], Response]
+    ) -> Response:
+        """Execute a request callable, retrying on HTTP 429 with Retry-After.
+
+        Retries up to ``_max_retries`` times. On each 429 response the
+        ``Retry-After`` header value (seconds) is honoured; when the header is
+        absent the configured ``_retry_after`` default is used.  After all
+        retries are exhausted ``SnipepyRateLimitError`` is raised.
+        """
+        for attempt in range(self._max_retries + 1):
+            response = make_request()
+            if response.status_code != HTTP_429_TOO_MANY_REQUESTS:
+                return response
+            if attempt < self._max_retries:
+                raw_wait = response.headers.get(
+                    "Retry-After", str(self._retry_after)
+                )
+                try:
+                    wait = int(raw_wait)
+                except ValueError:
+                    wait = self._retry_after
+                time.sleep(wait)
+        retries = self._max_retries
+        word = "retry" if retries == 1 else "retries"
+        raise SnipepyRateLimitError(
+            f"Rate limit exceeded after {retries} {word}"
+        )
+
+    def _raise_for_status(
+        self, response: Response, exc: requests.HTTPError
+    ) -> None:
+        """Translate HTTP error codes into Snipepy exceptions."""
+        entry = _STATUS_EXCEPTIONS.get(response.status_code)
+        if entry is not None:
+            exc_class, message = entry
+            raise exc_class(message) from exc
+        if HTTP_5XX_MIN <= response.status_code < HTTP_5XX_MAX:
+            raise SnipepyServerError(
+                "Server error", response=response
+            ) from exc
+        raise exc
+
+    def _unescape_strings(self, data: Any) -> Any:
+        """Recursively unescape HTML entities in all strings."""
+        if isinstance(data, str):
+            return html.unescape(data)
+        if isinstance(data, dict):
+            return {k: self._unescape_strings(v) for k, v in data.items()}
+        if isinstance(data, list):
+            return [self._unescape_strings(item) for item in data]
+        return data
+
+    def _parse_payload(self, response: Response) -> Any:
+        """Parse JSON; raise SnipepyValidationError on status:error."""
+        payload = response.json()
+        if not isinstance(payload, dict):
+            return payload
+        if payload.get("status") == "error":
+            messages = payload.get("messages", {})
+            raise SnipepyValidationError(str(messages))
+        result = payload.get("payload", payload)
+        return self._unescape_strings(result)
+
+    def _build_url(self, path: str, params: dict[str, Any] | None) -> str:
+        """Build a URL with optional query string; None params excluded."""
+        path_name: str = path.lstrip("/")
+        base_url: str = f"{self._config.url.rstrip('/')}/api/v1/{path_name}"
+
+        if not params:
+            return base_url
+
+        filtered_params = {k: v for k, v in params.items() if v is not None}
+
+        if not filtered_params:
+            return base_url
+
+        query_string = "&".join(f"{k}={v}" for k, v in filtered_params.items())
+        return f"{base_url}?{query_string}"
+
+    def _request(self, method: str, path: str) -> Any:
+        """Make a raw HTTP request (no params, no body)."""
+        url: str = self._build_url(path, None)
+        response = self._execute_request(
+            lambda: self._session.request(
+                method=method,
+                url=url,
+                timeout=self._config.timeout,
+                verify=self._config.verify_ssl,
+            )
+        )
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as e:
+            self._raise_for_status(response, e)
+        return self._parse_payload(response)
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        """Make a GET request."""
+        url: str = self._build_url(path, params)
+        response = self._execute_request(
+            lambda: self._session.get(
+                url=url,
+                timeout=self._config.timeout,
+                verify=self._config.verify_ssl,
+            )
+        )
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as e:
+            self._raise_for_status(response, e)
+        return self._parse_payload(response)
+
+    def post(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        """Make a POST request."""
+        url: str = self._build_url(path, None)
+        response = self._execute_request(
+            lambda: self._session.post(
+                url=url,
+                json=json,
+                timeout=self._config.timeout,
+                verify=self._config.verify_ssl,
+            )
+        )
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as e:
+            self._raise_for_status(response, e)
+        return self._parse_payload(response)
+
+    def put(self, path: str, json: dict[str, Any]) -> Any:
+        """Make a PUT request."""
+        url: str = self._build_url(path, None)
+        response = self._execute_request(
+            lambda: self._session.put(
+                url=url,
+                json=json,
+                timeout=self._config.timeout,
+                verify=self._config.verify_ssl,
+            )
+        )
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as e:
+            self._raise_for_status(response, e)
+        return self._parse_payload(response)
+
+    def patch(self, path: str, json: dict[str, Any]) -> Any:
+        """Make a PATCH request."""
+        url: str = self._build_url(path, None)
+        response = self._execute_request(
+            lambda: self._session.patch(
+                url=url,
+                json=json,
+                timeout=self._config.timeout,
+                verify=self._config.verify_ssl,
+            )
+        )
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as e:
+            self._raise_for_status(response, e)
+        return self._parse_payload(response)
+
+    def delete(self, path: str) -> Any:
+        """Make a DELETE request."""
+        url: str = self._build_url(path, None)
+        response = self._execute_request(
+            lambda: self._session.delete(
+                url=url,
+                timeout=self._config.timeout,
+                verify=self._config.verify_ssl,
+            )
+        )
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as e:
+            self._raise_for_status(response, e)
+        return self._parse_payload(response)
+
+    def upload(self, path: str, files: dict[str, Any]) -> Any:
+        """POST a multipart file upload to the SnipeIT API."""
+        url: str = self._build_url(path, None)
+        response = self._execute_request(
+            lambda: self._session.request(
+                method="POST",
+                url=url,
+                files=files,
+                timeout=self._config.timeout,
+                verify=self._config.verify_ssl,
+            )
+        )
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as e:
+            self._raise_for_status(response, e)
+        return self._parse_payload(response)
+
+    def post_binary(
+        self,
+        path: str,
+        json: dict[str, Any] | None = None,
+        accept: str = "application/octet-stream",
+    ) -> bytes:
+        """POST with JSON body and return binary response content."""
+        url: str = self._build_url(path, None)
+        response = self._execute_request(
+            lambda: self._session.post(
+                url=url,
+                json=json,
+                timeout=self._config.timeout,
+                verify=self._config.verify_ssl,
+                headers={"Accept": accept},
+            )
+        )
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as e:
+            self._raise_for_status(response, e)
+        return bytes(response.content)
+
+    def get_binary(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        accept: str = "application/octet-stream",
+    ) -> bytes:
+        """GET a binary response (PDF, PNG, ZIP) from the SnipeIT API."""
+        url: str = self._build_url(path, params)
+        response = self._execute_request(
+            lambda: self._session.get(
+                url=url,
+                timeout=self._config.timeout,
+                verify=self._config.verify_ssl,
+                headers={"Accept": accept},
+            )
+        )
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as e:
+            self._raise_for_status(response, e)
+        return bytes(response.content)

snipepy/_whitelist.py

@@ -0,0 +1,70 @@
+# Vulture whitelist - public API surface used by callers outside snipepy/
+from snipepy import Config, Snipepy
+from snipepy._http_client import (
+    HttpClientProtocol,
+    SnipepyAuthError,
+    SnipepyConflictError,
+    SnipepyError,
+    SnipepyForbiddenError,
+    SnipepyNotFoundError,
+    SnipepyRateLimitError,
+    SnipepyServerError,
+    SnipepyValidationError,
+)
+from snipepy.models.components import ComponentAsset, ComponentAssetList
+from snipepy.snipepy import (
+    AccessoriesService,
+    AssetMaintenancesService,
+    AssetModelsService,
+    AssetsService,
+    CategoriesService,
+    CompaniesService,
+    ComponentsService,
+    ConsumablesService,
+    CustomFieldsService,
+    DepartmentsService,
+    LicensesService,
+    LocationsService,
+    ManufacturersService,
+    ReportsService,
+    SettingsService,
+    StatusLabelsService,
+    SuppliersService,
+    UserGroupsService,
+    UsersService,
+)
+
+_ = (
+    ComponentAsset,
+    ComponentAssetList,
+    Config.from_env,
+    Snipepy.from_env,
+    HttpClientProtocol,
+    SnipepyError,
+    SnipepyAuthError,
+    SnipepyForbiddenError,
+    SnipepyNotFoundError,
+    SnipepyConflictError,
+    SnipepyValidationError,
+    SnipepyServerError,
+    SnipepyRateLimitError,
+    AssetsService,
+    UsersService,
+    LicensesService,
+    AccessoriesService,
+    ComponentsService,
+    ConsumablesService,
+    LocationsService,
+    CompaniesService,
+    CategoriesService,
+    ManufacturersService,
+    AssetModelsService,
+    StatusLabelsService,
+    DepartmentsService,
+    UserGroupsService,
+    SuppliersService,
+    AssetMaintenancesService,
+    SettingsService,
+    ReportsService,
+    CustomFieldsService,
+)

snipepy/models/__init__.py

@@ -0,0 +1,111 @@
+"""Pydantic models for SnipeIT resources."""
+
+from snipepy.models._shared import (
+    AssignedTo,
+    AvailableActions,
+    DateField,
+    DatetimeField,
+    NamedObject,
+    StatusLabelRef,
+)
+from snipepy.models.accessories import (
+    Accessory,
+    AccessoryCheckedOut,
+    AccessoryCheckedOutList,
+    AccessoryList,
+)
+from snipepy.models.asset_maintenances import (
+    AssetMaintenance,
+    AssetMaintenanceList,
+    AssetRef,
+)
+from snipepy.models.asset_models import AssetModel, AssetModelList
+from snipepy.models.assets import Asset, AssetFile, AssetFileList, AssetList
+from snipepy.models.categories import Category, CategoryList
+from snipepy.models.companies import Company, CompanyList
+from snipepy.models.components import Component, ComponentList
+from snipepy.models.consumables import Consumable, ConsumableList
+from snipepy.models.custom_fields import (
+    CustomField,
+    CustomFieldList,
+    Fieldset,
+    FieldsetList,
+)
+from snipepy.models.departments import Department, DepartmentList
+from snipepy.models.groups import Group, GroupList
+from snipepy.models.licenses import (
+    License,
+    LicenseList,
+    LicenseSeat,
+    LicenseSeatList,
+)
+from snipepy.models.locations import Location, LocationList
+from snipepy.models.manufacturers import Manufacturer, ManufacturerList
+from snipepy.models.reports import (
+    ActivityLog,
+    ActivityLogItem,
+    DepreciationAsset,
+    DepreciationList,
+)
+from snipepy.models.settings import Backup, BackupList
+from snipepy.models.status_labels import StatusLabel, StatusLabelList
+from snipepy.models.suppliers import Supplier, SupplierList
+from snipepy.models.users import User, UserList
+
+__all__ = [
+    "Accessory",
+    "AccessoryCheckedOut",
+    "AccessoryCheckedOutList",
+    "AccessoryList",
+    "ActivityLog",
+    "ActivityLogItem",
+    "Asset",
+    "AssetFile",
+    "AssetFileList",
+    "AssetList",
+    "AssetMaintenance",
+    "AssetMaintenanceList",
+    "AssetModel",
+    "AssetModelList",
+    "AssetRef",
+    "AssignedTo",
+    "AvailableActions",
+    "Backup",
+    "BackupList",
+    "Category",
+    "CategoryList",
+    "Company",
+    "CompanyList",
+    "Component",
+    "ComponentList",
+    "Consumable",
+    "ConsumableList",
+    "CustomField",
+    "CustomFieldList",
+    "DateField",
+    "DatetimeField",
+    "Department",
+    "DepartmentList",
+    "DepreciationAsset",
+    "DepreciationList",
+    "Fieldset",
+    "FieldsetList",
+    "Group",
+    "GroupList",
+    "License",
+    "LicenseList",
+    "LicenseSeat",
+    "LicenseSeatList",
+    "Location",
+    "LocationList",
+    "Manufacturer",
+    "ManufacturerList",
+    "NamedObject",
+    "StatusLabel",
+    "StatusLabelList",
+    "StatusLabelRef",
+    "Supplier",
+    "SupplierList",
+    "User",
+    "UserList",
+]