Metadata-Version: 2.4
Name: polyglot-logger
Version: 0.3.2
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)

Idiomatic Python bindings (`polyglot-logger`) for the Polyglot native structured logger.

Part of the **Polyglot modular monorepo** — see [polyglot-go](https://github.com/kishankumarhs/Polyglot) for the core Go implementation and other language bindings.

## Quick Start

```python
from polyglot_logger import Logger, Level

with Logger("payments-api", environment="prod", file_path="/var/log/payments.log") as log:
    log.set_fields({"traceId": "abc"})
    log.info("order created", order_id=123, amount=42.5)
    log.log_simple(Level.ERROR, "payment failed")
    print(log.stats())
```

## Features

- ✅ **Auto-initialization:** Place `polyglot.yaml` in project root, logger auto-discovers & loads it
- ✅ **Bundled binaries:** Pre-compiled native libraries for Windows/macOS/Linux included in wheel
- ✅ **Zero config:** Works immediately after `pip install` without manual setup
- ✅ **Thread-safe:** Concurrent `log`/`flush`/`stats`/`set_fields` calls safe on one instance
- ✅ **Type hints:** Full PEP 484 annotations in source

## Installation

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

All native binaries (`.so`, `.dll`, `.dylib`) are included in the wheel. No separate compilation needed.

## Building from Source

To build from the core repository with all language bindings:

```bash
git clone --recurse-submodules https://github.com/kishankumarhs/Polyglot.git
cd Polyglot

# Build native library and all bindings
make build-native
pip install -e bindings/python
```

## Configuration

Place a `polyglot.yaml` in your project root:

```yaml
service: payments-api
environment: prod
logging:
  level: info
  async: true
file:
  enabled: true
  path: /var/log/payments.log
```

On first import, the logger auto-discovers this config and initializes automatically.

Alternatively, set environment variables:

```bash
export POLYGLOT_CONFIG_PATH=/path/to/polyglot.yaml
export POLYGLOT_CONFIG_FILE=/path/to/config.json
```

## Documentation

| Resource                                            | Description                           |
| --------------------------------------------------- | ------------------------------------- |
| [Python API](../../docs/languages/python.md)        | Language-specific API reference       |
| [User Guide](../../docs/user-guide.md)              | Logging concepts, fields, async modes |
| [Configuration](../../docs/configuration.md)        | Full schema & examples                |
| [Getting Started](../../docs/getting-started.md)    | Build & run first log                 |
| [Architecture](../../docs/architecture.md)          | Design & internals                    |
| [Repositories Overview](../../docs/REPOSITORIES.md) | How all 4 repos work together         |

## Usage Examples

### Basic Logging

```python
from polyglot_logger import Logger, Level

log = Logger("my-app", environment="prod")
log.info("Application started")
log.error("Something went wrong", error="connection timeout")
log.close()
```

### With Context Fields

```python
log.set_fields({"user_id": "u123", "request_id": "r456"})
log.info("user action")  # Includes user_id & request_id automatically
```

### Multiple Sinks

```python
log = Logger(
    service="payments-api",
    environment="prod",
    file_path="/var/log/payments.log",
    http_endpoint="https://logs.company.com/ingest",
)
log.info("payment processed")  # Sent to both file and HTTP endpoint
```

### Statistics

```python
stats = log.stats()
print(stats.queued)    # Entries currently in queue
print(stats.flushed)   # Entries successfully written
print(stats.dropped)   # Entries dropped due to overflow
print(stats.errors)    # Write errors
```

## Thread Safety

A single logger instance is **safe for concurrent calls** to:

```python
log.log_simple(level, message)  # Thread-safe
log.info(msg, **fields)         # Thread-safe
log.flush()                     # Thread-safe
log.stats()                     # Thread-safe
log.set_fields(fields)          # Thread-safe
log.reload_config()             # Thread-safe
```

Only `close()` should be called by a single thread (one owner of the logger lifecycle).

## Native Library Auto-Discovery

The binding automatically discovers the native library:

1. Checks for bundled binary in `polyglot_logger/bin/`
2. Falls back to `POLYGLOT_LOGGER_LIB` environment variable (if set)
3. If neither found: error with helpful message

## Troubleshooting

**"native library not found"**

```bash
# Verify package has binaries
pip show polyglot-logger | grep Location
# Check if bin/ folder exists
ls ~/.venv/lib/python3.x/site-packages/polyglot_logger/bin/

# Set explicit path
export POLYGLOT_LOGGER_LIB=/path/to/liblogger.so
```

**"polyglot.yaml not found"**

```bash
# Create config in your project root
touch polyglot.yaml

# Or set environment variable
export POLYGLOT_CONFIG_PATH=/path/to/config.yaml
```

**ImportError on macOS**

Ensure you're using Python 3.9+:

```bash
python3 --version
pip install --upgrade polyglot-logger
```

## Version Management

This binding is independently versioned. Each release:

- Includes latest C ABI from polyglot-go
- Pre-compiled native binaries for all platforms
- Complete source with type hints

Check [polyglot-go releases](https://github.com/kishankumarhs/Polyglot/releases) to see which core version this binding is based on.

## Repository Links

- **This repo (Python bindings):** [polyglot-py](https://github.com/kishankumarhs/polyglot-py)
- **Core (Go logger):** [Polyglot](https://github.com/kishankumarhs/Polyglot)
- **Node.js bindings:** [polyglot-node](https://github.com/kishankumarhs/polyglot-node)
- **.NET bindings:** [polyglot-csharp](https://github.com/kishankumarhs/polyglot-csharp)

## Contributing

To contribute to Python bindings:

```bash
# Clone core with all submodules
git clone --recurse-submodules https://github.com/kishankumarhs/Polyglot.git
cd Polyglot/bindings/python

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

# Make changes
vim polyglot_logger/__init__.py

# Run tests
python -m pytest tests/

# Commit and push to polyglot-py
git add polyglot_logger/
git commit -m "fix: description"
git push origin main

# Update core submodule reference
cd ../..
git add bindings/python
git commit -m "chore: bump python binding"
git push origin main
```

## License

MIT — see LICENSE in this repository
