python-systemd

https://github.com/systemd/python-systemd
Admin
A Python module providing native access to systemd facilities for tasks such as sending and reading...
Tokens:58,495
Snippets:412
Trust Score:9.4
License:LGPL-2.1
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Example: Using listen_fds_with_names to iterate over sockets and names

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Example of using `listen_fds_with_names` to get a dictionary of file descriptors and their names, then printing each pair. Requires libsystemd ≥ 227.

```python
from systemd.daemon import listen_fds_with_names

sockets = listen_fds_with_names()
for fd, name in sockets.items():
    print(fd, name)
```

--------------------------------

### Example: Using listen_fds to iterate over activated sockets

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Example of using `listen_fds` to get a list of file descriptors and print each one. The returned list contains integers starting from 3 (LISTEN_FDS_START).

```python
from systemd.daemon import listen_fds

fds = listen_fds()
for fd in fds:
    print('activated socket on fd', fd)
```

--------------------------------

### Install python3-systemd on openSUSE/SLE

Source: https://github.com/systemd/python-systemd/blob/main/README.md

Install python3-systemd on openSUSE and SLE using zypper.

```bash
zypper in python3-systemd
```

--------------------------------

### Build, install, and test systemd journal

Source: https://github.com/systemd/python-systemd/blob/main/README.md

Build and install the package, then test sending a journal entry using the systemd.journal module.

```python
python -m build
python -m pip install .
python
>>> from systemd import journal
>>> journal.send("Test")
```

--------------------------------

### Install python3-systemd on Debian/Ubuntu/Mint

Source: https://github.com/systemd/python-systemd/blob/main/README.md

Update the package list and install python3-systemd on Debian, Ubuntu, or Mint using apt.

```bash
apt update
apt install python3-systemd
```

--------------------------------

### Install build dependencies on Debian/Ubuntu

Source: https://github.com/systemd/python-systemd/blob/main/README.md

Install build dependencies for building python-systemd from source on Debian or Ubuntu.

```bash
apt install libsystemd-dev gcc python3-dev pkg-config
```

--------------------------------

### Install python-systemd on Arch

Source: https://github.com/systemd/python-systemd/blob/main/README.md

Install python-systemd on Arch using pacman with the -Sy flags to refresh the package database.

```bash
pacman -Sy python-systemd
```

--------------------------------

### Install python3-systemd on Fedora

Source: https://github.com/systemd/python-systemd/blob/main/README.md

Install the python3-systemd package on Fedora using the dnf package manager.

```bash
dnf install python3-systemd
```

--------------------------------

### Example: map_priority usage

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.JournalHandler.md

Demonstrates calling map_priority with logging.WARNING, which returns 4 (LOG_WARNING).

```python
import logging
from systemd import journal

print(journal.JournalHandler.map_priority(logging.WARNING))  # 4 (LOG_WARNING)
```

--------------------------------

### Send notifications with notify()

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Examples of using daemon.notify() for basic readiness, unsetting the environment variable, and storing file descriptors with FDSTORE.

```python
from systemd import daemon

# Basic readiness
daemon.notify('READY=1')

# Unset the env var afterwards
daemon.notify('STATUS=Starting up', unset_environment=True)

# Store file descriptors for later retrieval (FDSTORE)
daemon.notify('FDSTORE=1', fds=[3, 4])
```

--------------------------------

### Build python-systemd from source on CentOS/RHEL/Fedora

Source: https://github.com/systemd/python-systemd/blob/main/README.md

Install build dependencies and build python-systemd from source on CentOS, RHEL, and Fedora.

```bash
dnf install git python3-pip gcc python3-devel systemd-devel
pip3 install 'git+https://github.com/systemd/python-systemd.git#egg=systemd-python'
```

--------------------------------

### get_catalog usage example

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.md

Example usage of get_catalog with error handling. Imports journal and id128, attempts to print the catalog entry for SD_MESSAGE_STARTUP_FINISHED, and catches OSError to print a fallback message.

```python
from systemd import journal
from systemd import id128

try:
    print(journal.get_catalog(id128.SD_MESSAGE_STARTUP_FINISHED))
except OSError as e:
    print('no catalog entry available:', e)
```

--------------------------------

### Reader instantiation examples

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.Reader.md

Shows various ways to instantiate Reader: default, with SYSTEM_ONLY flag, with a path, with custom converters, and as a context manager. The context manager automatically closes the journal.

```python
from systemd import journal

# Default: local journal only
j = journal.Reader()

# Volatile + system files, like "journalctl -b --system"
j2 = journal.Reader(flags=journal.SYSTEM_ONLY)

# Explicit journal directory
j3 = journal.Reader(path='/var/log/journal')

# Custom converters
j4 = journal.Reader(converters={'PRIORITY': int, '_EXE': str})

# Context manager closes the journal automatically
with journal.Reader() as j:
    for entry in j:
        pass
```

--------------------------------

### Iterate over seats with login.seats()

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/login.md

Example usage of login.seats() to iterate over and print each available seat.

```python
from systemd import login

for seat in login.seats():
    print(seat)
```

--------------------------------

### Example: using get_catalog

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.Reader.md

Example usage of get_catalog. Iterates over journal entries and prints the message and catalog text, catching IndexError and KeyError when no catalog text is available.

```python
from systemd import journal

j = journal.Reader()
for entry in j:
    try:
        print("MESSAGE: ", entry['MESSAGE'])
        print("CATALOG: ", j.get_catalog())
    except (IndexError, KeyError):
        pass  # no catalog text for this entry
```

--------------------------------

### Match filtering example

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.Reader.md

Filters journal entries to the current boot, log level INFO or lower, and the systemd-udevd.service unit, then prints each entry's MESSAGE.

```python
j = journal.Reader()
j.this_boot()
j.log_level(journal.LOG_INFO)
j.add_match(_SYSTEMD_UNIT='systemd-udevd.service')
for entry in j:
    print(entry['MESSAGE'])

```

--------------------------------

### Check if running under systemd with booted()

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Example usage of daemon.booted() to check if the system is running under systemd and print a message accordingly.

```python
from systemd import daemon
if daemon.booted():
    print('running under systemd')
```

--------------------------------

### sendv usage examples

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.md

Demonstrates sending messages with sendv, including multiple fields and binary data. str arguments are UTF-8 encoded; bytes are sent as-is.

```python
from systemd import journal

journal.sendv('MESSAGE=Hello world')
journal.sendv('MESSAGE=Hello, again, world', 'FIELD2=Greetings!',
              'FIELD3=Guten tag')
journal.sendv('MESSAGE=Binary message', b'BINARY=\xde\xad\xbe\xef')
```

--------------------------------

### send() usage examples

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.md

Examples of using journal.send() for basic messages, custom fields, binary payloads, and explicit caller information. Note that field names are not validated by send() itself.

```python
from systemd import journal
import uuid

# Basic message
journal.send('Hello world')

# Message with a type ID and custom fields
journal.send('Hello, again, world', MESSAGE_ID=uuid.uuid4(),
             FIELD2='Greetings!', FIELD3='Guten tag')

# Binary payloads are accepted for any field
journal.send('Binary message', BINARY=b'\xde\xad\xbe\xef')

# Explicit caller information
journal.send('failure', CODE_FILE=__file__, CODE_LINE=10, CODE_FUNC='main')
```

--------------------------------

### Get app-specific machine ID with id128.get_machine_app_specific()

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/id128.md

Example usage of id128.get_machine_app_specific() with a uuid.UUID argument. Requires libsystemd >= 240; otherwise raises OSError ENOSYS.

```python
import uuid
from systemd import id128

app = uuid.UUID('0123456789abcdef0123456789abcdef')
app_id = id128.get_machine_app_specific(app)
assert id128.get_machine_app_specific(app) == app_id  # deterministic per app
```

--------------------------------

### Using daemon.is_socket_sockaddr

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Example usage of daemon.is_socket_sockaddr to assert that a socket matches the address '127.0.0.1:2000'. The address grammar is documented in types.md and parsed locally by parse_sockaddr.

```python
from systemd import daemon

assert daemon.is_socket_sockaddr(sock, '127.0.0.1:2000')
```

--------------------------------

### stream usage examples

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.md

Demonstrates writing to a journal stream with an identifier and using print() with the stream. The stream is newline-buffered and opened in write mode.

```python
from systemd import journal

s = journal.stream('myapp')
s.write('message...\n')

# Convenient with print()
stream = journal.stream()
print('message...', file=stream)
```

--------------------------------

### Using daemon.is_socket

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Example usage of daemon.is_socket to assert that a socket object is a socket, and that it is an AF_UNIX stream socket that is listening.

```python
import socket
from systemd import daemon

assert daemon.is_socket(sock)
assert daemon.is_socket(sock, socket.AF_UNIX, socket.SOCK_STREAM, 1)
```

--------------------------------

### stream journal output

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.md

Shows the journal entries produced by the stream example: PRIORITY=7, SYSLOG_IDENTIFIER=myapp, and MESSAGE=message...

```text
PRIORITY=7
SYSLOG_IDENTIFIER=myapp
MESSAGE=message...
```

--------------------------------

### Using SD_MESSAGE_* constants with systemd.journal.send()

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/id128.md

Use this snippet to send a journal message with a specific SD_MESSAGE_* identifier. The constant is passed as the MESSAGE_ID keyword argument to systemd.journal.send(). The example sends a 'system startup finished' message using SD_MESSAGE_STARTUP_FINISHED.

```python
from systemd import journal, id128
journal.send('system startup finished', MESSAGE_ID=id128.SD_MESSAGE_STARTUP_FINISHED)
```

--------------------------------

### Send journal messages with journal.sendv()

Source: https://github.com/systemd/python-systemd/blob/main/README.md

Send journal messages using the journald sendv call directly. This should give the same results in the log as the journal.send() example.

```python
from systemd import journal
journal.sendv('MESSAGE=Hello world')
journal.sendv('MESSAGE=Hello, again, world', 'FIELD2=Greetings!',
               'FIELD3=Guten tag')
journal.sendv('MESSAGE=Binary message', b'BINARY=\xde\xad\xbe\xef')
```

--------------------------------

### Generate random ID with id128.randomize()

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/id128.md

Example usage of id128.randomize() to generate a random UUID and print it.

```python
from systemd import id128

mid = id128.randomize()
print(mid)  # e.g. 3b8f0a5c-4fce-4d90-9a1e-2e9f5a50c4d1
```

--------------------------------

### Handle OSError from login.seats()

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/login.md

Example of handling OSError from login.seats(), specifically checking for errno.ENOENT to indicate no seat data is available.

```python
import errno
from systemd import login

try:
    seats = login.seats()
except OSError as e:
    if e.errno == errno.ENOENT:
        print('no seat data available')
    else:
        raise
```

--------------------------------

### Using daemon.is_fifo

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Example usage of daemon.is_fifo to check if a socket object refers to a FIFO/pipe bound at the given path. Prints a confirmation message when the condition is true.

```python
from systemd import daemon

if daemon.is_fifo(sock, '/run/myapp/pipe'):
    print('yes, this is our pipe')
```

--------------------------------

### Polling for journal events with select.poll

Source: https://github.com/systemd/python-systemd/blob/main/docs/journal.rst

Demonstrates integrating the journal.Reader with an external event loop using select.poll. The setup ensures there is a message to read, adds a match, and then shows the poll event and the resulting journal entry. The output reveals the structure of a journal record, including metadata fields and timestamps.

```pycon
>>> import select
>>> from systemd import journal
>>> j = journal.Reader()
>>> j.seek_tail()
>>> journal.send('testing 1,2,3')   # make sure we have something to read
>>> j.add_match('MESSAGE=testing 1,2,3')
>>> p = select.poll()
>>> p.register(j, j.get_events())
>>> p.poll()
[(3, 1)]
>>> j.get_next()
{'_AUDIT_LOGINUID': 1000,
 '_CAP_EFFECTIVE': '0',
 '_SELINUX_CONTEXT': 'unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023',
 '_GID': 1000,
 'CODE_LINE': 1,
 '_HOSTNAME': '...',
 '_SYSTEMD_SESSION': 52,
 '_SYSTEMD_OWNER_UID': 1000,
 'MESSAGE': 'testing 1,2,3',
 '__MONOTONIC_TIMESTAMP':
    journal.Monotonic(timestamp=datetime.timedelta(2, 76200, 811585),
                      bootid=UUID('958b7e26-df4c-453a-a0f9-a8406cb508f2')),
 'SYSLOG_IDENTIFIER': 'python3',
 '_UID': 1000,
 '_EXE': '/usr/bin/python3',
 '_PID': 7733,
 '_COMM': '...',
 'CODE_FUNC': '<module>',
 'CODE_FILE': '<doctest journal.rst[4]>',
 '_SOURCE_REALTIME_TIMESTAMP':
     datetime.datetime(2015, 9, 5, 13, 17, 4, 944355),
 '__CURSOR': 's=...',
 '_BOOT_ID': UUID('958b7e26-df4c-453a-a0f9-a8406cb508f2'),
 '_CMDLINE': '/usr/bin/python3 ...',
 '_MACHINE_ID': UUID('263bb31e-3e13-4062-9bdb-f1f4518999d2'),
 '_SYSTEMD_SLICE': 'user-1000.slice',
 '_AUDIT_SESSION': 52,
 '__REALTIME_TIMESTAMP': datetime.datetime(2015, 9, 5, 13, 17, 4, 945110),
 '_SYSTEMD_UNIT': 'session-52.scope',
 '_SYSTEMD_CGROUP': '/user.slice/user-1000.slice/session-52.scope',
 '_TRANSPORT': 'journal'}
```

--------------------------------

### Handle notify() errors

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Error handling example for daemon.notify(). Catches OSError, checks for ENOSYS to indicate missing sd_pid_notify support, and prints a message based on the return value.

```python
import errno
from systemd import daemon

try:
    ok = daemon.notify('READY=1')
except OSError as e:
    if e.errno == errno.ENOSYS:
        print('built without sd_pid_notify support')
    else:
        raise
else:
    print('notified' if ok else 'no NOTIFY_SOCKET available')
```

--------------------------------

### Build documentation with ninja

Source: https://github.com/systemd/python-systemd/blob/main/README.md

Build the documentation locally using ninja. The compiled docs will be in build/html.

```shell
ninja -C build html
```

--------------------------------

### Read entries in a time window

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.Reader.md

Reads journal entries from the last 20 minutes and prints each entry's MESSAGE field. Uses seek_realtime to set the start time and iterates over the reader.

```python
from systemd import journal
from datetime import datetime, timedelta

j = journal.Reader()
j.seek_realtime(datetime.now() - timedelta(minutes=20))
for entry in j:
    print(entry['MESSAGE'])

```

--------------------------------

### systemd.login.Monitor.__init__

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/configuration.md

Constructor options for systemd.login.Monitor.

```APIDOC
## systemd.login.Monitor.__init__

### Description
Initializes a login monitor for a given event category.

### Parameters
- **category** (str or None) - Optional - Event category passed to sd_login_monitor_new(3). Valid values: "user", "login", "uid", "seat", "machine", "session". Default: None (monitors everything).
```

--------------------------------

### systemd.journal.Reader.__init__

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/configuration.md

Constructor options for systemd.journal.Reader.

```APIDOC
## systemd.journal.Reader.__init__

### Description
Initializes a journal reader with configurable flags, paths, files, converters, and namespace.

### Parameters
- **flags** (int) - Optional - OR of LOCAL_ONLY, RUNTIME_ONLY, SYSTEM_ONLY, CURRENT_USER, OS_ROOT. Defaults to LOCAL_ONLY if path and files are None, else 0.
- **path** (str or int) - Optional - Directory of journal files as a path or open fd.
- **files** (list[str] or list[int]) - Optional - List of journal file names or fds.
- **converters** (dict[str, callable]) - Optional - Field converters merged over DEFAULT_CONVERTERS.
- **namespace** (str) - Optional - Journal namespace to read (systemd >= 245).

### Notes
- flags, path, files, and namespace are mutually exclusive; path and files together raise ValueError.
```

--------------------------------

### systemd.journal.JournalHandler.__init__

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/configuration.md

Constructor options for systemd.journal.JournalHandler.

```APIDOC
## systemd.journal.JournalHandler.__init__

### Description
Initializes a journal handler for logging with configurable level, sender function, and extra fields.

### Parameters
- **level** (int) - Optional - Standard logging handler level. Default: logging.NOTSET.
- **sender_function** (callable) - Optional - Callable invoked as sender_function(msg, **fields). Default: journal.send.
- **kwargs** (str) - Optional - Extra journal fields attached to every record; SYSLOG_IDENTIFIER defaults to sys.argv[0] when absent.

### Classmethod
- **with_args(config=None)** - Accepts the same options via a single positional dict.
```

--------------------------------

### booted()

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Returns whether the system is running under systemd. Wraps sd_booted(3).

```APIDOC
## booted()

### Description
Returns `True` iff the system is running under systemd. Wraps `sd_booted(3)`. Raises `OSError` with `errno` on error.

### Method
Function call

### Endpoint
`booted()`

### Parameters
None

### Return
- **bool** - `True` if the system is running under systemd, `False` otherwise.

### Throws
- `OSError` - with `errno` set on error.

### Example
```python
from systemd import daemon
if daemon.booted():
    print('running under systemd')
```
```

--------------------------------

### Reader.seek_tail()

Source: https://github.com/systemd/python-systemd/blob/main/docs/journal.rst

Seeks to the end of the journal to read only new entries. Used in the polling example.

```APIDOC
## Reader.seek_tail()

### Description
Moves the read pointer to the end of the journal, so that only new entries are read. This is useful for monitoring live journal events.

### Method
seek_tail()

### Parameters
None

### Returns
None

### Example
```python
from systemd import journal
j = journal.Reader()
j.seek_tail()
```
```

--------------------------------

### Reader.get_events()

Source: https://github.com/systemd/python-systemd/blob/main/docs/journal.rst

Returns the event mask for the Reader to be used with poll. This is part of the polling example.

```APIDOC
## Reader.get_events()

### Description
Returns the event mask that should be used when registering the Reader with a poll object. This is used in conjunction with poll to wait for journal events.

### Method
get_events()

### Parameters
None

### Returns
An integer representing the event mask (e.g., POLLIN).

### Example
```python
import select
from systemd import journal
j = journal.Reader()
j.seek_tail()
journal.send('testing 1,2,3')
j.add_match('MESSAGE=testing 1,2,3')
p = select.poll()
p.register(j, j.get_events())
p.poll()
```
```

--------------------------------

### Create a login.Monitor for machine changes

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/login.md

Creates a Monitor instance to watch for machine/container changes. The category argument is passed verbatim to sd_login_monitor_new(3); valid values are "user", "login", "uid", "seat", "machine", and "session". An invalid value raises ValueError ("Invalid category"), and other failures raise OSError with errno.

```python
m = login.Monitor("machine")     # monitor machine/container changes
```

--------------------------------

### Reader.get_next()

Source: https://github.com/systemd/python-systemd/blob/main/docs/journal.rst

Fetches the next journal entry as a dictionary. Used in the polling example to read the event.

```APIDOC
## Reader.get_next()

### Description
Retrieves the next journal entry that matches the current filters. Returns a dictionary of the entry's fields.

### Method
get_next()

### Parameters
None

### Returns
A dictionary containing the journal entry fields, or None if no more entries.

### Example
```python
from systemd import journal
j = journal.Reader()
j.seek_tail()
journal.send('testing 1,2,3')
j.add_match('MESSAGE=testing 1,2,3')
entry = j.get_next()
```
```

--------------------------------

### Reader.add_match()

Source: https://github.com/systemd/python-systemd/blob/main/docs/journal.rst

Adds a match filter to the Reader to filter journal entries. Used in the polling example.

```APIDOC
## Reader.add_match()

### Description
Adds a match filter to the reader, so that only journal entries matching the given field-value pair are returned. This is used to filter journal events.

### Method
add_match(match)

### Parameters
- **match** (string) - Required - A match string in the form 'FIELD=value'.

### Returns
None

### Example
```python
from systemd import journal
j = journal.Reader()
j.add_match('MESSAGE=testing 1,2,3')
```
```

--------------------------------

### LISTEN_FDS_START

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Module constant representing the first socket-activation fd number, equivalent to SD_LISTEN_FDS_START from libsystemd. It is always 3.

```APIDOC
## LISTEN_FDS_START

### Description
Module constant (`int`): the first socket-activation fd number — `3`, i.e. `SD_LISTEN_FDS_START` from libsystemd.

### Type
`int`

### Value
`3`

### Example
```python
from systemd import daemon
print(daemon.LISTEN_FDS_START)  # 3
```
```

--------------------------------

### Monitor.__init__

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/login.md

Constructor for the Monitor class. Initializes a monitor for login events with an optional category.

```APIDOC
## Monitor.__init__

### Description
Initializes a Monitor object to monitor login sessions, users, seats, and virtual machines/containers. The category parameter determines which kind of events to watch.

### Method
Constructor

### Endpoint
Monitor([category]) -> ...

### Parameters
#### Parameters
- **category** (str or None) - Optional - Which kind of events to watch. Valid values: "user", "login", "uid", "seat", "machine", "session". None monitors all.

### Request Example
```python
m = login.Monitor("machine")
```

### Response
#### Success Response
Returns a Monitor object.

#### Error Handling
- Raises ValueError ("Invalid category") when sd_login_monitor_new returns -EINVAL.
- Raises OSError with errno for other failures (e.g., ENOENT when the system does not provide login data).
```

--------------------------------

### journal.send()

Source: https://github.com/systemd/python-systemd/blob/main/docs/journal.rst

Sends a message to the journal, creating a new journal entry. Used in the polling example to generate an event.

```APIDOC
## journal.send()

### Description
Sends a message to the journal. This is used to generate a journal event for testing or logging.

### Method
send(message)

### Parameters
- **message** (string) - Required - The message to send to the journal.

### Returns
None

### Example
```python
from systemd import journal
journal.send('testing 1,2,3')
```
```

--------------------------------

### Print LISTEN_FDS_START constant

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Prints the value of the LISTEN_FDS_START constant, which is the first socket-activation file descriptor number (3). This constant corresponds to SD_LISTEN_FDS_START from libsystemd.

```python
from systemd import daemon
print(daemon.LISTEN_FDS_START)  # 3
```

--------------------------------

### Procedural creation of the handler

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.JournalHandler.md

Demonstrates creating a JournalHandler directly with parameters.

```APIDOC
## Usage pattern: Procedural creation of the handler

### Description
Creates a `JournalHandler` programmatically with a logging level and a `SYSLOG_IDENTIFIER` field.

### Example
```python
import logging, sys
handler = journal.JournalHandler(level=logging.DEBUG,
                                 SYSLOG_IDENTIFIER=sys.argv[0])
logging.getLogger('app').addHandler(handler)
```
```

--------------------------------

### Monitor.__init__ signature

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/login.md

Constructor signature for the Monitor class. The optional category parameter is a string or None (default None) and is passed verbatim to sd_login_monitor_new(3). Valid categories are "user", "login", "uid", "seat", "machine", and "session"; an invalid value fails with -EINVAL and raises ValueError ("Invalid category").

```python
Monitor([category]) -> ...
```

--------------------------------

### Use login.Monitor as a context manager

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/login.md

Uses the Monitor as a context manager to watch user login events. Inside the with block, obtains the file descriptor and event mask.

```python
from systemd import login

with login.Monitor("user") as m:
    fd = m.fileno()
    events = m.get_events()
```

--------------------------------

### Monotonic type

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.Reader.md

Documentation for the `Monotonic` type, a named-tuple-like structure returned by `Reader.get_next` for the `__MONOTONIC_TIMESTAMP` entry field. It includes field descriptions and a Python usage example.

```APIDOC
## `Monotonic` type

A C struct-sequence (named-tuple-like) type exported as `journal.Monotonic` and as `_reader.Monotonic`. Fields:

| Field | Type (after Reader conversion) | Description |
|-------|-------------------------------|-------------|
| `timestamp` | `datetime.timedelta` (raw: `int` microseconds) | Time value |
| `bootid` | `uuid.UUID` (raw: `bytes`) | Unique identifier of the boot |

Source: `src/systemd/_reader.c:53`. Constructed by `_get_monotonic` with raw values and converted by `_convert_monotonic` (`journal.py:21`) inside `Reader.get_next`. Both the raw and converted forms are described in [types.md](../types.md).

```python
from systemd import journal

entry = journal.Reader().get_next()
mono = entry['__MONOTONIC_TIMESTAMP']
print(mono.timestamp, mono.bootid)
```
```

--------------------------------

### Import systemd.login module

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/login.md

Import the systemd.login module to access functions for querying logged-in users, seats, machines, and the Monitor class.

```python
from systemd import login
```

--------------------------------

### Import systemd.journal module

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.md

Import the systemd.journal module to access journal sending, reading, and logging functionality.

```python
from systemd import journal
```

--------------------------------

### Create JournalHandler with with_args

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.JournalHandler.md

Creates a JournalHandler using the with_args classmethod with a configuration dict that sets SYSLOG_IDENTIFIER to 'my-cool-app'.

```python
handler = journal.JournalHandler.with_args({'SYSLOG_IDENTIFIER': 'my-cool-app'})
```

--------------------------------

### sessions()

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/login.md

Returns a list of current login sessions as a list of strings. Wraps sd_get_sessions(3). Raises OSError on error.

```APIDOC
## sessions()

### Description
Returns a list of current login sessions, as `list[str]`. Wraps `sd_get_sessions(3)`.

### Method
Function call

### Endpoint
`sessions()`

### Parameters
None

### Request Example
```python
from systemd import login

sessions = login.sessions()
```

### Response
#### Success Response
- Returns a list of strings, each representing a session identifier.

#### Response Example
```python
['1', '2', '3']
```

### Error Handling
Raises `OSError` with `errno` from libsystemd (e.g., `ENOENT` when no data is available).
```

--------------------------------

### Show journal entries by executable with add_match()

Source: https://github.com/systemd/python-systemd/blob/main/README.md

Show entries by a specific executable, equivalent to journalctl /usr/bin/vim. Matches can be added from many fields, e.g., _PID for process ID or _SYSTEMD_UNIT for a unit.

```python
from systemd import journal
j = journal.Reader()
j.add_match('_EXE=/usr/bin/vim')
for entry in j:
    print(entry['MESSAGE'])
```

--------------------------------

### Attach MESSAGE_ID via extra

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.JournalHandler.md

Example showing how to attach a `MESSAGE_ID` to a log record by passing it in the `extra` dict of the log call. The handler is added to a logger with propagation disabled.

```python
import logging, uuid
from systemd import journal

log = logging.getLogger('app')
log.propagate = False
log.addHandler(journal.JournalHandler())
mid = uuid.UUID('0123456789ABCDEF0123456789ABCDEF')
log.warning("Message with ID", extra={'MESSAGE_ID': mid})
```

--------------------------------

### Monitor context manager protocol

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/login.md

Context manager protocol methods. __enter__ returns self; __exit__ closes the monitor.

```python
__enter__() -> self          # returns self
__exit__(type, value, traceback) -> None   # closes the monitor
```

--------------------------------

### Show journal entries with catalog explanations

Source: https://github.com/systemd/python-systemd/blob/main/README.md

Show explanations of log messages alongside entries, equivalent to journalctl -x. Uses j.get_catalog() and catches exceptions when no catalog is available.

```python
from systemd import journal
j = journal.Reader()
for entry in j:
    print("MESSAGE: ", entry['MESSAGE'])
    try:
        print("CATALOG: ", j.get_catalog())
    except:
        pass
```

--------------------------------

### DEFAULT_CONVERTERS dictionary definition

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.md

Module-level dict mapping journal field names to value converters. Used as the default converter table for every Reader. Fields not listed get default UTF-8 decoding; if any conversion raises ValueError (including UnicodeDecodeError), the raw bytes value is kept.

```python
DEFAULT_CONVERTERS = {
    'MESSAGE_ID': _convert_uuid,
    '_MACHINE_ID': _convert_uuid,
    '_BOOT_ID': _convert_uuid,
    'PRIORITY': int,
    'LEADER': int,
    'SESSION_ID': int,
    'USERSPACE_USEC': int,
    'INITRD_USEC': int,
    'KERNEL_USEC': int,
    '_UID': int,
    '_GID': int,
    '_PID': int,
    'SYSLOG_FACILITY': int,
    'SYSLOG_PID': int,
    '_AUDIT_SESSION': int,
    '_AUDIT_LOGINUID': int,
    '_SYSTEMD_SESSION': int,
    '_SYSTEMD_OWNER_UID': int,
    'CODE_LINE': int,
    'ERRNO': int,
    'EXIT_STATUS': int,
    '_SOURCE_REALTIME_TIMESTAMP': _convert_timestamp,
    '__REALTIME_TIMESTAMP': _convert_realtime,
    '_SOURCE_MONOTONIC_TIMESTAMP': _convert_source_monotonic,
    '__MONOTONIC_TIMESTAMP': _convert_monotonic,
    '__CURSOR': _convert_trivial,
    'COREDUMP': bytes,
    'COREDUMP_PID': int,
    'COREDUMP_UID': int,
    'COREDUMP_GID': int,
    'COREDUMP_SESSION': int,
    'COREDUMP_SIGNAL': int,
    'COREDUMP_TIMESTAMP': _convert_timestamp,
}
```

--------------------------------

### Import systemd.daemon module

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Import the systemd.daemon module to access its functions and constants.

```python
from systemd import daemon
```

--------------------------------

### Show kernel ring buffer with journal.Reader()

Source: https://github.com/systemd/python-systemd/blob/main/README.md

Show the kernel ring buffer, equivalent to journalctl -k, by matching the _TRANSPORT field to 'kernel'.

```python
from systemd import journal
j = journal.Reader()
j.add_match('_TRANSPORT=kernel')
for entry in j:
    print(entry['MESSAGE'])
```

--------------------------------

### dictConfig / fileConfig

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.JournalHandler.md

Demonstrates configuring the JournalHandler through dictConfig with standard handler options.

```APIDOC
## Usage pattern: dictConfig / fileConfig

### Description
Configures the `JournalHandler` via `logging.config.dictConfig` by specifying `systemd.journal.JournalHandler` as the handler class. Only standard handler options are supported: `level`, `formatter`, `filters`. For positional configuration dicts, use `with_args`.

### Example
```python
LOGGING = {
    'version': 1,
    'handlers': {
        'journal': {'class': 'systemd.journal.JournalHandler',
                    'level': 'DEBUG',
                    'SYSLOG_IDENTIFIER': 'my-cool-app'},
    },
    'root': {'handlers': ['journal']},
}
import logging.config
logging.config.dictConfig(LOGGING)
```
```

--------------------------------

### notify(status, unset_environment=False, pid=0, fds=None)

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Sends a message to the init system about a status change. Wraps sd_notify(3), sd_pid_notify(3), and sd_pid_notify_with_fds(3).

```APIDOC
## notify(status, unset_environment=False, pid=0, fds=None)

### Description
Sends a message to the init system about a status change (e.g. `READY=1`, `RELOADING=1`, `STOPPING=1`, `WATCHDOG=1`, `FDSTORE=1`). Wraps `sd_notify(3)`, `sd_pid_notify(3)`, and `sd_pid_notify_with_fds(3)`.

### Method
Function call

### Endpoint
`notify(status, unset_environment=False, pid=0, fds=None)`

### Parameters
#### Arguments
- **status** (str) - Required - `'KEY=VALUE'`-style notify payload.
- **unset_environment** (bool) - Optional - Default `False`. If true, unset `NOTIFY_SOCKET` after sending.
- **pid** (int) - Optional - Default `0`. Target pid; `0` addresses the calling process (`sd_notify`). Non-zero uses `sd_pid_notify` (requires libsystemd ≥ 214).
- **fds** (sequence of int) - Optional - Default `None`. File descriptors to store (`FDSTORE`); presence switches to `sd_pid_notify_with_fds` (requires libsystemd ≥ 219).

### Return
- **bool** - `True` iff the notification was sent (a readable socket was found). Returns `False` when `NOTIFY_SOCKET` is unset, exactly like the C API.

### Throws
- `OSError` (e.g. `ConnectionRefusedError`, errno `ECONNREFUSED`) when `NOTIFY_SOCKET` points to a non-accessible socket. `errno.ENOSYS` with "Compiled without support for sd_pid_notify" / "... sd_pid_notify_with_fds" when built against libsystemd < 214 / < 219.
- `OverflowError` ("Bad pid_t") when `pid < 0` or it does not fit in `pid_t`; `OverflowError` ("Value to large for an integer") when an fd item does not fit in an `int`.

### Examples
```python
from systemd import daemon

# Basic readiness
daemon.notify('READY=1')

# Unset the env var afterwards
daemon.notify('STATUS=Starting up', unset_environment=True)

# Store file descriptors for later retrieval (FDSTORE)
daemon.notify('FDSTORE=1', fds=[3, 4])
```

Error handling:

```python
import errno
from systemd import daemon

try:
    ok = daemon.notify('READY=1')
except OSError as e:
    if e.errno == errno.ENOSYS:
        print('built without sd_pid_notify support')
    else:
        raise
else:
    print('notified' if ok else 'no NOTIFY_SOCKET available')
```
```

--------------------------------

### listen_fds(unset_environment=True) / _listen_fds(unset_environment=True)

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Returns the number of descriptors passed to the process by the init system as part of socket-based activation. The Python variant returns a list of file descriptors, while the C variant returns an integer count.

```APIDOC
## listen_fds(unset_environment=True) / _listen_fds(unset_environment=True)

### Description
Returns the number of descriptors passed to this process by the init system as part of socket-based activation. Wraps `sd_listen_fds(3)`, which honors the `LISTEN_PID` and `LISTEN_FDS` environment variables. When `unset_environment` is true (default), the `LISTEN_PID`, `LISTEN_FDS`, and `LISTEN_FDNAMES` variables are unset after the call.

### Method
Function call

### Endpoint
- Python: `listen_fds(unset_environment=True)`
- C: `_listen_fds(unset_environment=True)`

### Parameters
#### Function Parameters
- **unset_environment** (bool) - Optional - If true (default), unsets `LISTEN_PID`, `LISTEN_FDS`, and `LISTEN_FDNAMES` after the call.

### Return Value
- `_listen_fds` → `int` (count of fds).
- `listen_fds` → `list[int]` of fds `range(LISTEN_FDS_START, LISTEN_FDS_START + num)`, i.e. `[3, 4, 5, …]` with `LISTEN_FDS_START == 3`.

### Example
```python
from systemd.daemon import listen_fds

fds = listen_fds()
for fd in fds:
    print('activated socket on fd', fd)
```
```

--------------------------------

### Reader.__init__

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.Reader.md

Initializes a new journal reader. Accepts flags, path, files, converters, and namespace parameters to control which journal entries are read.

```APIDOC
## Reader.__init__

### Description
Initializes a new journal reader. Accepts flags, path, files, converters, and namespace parameters to control which journal entries are read.

### Method
Constructor

### Signature
```python
def __init__(self, flags=None, path=None, files=None, converters=None, namespace=None)
```

### Parameters
- **flags** (int) - Optional - OR of `LOCAL_ONLY`, `RUNTIME_ONLY`, `SYSTEM_ONLY`, `CURRENT_USER`, `OS_ROOT`. When `None` and both `path` and `files` are `None`, defaults to `LOCAL_ONLY`; otherwise `0`.
- **path** (str or int) - Optional - Directory containing journal files, either a file-system path or an open file descriptor.
- **files** (list[str] or list[int]) - Optional - List of journal file names, or a list of fds.
- **converters** (dict[str, callable]) - Optional - Mapping of field names to single-argument converters (overrides `DEFAULT_CONVERTERS`). Keys for absent fields fall back to `DEFAULT_CONVERTERS`; unknown fields get UTF-8 decoding.
- **namespace** (str) - Optional - Journal namespace to read (requires systemd ≥ 245).

### Notes
- `flags`, `path`, `files`, and `namespace` are exclusive; `path` and `files` cannot both be given (`ValueError`).
- If `path` is an int, `_Reader` uses `sd_journal_open_directory_fd`; if `files` is a list of ints, `sd_journal_open_files_fd` (both require systemd ≥ 230, else `ENOSYS`).
- `namespace` support requires systemd ≥ 245.

### Example
```python
from systemd import journal

# Default: local journal only
j = journal.Reader()

# Volatile + system files, like "journalctl -b --system"
j2 = journal.Reader(flags=journal.SYSTEM_ONLY)

# Explicit journal directory
j3 = journal.Reader(path='/var/log/journal')

# Custom converters
j4 = journal.Reader(converters={'PRIORITY': int, '_EXE': str})

# Context manager closes the journal automatically
with journal.Reader() as j:
    for entry in j:
        pass
```
```

--------------------------------

### __version__

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Module constant representing the package version string, defined as PACKAGE_VERSION at build time. The same version string is exported by systemd.journal, systemd.id128, and systemd.login.

```APIDOC
## __version__

### Description
`str` — the package version, defined as `PACKAGE_VERSION` at build time.

### Type
`str`

### Value
Package version string (e.g., "252").

### Notes
`systemd.journal`, `systemd.id128`, and `systemd.login` export the same version string.
```

--------------------------------

### Function signatures for listen_fds_with_names and _listen_fds_with_names

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Shows the Python and C signatures for retrieving socket-activated file descriptors along with their names. The Python version returns a dictionary mapping fd to name, while the C version returns a tuple with count and names.

```python
listen_fds_with_names(unset_environment=True)    # py — src/systemd/daemon.py:76
_listen_fds_with_names(unset_environment=True)   # C  — src/systemd/_daemon.c:162 (:174)
```

--------------------------------

### machine_names()

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/login.md

Returns a list of currently running virtual machines and containers on the system as a list of strings. Wraps sd_get_machine_names(3). Raises OSError on error.

```APIDOC
## machine_names()

### Description
Returns a list of currently running virtual machines and containers on the system, as `list[str]`. Wraps `sd_get_machine_names(3)`.

### Method
Function call

### Endpoint
`machine_names()`

### Parameters
None

### Request Example
```python
from systemd import login

machines = login.machine_names()
```

### Response
#### Success Response
- Returns a list of strings, each representing a machine or container name.

#### Response Example
```python
['container1', 'vm1']
```

### Error Handling
Raises `OSError` with `errno` from libsystemd (e.g., `ENOENT` when no data is available).
```

--------------------------------

### `emit` (py)

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.JournalHandler.md

Documentation for the `emit` method of the `JournalHandler` class, which formats and sends log records to the systemd journal.

```APIDOC
## `emit` (py)

### Description
Formats a log record and sends it to the journal via `self.send` (default: `journal.send`). It constructs journal fields from the record and handler configuration, with precedence: message-level fields (highest) > exception fields > handler `_extra` (lowest).

### Method
`emit(self, record)`

### Parameters
- **record** (logging.LogRecord) - Required - The log record to format and send.

### Behavior
- Formats the record using `self.format(record)` and sends it via `self.send`.
- Constructs journal fields as follows:
  - `MESSAGE` = `self.format(record)`
  - `PRIORITY` = `format(self.map_priority(record.levelno))` (string of the int)
  - `LOGGER` = `record.name`
  - `THREAD_NAME` = `record.threadName`
  - `PROCESS_NAME` = `record.processName`
  - `CODE_FILE` = `record.pathname`
  - `CODE_LINE` = `record.lineno`
  - `CODE_FUNC` = `record.funcName`
  - `EXCEPTION_TEXT` = `record.exc_text` (only if set)
  - `EXCEPTION_INFO` = `record.exc_info` (only if set)
  - `CODE_ARGS` = `str(record.args)` (only if set)
  - `SYSLOG_IDENTIFIER` + constructor kwargs = handler `_extra`
  - ... plus every attribute of `record.__dict__` (merged last, so explicit record fields e.g. `MESSAGE_ID` win)

### Precedence
Message-level fields (highest, merged last) > exception fields > handler `_extra` (lowest).

### Error Handling
Wraps everything in `try/except Exception` and calls `self.handleError(record)` on failure, so a broken journal connection never propagates into the application logging call. The `send` callable is passed field names literally; the same field-name rules described under the constructor can surface as `ValueError` inside the handler (then routed to `handleError`).

### Example: Attaching `MESSAGE_ID` via `extra`
```python
import logging, uuid
from systemd import journal

log = logging.getLogger('app')
log.propagate = False
log.addHandler(journal.JournalHandler())
mid = uuid.UUID('0123456789ABCDEF0123456789ABCDEF')
log.warning("Message with ID", extra={'MESSAGE_ID': mid})
```
```

--------------------------------

### Create a default journal reader

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.Reader.md

Creates a default journal reader that reads the local journal only, mimicking journalctl.

```python
from systemd import journal
j = journal.Reader()
```

--------------------------------

### Root-logger redirection

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/journal.JournalHandler.md

Shows how to attach a JournalHandler to the root logger for systemd journal logging.

```APIDOC
## Usage pattern: Root-logger redirection

### Description
Adds a `JournalHandler` to the root logger to redirect all logging output to the systemd journal.

### Example
```python
import logging
logging.root.addHandler(journal.JournalHandler())
```
```

--------------------------------

### Context manager protocol

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/login.md

Context manager protocol for the Monitor class.

```APIDOC
## Context manager protocol

### Description
Supports the context manager protocol: __enter__ returns self, __exit__ closes the monitor.

### Method
Context manager

### Endpoint
__enter__() -> self
__exit__(type, value, traceback) -> None

### Parameters
None

### Response
#### Success Response
__enter__ returns self; __exit__ returns None.
```

--------------------------------

### Function signatures for listen_fds and _listen_fds

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Shows the Python and C signatures for retrieving socket-activated file descriptors. Both default to unsetting the LISTEN_PID, LISTEN_FDS, and LISTEN_FDNAMES environment variables after the call.

```python
listen_fds(unset_environment=True)     # py — src/systemd/daemon.py:58
_listen_fds(unset_environment=True)    # C  — src/systemd/_daemon.c:139 (:146)
```

--------------------------------

### booted() function signature

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/daemon.md

Signature of the booted function. Returns True if the system is running under systemd, otherwise False. Raises OSError on error.

```python
booted() -> bool
```

--------------------------------

### Monitor.fileno signature

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/login.md

Returns a file descriptor to poll for events. Wraps sd_login_monitor_get_fd(3). Raises OSError on error.

```python
fileno() -> int
```

--------------------------------

### Import systemd.id128 module

Source: https://github.com/systemd/python-systemd/blob/main/_autodocs/api-reference/id128.md

Import the id128 module from the systemd package.

```python
from systemd import id128
```
Tokens:
Raw