Metadata-Version: 2.4
Name: coakka-logger
Version: 1.2.2
Summary: Python connector package for the CoAkka native logger core
License: CoAkka Public Artifact Preview License 1.0
Project-URL: Homepage, https://github.com/phuong-tran/coakka-publish
Project-URL: Documentation, https://github.com/phuong-tran/coakka-samples/tree/main/docs
Project-URL: Samples, https://github.com/phuong-tran/coakka-samples
Project-URL: Issues, https://github.com/phuong-tran/coakka-samples/issues
Keywords: coakka,logger,native,observability
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# CoAkka Logger Python

Python connector package for the standalone CoAkka native logger core.

## New To CoAkka

CoAkka is a native-backed runtime and logger toolkit for application-owned
work.

This package is the logger lane. It gives a Python process a small API over
the native logger core: bounded queues, pressure state, manual draining,
structured records, native-backed lifecycle, and packaged native libraries.
It is for application-owned logging paths where the process should keep control
of queueing and draining without adding another private HTTP service just to
move local work across a boundary.

Use these public repositories to orient first:

| Repository | Use it for | Link |
| --- | --- | --- |
| `coakka-samples` | Runnable examples and code you can inspect first. | https://github.com/phuong-tran/coakka-samples |
| `coakka-publish` | Released packages, native archives, manifests, checksums, compatibility matrix, and release notes. | https://github.com/phuong-tran/coakka-publish |

Samples docs directory:
https://github.com/phuong-tran/coakka-samples/tree/main/docs

Public artifact and release notes:
https://github.com/phuong-tran/coakka-publish

## First Run

```sh
python3 -m venv coakka-logger-first-run
source coakka-logger-first-run/bin/activate
python -m pip install coakka-logger==1.2.2
```

```python
from coakka_logger import CoakkaLoggerLevel, Logger, LoggerSpec

with Logger.start(spec=LoggerSpec(system_name="logger-first-run", min_level=CoakkaLoggerLevel.INFO)) as logger:
    sequence = logger.info("orders", "accepted")
    record = logger.await_next(timeout_ms=1000)
    print({"sequence": sequence, "category": record.category, "message": record.message})
```

Expected output shape:

```text
{'sequence': 1, 'category': 'orders', 'message': 'accepted'}
```

## When To Use This Package

Use `coakka-logger` when a Python app needs native-backed logging, bounded
queue behavior, pressure visibility, or explicit drain control.

Use the runtime connector package, `coakka-v2-connector`, when the app needs
target-based work routing, request/reply, deadletters, or runtime diagnostics.

This package is intentionally smaller than the runtime connector:

- load `libcoakka_logger_core` through `ctypes`
- keep Python-side formatting above the native core
- let the native logger own queueing, pressure policy, sinks, and lifecycle
- package staged native libraries into the wheel for macOS aarch64, Linux
  aarch64/x86_64, and Windows aarch64/x86_64

## Public Samples

Runnable logger samples live in:

https://github.com/phuong-tran/coakka-samples/tree/main/logger/python

The samples install the PyPI package into a temporary environment and exercise
the public API against the packaged native logger core.

## Build

```sh
./logger/python/scripts/build_wheel.sh
```

The script stages native libraries from:

```text
logger/staging/native/1.2.1+f50756ebff0d/
```

## Smoke

```sh
./logger/python/scripts/test_package.sh
./logger/python/scripts/smoke_packaged_wheel.sh
./logger/python/scripts/check_pypi_readiness.sh
```

## Example

```python
from coakka_logger import Logger

with Logger.start() as logger:
    logger.info("app", "started")
    record = logger.await_next(timeout_ms=1000)
```

Public docs:

- CoAkka samples: https://github.com/phuong-tran/coakka-samples
- Public artifacts and release notes: https://github.com/phuong-tran/coakka-publish
- Package-manager roadmap: https://github.com/phuong-tran/coakka-publish/blob/main/docs/package-manager-roadmap.md
