honeycomb-api 0.1.0__py3-none-any.whl

honeycomb/tools/schemas.py

@@ -0,0 +1,184 @@
+"""Schema generation utilities for Claude tool definitions.
+
+This module provides utilities to generate JSON Schema definitions from Pydantic models,
+suitable for Claude's tool calling API.
+"""
+
+import re
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def validate_tool_name(name: str) -> None:
+    """Validate tool name follows Claude's naming constraints.
+
+    Args:
+        name: The tool name to validate
+
+    Raises:
+        ValueError: If name doesn't match pattern ^[a-zA-Z0-9_-]{1,64}$
+    """
+    pattern = r"^[a-zA-Z0-9_-]{1,64}$"
+    if not re.match(pattern, name):
+        raise ValueError(
+            f"Tool name '{name}' must match pattern {pattern}. "
+            "Only letters, numbers, underscores, and hyphens allowed, 1-64 characters."
+        )
+
+
+def generate_schema_from_model(
+    model: type[BaseModel], exclude_fields: set[str] | None = None
+) -> dict[str, Any]:
+    """Generate JSON Schema from a Pydantic model.
+
+    Args:
+        model: The Pydantic model class to generate schema from
+        exclude_fields: Optional set of field names to exclude from schema
+
+    Returns:
+        JSON Schema dict suitable for Claude tool definitions
+    """
+    exclude_fields = exclude_fields or set()
+
+    # Get the full JSON schema from Pydantic
+    full_schema = model.model_json_schema()
+
+    # Extract properties and required fields
+    properties = {
+        k: v for k, v in full_schema.get("properties", {}).items() if k not in exclude_fields
+    }
+    required = [f for f in full_schema.get("required", []) if f not in exclude_fields]
+
+    # Build the schema
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+    }
+
+    if required:
+        schema["required"] = required
+
+    # Handle definitions/defs for nested models
+    if "$defs" in full_schema:
+        schema["$defs"] = full_schema["$defs"]
+    elif "definitions" in full_schema:
+        schema["definitions"] = full_schema["definitions"]
+
+    return schema
+
+
+def merge_schemas(*schemas: dict[str, Any]) -> dict[str, Any]:
+    """Merge multiple JSON schemas into one.
+
+    Useful for combining schemas from multiple models (e.g., dataset + model-specific params).
+
+    Args:
+        *schemas: Variable number of schema dicts to merge
+
+    Returns:
+        Merged schema dict
+    """
+    merged: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": [],
+    }
+
+    all_defs: dict[str, Any] = {}
+
+    for schema in schemas:
+        # Merge properties
+        merged["properties"].update(schema.get("properties", {}))
+
+        # Merge required fields
+        required = schema.get("required", [])
+        if required:
+            merged["required"].extend(required)
+
+        # Merge definitions
+        if "$defs" in schema:
+            all_defs.update(schema["$defs"])
+        elif "definitions" in schema:
+            all_defs.update(schema["definitions"])
+
+    # Deduplicate required fields
+    if merged["required"]:
+        merged["required"] = list(dict.fromkeys(merged["required"]))
+    else:
+        del merged["required"]
+
+    # Add definitions if any
+    if all_defs:
+        merged["$defs"] = all_defs
+
+    return merged
+
+
+def add_parameter(
+    schema: dict[str, Any],
+    name: str,
+    param_type: str,
+    description: str,
+    required: bool = True,
+    **kwargs: Any,
+) -> None:
+    """Add a parameter to an existing schema.
+
+    Args:
+        schema: The schema dict to modify
+        name: Parameter name
+        param_type: JSON Schema type (string, integer, object, array, etc.)
+        description: Parameter description
+        required: Whether parameter is required
+        **kwargs: Additional schema properties (enum, items, etc.)
+    """
+    schema["properties"][name] = {
+        "type": param_type,
+        "description": description,
+        **kwargs,
+    }
+
+    if required:
+        if "required" not in schema:
+            schema["required"] = []
+        if name not in schema["required"]:
+            schema["required"].append(name)
+
+
+def validate_schema(schema: dict[str, Any]) -> None:
+    """Validate a JSON Schema is well-formed.
+
+    Args:
+        schema: The schema dict to validate
+
+    Raises:
+        ValueError: If schema is invalid
+    """
+    if not isinstance(schema, dict):
+        raise ValueError("Schema must be a dictionary")
+
+    if schema.get("type") != "object":
+        raise ValueError("Schema type must be 'object'")
+
+    if "properties" not in schema:
+        raise ValueError("Schema must have 'properties' field")
+
+    if not isinstance(schema["properties"], dict):
+        raise ValueError("Schema properties must be a dictionary")
+
+    # Check all required fields exist in properties
+    required = schema.get("required", [])
+    properties = schema["properties"]
+
+    for field in required:
+        if field not in properties:
+            raise ValueError(f"Required field '{field}' not found in properties")
+
+    # Check all properties have descriptions
+    for field_name, field_schema in properties.items():
+        if "description" not in field_schema and "$ref" not in field_schema:
+            raise ValueError(
+                f"Field '{field_name}' missing description. "
+                "All fields must have descriptions for Claude tool definitions."
+            )

honeycomb_api-0.1.0.dist-info/METADATA

@@ -0,0 +1,451 @@
+Metadata-Version: 2.4
+Name: honeycomb-api
+Version: 0.1.0
+Summary: Python client for the Honeycomb.io API
+License-Expression: MIT
+License-File: LICENSE
+Keywords: honeycomb,observability,api,client,sdk
+Author: Irving Popovetsky
+Requires-Python: >=3.10
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: attrs (>=23.0)
+Requires-Dist: httpx (>=0.27)
+Requires-Dist: pydantic (>=2.0)
+Requires-Dist: pytest-xdist (>=3.8.0,<4.0.0)
+Requires-Dist: python-dateutil (>=2.8)
+Project-URL: Homepage, https://github.com/irvingpop/honeycomb-api-python
+Project-URL: Repository, https://github.com/irvingpop/honeycomb-api-python
+Description-Content-Type: text/markdown
+
+# honeycomb-api-python
+
+A modern, async-first Python client for the [Honeycomb.io](https://www.honeycomb.io/) API.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+📚 **[Read the full documentation](https://irvingpop.github.io/honeycomb-api-python/)**
+
+## Features
+
+- **Async-first design** with full sync support
+- **Fluent builder pattern** for queries, triggers, SLOs, and boards
+- **Pydantic models** for type-safe request/response handling
+- **Automatic retries** with exponential backoff for transient failures
+- **Comprehensive error handling** with specific exception types
+- **Dual authentication** support (API keys and Management keys)
+- **Resource-oriented API** for intuitive usage
+
+## Installation (coming soon)
+
+```bash
+pip install honeycomb-api-python
+```
+
+Or with Poetry:
+
+```bash
+poetry add honeycomb-api-python
+```
+
+## Quick Start
+
+### Async Usage (Recommended)
+
+```python
+import asyncio
+from honeycomb import HoneycombClient, QueryBuilder
+
+async def main():
+    async with HoneycombClient(api_key="your-api-key") as client:
+        # List all datasets
+        datasets = await client.datasets.list_async()
+        for ds in datasets:
+            print(f"Dataset: {ds.name} ({ds.slug})")
+
+        # Run a query using the fluent QueryBuilder
+        query, result = await client.query_results.create_and_run_async(
+            QueryBuilder("Error Analysis")  # Optional name for board integration
+                .dataset("my-dataset")       # Dataset scope on builder
+                .last_24_hours()             # Time preset matching Honeycomb UI
+                .count()
+                .p99("duration_ms")
+                .avg("duration_ms")
+                .gte("status_code", 500)     # Filter shortcuts: gte, eq, contains, etc.
+                .group_by("service", "endpoint")
+                .order_by_count()
+                .limit(100)
+        )
+
+        for row in result.data.rows:
+            print(f"Service: {row['service']}, Count: {row['COUNT']}, P99: {row['P99']}")
+
+asyncio.run(main())
+```
+
+### Sync Usage
+
+```python
+from honeycomb import HoneycombClient, QueryBuilder
+
+with HoneycombClient(api_key="your-api-key", sync=True) as client:
+    datasets = client.datasets.list()
+
+    # Run queries with the same fluent API
+    query, result = client.query_results.create_and_run(
+        QueryBuilder()
+            .dataset("my-dataset")
+            .last_1_hour()
+            .count()
+            .group_by("endpoint"),
+    )
+```
+
+## Builders with resource mixins
+
+### TriggerBuilder
+
+```python
+from honeycomb import TriggerBuilder
+
+# Create sophisticated alert in one fluent call
+trigger = await client.triggers.create_async(
+    "api-logs",
+    TriggerBuilder("High Error Rate")
+        .dataset("api-logs")             # Or .environment_wide() for all datasets
+        .last_15_minutes()                # Frequency presets
+        .count()
+        .gte("status_code", 500)
+        .threshold_gt(100)                # Threshold shortcuts
+        .email("oncall@example.com")      # Multiple recipients
+        .pagerduty("critical")
+        .slack("#incidents")
+        .tag("team", "backend")           # Tag support with validation
+        .build()
+)
+```
+
+### SLOBuilder
+
+```python
+from honeycomb import SLOBuilder
+
+# Create SLO with derived column and burn alerts automatically
+slos = await client.slos.create_from_bundle_async(
+    SLOBuilder("API Availability")
+        .dataset("api-logs")
+        .target_nines(3)                         # 99.9% = .target_percentage(99.9)
+        .time_period_days(30)
+        .sli(
+            alias="success_rate",
+            expression="IF(LT($status_code, 400), 1, 0)",
+            description="Success indicator"
+        )
+        # Burn alerts with integrated recipients
+        .exhaustion_alert(exhaustion_minutes=15)
+        .budget_rate_alert(window_minutes=60, threshold_percentage=10)
+        .email("sre@example.com")
+        .pagerduty("critical")
+        .build()
+)
+```
+
+### BoardBuilder
+
+```python
+from honeycomb import BoardBuilder, QueryBuilder, SLOBuilder
+
+# Create board with inline queries and SLOs - no pre-creation needed!
+board = await client.boards.create_from_bundle_async(
+    BoardBuilder("Production Dashboard")
+        .description("Service health monitoring")
+        .auto_layout()
+        .tag("team", "platform")
+        # Inline QueryBuilder - creates query automatically
+        .query(
+            QueryBuilder("Request Count")
+                .dataset("api-logs")
+                .last_24_hours()
+                .count()
+                .group_by("service"),
+            style="graph"
+        )
+        # Inline SLOBuilder - creates SLO automatically
+        .slo(
+            SLOBuilder("API Availability")
+                .dataset("api-logs")
+                .target_nines(3)
+                .sli(alias="sli_success")
+        )
+        # Environment-wide query
+        .query(
+            QueryBuilder("P99 Latency")
+                .environment_wide()  # All datasets
+                .last_1_hour()
+                .p99("duration_ms")
+                .group_by("endpoint"),
+            style="table"
+        )
+        .build()
+)
+```
+
+See [full documentation](https://irvingpop.github.io/honeycomb-api-python/) for more examples and advanced features.
+
+## Authentication
+
+The client supports two authentication methods:
+
+### API Key (Single Environment)
+
+For accessing a single Honeycomb environment:
+
+```python
+client = HoneycombClient(api_key="your-api-key")
+```
+
+The API key is sent via the `X-Honeycomb-Team` header.
+
+### Management Key (Multi-Environment)
+
+For management operations across multiple environments:
+
+```python
+client = HoneycombClient(
+    management_key="your-key-id",
+    management_secret="your-key-secret"
+)
+```
+
+Management credentials are sent via the `Authorization: Bearer` header.
+
+## Usage Guide
+
+For complete usage examples and guides, see the [full documentation](https://irvingpop.github.io/honeycomb-api-python/):
+
+- [Quick Start Guide](https://irvingpop.github.io/honeycomb-api-python/getting-started/quickstart/) - Common operations with examples
+- [Working with Queries](https://irvingpop.github.io/honeycomb-api-python/usage/queries/) - Saved, ephemeral, and combined query patterns
+- [Working with Triggers](https://irvingpop.github.io/honeycomb-api-python/usage/triggers/) - Alert configuration
+- [Working with SLOs](https://irvingpop.github.io/honeycomb-api-python/usage/slos/) - Service level objectives
+- [API Reference](https://irvingpop.github.io/honeycomb-api-python/api/resources/) - Complete API documentation
+
+## Error Handling
+
+The client provides specific exception types for different error scenarios (authentication, rate limiting, validation, etc.). All exceptions include useful debugging information like HTTP status codes and request IDs for support tickets.
+
+See the [Error Handling Guide](https://irvingpop.github.io/honeycomb-api-python/advanced/error-handling/) for complete documentation and best practices.
+
+## Configuration
+
+### Client Options
+
+```python
+from honeycomb import HoneycombClient, RetryConfig
+
+client = HoneycombClient(
+    api_key="...",                              # API key for single-environment access
+    management_key="...",                       # Management key ID (alternative auth)
+    management_secret="...",                    # Management key secret
+    base_url="https://api.honeycomb.io",        # API base URL (default)
+    timeout=30.0,                               # Request timeout in seconds (default: 30)
+    max_retries=3,                              # Max retry attempts (default: 3)
+    retry_config=None,                          # Custom retry configuration (optional)
+    sync=False,                                 # Use sync mode (default: False)
+)
+```
+
+### Retry Behavior
+
+The client automatically retries requests on:
+- HTTP 429 (Rate Limited) - respects `Retry-After` header
+- HTTP 500, 502, 503, 504 (Server Errors)
+- Connection timeouts
+
+Retries use exponential backoff: 1s, 2s, 4s, ... up to 30s max.
+
+#### Custom Retry Configuration
+
+```python
+from honeycomb import HoneycombClient, RetryConfig
+
+# Customize retry behavior
+retry_config = RetryConfig(
+    max_retries=5,                # More retry attempts
+    base_delay=2.0,               # Start with 2s delay
+    max_delay=60.0,               # Cap at 60s
+    exponential_base=2.0,         # Double each time
+    retry_statuses={429, 503},    # Only retry these status codes
+)
+
+client = HoneycombClient(api_key="...", retry_config=retry_config)
+```
+
+## API Reference
+
+The client provides resource-oriented access to the Honeycomb API:
+
+**Core Resources:**
+- `client.datasets` - Dataset management
+- `client.triggers` - Alert triggers
+- `client.slos` - Service level objectives
+- `client.boards` - Dashboards
+- `client.queries` - Saved queries
+- `client.query_results` - Query execution
+
+**Data Management:**
+- `client.columns` - Column schema management
+- `client.markers` - Event markers and annotations
+- `client.recipients` - Notification recipients
+- `client.burn_alerts` - SLO burn rate alerts
+- `client.events` - Event ingestion (send data to Honeycomb)
+
+**Team Management (v2 - requires Management Key):**
+- `client.api_keys` - API key management (team-scoped)
+- `client.environments` - Environment management (team-scoped)
+
+All methods have both sync and async variants (`list()` / `list_async()`).
+
+See the [API Reference](https://irvingpop.github.io/honeycomb-api-python/api/resources/) for complete documentation.
+
+## Development
+
+### Prerequisites
+
+- Python 3.10+
+- [Poetry](https://python-poetry.org/) for dependency management
+- [direnv](https://direnv.net/) (optional, for environment management)
+- Make
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/irvingpop/honeycomb-api-python.git
+cd honeycomb-api-python
+
+# Install dependencies
+make install-dev
+# Or: poetry install
+
+# Set up environment variables (for live API testing)
+cp .envrc.example .envrc
+# Edit .envrc with your API key
+direnv allow
+```
+
+### Make Commands
+
+All common development tasks are available via `make`. Run `make help` for a full list:
+
+```bash
+make help          # Show all available commands
+```
+
+#### Setup
+| Command | Description |
+|---------|-------------|
+| `make install` | Install poetry production dependencies only |
+| `make install-dev` | Install all poetry dependencies (including dev) |
+
+#### Code Quality
+| Command | Description |
+|---------|-------------|
+| `make lint` | Run linter (ruff check) |
+| `make lint-fix` | Run linter and auto-fix issues |
+| `make format` | Format code with ruff |
+| `make typecheck` | Run type checker (mypy) |
+| `make check` | Run all checks (lint + typecheck) |
+
+#### Testing
+| Command | Description |
+|---------|-------------|
+| `make test` | Run all tests |
+| `make test-unit` | Run only unit tests |
+| `make test-cov` | Run tests with coverage report |
+| `make test-live` | Run live API tests (requires `HONEYCOMB_API_KEY`) |
+
+#### Build & Publish
+| Command | Description |
+|---------|-------------|
+| `make build` | Build distribution packages |
+| `make publish` | Publish to PyPI |
+| `make publish-test` | Publish to Test PyPI |
+
+#### Maintenance
+| Command | Description |
+|---------|-------------|
+| `make clean` | Remove build artifacts and cache files |
+| `make update-deps` | Update dependencies to latest versions |
+| `make ci` | Run full CI pipeline (install, check, test) |
+
+### Running Tests (Manual)
+
+```bash
+# Run all tests
+make test
+# Or: poetry run pytest tests/ -v
+
+# Run with coverage
+make test-cov
+# Or: poetry run pytest --cov=honeycomb --cov-report=html
+
+# Run specific test file
+poetry run pytest tests/unit/test_wrapper_client.py -v
+```
+
+### Code Quality (Manual)
+
+```bash
+# Run all checks
+make check
+
+# Or run individually:
+poetry run ruff check src/ tests/    # Linting
+poetry run ruff format src/ tests/   # Formatting
+poetry run mypy src/                 # Type checking
+```
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run checks and tests (`make check && make test`)
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+### Guidelines
+
+- Follow the existing code style (enforced by Ruff)
+- Add tests for new functionality
+- Update documentation as needed
+- Keep commits focused and atomic
+- Run `make ci` before submitting to ensure all checks pass
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Related Links
+
+- [Honeycomb Documentation](https://docs.honeycomb.io/)
+- [Honeycomb API Reference](https://docs.honeycomb.io/api/)
+- [Issue Tracker](https://github.com/irvingpop/honeycomb-api-python/issues)
+
+## Acknowledgments
+
+- Built with [httpx](https://www.python-httpx.org/) for async HTTP
+- Models powered by [Pydantic](https://docs.pydantic.dev/)
+- API spec from [Honeycomb OpenAPI](https://docs.honeycomb.io/api/)
+