Xaeian

Python utilities. Zero dependencies for core. Optional extras for time, serial, media, database and more...

Philosophy

Xaeian wraps stdlib boilerplate into intent-level APIs. You read what code does, not how. In real projects this cuts ~35% of code volume.

This follows the Zen of Python:

• Beautiful over ugly: Time() + "15m" vs datetime.now(tz=...) + timedelta(minutes=15)
• Simple over complex: db.find_one("users", id=42) vs acquire/try/finally/dict/close
• Flat over nested: DIR.zip(src, out) vs os.walk + zipfile + os.path.relpath loop
• Readability counts: code reads like intentions, not implementation
• One obvious way to do it: crc16_modbus.encode(frame), JSON.load(path), Time(ts).to("iso")
• Errors should never pass silently: DatabaseError wraps driver exceptions with context
• Namespaces are one honking great idea: FILE, DIR, PATH, CSV, JSON as static classes

Trade-offs:

• Explicit over implicit: PATH.resolve auto-joins with CWD, db.insert auto-serializes dicts to JSON. Convenient in 95% of cases, surprising in the rest. Deliberate, and switchable where it gets in the way (auto_resolve=False).
• Performance: an extra abstraction layer costs. Path resolution, auto-serialization and placeholder conversion run on every call. Negligible for APIs and tools, not for tight loops over millions of rows.

Type safety comes from Pydantic models and type hints on the application layer. Xaeian is the plumbing underneath. Each layer does one thing and stays out of the way. It fits best when you own the stack end-to-end and value compact code over configurability.

Install

pip install xaeian            # core
pip install xaeian[time]      # + pytz, tzlocal
pip install xaeian[serial]    # + pyserial
pip install xaeian[plot]      # + matplotlib
pip install xaeian[dsp]       # + scipy
pip install xaeian[db]        # + pymysql, psycopg2
pip install xaeian[db-async]  # + aiomysql, asyncpg, aiosqlite
pip install xaeian[media]     # + pypdf, PyMuPDF, Pillow
pip install xaeian[eda]       # + sexpdata, pypdf, PyMuPDF
pip install xaeian[sftp]      # + paramiko
pip install xaeian[all]       # everything

Examples

from xaeian import FILE, JSON, CSV, Time, logger, split_str, generate_password
from xaeian.crc import crc16_modbus
from xaeian.db import Database

# Files: auto extension, context-based paths
JSON.save("config", {"debug": True, "port": 8080})
CSV.save("users", [{"name": "Jan", "age": 30}, {"name": "Anna", "age": 25}])

# Time: parse anything, arithmetic with strings
t = Time("2025-03-01T00:00:00+01:00") + "2w 3d"
t.round("w")  # Monday 00:00
t.to("iso")   # "2025-03-18T00:00:00+01:00", the offset you gave is the offset you get

# CRC: encode/decode with Modbus, ISO, custom
frame = crc16_modbus.encode(b"\x01\x03\x00\x00\x00\x0A")
assert crc16_modbus.decode(frame) is not None

# String tools
split_str('a,"b,c",d', sep=",")  # ['a', '"b,c"', 'd']
generate_password(16)            # 'aB3$xY9!mN2@pQ7&'

# Database: sqlite/mysql/postgres, sync/async
db = Database("sqlite", "app.db")
db.insert("users", {"name": "Jan", "settings": {"theme": "dark"}})
db.find("users", order="name", limit=10)
with db.transaction():
  db.update("users", {"verified": True}, "id = ?", 42) # `?` on every backend

# Serial recorders: threaded read, latest value via .value
from xaeian.serial import Recorder
recs = [Recorder(p, name=n, regex=Recorder.SCI_NORM)
  for n, p in {"U1": "COM7", "I1": "COM8"}.items()]
for r in recs: r.start()  # background reader threads
...                       # app-side reap loop snapshots r.value (CSV, DB, MQTT)
for r in recs: r.stop()

# Plot: fluent, stacked panels, auto datetime
from xaeian.plot import Plot
(Plot(theme="dark")
  .line(t, temp, "Temperature [°C]")
  .panel()
  .line(t, hum, "Humidity [%]")
  .title("Sensors")
  .save("dashboard.png"))

# DSP: immutable signals, filters, FFT, vibration metrics
from xaeian.dsp import Signal
sig = Signal.from_accel(raw_x, fs=6666, bits=16, g_range=2)
clean = sig.highpass(10).lowpass(500)
print(f"RMS:{clean.rms:.4f}  peak_freq:{clean.fft().peak_freq:.0f}Hz")

# Binary structs: C-like encoding with CRC, bitfields, scale/offset
from xaeian.cstruct import Struct, Field, Bitfield, Type, Endian
from xaeian.crc import crc32_iso
pkt = Struct(endian=Endian.little, crc=crc32_iso)
pkt.add(
  Field(Type.uint32, "timestamp", "s"),
  Bitfield("flags", [("enabled", 1), ("error", 1), ("mode", 6)]),
  Field(Type.float, "temperature", "°C"),
)
flags = {"enabled": 1, "error": 0, "mode": 5}
raw = pkt.encode({"timestamp": 1234567890, "flags": flags, "temperature": 23.5})
pkt.decode(raw) # {"timestamp": 1234567890, "flags": {...}, "temperature": 23.5}

# Media: compress, strip metadata
from xaeian.media.min import compress
compress("report.pdf")            # → report-min.pdf
compress("photos/", max_px=1280)  # → photos-min/ (recursive)

# Logging: colored, rotating
log = logger("app", file="app.log")
log.inf("started") # 2025-03-01 14:32:01 INF started

CLI

xn tree .                       # directory tree
xn dupes photos/                # find duplicates
xn wifi                         # saved Wi-Fi passwords
xn fonts web/fonts/             # rename to {family}-{weight}
xn host 10.0.0.1 --drop         # drop a pinned SSH host key
xn min report.pdf               # compress PDF
xn min photo.jpg -f avif        # convert to AVIF
xn min photos/ --max-px 1280    # batch resize
xn meta photo.jpg -i            # strip EXIF in-place
xn ico logo.png -o favicon.ico  # multi-size .ico

Modules