expressql is a flexible, Pythonic Domain-Specific Language (DSL) for constructing complex SQL conditions and expressions safely and expressively.
It is designed to reduce boilerplate, prevent common SQL mistakes, and allow arithmetic, logical, and chained comparisons directly in Python syntax.
Supports Python 3.8 through 3.14 with comprehensive test coverage across all versions.
✅ Arithmetic expressions with automatic SQL translation
✅ Logical composition (AND, OR, NOT) using natural Python operators
✅ Chained inequalities (50 < col("age") < 80)
✅ SQL-safe placeholder management
✅ Null-safe operations (is_null, not_null)
✅ Set membership (IN, NOT IN)
✅ Supports custom SQL functions (Func(...))
✅ Fluent API for advanced condition building
✅ Parsing of SQL-like strings into expressions and conditions
✅ Automatic expansion of BETWEEN clauses into composite comparisons
expressql is part of a complete SQL toolkit for Python:
- expressql (this package) - Build SQL expressions and conditions with safe, intuitive syntax
- recordsql - Full query builder for DML operations (SELECT, INSERT, UPDATE, DELETE, JOIN, WITH)
- tablesqlite - SQLite schema management and DDL operations (CREATE TABLE, ALTER TABLE, migrations)
Use them independently or together for a complete, type-safe SQL solution.
from expressql import col, cols, Func
age, salary, department = cols("age", "salary", "department")
condition = ((age > 30) * (department == "HR")) + (salary > 50000)
print(condition.placeholder_pair())
# ('((age > ?) AND (department = ?)) OR (salary > ?)', [30, 'HR', 50000])You can parse raw strings into full SQL-safe expressions:
from expressql.parsers import parse_expression
expr = parse_expression("LOG(age, 10) + CUSTOM_FUNC(salary, bonus + 10) + 15")
print(expr.placeholder_pair())
# ('(? + LOG(age, ?) + CUSTOM_FUNC(salary, (bonus + ?)))', [15, 10, 10])Or transform high-level condition strings:
from expressql.parsers import parse_condition
cond = parse_condition("age BETWEEN 30 AND 50 AND department = 'IT'")
print(cond.placeholder_pair())
# ('(age >= ? AND age <= ?) AND (department = ?)', [30, 50, 'IT'])Auto-convert BETWEEN clauses:
from expressql.parsers import transform_betweens
s = "weight/POWER(height, 2) BETWEEN 18.5 AND 24.9 AND age >= 18"
print(transform_betweens(s))
# '(weight / POWER(height, 2) >= 18.5 AND weight / POWER(height, 2) <= 24.9 AND age >= 18)'from expressql import col
age = col("age")
condition = (age + 10) > 50SQL:
(age + 10) > 50score = col("score")
cond = (50 < score) < 80 # Equivalent to 50 < score < 80SQL:
(score > 50 AND score < 80)Use * or & for AND, + or | for OR, and ~ for NOT:
salary = col("salary")
dept = col("department")
cond = (salary > 40000) * (dept == "IT")SQL:
(salary > 40000 AND department = 'IT')Functions can be called directly on expressions if they are uppercase:
from expressql import col
total = col("salary") + col("bonus")
cond = total.LOG() > 10SQL:
LOG((salary + bonus)) > 10Custom functions:
from expressql import functions as f, cols
salary, bonus, passive_incomes = cols("salary", "bonus", "passive_incomes")
func_expr = f.CUSTOM_FUNC_FOO(salary, bonus, passive_incomes, inverted=True)SQL:
1/CUSTOM_FUNC_FOO(salary, bonus, passive_incomes)city = col("city")
region = col("region")
cond = city.is_null + region.isin(["North", "South"])SQL:
(city IS NULL OR region IN ('North', 'South'))Check the provided examples:
python simple_examples.py
python complex_examples.pyThese demonstrate arithmetic, chaining, null logic, function use, and condition parsing.
Comprehensive documentation is available, built with Sphinx:
To build the documentation locally:
# Install documentation dependencies
pip install sphinx sphinx-rtd-theme sphinx-autodoc-typehints
# Build HTML documentation
cd docs
make html
# Open docs/build/html/index.html in your browser- Quick Start Guide: Get up and running quickly
- User Guide: Detailed guides on expressions, conditions, functions, and parsing
- API Reference: Complete API documentation for all modules
- Examples: Comprehensive examples for various use cases
- Contributing Guide: How to contribute to the project
The documentation includes:
- Detailed explanations of all features
- Code examples with expected output
- Best practices and common patterns
- Integration examples with popular databases
Why doesn't expressql include full query builders?
expressql focuses specifically on expressions and conditions - the building blocks of SQL queries. For complete query building:
- Use recordsql for DML operations (SELECT, INSERT, UPDATE, DELETE)
- Use tablesqlite for DDL operations (CREATE TABLE, schema management)
This modular approach lets you use only what you need, or combine all three for a complete SQL solution.
Can you make the column name validation more permissive?
In most cases, strict column validation prevents SQL injection or typos. However, I have a version that does a simpler check and allows passing forgiven characters. If it proves relevant, I will probably update it.
Every condition string comes wrapped in brackets, is there any way to avoid it? The conditions wrap themselves in brackets to pass it to other functions that might be calling it. Avoiding this could be implemented by setting a check '_first = True' into the functions, but it's just one extra pair of parenthesis on the final expression
🔥 Tip
If you're using this in a larger query builder or ORM, let me know —
I might have anexpressql-querybuilderin the works 👀.
Contributions are welcome!
If you have suggestions for improvements, new features, or find any bugs, feel free to open an issue or submit a pull request.
I'm especially interested in ideas for better query builders and integrations with ORMs.
- 🌌 More built-in SQL functions (
expressql.functions) - 🌌 Chain-aware logical optimizations
- 🌌 Better error tracing and SQL preview options
- 🌌 Performance optimizations for complex expression trees
MIT License — free for personal and commercial use.