Metadata-Version: 2.4
Name: journald-send
Version: 0.2.0
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Operating System :: POSIX :: Linux
Classifier: Typing :: Typed
License-File: LICENSE
Summary: A thin library to send messages to journald using its native protocol.
Author-email: Nguyễn Hồng Quân <ng.hong.quan@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/hongquan/journald-send/blob/main/CHANGELOG.md
Project-URL: Documentation, https://journald-send.readthedocs.io
Project-URL: Homepage, https://github.com/hongquan/journald-send
Project-URL: Repository, https://github.com/hongquan/journald-send

# 📜 journald-send

![made-in-vietnam](https://madewithlove.vercel.app/vn?heart=true&colorA=%23ffcd00&colorB=%23da251d)
[![journald-send](https://badge.fury.io/py/journald-send.svg)](https://pypi.org/project/journald-send/)
[![ReadTheDocs](https://readthedocs.org/projects/journald-send/badge/?version=latest)](https://journald-send.readthedocs.io?badge=latest)
[![Common Changelog](https://common-changelog.org/badge.svg)](https://common-changelog.org)


A lightweight Python library to send messages to [journald] (Linux system logging) using its native protocol.

## 💡 Features

- Simple function to log messages directly to [journald] using its native protocol.
- Best for structured logging.
- Pure-Rust (not depending on [libc], although PyO3 may include it when linking with CPython).
- Not depend on C-based `libsystemd` (``journald-send`` only writes to journald, does not read or interact with [systemd]).

## 🤔 Motivation

Previously, I used [systemd-python], but this library was slow to release, and its support for Python 3.14, especially in free-threaded mode, was unknown.
So I developed `journald-send` to support Python 3.14 and free-threaded mode.

It is implemented using pure-Rust [rustix] and [memfd] crates, which provide an elegant, Rust-ergonomic API compared to *libc*.

## 📦 Installation

Install via pip:

```sh
pip install journald-send
```

Or using uv:

```sh
uv add journald-send
```

## 🐍 Usage

Import and use the send function:

```python
import journald_send
journald_send.send("Hello, journald!")
```

Or use the ``JournalHandler`` for Python logging framework integration:

```python
import logging
from journald_send.log_handler import JournalHandler

log = logging.getLogger("my-app")
log.addHandler(JournalHandler(SYSLOG_IDENTIFIER="my-app"))
log.warning("Something happened")
```

## 📁 Examples

See examples in the *examples* folder.

## 📖 Documentation

Full documentation is available at [Read the Docs](https://journald-send.readthedocs.io).

## 🤝 Contributing

Contributions welcome; open an issue or PR.

## 🔧 Development

### Prerequisites

- Python >= 3.12
- Rust toolchain
- [uv] package manager

### Setup

```sh
uv sync --all-groups
```

### Build

```sh
uv run maturin develop
```

### Run Tests

```sh
uv run pytest
```

### Build Documentation

```sh
just docs
```

## 🙏 Credits

This project learned from [tracing-journald] crate for how to talk with [journald] at low level.


[journald]: https://wiki.archlinux.org/title/Systemd/Journal
[systemd]: https://systemd.io/
[systemd-python]: https://pypi.org/project/systemd-python/
[uv]: https://pypi.org/project/uv/
[libc]: https://crates.io/crates/libc
[rustix]: https://crates.io/crates/rustix
[memfd]: https://crates.io/crates/memfd
[tracing-journald]: https://crates.io/crates/tracing-journald

