pylogging 0.1.1

A small, ergonomic logging library inspired by Python's logging module.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

# pylogging

[![Crates.io](https://img.shields.io/crates/v/pylogging.svg)](https://crates.io/crates/pylogging)
[![Documentation](https://docs.rs/pylogging/badge.svg)](https://docs.rs/pylogging)
[![License](https://img.shields.io/crates/l/pylogging.svg)](#license)

A small, ergonomic logging library for Rust, inspired by Python's
[`logging`](https://docs.python.org/3/library/logging.html) module.

It is published as the **`pylogging`** crate but imported as **`logging`**, so
the API reads the way it does in Python.

## Features

- **Named loggers** in a process-global registry (`Logger::get("my::module")`).
- **Inheritance** from a configurable **root** logger (handlers + level).
- **Level filtering** (`Debug`, `Info`, `Warning`, `Error`, `Critical`) with
  cheap, allocation-free rejection of messages below the threshold.
- **Pattern-based formatting** with field placeholders, width/alignment, and
  truncation, e.g. `"%(timestamp) [%(level)-8] %(name)-12 | %(message)"`.
- **Pluggable handlers** via the `Handler` trait; a `StreamHandler` writes to
  any `std::io::Write` sink (stdout, files, in-memory buffers, ...).
- **Transformers** for post-processing a rendered line (e.g. ANSI colors).

## Installation

```toml
[dependencies]
pylogging = "0.1"
```

The crate is imported as `logging`:

```rust
use logging::{Formatter, Level, Logger, StreamHandler};
```

## Quick start

```rust
use logging::{Logger, StreamHandler};

let logger = Logger::get("example");
logger
    .add_handler(StreamHandler::with_pattern(std::io::stdout(), "%(level): %(message)"))
    .unwrap();
logger.info("hello");
// prints: INFO: hello
```

Configure the **root** logger once and every logger inherits it:

```rust
use logging::{Formatter, Level, Logger, StreamHandler};

let mut formatter = Formatter::new("%(timestamp) [%(level)-8] %(name)-12 | %(message)");
formatter.set_time_format("%Y-%m-%d %H:%M:%S");

let root = Logger::root();
root.add_handler(StreamHandler::new(formatter, std::io::stdout())).unwrap();
root.set_level(Level::Debug);

let logger = Logger::get("my::module");
logger.info("inherits root's handler and level");
```

See [`examples/quickstart.rs`](examples/quickstart.rs) for a fuller demo
(including per-level ANSI colors). Run it with:

```sh
cargo run --example quickstart
```

## Pattern syntax

A pattern is literal text interspersed with `%(field)` placeholders. A
placeholder may be followed by a spec controlling width and alignment:

| Spec        | Meaning                                              |
|:------------|:-----------------------------------------------------|
| `%(name)`   | The value of `name`, or `""` if absent.              |
| `%(name)8`  | Right-align to a minimum width of 8.                 |
| `%(name)-8` | Left-align to a minimum width of 8.                  |
| `%(name).4` | Truncate to at most 4 characters.                    |
| `%(name)-8.4` | Truncate to 4, then left-pad to width 8.           |

Common fields populated per record: `message`, `level`, `name`, `timestamp`,
`thread`.

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.