Metadata-Version: 2.4
Name: hostess-python
Version: 0.1.0
Summary: Hostess SDK for Python — native API Insights for FastAPI and beyond.
Project-URL: Homepage, https://hostess.sh
Project-URL: Repository, https://github.com/howl-cloud/hostess-python
Author: Horizon Web Labs
License: MIT License
        
        Copyright (c) 2026 Horizon Web Labs
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: fastapi,hostess,insights,observability,opentelemetry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Requires-Dist: opentelemetry-api>=1.27.0
Requires-Dist: opentelemetry-sdk>=1.27.0
Provides-Extra: fastapi
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0; extra == 'fastapi'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'fastapi'
Description-Content-Type: text/markdown

# hostess-python

The Hostess SDK for Python. Native **API Insights** for FastAPI (and, later,
other Python frameworks) with one line of code.

```bash
pip install "hostess-python[fastapi]"
```

```python
from fastapi import FastAPI
from hostess_sdk.fastapi import instrument

app = FastAPI()
instrument(app)
```

That's it. When deployed on Hostess, route-level traffic, latency, status
codes, and error rates appear in Studio — no OTLP, collector, or Prometheus
configuration required.

## What `instrument(app)` does

- Applies OpenTelemetry FastAPI instrumentation, so requests produce server
  spans carrying the **route template** (`/items/{item_id}`), method, and
  status — never raw paths or query strings.
- Exports spans over OTLP/HTTP to the Hostess collector. The endpoint is
  injected by the platform (`HOSTESS_OTEL_ENDPOINT`); override with
  `otlp_endpoint=` for local use.
- Emits a periodic **marker heartbeat** so Studio can tell "installed, waiting
  for traffic" from "not installed".

It is idempotent, fails silent and cheap (bounded queue, never adds request
latency or crashes the app), and is a clean no-op when disabled
(`enabled=False` / `HOSTESS_INSTRUMENTATION=false`) or when no collector
endpoint is available.

## Options

```python
instrument(
    app,
    enabled=None,            # None → env (HOSTESS_INSTRUMENTATION), default on
    service_name=None,       # defaults to the platform-injected name
    exclude_paths=["/health"],
    otlp_endpoint=None,      # local/advanced override
)
```

## Privacy

The helper collects HTTP method, route template, status code, and duration. It
never collects request/response bodies, query strings, raw URLs, headers,
cookies, tokens, user IDs, or client IPs.

## Development

```bash
uv sync
uv run pytest
```

## Status

v0.1 — `instrument(app)` for FastAPI. Roadmap: a `HostessFastAPI` drop-in,
opt-in exception metrics, and additional framework helpers (Django, Flask).
