mongoquery

1.4.3 verified Fri May 01 auth: no python maintenance

A utility library that provides a MongoDB-like query language for querying Python collections, especially lists of dicts from JSON or YAML parsers. Current version is 1.4.3. Releases are infrequent; the last release was around 2019.

pip install mongoquery

Common errors

error TypeError: 'Query' object is not iterable ↓

cause Calling .match() incorrectly expects an iterable of dicts, but a single dict was passed.

fix

Wrap single dict in a list: q.match([my_dict]) or use q.match(my_dict) only if my_dict is itself a list.

error AttributeError: 'str' object has no attribute 'items' ↓

cause A string was passed where a dict was expected (e.g., using $regex as a value without proper operator syntax).

fix

For regex matching, use compiled regex: q = Query({'field': re.compile(r'pattern')}) or use dict: q = Query({'field': {'$regex': 'pattern'}}).

Warnings

breaking Version 1.4.0 changed how compiled regexes are supplied: they must be compiled regex objects (not strings with $regex) when using $regex operator. ↓

fix Use re.compile(r'pattern') directly as a value, or use string with '$regex' key in dict structure.

gotcha The library only matches against lists of dicts (or similar nested structures). It does not operate on arbitrary Python objects or ORM models. ↓

fix Ensure input data is a list of dicts-like structures. For objects, use __dict__ or convert to dict first.

gotcha Operators like $elemMatch may behave unexpectedly if the array contains objects with extra keys; matching is done against each element entirely. ↓

fix Review MongoDB documentation for $elemMatch semantics and test with your data.

Imports

Query
wrong
```
import mongoquery
```
correct
```
from mongoquery import Query
```
The main class is Query; importing the module alone requires mongoquery.Query.

Quickstart

Basic usage: create a Query with a MongoDB-like filter and call .match() on a list of dicts.

from mongoquery import Query

items = [
    {'name': 'Alice', 'age': 30},
    {'name': 'Bob', 'age': 25},
    {'name': 'Charlie', 'age': 35}
]

q = Query({'age': {'$gte': 30}})
result = q.match(items)
print(result)  # [{'name': 'Alice', 'age': 30}, {'name': 'Charlie', 'age': 35}]