honeycomb-api 0.1.0__py3-none-any.whl

honeycomb/models/datasets.py

@@ -0,0 +1,51 @@
+"""Pydantic models for Honeycomb Datasets."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class DatasetCreate(BaseModel):
+    """Model for creating a new dataset."""
+
+    name: str = Field(description="Human-readable name for the dataset")
+    description: str | None = Field(default=None, description="Longer description")
+    expand_json_depth: int = Field(
+        default=0,
+        ge=0,
+        le=10,
+        description="Depth to expand JSON fields (0-10)",
+    )
+
+    def model_dump_for_api(self) -> dict[str, Any]:
+        """Serialize for API request."""
+        data: dict[str, Any] = {
+            "name": self.name,
+        }
+
+        if self.description:
+            data["description"] = self.description
+
+        if self.expand_json_depth > 0:
+            data["expand_json_depth"] = self.expand_json_depth
+
+        return data
+
+
+class Dataset(BaseModel):
+    """A Honeycomb dataset (response model)."""
+
+    name: str = Field(description="Dataset name")
+    slug: str = Field(description="URL-safe identifier")
+    description: str | None = Field(default=None, description="Longer description")
+    expand_json_depth: int = Field(default=0, description="JSON expansion depth")
+    created_at: datetime | None = Field(default=None, description="Creation timestamp")
+    last_written_at: datetime | None = Field(
+        default=None, description="Last event written timestamp"
+    )
+    regular_columns_count: int | None = Field(default=None, description="Number of regular columns")
+
+    model_config = {"extra": "allow"}

honeycomb/models/derived_columns.py

@@ -0,0 +1,107 @@
+"""Pydantic models and builder for Honeycomb Derived Columns (Calculated Fields)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+from typing_extensions import Self
+
+
+class DerivedColumnCreate(BaseModel):
+    """Model for creating a derived column (calculated field).
+
+    Derived columns (also called Calculated Fields) allow you to run queries
+    based on the value of an expression that is calculated from the fields in an event.
+    """
+
+    alias: str = Field(description="Name of the derived column")
+    expression: str = Field(
+        description="Expression to calculate the value. See https://docs.honeycomb.io/reference/derived-column-formula/"
+    )
+    description: str | None = Field(default=None, description="Human-readable description")
+
+    def model_dump_for_api(self) -> dict[str, Any]:
+        """Serialize for API request."""
+        data = {"alias": self.alias, "expression": self.expression}
+        if self.description:
+            data["description"] = self.description
+        return data
+
+
+class DerivedColumn(BaseModel):
+    """A derived column (calculated field) response model."""
+
+    id: str = Field(description="Unique identifier")
+    alias: str = Field(description="Name of the derived column")
+    expression: str = Field(description="Expression to calculate the value")
+    description: str | None = Field(default=None, description="Human-readable description")
+    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"}
+
+
+class DerivedColumnBuilder:
+    """Builder for derived columns.
+
+    Example:
+        >>> dc = (
+        ...     DerivedColumnBuilder("request_success")
+        ...     .expression("IF(LT($status_code, 400), 1, 0)")
+        ...     .description("1 if request succeeded, 0 otherwise")
+        ...     .build()
+        ... )
+        >>> await client.derived_columns.create_async(dataset="api-logs", derived_column=dc)
+    """
+
+    def __init__(self, alias: str):
+        """Initialize builder with column alias.
+
+        Args:
+            alias: Name of the derived column.
+        """
+        self._alias = alias
+        self._expression: str | None = None
+        self._description: str | None = None
+
+    def expression(self, expr: str) -> Self:
+        """Set the expression for the derived column.
+
+        Args:
+            expr: Expression to calculate the value.
+                See https://docs.honeycomb.io/reference/derived-column-formula/
+
+        Returns:
+            Self for method chaining.
+        """
+        self._expression = expr
+        return self
+
+    def description(self, desc: str) -> Self:
+        """Set the description.
+
+        Args:
+            desc: Human-readable description.
+
+        Returns:
+            Self for method chaining.
+        """
+        self._description = desc
+        return self
+
+    def build(self) -> DerivedColumnCreate:
+        """Build DerivedColumnCreate object.
+
+        Returns:
+            DerivedColumnCreate object ready for API submission.
+
+        Raises:
+            ValueError: If expression is not set.
+        """
+        if not self._expression:
+            raise ValueError("Expression is required")
+        return DerivedColumnCreate(
+            alias=self._alias, expression=self._expression, description=self._description
+        )

honeycomb/models/environments.py

@@ -0,0 +1,106 @@
+"""Pydantic models for Honeycomb Environments (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 EnvironmentColor(str, Enum):
+    """Environment display colors.
+
+    Note: 'classic' is a special color used only for auto-created Classic environments
+    and cannot be set on any other environment. Classic environments cannot be set
+    to any other color.
+    """
+
+    BLUE = "blue"
+    GREEN = "green"
+    GOLD = "gold"
+    RED = "red"
+    PURPLE = "purple"
+    LIGHT_BLUE = "lightBlue"
+    LIGHT_GREEN = "lightGreen"
+    LIGHT_GOLD = "lightGold"
+    LIGHT_RED = "lightRed"
+    LIGHT_PURPLE = "lightPurple"
+    # Special read-only color for Classic environments
+    CLASSIC = "classic"
+
+
+class EnvironmentCreate(BaseModel):
+    """Model for creating a new environment."""
+
+    name: str = Field(description="Name for the environment", max_length=255)
+    description: str | None = Field(
+        default=None, description="Description of the environment", max_length=255
+    )
+    color: EnvironmentColor | None = Field(default=None, description="Display color")
+
+    def to_jsonapi(self) -> dict[str, Any]:
+        """Convert to JSON:API format for API request."""
+        attributes: dict[str, Any] = {"name": self.name}
+        if self.description:
+            attributes["description"] = self.description
+        if self.color:
+            attributes["color"] = self.color.value
+
+        return {"data": {"type": "environments", "attributes": attributes}}
+
+
+class EnvironmentUpdate(BaseModel):
+    """Model for updating an environment."""
+
+    description: str | None = Field(default=None, description="Description", max_length=255)
+    color: EnvironmentColor | None = Field(default=None, description="Display color")
+    delete_protected: bool | None = Field(
+        default=None, description="If true, environment cannot be deleted"
+    )
+
+    def to_jsonapi(self, env_id: str) -> dict[str, Any]:
+        """Convert to JSON:API format for API request."""
+        attributes: dict[str, Any] = {}
+        if self.description is not None:
+            attributes["description"] = self.description
+        if self.color:
+            attributes["color"] = self.color.value
+        if self.delete_protected is not None:
+            attributes["settings"] = {"delete_protected": self.delete_protected}
+
+        return {"data": {"id": env_id, "type": "environments", "attributes": attributes}}
+
+
+class Environment(BaseModel):
+    """A Honeycomb environment (response model)."""
+
+    id: str = Field(description="Unique identifier")
+    name: str = Field(description="Name of the environment")
+    slug: str = Field(description="URL-friendly slug")
+    description: str | None = Field(default=None, description="Description")
+    color: EnvironmentColor | None = Field(default=None, description="Display color")
+    delete_protected: bool = Field(default=False, description="Whether delete-protected")
+    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]) -> Environment:
+        """Parse from JSON:API format."""
+        obj = data.get("data", data)  # Handle both wrapped and unwrapped
+        attributes = obj.get("attributes", {})
+        settings = attributes.get("settings", {})
+
+        return cls(
+            id=obj.get("id", ""),
+            name=attributes.get("name", ""),
+            slug=attributes.get("slug", ""),
+            description=attributes.get("description"),
+            color=attributes.get("color"),
+            delete_protected=settings.get("delete_protected", False),
+            created_at=attributes.get("created_at"),
+            updated_at=attributes.get("updated_at"),
+        )

honeycomb/models/events.py

@@ -0,0 +1,35 @@
+"""Pydantic models for Honeycomb Events (data ingestion)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class BatchEvent(BaseModel):
+    """Model for a batch event."""
+
+    data: dict[str, Any] = Field(description="Event payload (key-value pairs)")
+    time: str | None = Field(
+        default=None, description="Event timestamp (ISO8601 format). Defaults to server time."
+    )
+    samplerate: int | None = Field(default=None, description="Sample rate. Defaults to 1.")
+
+    def model_dump_for_api(self) -> dict:
+        """Serialize for API request."""
+        result: dict[str, Any] = {"data": self.data}
+        if self.time:
+            result["time"] = self.time
+        if self.samplerate:
+            result["samplerate"] = self.samplerate
+        return result
+
+
+class BatchEventResult(BaseModel):
+    """Result for a single event in a batch."""
+
+    status: int = Field(description="HTTP status code for this event")
+    error: str | None = Field(default=None, description="Error message if status != 202")
+
+    model_config = {"extra": "allow"}

honeycomb/models/marker_builder.py

@@ -0,0 +1,136 @@
+"""Marker Builder - Fluent interface for creating markers."""
+
+from __future__ import annotations
+
+import time
+
+from honeycomb.models.markers import MarkerCreate, MarkerSettingCreate
+
+
+class MarkerBuilder:
+    """Fluent builder for markers.
+
+    Example - Point marker:
+        marker = (
+            MarkerBuilder("Deployed v1.2.3")
+            .type("deploy")
+            .url("https://github.com/org/repo/releases/v1.2.3")
+            .build()
+        )
+
+    Example - Duration marker:
+        marker = (
+            MarkerBuilder("Maintenance window")
+            .type("maintenance")
+            .start_time(1703980800)
+            .end_time(1703984400)
+            .build()
+        )
+
+    Example - Duration from now:
+        marker = (
+            MarkerBuilder("Load test in progress")
+            .type("test")
+            .duration_minutes(30)
+            .build()
+        )
+    """
+
+    def __init__(self, message: str):
+        self._message = message
+        self._type: str | None = None
+        self._start_time: int | None = None
+        self._end_time: int | None = None
+        self._url: str | None = None
+
+    def type(self, marker_type: str) -> MarkerBuilder:
+        """Set marker type (groups similar markers).
+
+        Args:
+            marker_type: Type identifier (e.g., "deploy", "maintenance", "incident")
+        """
+        self._type = marker_type
+        return self
+
+    def url(self, url: str) -> MarkerBuilder:
+        """Set target URL for the marker.
+
+        Args:
+            url: URL to link to (e.g., deployment, incident, PR)
+        """
+        self._url = url
+        return self
+
+    def start_time(self, timestamp: int) -> MarkerBuilder:
+        """Set start time as Unix timestamp.
+
+        Args:
+            timestamp: Unix timestamp in seconds
+        """
+        self._start_time = timestamp
+        return self
+
+    def end_time(self, timestamp: int) -> MarkerBuilder:
+        """Set end time as Unix timestamp (for duration markers).
+
+        Args:
+            timestamp: Unix timestamp in seconds
+        """
+        self._end_time = timestamp
+        return self
+
+    def duration_minutes(self, minutes: int) -> MarkerBuilder:
+        """Set duration from now.
+
+        Args:
+            minutes: Duration in minutes from current time
+        """
+        now = int(time.time())
+        self._start_time = now
+        self._end_time = now + (minutes * 60)
+        return self
+
+    def duration_hours(self, hours: int) -> MarkerBuilder:
+        """Set duration from now in hours.
+
+        Args:
+            hours: Duration in hours from current time
+        """
+        return self.duration_minutes(hours * 60)
+
+    @staticmethod
+    def setting(marker_type: str, color: str) -> MarkerSettingCreate:
+        """Create a marker setting (color configuration).
+
+        Args:
+            marker_type: Type of marker to configure
+            color: Hex color code (e.g., '#F96E11')
+
+        Returns:
+            MarkerSettingCreate object
+
+        Example:
+            >>> setting = MarkerBuilder.setting("deploy", "#00FF00")
+            >>> await client.markers.create_setting_async(setting)
+        """
+        return MarkerSettingCreate(type=marker_type, color=color)
+
+    def build(self) -> MarkerCreate:
+        """Build MarkerCreate with validation.
+
+        Returns:
+            MarkerCreate object ready to be sent to the API
+
+        Raises:
+            ValueError: If marker type is missing
+        """
+        if not self._type:
+            raise ValueError("Marker type is required. Use type().")
+
+        return MarkerCreate(
+            message=self._message,
+            type=self._type,
+            start_time=self._start_time,
+            end_time=self._end_time,
+            url=self._url,
+        )

honeycomb/models/markers.py

@@ -0,0 +1,73 @@
+"""Pydantic models for Honeycomb Markers."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class MarkerCreate(BaseModel):
+    """Model for creating a new marker."""
+
+    message: str = Field(description="Message to describe this marker")
+    type: str = Field(description="Groups similar markers (e.g., 'deploy')")
+    start_time: int | None = Field(
+        default=None,
+        description="Unix timestamp when marker should be placed (defaults to now)",
+    )
+    end_time: int | None = Field(
+        default=None, description="Unix timestamp for end of marker (for time ranges)"
+    )
+    url: str | None = Field(default=None, description="Target URL for the marker")
+
+    def model_dump_for_api(self) -> dict[str, Any]:
+        """Serialize for API request."""
+        data: dict[str, Any] = {"message": self.message, "type": self.type}
+        if self.start_time is not None:
+            data["start_time"] = self.start_time
+        if self.end_time is not None:
+            data["end_time"] = self.end_time
+        if self.url:
+            data["url"] = self.url
+        return data
+
+
+class Marker(BaseModel):
+    """A Honeycomb marker (response model)."""
+
+    id: str = Field(description="Unique identifier (6 character hex)")
+    message: str = Field(description="Message describing this marker")
+    type: str = Field(description="Groups similar markers")
+    start_time: int = Field(description="Unix timestamp when marker is placed")
+    end_time: int | None = Field(default=None, description="Unix timestamp for end of marker")
+    url: str | None = Field(default=None, description="Target URL for the marker")
+    color: str | None = Field(default=None, description="Hex color code (from marker settings)")
+    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"}
+
+
+class MarkerSettingCreate(BaseModel):
+    """Model for creating a new marker setting."""
+
+    type: str = Field(description="Marker type to configure")
+    color: str = Field(description="Hex color code (e.g., '#F96E11')")
+
+    def model_dump_for_api(self) -> dict[str, str]:
+        """Serialize for API request."""
+        return {"type": self.type, "color": self.color}
+
+
+class MarkerSetting(BaseModel):
+    """A Honeycomb marker setting (response model)."""
+
+    id: str = Field(description="Unique identifier")
+    type: str = Field(description="Marker type")
+    color: str = Field(description="Hex color code")
+    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"}