Metadata-Version: 2.5
Name: spanlog
Version: 0.1.0
Summary: Readable call-boundary logs: one line when a call starts, one when it ends.
Project-URL: Homepage, https://github.com/chaugiakhang193/spanlog
Project-URL: Documentation, https://github.com/chaugiakhang193/spanlog/blob/main/docs/python.md
Project-URL: Changelog, https://github.com/chaugiakhang193/spanlog/blob/main/docs/CHANGELOG.md
Project-URL: Issues, https://github.com/chaugiakhang193/spanlog/issues
Author: chaugiakhang193
License-Expression: MIT
License-File: LICENSE
Keywords: asgi,fastapi,flask,logging,request-id,sqlalchemy,wsgi
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: asyncpg==0.32.0; extra == 'dev'
Requires-Dist: build==1.6.1; extra == 'dev'
Requires-Dist: fastapi==0.162.0; extra == 'dev'
Requires-Dist: flask==3.1.3; extra == 'dev'
Requires-Dist: greenlet==3.5.6; extra == 'dev'
Requires-Dist: mypy==2.4.1; extra == 'dev'
Requires-Dist: psycopg[binary]==3.3.6; extra == 'dev'
Requires-Dist: pytest==9.2.0; extra == 'dev'
Requires-Dist: ruff==0.17.3; extra == 'dev'
Requires-Dist: sqlalchemy==2.1.6; extra == 'dev'
Requires-Dist: starlette==1.10.0; extra == 'dev'
Requires-Dist: uvicorn==0.54.0; extra == 'dev'
Requires-Dist: waitress==3.0.2; extra == 'dev'
Provides-Extra: sqlalchemy
Requires-Dist: sqlalchemy<3,>=2.0; extra == 'sqlalchemy'
Description-Content-Type: text/markdown

# spanlog for Python

spanlog writes one line when a call starts and one line when it ends, with its duration, into the logger the application
already uses.

```text
2026-11-12 21:04:44.830 +07:00 INFO  [shop] req=e5e0891a POST /orders | START
2026-11-12 21:04:44.831 +07:00 INFO  [shop] [OrderService.handle_order] req=e5e0891a run | START
2026-11-12 21:04:44.831 +07:00 INFO  [shop] [OrderService.handle_order] req=e5e0891a call InventoryService.reserve | START
2026-11-12 21:04:44.832 +07:00 DEBUG [shop] [InventoryService.reserve] req=e5e0891a query UPDATE inventory | START
2026-11-12 21:04:44.836 +07:00 DEBUG [shop] [InventoryService.reserve] req=e5e0891a query UPDATE inventory | DONE 3.6ms
2026-11-12 21:04:44.838 +07:00 ERROR [shop] [OrderService.handle_order] req=e5e0891a call InventoryService.reserve | FAILED 6.6ms ValueError: stock not available
    at InventoryService.reserve (/app/server.py:52)
2026-11-12 21:04:44.838 +07:00 INFO  [shop] [OrderService.handle_order] req=e5e0891a run | FAILED 7ms ValueError: stock not available
2026-11-12 21:04:44.838 +07:00 WARN  [shop] req=e5e0891a POST /orders | FAILED 500 8.2ms
```

This is one failed request from
[`examples/fastapi-orders`](https://github.com/chaugiakhang193/spanlog/blob/main/examples/fastapi-orders/server.py),
without the lines of one internal call. Stack paths are shortened.

## Install

```bash
pip install spanlog
```

Query lines for SQLAlchemy need the extra: `pip install "spanlog[sqlalchemy]"`.

## Quick start

```python
from fastapi import FastAPI
from spanlog import Spanlog
from spanlog.asgi import LogRequests


class OrderService:
    async def handle_order(self, sku: str) -> dict[str, str]:
        return {"sku": sku}


log = Spanlog(service="shop")
orders = log.traced(OrderService(), "OrderService")

app = FastAPI()
app.add_middleware(LogRequests, log=log)


@app.post("/orders/{sku}")
async def create_order(sku: str) -> dict[str, str]:
    return await orders.handle_order(sku)
```

Flask has the same two lines through `spanlog.wsgi`.

## Documentation

- [Python guide](https://github.com/chaugiakhang193/spanlog/blob/main/docs/python.md)
- [Log format](https://github.com/chaugiakhang193/spanlog/blob/main/docs/log-format.md)
- [Examples](https://github.com/chaugiakhang193/spanlog/blob/main/examples/README.md)

## License

[MIT](https://github.com/chaugiakhang193/spanlog/blob/main/python/LICENSE)
