sqlean.py

sqlean.py packages Python’s standard sqlite3 module together with the sqlean C extensions, giving you crypto, regex, fuzzy matching, statistics, and a dozen other SQL functions that stock SQLite doesn’t ship with. It’s built as a drop-in replacement: swap import sqlite3 for import sqlean as sqlite3 and existing DB-API 2.0 code keeps working unchanged, with the extra functions available but disabled until you opt in.

Under the hood it’s a fork of pysqlite3, statically linking a pinned SQLite amalgamation and the sqlean extension sources instead of relying on the host OS’s sqlite3 library. That sidesteps version-skew issues between what a system ships and what your code expects, at the cost of maintaining a compiled wheel per platform.

What You Get

• A DB-API 2.0 compliant, sqlite3-compatible module (sqlean.dbapi2) usable as a straight import swap
• Twelve bundled SQLite extensions covering crypto, define, fileio, fuzzy, ipaddr, regexp, stats, text, time, unicode, uuid, and vsv
• Environment-variable-based extension toggling via sqlean.extensions.enable_all()/enable(*names)
• Prebuilt binary wheels for Linux (x86_64/aarch64) and macOS (x86_64/arm64)

Common Use Cases

• Replacing sqlite3 in existing code with zero API changes
• Running regex and fuzzy-matching queries directly in SQL
• Computing hashes and statistical aggregates inside SQLite queries without round-tripping to Python

Under The Hood

Architecture The package is a thin two-layer wrapper: a small pure-Python control surface (sqlean/__init__.py, dbapi2.py, extensions.py) sitting on top of a compiled C extension module (sqlean._sqlite3) built from a set of sources forked from pysqlite3/pysqlite (module, connection, cursor, cache, microprotocols, prepare_protocol, statement, util, row, blob). The Python extensions module doesn’t touch the C layer directly — it sets environment variables that are read during C-level initialization through a build-time macro wiring, which conditionally registers the vendored sqlean extensions before any connection opens. This env-var handshake between the Python and C layers is unusual but simple; changing the core abstraction (e.g. swapping the vendored SQLite amalgamation) means touching the build script and vendored sources, not the Python-facing API.

Tech Stack Written in C and Python, targeting modern Python only, with no runtime Python dependencies. The build vendors a pinned SQLite amalgamation and the sqlean extension sources via dedicated fetch steps, then compiles them together into a single extension module using setuptools’ build_ext machinery with custom source and macro wiring. Distribution is through prebuilt wheels on PyPI, with continuous integration exercising the build and test suite across a broad matrix of Python versions on Linux.

Code Quality The test suite is extensive, inherited from CPython’s own sqlite3 test coverage and organized into focused modules covering backups, the DB-API surface, extensions, connection factories, hooks, regressions, transactions, type handling, and user-defined functions. Tests run via a custom unittest runner across multiple Python versions in CI on every push and pull request, giving strong confidence in DB-API compatibility across versions. There’s no visible static typing or linter configuration in the repository, and the C layer’s error handling wasn’t independently audited beyond its DB-API-compliant exception hierarchy inherited from pysqlite3.

API Design The package’s core promise is zero-friction compatibility: import sqlean as sqlite3 preserves the entire DB-API 2.0 surface, including Row objects and the adapter/converter protocol, so existing code needs no changes. Extension activation is an explicit, discoverable opt-in — enable_all() or enable("stats", "text") — rather than magic connection-string flags, which keeps the default path frictionless while making the advanced path a single clear call made before connecting. Documentation is a concise, example-driven README, though the project explicitly states it’s no longer maintained, which tempers confidence in the API’s forward evolution.