honeycomb-api 0.1.0__py3-none-any.whl

honeycomb/resources/environments.py

@@ -0,0 +1,295 @@
+"""Environments resource for Honeycomb API (v2 team-scoped)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from urllib.parse import parse_qs, urlparse
+
+from ..models.environments import Environment, EnvironmentCreate, EnvironmentUpdate
+from .base import BaseResource
+
+if TYPE_CHECKING:
+    from ..client import HoneycombClient
+
+# Default page size for pagination (API max is 100)
+DEFAULT_PAGE_SIZE = 100
+
+
+class EnvironmentsResource(BaseResource):
+    """Resource for managing environments (v2 team-scoped).
+
+    This resource requires Management Key authentication and operates
+    on a specific team. Environments help organize your data and API keys.
+
+    Note:
+        The list methods automatically paginate through all results. For teams
+        with many environments, this may result in multiple API requests. The default
+        rate limit is 100 requests per minute per operation. If you need higher
+        limits, contact Honeycomb support: https://www.honeycomb.io/support
+
+    Example (async):
+        >>> async with HoneycombClient(
+        ...     management_key="hcamk_xxx",
+        ...     management_secret="xxx"
+        ... ) as client:
+        ...     envs = await client.environments.list_async(team="my-team")
+        ...     env = await client.environments.create_async(
+        ...         team="my-team",
+        ...         environment=EnvironmentCreate(
+        ...             name="Production",
+        ...             description="Production environment",
+        ...             color=EnvironmentColor.RED
+        ...         )
+        ...     )
+
+    Example (sync):
+        >>> with HoneycombClient(
+        ...     management_key="hcamk_xxx",
+        ...     management_secret="xxx",
+        ...     sync=True
+        ... ) as client:
+        ...     envs = client.environments.list(team="my-team")
+    """
+
+    def __init__(self, client: HoneycombClient) -> None:
+        super().__init__(client)
+
+    def _build_path(self, team: str, env_id: str | None = None) -> str:
+        """Build API path for environments."""
+        base = f"/2/teams/{team}/environments"
+        if env_id:
+            return f"{base}/{env_id}"
+        return base
+
+    def _extract_cursor(self, next_link: str | None) -> str | None:
+        """Extract cursor value from pagination next link."""
+        if not next_link:
+            return None
+        parsed = urlparse(next_link)
+        query_params = parse_qs(parsed.query)
+        cursor_values = query_params.get("page[after]", [])
+        return cursor_values[0] if cursor_values else None
+
+    def _build_params(
+        self,
+        cursor: str | None = None,
+        page_size: int = DEFAULT_PAGE_SIZE,
+    ) -> dict[str, Any]:
+        """Build query parameters for list requests."""
+        params: dict[str, Any] = {"page[size]": page_size}
+        if cursor:
+            params["page[after]"] = cursor
+        return params
+
+    # -------------------------------------------------------------------------
+    # Async methods
+    # -------------------------------------------------------------------------
+
+    async def list_async(self, team: str) -> list[Environment]:
+        """List all environments for a team (async).
+
+        Automatically paginates through all results. For teams with many environments,
+        this may result in multiple API requests.
+
+        Args:
+            team: Team slug.
+
+        Returns:
+            List of Environment objects.
+
+        Note:
+            The default rate limit is 100 requests per minute per operation.
+            Contact Honeycomb support for higher limits: https://www.honeycomb.io/support
+        """
+        results: list[Environment] = []
+        cursor: str | None = None
+        path = self._build_path(team)
+
+        while True:
+            params = self._build_params(cursor=cursor)
+            data = await self._get_async(path, params=params)
+
+            # Parse JSON:API response
+            if isinstance(data, dict) and "data" in data:
+                items = data["data"]
+                results.extend(Environment.from_jsonapi({"data": item}) for item in items)
+
+                # Check for next page
+                next_link = data.get("links", {}).get("next")
+                cursor = self._extract_cursor(next_link)
+                if not cursor:
+                    break
+            else:
+                break
+
+        return results
+
+    async def get_async(self, team: str, env_id: str) -> Environment:
+        """Get a specific environment (async).
+
+        Args:
+            team: Team slug.
+            env_id: Environment ID.
+
+        Returns:
+            Environment object.
+        """
+        data = await self._get_async(self._build_path(team, env_id))
+        return Environment.from_jsonapi(data)
+
+    async def create_async(self, team: str, environment: EnvironmentCreate) -> Environment:
+        """Create a new environment (async).
+
+        Args:
+            team: Team slug.
+            environment: Environment configuration.
+
+        Returns:
+            Created Environment object.
+        """
+        data = await self._post_async(
+            self._build_path(team),
+            json=environment.to_jsonapi(),
+            headers={"Content-Type": "application/vnd.api+json"},
+        )
+        return Environment.from_jsonapi(data)
+
+    async def update_async(
+        self, team: str, env_id: str, environment: EnvironmentUpdate
+    ) -> Environment:
+        """Update an existing environment (async).
+
+        Args:
+            team: Team slug.
+            env_id: Environment ID.
+            environment: Updated environment configuration.
+
+        Returns:
+            Updated Environment object.
+        """
+        data = await self._patch_async(
+            self._build_path(team, env_id),
+            json=environment.to_jsonapi(env_id),
+            headers={"Content-Type": "application/vnd.api+json"},
+        )
+        return Environment.from_jsonapi(data)
+
+    async def delete_async(self, team: str, env_id: str) -> None:
+        """Delete an environment (async).
+
+        Args:
+            team: Team slug.
+            env_id: Environment ID.
+        """
+        await self._delete_async(self._build_path(team, env_id))
+
+    # -------------------------------------------------------------------------
+    # Sync methods
+    # -------------------------------------------------------------------------
+
+    def list(self, team: str) -> list[Environment]:
+        """List all environments for a team.
+
+        Automatically paginates through all results. For teams with many environments,
+        this may result in multiple API requests.
+
+        Args:
+            team: Team slug.
+
+        Returns:
+            List of Environment objects.
+
+        Note:
+            The default rate limit is 100 requests per minute per operation.
+            Contact Honeycomb support for higher limits: https://www.honeycomb.io/support
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use list_async() for async mode, or pass sync=True to client")
+
+        results: list[Environment] = []
+        cursor: str | None = None
+        path = self._build_path(team)
+
+        while True:
+            params = self._build_params(cursor=cursor)
+            data = self._get_sync(path, params=params)
+
+            # Parse JSON:API response
+            if isinstance(data, dict) and "data" in data:
+                items = data["data"]
+                results.extend(Environment.from_jsonapi({"data": item}) for item in items)
+
+                # Check for next page
+                next_link = data.get("links", {}).get("next")
+                cursor = self._extract_cursor(next_link)
+                if not cursor:
+                    break
+            else:
+                break
+
+        return results
+
+    def get(self, team: str, env_id: str) -> Environment:
+        """Get a specific environment.
+
+        Args:
+            team: Team slug.
+            env_id: Environment ID.
+
+        Returns:
+            Environment 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(team, env_id))
+        return Environment.from_jsonapi(data)
+
+    def create(self, team: str, environment: EnvironmentCreate) -> Environment:
+        """Create a new environment.
+
+        Args:
+            team: Team slug.
+            environment: Environment configuration.
+
+        Returns:
+            Created Environment 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(team),
+            json=environment.to_jsonapi(),
+            headers={"Content-Type": "application/vnd.api+json"},
+        )
+        return Environment.from_jsonapi(data)
+
+    def update(self, team: str, env_id: str, environment: EnvironmentUpdate) -> Environment:
+        """Update an existing environment.
+
+        Args:
+            team: Team slug.
+            env_id: Environment ID.
+            environment: Updated environment configuration.
+
+        Returns:
+            Updated Environment object.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use update_async() for async mode, or pass sync=True to client")
+        data = self._patch_sync(
+            self._build_path(team, env_id),
+            json=environment.to_jsonapi(env_id),
+            headers={"Content-Type": "application/vnd.api+json"},
+        )
+        return Environment.from_jsonapi(data)
+
+    def delete(self, team: str, env_id: str) -> None:
+        """Delete an environment.
+
+        Args:
+            team: Team slug.
+            env_id: Environment 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(team, env_id))

honeycomb/resources/events.py

@@ -0,0 +1,156 @@
+"""Events resource for Honeycomb API (data ingestion)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ..models.events import BatchEvent, BatchEventResult
+from .base import BaseResource
+
+if TYPE_CHECKING:
+    from ..client import HoneycombClient
+
+
+class EventsResource(BaseResource):
+    """Resource for sending events (data ingestion).
+
+    Events are the core telemetry data sent to Honeycomb. This resource
+    provides methods to send single events or batches of events.
+
+    Note: Batch sending is highly preferred over single events for efficiency.
+
+    Example (async):
+        >>> async with HoneycombClient(api_key="...") as client:
+        ...     # Send single event
+        ...     await client.events.send(
+        ...         dataset="my-dataset",
+        ...         data={"endpoint": "/api/users", "duration_ms": 42}
+        ...     )
+        ...     # Send batch of events
+        ...     results = await client.events.send_batch(
+        ...         dataset="my-dataset",
+        ...         events=[
+        ...             BatchEvent(data={"endpoint": "/api/users", "duration_ms": 42}),
+        ...             BatchEvent(data={"endpoint": "/api/posts", "duration_ms": 18}),
+        ...         ]
+        ...     )
+
+    Example (sync):
+        >>> with HoneycombClient(api_key="...", sync=True) as client:
+        ...     client.events.send(dataset="my-dataset", data={"key": "value"})
+    """
+
+    def __init__(self, client: HoneycombClient) -> None:
+        super().__init__(client)
+
+    # -------------------------------------------------------------------------
+    # Async methods
+    # -------------------------------------------------------------------------
+
+    async def send_async(
+        self,
+        dataset: str,
+        data: dict[str, Any],
+        timestamp: int | None = None,
+        samplerate: int | None = None,
+    ) -> None:
+        """Send a single event (async).
+
+        Note: For production use, prefer send_batch() for better efficiency.
+
+        Args:
+            dataset: Dataset slug.
+            data: Event payload (key-value pairs).
+            timestamp: Unix timestamp for the event (optional).
+            samplerate: Sample rate (optional, defaults to 1).
+        """
+        path = f"/1/events/{dataset}"
+        headers = {}
+        if timestamp is not None:
+            headers["X-Honeycomb-Event-Time"] = str(timestamp)
+        if samplerate is not None:
+            headers["X-Honeycomb-Samplerate"] = str(samplerate)
+
+        # Single event endpoint returns empty 200, don't try to parse JSON
+        await self._client.post_async(path, json=data, headers=headers)
+
+    async def send_batch_async(
+        self, dataset: str, events: list[BatchEvent]
+    ) -> list[BatchEventResult]:
+        """Send a batch of events (async).
+
+        This is the preferred method for sending events to Honeycomb.
+
+        Args:
+            dataset: Dataset slug.
+            events: List of BatchEvent objects.
+
+        Returns:
+            List of BatchEventResult objects indicating status for each event.
+        """
+        path = f"/1/batch/{dataset}"
+        payload = [event.model_dump_for_api() for event in events]
+        data = await self._post_async(path, json=payload)  # type: ignore[arg-type]
+
+        # Parse results
+        if isinstance(data, list):
+            return self._parse_model_list(BatchEventResult, data)
+        return []
+
+    # -------------------------------------------------------------------------
+    # Sync methods
+    # -------------------------------------------------------------------------
+
+    def send(
+        self,
+        dataset: str,
+        data: dict[str, Any],
+        timestamp: int | None = None,
+        samplerate: int | None = None,
+    ) -> None:
+        """Send a single event.
+
+        Note: For production use, prefer send_batch() for better efficiency.
+
+        Args:
+            dataset: Dataset slug.
+            data: Event payload (key-value pairs).
+            timestamp: Unix timestamp for the event (optional).
+            samplerate: Sample rate (optional, defaults to 1).
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use send_async() for async mode, or pass sync=True to client")
+
+        path = f"/1/events/{dataset}"
+        headers = {}
+        if timestamp is not None:
+            headers["X-Honeycomb-Event-Time"] = str(timestamp)
+        if samplerate is not None:
+            headers["X-Honeycomb-Samplerate"] = str(samplerate)
+
+        # Single event endpoint returns empty 200, don't try to parse JSON
+        self._client.post_sync(path, json=data, headers=headers)
+
+    def send_batch(self, dataset: str, events: list[BatchEvent]) -> list[BatchEventResult]:
+        """Send a batch of events.
+
+        This is the preferred method for sending events to Honeycomb.
+
+        Args:
+            dataset: Dataset slug.
+            events: List of BatchEvent objects.
+
+        Returns:
+            List of BatchEventResult objects indicating status for each event.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use send_batch_async() for async mode, or pass sync=True to client")
+
+        path = f"/1/batch/{dataset}"
+        payload = [event.model_dump_for_api() for event in events]
+        data = self._post_sync(path, json=payload)  # type: ignore[arg-type]
+
+        # Parse results
+        if isinstance(data, list):
+            return self._parse_model_list(BatchEventResult, data)
+        return []