Metadata-Version: 2.4
Name: polyglot-logger
Version: 0.3.3
Summary: Python bindings for the Polyglot native structured logger
Author: Polyglot
License: MIT
Keywords: logging,structured,logger,native,performance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"

# polyglot-logger

Python bindings for [Polyglot](https://github.com/kishankumarhs/Polyglot) — a shared Go logging core with a C ABI. Same `polyglot.yaml`, JSON shape, and sinks as the Node and .NET packages. Native libs ship in the wheel (Linux, Windows, macOS arm64); no Go/CGO required.

Current line: **0.3.x**.

```bash
pip install polyglot-logger
```

```python
from polyglot_logger import Logger

with Logger(service="api", stdout=True) as log:
    log.info("hello", user_id=1)
```

`__exit__` calls `close()`. Side-by-side APIs: [sdk.md](https://github.com/kishankumarhs/Polyglot/blob/main/docs/sdk.md).

## Config file (optional)

Constructors load `polyglot.yaml` in the native core (`POLYGLOT_CONFIG` → cwd → parents, stop at `.git`). No PyYAML required for that path. Kwargs override file keys.

```yaml
# polyglot.yaml (repo root)
service: payments-api
environment: prod
level: info
stdout: true
file:
  enabled: true
  path: /var/log/payments.log
```

```python
Logger(service="payments-api")  # sinks from YAML
```

Full schema: [configuration](https://github.com/kishankumarhs/Polyglot/blob/main/docs/configuration.md) · [zero-config](https://github.com/kishankumarhs/Polyglot/blob/main/docs/zero-config.md).

## Levels, fields, lifecycle

```python
from polyglot_logger import Logger, Level

with Logger(
    "payments-api",
    environment="prod",
    level="info",
    stdout=True,
) as log:
    log.set_fields({"region": "us-east"})
    req = log.with_fields(request_id="r1")  # or log.bind(...)
    req.info("order created", order_id=123, amount=42.5)
    req.log_simple(Level.ERROR, "payment failed")
    req.close()
    log.flush()
```

- Levels: `trace` … `fatal` (`fatal` does not exit the process).
- Prefer `with_fields` / `bind` for per-request context; avoid sharing `set_fields` across threads for request data.
- One instance is fine for concurrent `log` / `flush` / `stats` / `set_fields`. Close from a single owner (or use the context manager).

## Native library

Published wheels include platform natives. For a local monorepo build:

```bash
export POLYGLOT_LOGGER_LIB=$PWD/dist/liblogger.so   # logger.dll / liblogger.dylib
```

Intel Macs: arm64 is what ships today; set `POLYGLOT_LOGGER_LIB` for amd64 until CI covers it.

## From source

```bash
git clone --recurse-submodules https://github.com/kishankumarhs/Polyglot.git
cd Polyglot && make build-native
pip install -e bindings/python
```

## Docs

- [SDK comparison](https://github.com/kishankumarhs/Polyglot/blob/main/docs/sdk.md)
- [First log](https://github.com/kishankumarhs/Polyglot/blob/main/docs/first-log.md)
- [Python API](https://github.com/kishankumarhs/Polyglot/blob/main/docs/languages/python.md)
- [Configuration](https://github.com/kishankumarhs/Polyglot/blob/main/docs/configuration.md)
- [Sinks & Loki](https://github.com/kishankumarhs/Polyglot/blob/main/docs/sinks.md)
- [Migrate from Python logging](https://github.com/kishankumarhs/Polyglot/blob/main/docs/migrate-from-python-logging.md)
- [Compatibility](https://github.com/kishankumarhs/Polyglot/blob/main/docs/compatibility.md)
- [Benchmarks / methodology](https://github.com/kishankumarhs/Polyglot/blob/main/bench/README.md)

Polyglot is for multi-language stacks that want one ops model — shared config and sinks without reimplementing them per language.

Repos: [polyglot-py](https://github.com/kishankumarhs/polyglot-py) · core: [Polyglot](https://github.com/kishankumarhs/Polyglot)

MIT
