Metadata-Version: 2.4
Name: nexuslog-lib
Version: 0.9.0
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
License-File: LICENSE
Summary: Fast async logger with Python bindings
Keywords: logging,async,fast,rust
Author: river-walras
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/river-walras/nexuslogger
Project-URL: Issues, https://github.com/river-walras/nexuslogger/issues
Project-URL: Repository, https://github.com/river-walras/nexuslogger

# NexusLog

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Python](https://img.shields.io/badge/python-3.11%20|%203.12%20|%203.13-blue)
![Version](https://img.shields.io/pypi/v/nexuslog?color=blue)

High-performance async logging library, compatible with Python standard logging API.

[中文文档](README_CN.md)

## Benchmark

<p align="center">
  <img src="assets/bench.png" width="720" alt="Benchmark chart" />
</p>

```
Benchmarking with 1,000,000 log messages

------------------------------------------------------------
Logger               Time (s)     Msgs/sec        Log size    
------------------------------------------------------------
loguru               7.675        130,297         89,888,890 bytes
Python logging       5.313        188,206         82,888,890 bytes
picologging          2.038        490,626         79,888,888 bytes
spdlog               0.199        5,034,527       79,888,890 bytes
NexusLogger          0.049        20,304,036      97,888,890 bytes
NexusLogger unix_ts  0.049        20,451,884      83,868,922 bytes
------------------------------------------------------------

NexusLogger is 4.03x faster than spdlog
NexusLogger is 41.38x faster than picologging
NexusLogger is 107.88x faster than Python logging
NexusLogger is 155.83x faster than loguru
NexusLogger unix_ts is 4.06x faster than spdlog
NexusLogger unix_ts is 41.69x faster than picologging
NexusLogger unix_ts is 108.67x faster than Python logging
NexusLogger unix_ts is 156.96x faster than loguru
```

## Installation

```bash
pip install nexuslog
```

## Quick Start

```python
import nexuslog as logging

logging.basicConfig(level=logging.INFO)

logging.info("Hello, world!")
logging.warning("This is a warning")
logging.error("This is an error")
```

## API

### Log Levels

```python
logging.TRACE
logging.DEBUG
logging.INFO
logging.WARNING
logging.ERROR
```

### Module-level Functions

```python
logging.basicConfig(filename=None, level=logging.INFO, unix_ts=False, color="auto", format="logfmt")
logging.basicConfig(
    level=logging.INFO,
    name_levels={"db": logging.DEBUG, "http.client": logging.WARNING},
)
logging.trace(message, *args)
logging.debug(message, *args)
logging.info(message, *args)
logging.warning(message, *args)
logging.error(message, *args)
```

### Lazy %-style Formatting

Like the standard `logging` module, extra arguments are merged into the
message with %-style formatting — but only if the log level is enabled.
When the level is disabled, the arguments are never formatted (no
`str()`/`repr()` calls), making disabled log calls nearly free:

```python
logger.info("price=%s qty=%s side=%s", price, qty, side)
logger.debug("state=%r retries=%d", state, retries)  # zero cost at INFO level
```

Supported conversions: `%s` `%r` `%d` `%i` `%f` `%e` `%g` `%x` `%o` `%%`,
plus the full `%` operator spec (width, precision, flags, `%(name)s` with a
dict argument) with semantics identical to Python's `message % args`. Simple
placeholders are rendered natively in Rust — formatting with args is faster
than building the message with an f-string at the call site. A message
logged without args is emitted verbatim, so literal `%` needs no escaping.

### Colored Output

```python
logging.basicConfig(color="auto")  # default
```

The `color` option controls ANSI colorization of the level value (by
severity) and the logfmt keys (dimmed):

- `"auto"` (default) — color only when writing to a color-capable terminal.
  File and piped output stay plain. Honors the `NO_COLOR` (force off) and
  `FORCE_COLOR` (force on) environment variables; `NO_COLOR` wins.
- `"off"` — never emit ANSI color.
- `"always"` — always emit ANSI color, even to files and pipes.

Colors: `error` red, `warn` yellow, `info` green, `debug` cyan, `trace` dim.
The message body is never colored. There is no cost on the hot path when
color is inactive.

### JSON Output

```python
logging.basicConfig(filename="app.log", format="json")
```

`format` selects the line layout:

- `"logfmt"` (default) — `time=... level=... [name=...] msg="..."`.
- `"json"` — one JSON object per line (NDJSON):

  ```json
  {"time":"2026-07-09T09:45:59.914644+08:00","level":"warn","name":"svc","msg":"disk 90% full"}
  ```

  Fields are `{time, level, name, msg}`, with proper JSON escaping of the
  message. `time` is an ISO-8601 string, or a number when `unix_ts=True`.
  `name` is omitted when unset. JSON output ignores `color` (it is never
  colorized).

NDJSON is the recommended format for shipping logs to a database: write to a
file, then let a forwarder (Vector, Fluent Bit, Fluentd, Logstash) tail it and
insert into ClickHouse / PostgreSQL / etc. — the JSON parses with near-zero
configuration.

### Logger Class

```python
from nexuslog import Logger, Level

logger = Logger("myapp", path="/var/log/app", level=Level.Info)
logger.info("message")
logger.shutdown()
```

### getLogger

```python
import nexuslog as logging

logging.basicConfig(filename="/var/log/app.log", level=logging.DEBUG)
logger = logging.getLogger("myapp")
logger.info("message")
```

## License

MIT

