v0.2.0 — Parser Correctness & Reliability

⚠️ Breaking Changes

Two silent failure modes have been replaced with explicit errors. If your code relied on either behaviour, see the migration guide below.

	Before	After
parse_date("bad-input")	Returned "bad-input" as a string	Raises FilterError
parse_regex("/foo/g")	Silently dropped g, returned {"$regex": "foo"}	Raises FilterError

Migration

from moleql.mql.errors import FilterError

# parse_date
try:
    result = parse("created>bad-date")
except FilterError:
    ...  # handle invalid date

# parse_regex
try:
    result = parse("name=/foo/g")   # "g" is not a MongoDB flag
except FilterError:
    ...  # handle invalid flags

---

🐛 Bug Fixes

Critical — Wrong operator selected when value contains operator characters

Queries like price>10=something were parsed with the wrong operator (= instead of >), producing silently incorrect MongoDB filters. The operator is now always resolved by scanning left-to-right for the first operator character in the string.

High — Intentional None from a custom caster was silently discarded

When a custom caster deliberately returned None (e.g. to store a null MongoDB value), cast() treated it as "no rule matched" and fell through to default_cast, ignoring the caster's result entirely. A sentinel value now correctly distinguishes the two cases.

High — parse_date silently fell back to a string on invalid input (breaking)

An unparseable date string was returned unchanged, causing silent string comparisons in MongoDB instead of date comparisons. parse_date now raises FilterError immediately on invalid input.

Medium — parse_regex silently dropped unrecognised flags (breaking)

Flags outside MongoDB's supported set (i, m, s, x) were filtered out without any indication. parse_regex now raises FilterError when an unrecognised flag is encountered.

Low — Typo in skip/limit error message

"{parameter} if not a valid skip/limit value" corrected to "{parameter} is not a valid skip/limit value".

Low — Incorrect type annotations (any → Any)

Several type hints used the built-in any function instead of typing.Any, producing incorrect type information for static analysers.

---

🧪 Tests

10 new regression tests added covering each of the fixed scenarios. All 181 tests pass.

---

📦 Dependencies

All runtime and development dependencies updated to their latest compatible versions.

Package	From	To
dateparser	1.2.2	1.4.0
pymongo	4.15.5	4.16.0
coverage	7.13.0	7.13.5
mypy	1.19.1	1.20.0
pytest	9.0.2	9.0.3
pytest-cov	7.0.0	7.1.0
ruff	0.14.10	0.15.10

Full changelog: v0.1.3...v0.2.0

🧬 MoleQL v0.1.0 — First Public Release

Overview

This is the first official release of MoleQL,
a lightweight Python library that converts human-readable query-string expressions into structured, type-safe MongoDB queries.

MoleQL is designed for developers building APIs, CLI tools, or data pipelines that need to translate URL parameters like:

?age>30&country=US&status=in(active,pending)

into a clean MongoDB query document ready for find() or aggregation pipelines.

This initial version lays the foundation for the MoleQL syntax engine, including parsing, validation, and conversion to MongoDB-compliant filters, sort directives, projections, and text search operators.

🚀 Key Features

• Filter operators: =, !=, <, <=, >, >=
• List support: in(...), !=in(...)
• Regex parsing: /pattern/flags → $regex + $options
• Sorting: sort=-created_at,name
• Pagination: skip=10, limit=50
• Field selection: fields=name,email,age
• Text search: text=search terms
• Blacklisting: exclude restricted fields from parsing
• Custom type casters: safely extend value conversions

🧱 Technical Highlights

• Fully compatible with Python ≥ 3.12
• Built using uv, pytest, and Ruff
• CI/CD with GitHub Actions and Trusted PyPI Publishing
• Extensible handler architecture (FilterHandler, SortHandler, etc.)
• Clean, typed design using PEP-484 annotations and modern Python idioms

📦 Installation

pip install moleql
# or
uv add moleql

❤️ Acknowledgments

Created and maintained by Pedro Guzmán (@OneTesseractInMultiverse).
Special thanks to early contributors and the open-source Python community
for inspiration and tooling support (uv, Ruff, pytest, PyPA).