Metadata-Version: 2.4
Name: loglite
Version: 1.1.0
Summary: Lightweight log service — Python CLI and harvester layer over the loglite C++ core
Keywords: logging,metrics,sqlite,lightweight,c++
Author-Email: Di Lu <dilu3100@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Project-URL: Documentation, https://loglite.lu-d.com/
Project-URL: Homepage, https://loglite.lu-d.com/
Project-URL: Issues, https://github.com/namoshizun/loglite/issues
Project-URL: Repository, https://github.com/namoshizun/loglite
Requires-Python: >=3.10
Requires-Dist: loguru>=0.7.3
Requires-Dist: typer>=0.15.2
Provides-Extra: zmq
Requires-Dist: pyzmq>=26.0.0; extra == "zmq"
Description-Content-Type: text/markdown

# Loglite (Python)

The Python package is a thin convenience layer on top of the [loglite C++ core](https://github.com/namoshizun/loglite/tree/main/cpp). It provides:

- **CLI** (`loglite server run`, `loglite migrate rollout/rollback`) — delegates directly to the C++ server via a pybind11 extension (`_core`).
- **Built-in harvesters** — `SocketHarvester` and (optional) `ZMQHarvester`.
- **Custom harvesters** — subclass `loglite.Harvester[Config]` to write custom log ingestors in Python. Ingested entries are pushed directly into the C++ server's backlog in the same process.

The C++ core handles everything else: the HTTP server, SQLite read/write, migrations, SSE, and vacuuming. The Python package adds zero server-side overhead.

## Installation

Pre-built wheels are published to PyPI:

```bash
pip install loglite

# With ZeroMQ harvester support
pip install "loglite[zmq]"
```

## Writing a custom harvester

```python
from dataclasses import dataclass
from loglite.harvesters.base import BaseHarvesterConfig, Harvester

@dataclass
class MyConfig(BaseHarvesterConfig):
    source: str

class MyHarvester(Harvester[MyConfig]):
    async def run(self):
        while self._running:
            log = await fetch_from_somewhere(self.config.source)
            self.ingest(log)  # pushes into the C++ backlog, thread-safe
```

Register it in your YAML config:

```yaml
harvesters:
  - type: myapp.harvesters.MyHarvester
    name: my-source
    config:
      source: "tcp://localhost:5000"
```

## Local development

### Prerequisites

- [uv](https://docs.astral.sh/uv/)
- [Conan 2](https://docs.conan.io/2/installation.html) — `pip install conan && conan profile detect`
- CMake ≥ 3.25
- A C++20-capable compiler (GCC 12+, Clang 16+, or Homebrew LLVM on macOS)

### Build

```bash
cd py
uv sync --all-groups
```

That's it. CMake automatically invokes Conan during the configure step, so no separate Conan command is needed. The first sync compiles the C++ dependencies (SQLite3, Boost headers, yaml-cpp); subsequent syncs use Conan's binary cache and are fast 💪.

For building docs

```bash
uv run --group docs sphinx-build -W --keep-going -b html ../docs ../docs/_build/html
```

### Running tests

```bash
cd py
uv run pytest                    # all tests
uv run pytest tests/test_cli.py  # single file
```
