honeycomb-api 0.1.0__py3-none-any.whl

honeycomb/resources/boards.py

@@ -0,0 +1,350 @@
+"""Boards resource for Honeycomb API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ..models.boards import Board, BoardCreate
+from .base import BaseResource
+
+if TYPE_CHECKING:
+    from ..client import HoneycombClient
+    from ..models.board_builder import BoardBundle
+
+
+class BoardsResource(BaseResource):
+    """Resource for managing Honeycomb boards.
+
+    Boards are dashboards that display visualizations of your data.
+
+    Example (async):
+        >>> async with HoneycombClient(api_key="...") as client:
+        ...     boards = await client.boards.list()
+        ...     board = await client.boards.get(board_id="abc123")
+
+    Example (sync):
+        >>> with HoneycombClient(api_key="...", sync=True) as client:
+        ...     boards = client.boards.list()
+    """
+
+    def __init__(self, client: HoneycombClient) -> None:
+        super().__init__(client)
+
+    def _build_path(self, board_id: str | None = None) -> str:
+        """Build API path for boards."""
+        base = "/1/boards"
+        if board_id:
+            return f"{base}/{board_id}"
+        return base
+
+    # -------------------------------------------------------------------------
+    # Async methods
+    # -------------------------------------------------------------------------
+
+    async def list_async(self) -> list[Board]:
+        """List all boards (async).
+
+        Returns:
+            List of Board objects.
+        """
+        data = await self._get_async(self._build_path())
+        return self._parse_model_list(Board, data)
+
+    async def get_async(self, board_id: str) -> Board:
+        """Get a specific board (async).
+
+        Args:
+            board_id: Board ID.
+
+        Returns:
+            Board object.
+        """
+        data = await self._get_async(self._build_path(board_id))
+        return self._parse_model(Board, data)
+
+    async def create_async(self, board: BoardCreate) -> Board:
+        """Create a new board (async).
+
+        Args:
+            board: Board configuration.
+
+        Returns:
+            Created Board object.
+        """
+        data = await self._post_async(self._build_path(), json=board.model_dump_for_api())
+        return self._parse_model(Board, data)
+
+    async def update_async(self, board_id: str, board: BoardCreate) -> Board:
+        """Update an existing board (async).
+
+        Args:
+            board_id: Board ID.
+            board: Updated board configuration.
+
+        Returns:
+            Updated Board object.
+        """
+        data = await self._put_async(self._build_path(board_id), json=board.model_dump_for_api())
+        return self._parse_model(Board, data)
+
+    async def delete_async(self, board_id: str) -> None:
+        """Delete a board (async).
+
+        Args:
+            board_id: Board ID.
+        """
+        await self._delete_async(self._build_path(board_id))
+
+    async def create_from_bundle_async(self, bundle: BoardBundle) -> Board:
+        """Create board from BoardBundle with automatic query creation.
+
+        Orchestrates:
+        1. Create queries + annotations from QueryBuilder instances
+        2. Assemble all panel configurations
+        3. Create board with all panels
+
+        Panels are added to the board in the order they appear in the bundle:
+        - Auto-layout: Honeycomb arranges panels in this order
+        - Manual-layout: Respects explicit positions
+
+        Args:
+            bundle: BoardBundle from BoardBuilder.build()
+
+        Returns:
+            Created Board object
+
+        Example:
+            >>> board = await client.boards.create_from_bundle_async(
+            ...     BoardBuilder("Dashboard")
+            ...         .auto_layout()
+            ...         .query(
+            ...             QueryBuilder("Request Count")
+            ...                 .dataset("api-logs")
+            ...                 .last_1_hour()
+            ...                 .count()
+            ...         )
+            ...         .build()
+            ... )
+        """
+
+        panels = []
+
+        # Create query panels from QueryBuilder instances
+        for qb_panel in bundle.query_builder_panels:
+            # Apply dataset override if specified
+            if qb_panel.dataset_override:
+                # Temporarily override the dataset on the builder
+                original_dataset = qb_panel.builder.get_dataset()
+                qb_panel.builder.dataset(qb_panel.dataset_override)
+                query, annotation_id = await self._client.queries.create_with_annotation_async(
+                    qb_panel.builder
+                )
+                # Restore original dataset
+                qb_panel.builder.dataset(original_dataset)
+            else:
+                query, annotation_id = await self._client.queries.create_with_annotation_async(
+                    qb_panel.builder
+                )
+            panels.append(
+                self._build_query_panel_dict(
+                    query.id,
+                    annotation_id,
+                    qb_panel.position,
+                    qb_panel.style,
+                    qb_panel.visualization,
+                )
+            )
+
+        # Add existing query panels
+        for existing in bundle.existing_query_panels:
+            panels.append(
+                self._build_query_panel_dict(
+                    existing.query_id,
+                    existing.annotation_id,
+                    existing.position,
+                    existing.style,
+                    existing.visualization,
+                )
+            )
+
+        # Create SLOs from SLOBuilder instances
+        for slo_panel in bundle.slo_builder_panels:
+            # Create SLO using existing orchestration
+            slo_dict = await self._client.slos.create_from_bundle_async(slo_panel.builder.build())
+            # Get first SLO (should only be one dataset for board usage)
+            slo = next(iter(slo_dict.values()))
+            panels.append(self._build_slo_panel_dict(slo.id, slo_panel.position))
+
+        # Add existing SLO panels
+        for slo_existing in bundle.existing_slo_panels:
+            panels.append(self._build_slo_panel_dict(slo_existing.slo_id, slo_existing.position))
+
+        # Add text panels
+        for text in bundle.text_panels:
+            panels.append(self._build_text_panel_dict(text.content, text.position))
+
+        # Create board
+        board_create = BoardCreate(
+            name=bundle.board_name,
+            description=bundle.board_description,
+            type="flexible",
+            panels=panels if panels else None,
+            layout_generation=bundle.layout_generation,
+            tags=bundle.tags,
+            preset_filters=bundle.preset_filters,
+        )
+
+        return await self.create_async(board_create)
+
+    def _build_query_panel_dict(
+        self,
+        query_id: str,
+        annotation_id: str,
+        position: tuple[int, int, int, int] | None,
+        style: str,
+        visualization: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        """Build query panel dictionary for API."""
+        query_panel: dict[str, Any] = {
+            "query_id": query_id,
+            "query_annotation_id": annotation_id,
+            "query_style": style,
+        }
+        # Dataset is not included - query already knows its scope
+        if visualization:
+            query_panel["visualization_settings"] = visualization
+
+        panel: dict[str, Any] = {
+            "type": "query",
+            "query_panel": query_panel,
+        }
+        if position:
+            panel["position"] = {
+                "x_coordinate": position[0],
+                "y_coordinate": position[1],
+                "width": position[2],
+                "height": position[3],
+            }
+        return panel
+
+    def _build_slo_panel_dict(
+        self,
+        slo_id: str,
+        position: tuple[int, int, int, int] | None,
+    ) -> dict[str, Any]:
+        """Build SLO panel dictionary for API."""
+        panel = {"type": "slo", "slo_panel": {"slo_id": slo_id}}
+        if position:
+            panel["position"] = {
+                "x_coordinate": position[0],
+                "y_coordinate": position[1],
+                "width": position[2],
+                "height": position[3],
+            }
+        return panel
+
+    def _build_text_panel_dict(
+        self,
+        content: str,
+        position: tuple[int, int, int, int] | None,
+    ) -> dict[str, Any]:
+        """Build text panel dictionary for API."""
+        panel = {"type": "text", "text_panel": {"content": content}}
+        if position:
+            panel["position"] = {
+                "x_coordinate": position[0],
+                "y_coordinate": position[1],
+                "width": position[2],
+                "height": position[3],
+            }
+        return panel
+
+    # -------------------------------------------------------------------------
+    # Sync methods
+    # -------------------------------------------------------------------------
+
+    def list(self) -> list[Board]:
+        """List all boards.
+
+        Returns:
+            List of Board objects.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use list_async() for async mode, or pass sync=True to client")
+        data = self._get_sync(self._build_path())
+        return self._parse_model_list(Board, data)
+
+    def get(self, board_id: str) -> Board:
+        """Get a specific board.
+
+        Args:
+            board_id: Board ID.
+
+        Returns:
+            Board object.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use get_async() for async mode, or pass sync=True to client")
+        data = self._get_sync(self._build_path(board_id))
+        return self._parse_model(Board, data)
+
+    def create(self, board: BoardCreate) -> Board:
+        """Create a new board.
+
+        Args:
+            board: Board configuration.
+
+        Returns:
+            Created Board object.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use create_async() for async mode, or pass sync=True to client")
+        data = self._post_sync(self._build_path(), json=board.model_dump_for_api())
+        return self._parse_model(Board, data)
+
+    def update(self, board_id: str, board: BoardCreate) -> Board:
+        """Update an existing board.
+
+        Args:
+            board_id: Board ID.
+            board: Updated board configuration.
+
+        Returns:
+            Updated Board object.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use update_async() for async mode, or pass sync=True to client")
+        data = self._put_sync(self._build_path(board_id), json=board.model_dump_for_api())
+        return self._parse_model(Board, data)
+
+    def delete(self, board_id: str) -> None:
+        """Delete a board.
+
+        Args:
+            board_id: Board ID.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use delete_async() for async mode, or pass sync=True to client")
+        self._delete_sync(self._build_path(board_id))
+
+    def create_from_bundle(self, bundle: BoardBundle) -> Board:
+        """Create board from BoardBundle with automatic query creation (sync).
+
+        Orchestrates:
+        1. Create queries + annotations from QueryBuilder instances
+        2. Assemble all panel configurations
+        3. Create board with all panels
+
+        Args:
+            bundle: BoardBundle from BoardBuilder.build()
+
+        Returns:
+            Created Board object
+        """
+        if not self._client.is_sync:
+            raise RuntimeError(
+                "Use create_from_bundle_async() for async mode, or pass sync=True to client"
+            )
+        import asyncio
+
+        return asyncio.run(self.create_from_bundle_async(bundle))

honeycomb/resources/burn_alerts.py

@@ -0,0 +1,205 @@
+"""Burn Alerts resource for Honeycomb API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..models.burn_alerts import BurnAlert, BurnAlertCreate
+from .base import BaseResource
+
+if TYPE_CHECKING:
+    from ..client import HoneycombClient
+
+
+class BurnAlertsResource(BaseResource):
+    """Resource for managing SLO burn alerts.
+
+    Burn alerts notify you when you're consuming your SLO error budget too quickly.
+    Two alert types are supported:
+    - exhaustion_time: Alerts when budget will be exhausted within X minutes
+    - budget_rate: Alerts when budget drops by X% within a time window
+
+    Example (async):
+        >>> async with HoneycombClient(api_key="...") as client:
+        ...     alerts = await client.burn_alerts.list(
+        ...         dataset="my-dataset",
+        ...         slo_id="abc123"
+        ...     )
+        ...     alert = await client.burn_alerts.create(
+        ...         dataset="my-dataset",
+        ...         burn_alert=BurnAlertCreate(
+        ...             alert_type=BurnAlertType.EXHAUSTION_TIME,
+        ...             slo_id="abc123",
+        ...             exhaustion_minutes=120
+        ...         )
+        ...     )
+
+    Example (sync):
+        >>> with HoneycombClient(api_key="...", sync=True) as client:
+        ...     alerts = client.burn_alerts.list(
+        ...         dataset="my-dataset",
+        ...         slo_id="abc123"
+        ...     )
+    """
+
+    def __init__(self, client: HoneycombClient) -> None:
+        super().__init__(client)
+
+    def _build_path(self, dataset: str, burn_alert_id: str | None = None) -> str:
+        """Build API path for burn alerts."""
+        base = f"/1/burn_alerts/{dataset}"
+        if burn_alert_id:
+            return f"{base}/{burn_alert_id}"
+        return base
+
+    # -------------------------------------------------------------------------
+    # Async methods
+    # -------------------------------------------------------------------------
+
+    async def list_async(self, dataset: str, slo_id: str) -> list[BurnAlert]:
+        """List all burn alerts for an SLO (async).
+
+        Args:
+            dataset: Dataset slug.
+            slo_id: SLO ID to list burn alerts for.
+
+        Returns:
+            List of BurnAlert objects.
+        """
+        path = f"{self._build_path(dataset)}?slo_id={slo_id}"
+        data = await self._get_async(path)
+        return self._parse_model_list(BurnAlert, data)
+
+    async def get_async(self, dataset: str, burn_alert_id: str) -> BurnAlert:
+        """Get a specific burn alert (async).
+
+        Args:
+            dataset: Dataset slug.
+            burn_alert_id: Burn Alert ID.
+
+        Returns:
+            BurnAlert object.
+        """
+        data = await self._get_async(self._build_path(dataset, burn_alert_id))
+        return self._parse_model(BurnAlert, data)
+
+    async def create_async(self, dataset: str, burn_alert: BurnAlertCreate) -> BurnAlert:
+        """Create a new burn alert (async).
+
+        Args:
+            dataset: Dataset slug.
+            burn_alert: Burn alert configuration.
+
+        Returns:
+            Created BurnAlert object.
+        """
+        data = await self._post_async(
+            self._build_path(dataset), json=burn_alert.model_dump_for_api()
+        )
+        return self._parse_model(BurnAlert, data)
+
+    async def update_async(
+        self, dataset: str, burn_alert_id: str, burn_alert: BurnAlertCreate
+    ) -> BurnAlert:
+        """Update an existing burn alert (async).
+
+        Args:
+            dataset: Dataset slug.
+            burn_alert_id: Burn Alert ID.
+            burn_alert: Updated burn alert configuration.
+
+        Returns:
+            Updated BurnAlert object.
+        """
+        data = await self._put_async(
+            self._build_path(dataset, burn_alert_id), json=burn_alert.model_dump_for_api()
+        )
+        return self._parse_model(BurnAlert, data)
+
+    async def delete_async(self, dataset: str, burn_alert_id: str) -> None:
+        """Delete a burn alert (async).
+
+        Args:
+            dataset: Dataset slug.
+            burn_alert_id: Burn Alert ID.
+        """
+        await self._delete_async(self._build_path(dataset, burn_alert_id))
+
+    # -------------------------------------------------------------------------
+    # Sync methods
+    # -------------------------------------------------------------------------
+
+    def list(self, dataset: str, slo_id: str) -> list[BurnAlert]:
+        """List all burn alerts for an SLO.
+
+        Args:
+            dataset: Dataset slug.
+            slo_id: SLO ID to list burn alerts for.
+
+        Returns:
+            List of BurnAlert objects.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use list_async() for async mode, or pass sync=True to client")
+        path = f"{self._build_path(dataset)}?slo_id={slo_id}"
+        data = self._get_sync(path)
+        return self._parse_model_list(BurnAlert, data)
+
+    def get(self, dataset: str, burn_alert_id: str) -> BurnAlert:
+        """Get a specific burn alert.
+
+        Args:
+            dataset: Dataset slug.
+            burn_alert_id: Burn Alert ID.
+
+        Returns:
+            BurnAlert object.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use get_async() for async mode, or pass sync=True to client")
+        data = self._get_sync(self._build_path(dataset, burn_alert_id))
+        return self._parse_model(BurnAlert, data)
+
+    def create(self, dataset: str, burn_alert: BurnAlertCreate) -> BurnAlert:
+        """Create a new burn alert.
+
+        Args:
+            dataset: Dataset slug.
+            burn_alert: Burn alert configuration.
+
+        Returns:
+            Created BurnAlert object.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use create_async() for async mode, or pass sync=True to client")
+        data = self._post_sync(self._build_path(dataset), json=burn_alert.model_dump_for_api())
+        return self._parse_model(BurnAlert, data)
+
+    def update(self, dataset: str, burn_alert_id: str, burn_alert: BurnAlertCreate) -> BurnAlert:
+        """Update an existing burn alert.
+
+        Args:
+            dataset: Dataset slug.
+            burn_alert_id: Burn Alert ID.
+            burn_alert: Updated burn alert configuration.
+
+        Returns:
+            Updated BurnAlert object.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use update_async() for async mode, or pass sync=True to client")
+        data = self._put_sync(
+            self._build_path(dataset, burn_alert_id), json=burn_alert.model_dump_for_api()
+        )
+        return self._parse_model(BurnAlert, data)
+
+    def delete(self, dataset: str, burn_alert_id: str) -> None:
+        """Delete a burn alert.
+
+        Args:
+            dataset: Dataset slug.
+            burn_alert_id: Burn Alert ID.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use delete_async() for async mode, or pass sync=True to client")
+        self._delete_sync(self._build_path(dataset, burn_alert_id))