honeycomb-api 0.1.0__py3-none-any.whl

honeycomb/exceptions.py

@@ -0,0 +1,236 @@
+"""Exception hierarchy for Honeycomb API errors."""
+
+from __future__ import annotations
+
+
+class HoneycombAPIError(Exception):
+    """Base exception for all Honeycomb API errors.
+
+    Attributes:
+        message: Human-readable error message.
+        status_code: HTTP status code from the response.
+        request_id: Honeycomb request ID for support debugging (if available).
+        response_body: Raw response body (if available).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        request_id: str | None = None,
+        response_body: dict | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.request_id = request_id
+        self.response_body = response_body
+
+    def __str__(self) -> str:
+        parts = [f"[{self.status_code}] {self.message}"]
+        if self.request_id:
+            parts.append(f"(request_id: {self.request_id})")
+        return " ".join(parts)
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"message={self.message!r}, "
+            f"status_code={self.status_code}, "
+            f"request_id={self.request_id!r})"
+        )
+
+
+class HoneycombAuthError(HoneycombAPIError):
+    """401 Unauthorized - Invalid or missing API key.
+
+    Raised when the API key is missing, invalid, or expired.
+    """
+
+    pass
+
+
+class HoneycombForbiddenError(HoneycombAPIError):
+    """403 Forbidden - Insufficient permissions.
+
+    Raised when the API key doesn't have permission for the requested operation.
+    """
+
+    pass
+
+
+class HoneycombNotFoundError(HoneycombAPIError):
+    """404 Not Found - Resource doesn't exist.
+
+    Raised when the requested resource (dataset, trigger, SLO, etc.) is not found.
+    """
+
+    pass
+
+
+class HoneycombValidationError(HoneycombAPIError):
+    """422 Validation Error - Invalid request data.
+
+    Raised when the request body fails validation.
+
+    Attributes:
+        errors: List of field-level validation errors (if available).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 422,
+        request_id: str | None = None,
+        response_body: dict | None = None,
+        errors: list[dict] | None = None,
+    ) -> None:
+        super().__init__(message, status_code, request_id, response_body)
+        self.errors = errors or []
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        if self.errors:
+            error_details = "; ".join(
+                f"{e.get('field', 'unknown')}: {e.get('message', 'invalid')}" for e in self.errors
+            )
+            return f"{base} - {error_details}"
+        return base
+
+
+class HoneycombRateLimitError(HoneycombAPIError):
+    """429 Rate Limited - Too many requests.
+
+    Raised when the API rate limit has been exceeded.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying (if provided by API).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 429,
+        request_id: str | None = None,
+        response_body: dict | None = None,
+        retry_after: int | None = None,
+    ) -> None:
+        super().__init__(message, status_code, request_id, response_body)
+        self.retry_after = retry_after
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        if self.retry_after:
+            return f"{base} (retry after {self.retry_after}s)"
+        return base
+
+
+class HoneycombServerError(HoneycombAPIError):
+    """5xx Server Error - Honeycomb service issue.
+
+    Raised when Honeycomb's servers encounter an error.
+    These errors are typically transient and can be retried.
+    """
+
+    pass
+
+
+class HoneycombTimeoutError(HoneycombAPIError):
+    """Request timed out.
+
+    Raised when a request to the Honeycomb API times out.
+    """
+
+    def __init__(
+        self,
+        message: str = "Request timed out",
+        timeout: float | None = None,
+    ) -> None:
+        super().__init__(message, status_code=0)
+        self.timeout = timeout
+
+    def __str__(self) -> str:
+        if self.timeout:
+            return f"{self.message} (timeout: {self.timeout}s)"
+        return self.message
+
+
+class HoneycombConnectionError(HoneycombAPIError):
+    """Connection error.
+
+    Raised when unable to connect to the Honeycomb API.
+    """
+
+    def __init__(
+        self,
+        message: str = "Failed to connect to Honeycomb API",
+        original_error: Exception | None = None,
+    ) -> None:
+        super().__init__(message, status_code=0)
+        self.original_error = original_error
+
+
+def raise_for_status(
+    status_code: int,
+    response_body: dict | None = None,
+    request_id: str | None = None,
+) -> None:
+    """Raise an appropriate exception based on HTTP status code.
+
+    Args:
+        status_code: HTTP status code from the response.
+        response_body: Parsed response body (if available).
+        request_id: Request ID from response headers (if available).
+
+    Raises:
+        HoneycombAuthError: For 401 responses.
+        HoneycombForbiddenError: For 403 responses.
+        HoneycombNotFoundError: For 404 responses.
+        HoneycombValidationError: For 422 responses.
+        HoneycombRateLimitError: For 429 responses.
+        HoneycombServerError: For 5xx responses.
+        HoneycombAPIError: For other error responses.
+    """
+    if 200 <= status_code < 300:
+        return
+
+    # Extract error message from response body
+    message = "Unknown error"
+    errors: list[dict] | None = None
+    retry_after: int | None = None
+
+    if response_body:
+        # Try different error formats
+        if "error" in response_body:
+            message = response_body["error"]
+        elif "message" in response_body:
+            message = response_body["message"]
+        elif "title" in response_body:
+            message = response_body["title"]
+            if "detail" in response_body:
+                message = f"{message}: {response_body['detail']}"
+        elif "errors" in response_body and isinstance(response_body["errors"], list):
+            # JSON:API format
+            first_error = response_body["errors"][0] if response_body["errors"] else {}
+            message = first_error.get("detail") or first_error.get("title") or message
+            errors = response_body["errors"]
+
+        # Extract validation errors
+        if "type_detail" in response_body:
+            errors = response_body.get("type_detail", [])
+
+    # Map status codes to exceptions
+    if status_code == 401:
+        raise HoneycombAuthError(message, status_code, request_id, response_body)
+    elif status_code == 403:
+        raise HoneycombForbiddenError(message, status_code, request_id, response_body)
+    elif status_code == 404:
+        raise HoneycombNotFoundError(message, status_code, request_id, response_body)
+    elif status_code == 422:
+        raise HoneycombValidationError(message, status_code, request_id, response_body, errors)
+    elif status_code == 429:
+        raise HoneycombRateLimitError(message, status_code, request_id, response_body, retry_after)
+    elif 500 <= status_code < 600:
+        raise HoneycombServerError(message, status_code, request_id, response_body)
+    else:
+        raise HoneycombAPIError(message, status_code, request_id, response_body)

honeycomb/models/__init__.py

@@ -0,0 +1,157 @@
+"""Pydantic models for Honeycomb API resources."""
+
+from .api_keys import ApiKey, ApiKeyCreate, ApiKeyType
+from .board_builder import (
+    BoardBuilder,
+    BoardBundle,
+    ExistingQueryPanel,
+    ExistingSLOPanel,
+    QueryBuilderPanel,
+    SLOBuilderPanel,
+    TextPanel,
+)
+from .boards import Board, BoardCreate
+from .burn_alerts import BurnAlert, BurnAlertCreate, BurnAlertRecipient, BurnAlertType
+from .columns import Column, ColumnCreate, ColumnType
+from .datasets import Dataset, DatasetCreate
+from .derived_columns import DerivedColumn, DerivedColumnBuilder, DerivedColumnCreate
+from .environments import Environment, EnvironmentColor, EnvironmentCreate, EnvironmentUpdate
+from .events import BatchEvent, BatchEventResult
+from .marker_builder import MarkerBuilder
+from .markers import Marker, MarkerCreate, MarkerSetting, MarkerSettingCreate
+from .queries import Query, QueryResult, QueryResultData, QuerySpec
+from .query_annotations import QueryAnnotation, QueryAnnotationCreate, QueryAnnotationSource
+from .query_builder import (
+    CalcOp,
+    Calculation,
+    Filter,
+    FilterCombination,
+    FilterOp,
+    Having,
+    Order,
+    OrderDirection,
+    QueryBuilder,
+)
+from .recipient_builder import RecipientBuilder, RecipientMixin
+from .recipients import Recipient, RecipientCreate, RecipientType
+from .service_map_dependencies import (
+    ServiceMapDependency,
+    ServiceMapDependencyRequest,
+    ServiceMapDependencyRequestCreate,
+    ServiceMapDependencyRequestStatus,
+    ServiceMapDependencyResult,
+    ServiceMapNode,
+    ServiceMapNodeType,
+)
+from .slo_builder import BurnAlertBuilder, BurnAlertDefinition, SLIDefinition, SLOBuilder, SLOBundle
+from .slos import SLI, SLO, SLOCreate
+from .tags_mixin import TagsMixin
+from .trigger_builder import TriggerBuilder, TriggerBundle
+from .triggers import (
+    Trigger,
+    TriggerAlertType,
+    TriggerCreate,
+    TriggerQuery,
+    TriggerThreshold,
+    TriggerThresholdOp,
+)
+
+__all__ = [
+    # Query Builder (enums and typed models)
+    "CalcOp",
+    "FilterOp",
+    "OrderDirection",
+    "FilterCombination",
+    "Calculation",
+    "Filter",
+    "Order",
+    "Having",
+    "QueryBuilder",
+    # Triggers
+    "Trigger",
+    "TriggerCreate",
+    "TriggerThreshold",
+    "TriggerThresholdOp",
+    "TriggerAlertType",
+    "TriggerQuery",
+    "TriggerBuilder",
+    "TriggerBundle",
+    # SLOs
+    "SLO",
+    "SLOCreate",
+    "SLI",
+    "SLOBuilder",
+    "SLOBundle",
+    "SLIDefinition",
+    "BurnAlertBuilder",
+    "BurnAlertDefinition",
+    # Datasets
+    "Dataset",
+    "DatasetCreate",
+    # Boards
+    "Board",
+    "BoardBuilder",
+    "BoardBundle",
+    "BoardCreate",
+    "ExistingQueryPanel",
+    "ExistingSLOPanel",
+    "QueryBuilderPanel",
+    "SLOBuilderPanel",
+    "TextPanel",
+    # Queries
+    "Query",
+    "QuerySpec",
+    "QueryResult",
+    "QueryResultData",
+    # Query Annotations
+    "QueryAnnotation",
+    "QueryAnnotationCreate",
+    "QueryAnnotationSource",
+    # Columns
+    "Column",
+    "ColumnCreate",
+    "ColumnType",
+    # Derived Columns (Calculated Fields)
+    "DerivedColumn",
+    "DerivedColumnCreate",
+    "DerivedColumnBuilder",
+    # Markers
+    "Marker",
+    "MarkerBuilder",
+    "MarkerCreate",
+    "MarkerSetting",
+    "MarkerSettingCreate",
+    # Recipients
+    "Recipient",
+    "RecipientCreate",
+    "RecipientType",
+    "RecipientBuilder",
+    "RecipientMixin",
+    # Tags
+    "TagsMixin",
+    # Burn Alerts
+    "BurnAlert",
+    "BurnAlertCreate",
+    "BurnAlertRecipient",
+    "BurnAlertType",
+    # Events
+    "BatchEvent",
+    "BatchEventResult",
+    # API Keys (v2)
+    "ApiKey",
+    "ApiKeyCreate",
+    "ApiKeyType",
+    # Environments (v2)
+    "Environment",
+    "EnvironmentCreate",
+    "EnvironmentUpdate",
+    "EnvironmentColor",
+    # Service Map Dependencies
+    "ServiceMapDependency",
+    "ServiceMapDependencyRequest",
+    "ServiceMapDependencyRequestCreate",
+    "ServiceMapDependencyRequestStatus",
+    "ServiceMapDependencyResult",
+    "ServiceMapNode",
+    "ServiceMapNodeType",
+]

honeycomb/models/api_keys.py

@@ -0,0 +1,81 @@
+"""Pydantic models for Honeycomb API Keys (v2 team-scoped)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ApiKeyType(str, Enum):
+    """API key types."""
+
+    INGEST = "ingest"
+    CONFIGURATION = "configuration"
+
+
+class ApiKeyCreate(BaseModel):
+    """Model for creating a new API key."""
+
+    name: str = Field(description="Name for the API key")
+    key_type: ApiKeyType = Field(description="Type of API key")
+    environment_id: str = Field(description="Environment ID this key belongs to")
+    disabled: bool = Field(default=False, description="Whether key is disabled")
+
+    def to_jsonapi(self) -> dict[str, Any]:
+        """Convert to JSON:API format for API request."""
+        return {
+            "data": {
+                "type": "api-keys",
+                "attributes": {
+                    "name": self.name,
+                    "key_type": self.key_type.value,
+                    "disabled": self.disabled,
+                },
+                "relationships": {
+                    "environment": {"data": {"type": "environments", "id": self.environment_id}}
+                },
+            }
+        }
+
+
+class ApiKey(BaseModel):
+    """A Honeycomb API key (response model)."""
+
+    id: str = Field(description="Unique identifier (includes key prefix)")
+    name: str = Field(description="Name of the API key")
+    key_type: ApiKeyType = Field(description="Type of API key")
+    environment_id: str | None = Field(default=None, description="Environment ID")
+    disabled: bool = Field(default=False, description="Whether key is disabled")
+    secret: str | None = Field(
+        default=None, description="Key secret (only available during creation)"
+    )
+    created_at: datetime | None = Field(default=None, description="Creation timestamp")
+    updated_at: datetime | None = Field(default=None, description="Last update timestamp")
+
+    model_config = {"extra": "allow"}
+
+    @classmethod
+    def from_jsonapi(cls, data: dict[str, Any]) -> ApiKey:
+        """Parse from JSON:API format."""
+        obj = data.get("data", data)  # Handle both wrapped and unwrapped
+        attributes = obj.get("attributes", {})
+        relationships = obj.get("relationships", {})
+
+        env_id = None
+        if "environment" in relationships:
+            env_data = relationships["environment"].get("data", {})
+            env_id = env_data.get("id")
+
+        return cls(
+            id=obj.get("id", ""),
+            name=attributes.get("name", ""),
+            key_type=attributes.get("key_type", "ingest"),
+            environment_id=env_id,
+            disabled=attributes.get("disabled", False),
+            secret=attributes.get("secret"),
+            created_at=attributes.get("created_at"),
+            updated_at=attributes.get("updated_at"),
+        )