moleql 0.1.1__tar.gz

moleql-0.1.1/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.3
+Name: moleql
+Version: 0.1.1
+Summary: Add your description here
+Author: Pedro Guzmán
+Author-email: Pedro Guzmán <pedro@subvertic.com>
+Requires-Dist: dateparse>=1.4.0
+Requires-Dist: dateparser>=1.2.2
+Requires-Dist: mypy>=1.18.2
+Requires-Dist: pymongo>=4.15.3
+Requires-Dist: pytest>=8.4.2
+Requires-Dist: ruff>=0.14.4
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/OneTesseractInMultiverse/moleql
+Project-URL: Issues, https://github.com/OneTesseractInMultiverse/moleql/issues
+Description-Content-Type: text/markdown
+
+# MoleQL
+
+> Expressive URL-query to MongoDB query conversion library.
+
+[![CI](https://github.com/OneTesseractInMultiverse/moleql/actions/workflows/ci.yml/badge.svg)](https://github.com/OneTesseractInMultiverse/moleql/actions)
+[![License](https://img.shields.io/github/license/OneTesseractInMultiverse/moleql.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/moleql.svg)](https://pypi.org/project/moleql)
+[![Python Versions](https://img.shields.io/pypi/pyversions/moleql.svg)](https://pypi.org/project/moleql)
+
+## Overview
+
+MoleQL allows your REST APIs or data layers to accept
+URL-style query strings (e.g. `?age>30&status=in(active,pending)`)
+and converts them into MongoDB-compatible query dictionaries.
+It supports filters, sorting, skip/limit, projection and text search.
+
+Example:
+
+```python
+from moleql import parse
+
+query = parse("age>30&country=US&name=/^John/i")
+# yields:
+# {
+#   "filter": {"age": {"$gt": 30}, "country": "US", "name": {"$regex": "^John", "$options": "i"}},
+#   "sort": None,
+#   "skip": 0,
+#   "limit": 0,
+#   "projection": None
+# }
+```
+
+## ✨ Features
+
+- 🧠 Intuitive syntax: `=, !=, <, <=, >, >=`
+- 📋 List operators: `in(...), ...`
+- 🔍 Regex: `/pattern/flags → $regex + $options`
+- 🧾 Pagination: `skip=10, limit=50`
+- ⚙️ Sorting: `sort=-created_at,name`
+- 🧩 Projection: `fields=name,email,age`
+- 🔠 Text search: `text=free text here`
+- 🧱 Type casters: `custom value transformations`
+- 🚫 Blacklist: skip parsing of restricted fields
+- 🧪 Tested: full pytest coverage, Ruff linting
+
+## 🧰 Installation
+
+With uv (recommended):
+
+```bash
+uv add moleql
+```
+
+```bash
+pip install moleql
+```
+
+## 🚀 Quick Start
+
+from moleql import parse
+
+query = parse("age>30&country=US&name=/^John/i")
+print(query)
+
+```python
+from moleql import parse
+
+query = parse("age>30&country=US&name=/^John/i")
+print(query)
+
+# {
+#   "filter": {
+#       "age": {"$gt": 30},
+#       "country": "US",
+#       "name": {"$regex": "^John", "$options": "i"}
+#   },
+#   "sort": None,
+#   "skip": 0,
+#   "limit": 0,
+#   "projection": None
+# }
+```
+
+Extended example
+
+```python
+from moleql import parse
+
+query = parse(
+    "age>=18&status=in(active,pending)"
+    "&sort=-created_at,name"
+    "&skip=10&limit=20"
+    "&fields=name,email,age"
+)
+
+```
+
+Output:
+
+```python
+{
+    "filter": {
+        "age": {"$gte": 18},
+        "status": {"$in": ["active", "pending"]}
+    },
+    "sort": {"created_at": -1, "name": 1},
+    "skip": 10,
+    "limit": 20,
+    "projection": {"name": 1, "email": 1, "age": 1}
+}
+
+```
+
+## 🔣 Supported Operators
+
+|       Expression | Mongo Operator | Example                   |
+|-----------------:|:---------------|:--------------------------|
+|              `=` | direct match   | `age=20` → `{"age": 20}`  |
+|             `!=` | `$ne`          | `status!=active`          |
+|       `>` / `>=` | `$gt` / `$gte` | `score>=80`               |
+|       `<` / `<=` | `$lt` / `$lte` | `price<10`                |
+|        `in(...)` | `$in`          | `role=in(admin,user)`     |
+|      `!=in(...)` | `$nin`         | `tier!=in(gold,platinum)` |
+| `/pattern/flags` | `$regex`       | `name=/^Jo/i`             |
+|          `text=` | `$text`        | `text=free search text`   |
+|        `fields=` | projection     | `fields=name,email`       |
+|          `sort=` | sort directive | `sort=-created_at,name`   |
+
+## 🧱 Quick API Reference
+
+`parse(moleql_query: str, blacklist=None, casters=None) -> dict`
+
+```python
+from moleql import parse
+
+parse("age>25&active=true")
+```
+
+Returns a dictionary with:
+`filter`, `sort`, `skip`, `limit`, `projection`
+
+`moleqularize(moleql_query: str, blacklist=None, casters=None) -> MoleQL`
+
+Parse a MoleQL string and return the internal MoleQL object for
+advanced inspection and debugging.
+
+```python
+from moleql import moleqularize
+
+m = moleqularize("age>25")
+print(m.mongo_query)
+
+```
+
+## 🧩 Custom Casters
+
+You can define custom casters to control type conversions.
+
+```python
+from moleql import parse, get_casters
+
+
+def to_bool(value: str) -> bool:
+    return value.lower() in ("true", "1", "yes")
+
+
+custom_casters = {"bool": to_bool}
+
+q = parse("active=bool(true)&age>30", casters=custom_casters)
+
+```
+
+## 🧠 Design Philosophy
+
+- Transparency — The query string is readable and reversible.
+- Safety — No eval, injection-safe parsing.
+- Extensibility — Easy to plug in custom handlers.
+- Predictability — Every operator maps 1:1 to Mongo semantics.
+- Minimal dependencies — Pure Python, no ODM required.
+
+## ⚙️ Integration Examples
+
+**FastAPI**
+
+```python
+from fastapi import FastAPI, Request
+from moleql import parse
+from pymongo import MongoClient
+
+db = MongoClient()["app"]
+app = FastAPI()
+
+
+@app.get("/users")
+def list_users(request: Request):
+    q = parse(request.url.query.lstrip("?"))
+    return list(db.users.find(q["filter"]))
+
+```
+
+**Flask**
+
+```python
+from flask import Flask, request, jsonify
+from moleql import parse
+
+app = Flask(__name__)
+
+
+@app.get("/orders")
+def orders():
+    q = parse(request.query_string.decode())
+    return jsonify(q)
+
+```
+
+## 🧪 Testing
+
+Run the full suite using uv:
+
+```bash
+uv sync --all-extras --dev
+uv run pytest -vv
+
+```
+
+Generate coverage:
+
+```bash
+uv run pytest --cov=moleql --cov-report=term-missing
+
+```
+
+## 🧹 Code Quality
+
+This repository uses:
+
+ - Ruff — Linting + formatting (UP / pyupgrade rules)
+ - pre-commit — automatic checks
+ - pytest — testing
+ - uv — environment & packaging
+
+Set up hooks:
+```bash
+uv run pre-commit install
+uv run pre-commit run --all-files
+```
+
+## 🧭 Roadmap
+
+- [] Add exists(field) and between(a,b) operators
+- [] Add alias for text= → $search convenience
+- [] Add optional CLI (moleql "age>20" --as-json)
+- [] Extended docs and tutorials
+
+🤝 Contributing
+
+1. Fork this repository
+2. Create your feature branch
+
+    ```bash
+    git checkout -b feat/awesome-change
+    ```
+3. Run formatting and tests
+
+    ```bash
+    uv run pre-commit run --all-files
+    uv run pytest
+    ```
+4. Commit and push your changes
+5. Open a Pull Request 🚀
+
+## 🌟 Acknowledgments
+
+Built and maintained by [@OneTesseractInMultiverse](https://github.com/OneTesseractInMultiverse)
+Inspired by the need for readable, typed, and safe Mongo queries in API
+environments.

moleql-0.1.1/README.md

@@ -0,0 +1,277 @@
+# MoleQL
+
+> Expressive URL-query to MongoDB query conversion library.
+
+[![CI](https://github.com/OneTesseractInMultiverse/moleql/actions/workflows/ci.yml/badge.svg)](https://github.com/OneTesseractInMultiverse/moleql/actions)
+[![License](https://img.shields.io/github/license/OneTesseractInMultiverse/moleql.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/moleql.svg)](https://pypi.org/project/moleql)
+[![Python Versions](https://img.shields.io/pypi/pyversions/moleql.svg)](https://pypi.org/project/moleql)
+
+## Overview
+
+MoleQL allows your REST APIs or data layers to accept
+URL-style query strings (e.g. `?age>30&status=in(active,pending)`)
+and converts them into MongoDB-compatible query dictionaries.
+It supports filters, sorting, skip/limit, projection and text search.
+
+Example:
+
+```python
+from moleql import parse
+
+query = parse("age>30&country=US&name=/^John/i")
+# yields:
+# {
+#   "filter": {"age": {"$gt": 30}, "country": "US", "name": {"$regex": "^John", "$options": "i"}},
+#   "sort": None,
+#   "skip": 0,
+#   "limit": 0,
+#   "projection": None
+# }
+```
+
+## ✨ Features
+
+- 🧠 Intuitive syntax: `=, !=, <, <=, >, >=`
+- 📋 List operators: `in(...), ...`
+- 🔍 Regex: `/pattern/flags → $regex + $options`
+- 🧾 Pagination: `skip=10, limit=50`
+- ⚙️ Sorting: `sort=-created_at,name`
+- 🧩 Projection: `fields=name,email,age`
+- 🔠 Text search: `text=free text here`
+- 🧱 Type casters: `custom value transformations`
+- 🚫 Blacklist: skip parsing of restricted fields
+- 🧪 Tested: full pytest coverage, Ruff linting
+
+## 🧰 Installation
+
+With uv (recommended):
+
+```bash
+uv add moleql
+```
+
+```bash
+pip install moleql
+```
+
+## 🚀 Quick Start
+
+from moleql import parse
+
+query = parse("age>30&country=US&name=/^John/i")
+print(query)
+
+```python
+from moleql import parse
+
+query = parse("age>30&country=US&name=/^John/i")
+print(query)
+
+# {
+#   "filter": {
+#       "age": {"$gt": 30},
+#       "country": "US",
+#       "name": {"$regex": "^John", "$options": "i"}
+#   },
+#   "sort": None,
+#   "skip": 0,
+#   "limit": 0,
+#   "projection": None
+# }
+```
+
+Extended example
+
+```python
+from moleql import parse
+
+query = parse(
+    "age>=18&status=in(active,pending)"
+    "&sort=-created_at,name"
+    "&skip=10&limit=20"
+    "&fields=name,email,age"
+)
+
+```
+
+Output:
+
+```python
+{
+    "filter": {
+        "age": {"$gte": 18},
+        "status": {"$in": ["active", "pending"]}
+    },
+    "sort": {"created_at": -1, "name": 1},
+    "skip": 10,
+    "limit": 20,
+    "projection": {"name": 1, "email": 1, "age": 1}
+}
+
+```
+
+## 🔣 Supported Operators
+
+|       Expression | Mongo Operator | Example                   |
+|-----------------:|:---------------|:--------------------------|
+|              `=` | direct match   | `age=20` → `{"age": 20}`  |
+|             `!=` | `$ne`          | `status!=active`          |
+|       `>` / `>=` | `$gt` / `$gte` | `score>=80`               |
+|       `<` / `<=` | `$lt` / `$lte` | `price<10`                |
+|        `in(...)` | `$in`          | `role=in(admin,user)`     |
+|      `!=in(...)` | `$nin`         | `tier!=in(gold,platinum)` |
+| `/pattern/flags` | `$regex`       | `name=/^Jo/i`             |
+|          `text=` | `$text`        | `text=free search text`   |
+|        `fields=` | projection     | `fields=name,email`       |
+|          `sort=` | sort directive | `sort=-created_at,name`   |
+
+## 🧱 Quick API Reference
+
+`parse(moleql_query: str, blacklist=None, casters=None) -> dict`
+
+```python
+from moleql import parse
+
+parse("age>25&active=true")
+```
+
+Returns a dictionary with:
+`filter`, `sort`, `skip`, `limit`, `projection`
+
+`moleqularize(moleql_query: str, blacklist=None, casters=None) -> MoleQL`
+
+Parse a MoleQL string and return the internal MoleQL object for
+advanced inspection and debugging.
+
+```python
+from moleql import moleqularize
+
+m = moleqularize("age>25")
+print(m.mongo_query)
+
+```
+
+## 🧩 Custom Casters
+
+You can define custom casters to control type conversions.
+
+```python
+from moleql import parse, get_casters
+
+
+def to_bool(value: str) -> bool:
+    return value.lower() in ("true", "1", "yes")
+
+
+custom_casters = {"bool": to_bool}
+
+q = parse("active=bool(true)&age>30", casters=custom_casters)
+
+```
+
+## 🧠 Design Philosophy
+
+- Transparency — The query string is readable and reversible.
+- Safety — No eval, injection-safe parsing.
+- Extensibility — Easy to plug in custom handlers.
+- Predictability — Every operator maps 1:1 to Mongo semantics.
+- Minimal dependencies — Pure Python, no ODM required.
+
+## ⚙️ Integration Examples
+
+**FastAPI**
+
+```python
+from fastapi import FastAPI, Request
+from moleql import parse
+from pymongo import MongoClient
+
+db = MongoClient()["app"]
+app = FastAPI()
+
+
+@app.get("/users")
+def list_users(request: Request):
+    q = parse(request.url.query.lstrip("?"))
+    return list(db.users.find(q["filter"]))
+
+```
+
+**Flask**
+
+```python
+from flask import Flask, request, jsonify
+from moleql import parse
+
+app = Flask(__name__)
+
+
+@app.get("/orders")
+def orders():
+    q = parse(request.query_string.decode())
+    return jsonify(q)
+
+```
+
+## 🧪 Testing
+
+Run the full suite using uv:
+
+```bash
+uv sync --all-extras --dev
+uv run pytest -vv
+
+```
+
+Generate coverage:
+
+```bash
+uv run pytest --cov=moleql --cov-report=term-missing
+
+```
+
+## 🧹 Code Quality
+
+This repository uses:
+
+ - Ruff — Linting + formatting (UP / pyupgrade rules)
+ - pre-commit — automatic checks
+ - pytest — testing
+ - uv — environment & packaging
+
+Set up hooks:
+```bash
+uv run pre-commit install
+uv run pre-commit run --all-files
+```
+
+## 🧭 Roadmap
+
+- [] Add exists(field) and between(a,b) operators
+- [] Add alias for text= → $search convenience
+- [] Add optional CLI (moleql "age>20" --as-json)
+- [] Extended docs and tutorials
+
+🤝 Contributing
+
+1. Fork this repository
+2. Create your feature branch
+
+    ```bash
+    git checkout -b feat/awesome-change
+    ```
+3. Run formatting and tests
+
+    ```bash
+    uv run pre-commit run --all-files
+    uv run pytest
+    ```
+4. Commit and push your changes
+5. Open a Pull Request 🚀
+
+## 🌟 Acknowledgments
+
+Built and maintained by [@OneTesseractInMultiverse](https://github.com/OneTesseractInMultiverse)
+Inspired by the need for readable, typed, and safe Mongo queries in API
+environments.

moleql-0.1.1/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "moleql"
+version = "0.1.1"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Pedro Guzmán", email = "pedro@subvertic.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "dateparse>=1.4.0",
+    "dateparser>=1.2.2",
+    "mypy>=1.18.2",
+    "pymongo>=4.15.3",
+    "pytest>=8.4.2",
+    "ruff>=0.14.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/OneTesseractInMultiverse/moleql"
+Issues = "https://github.com/OneTesseractInMultiverse/moleql/issues"
+
+[build-system]
+requires = ["uv_build>=0.8.23,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["F", "E", "W", "I", "UP", "PERF"]
+ignore = []  # add codes you want to silence
+
+[tool.ruff.format]
+
+[tool.hatch.build.include]
+paths = ["LICENSE", "NOTICE", "AUTHORS"]
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.3.0",
+    "pyinstrument>=5.1.1",
+    "pytest>=8.4.2",
+    "pytest-benchmark>=5.2.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.14.4",
+]

moleql-0.1.1/src/moleql/__init__.py

@@ -0,0 +1,3 @@
+from moleql.mql import MoleQL as MoleQL
+from moleql.parse import moleqularize as moleqularize
+from moleql.parse import parse as parse

moleql-0.1.1/src/moleql/default_casters.py

@@ -0,0 +1,20 @@
+from collections.abc import Callable
+
+from moleql.mql.casters import (
+    cast_as_list,
+    cast_as_object_id,
+    cast_as_object_id_ts,
+    cast_as_str,
+    cast_as_timestamp,
+)
+
+MONGO_MODEL_ID_KEY: str = "mongo_id"
+MONGO_INTERNAL_ID_KEY: str = "_id"
+DEFAULT_HQL_CASTERS: dict[str, Callable] = {
+    "list": cast_as_list,
+    "in": cast_as_list,
+    "object_id": cast_as_object_id,
+    "object_id_ts": cast_as_object_id_ts,
+    "ts": cast_as_timestamp,
+    "str": cast_as_str,
+}

moleql-0.1.1/src/moleql/mql/__init__.py

@@ -0,0 +1,3 @@
+from moleql.mql.core import MoleQL
+
+__all__ = ["MoleQL"]

moleql-0.1.1/src/moleql/mql/casters.py

@@ -0,0 +1,44 @@
+import datetime
+
+from bson import ObjectId
+
+LIST_DEFAULT_SEPARATOR: str = ","
+EMPTY_STRING: str = ""
+
+
+# ---------------------------------------------------------
+# CAST AS LIST
+# ---------------------------------------------------------
+def cast_as_list(value: str) -> list[str]:
+    output_list: list[str] = value.strip().split(LIST_DEFAULT_SEPARATOR)
+    if output_list == [EMPTY_STRING]:
+        return []
+    return output_list
+
+
+# ---------------------------------------------------------
+# CAST AS OBJECT ID
+# ---------------------------------------------------------
+def cast_as_object_id(value: str) -> ObjectId:
+    return ObjectId(value)
+
+
+# ---------------------------------------------------------
+# CAST AS OBJECT ID TS
+# ---------------------------------------------------------
+def cast_as_object_id_ts(value: str) -> datetime.datetime:
+    return ObjectId(value).generation_time
+
+
+# ---------------------------------------------------------
+# CAST AS OBJECT ID
+# ---------------------------------------------------------
+def cast_as_timestamp(value: str) -> datetime.datetime:
+    return datetime.datetime.fromtimestamp(int(value))
+
+
+# ---------------------------------------------------------
+# CAST AS OBJECT ID
+# ---------------------------------------------------------
+def cast_as_str(value: any) -> str:
+    return str(value)

moleql-0.1.1/src/moleql/mql/constants.py

@@ -0,0 +1,10 @@
+FILTERS_KEY: str = "filters"
+SORT_KEY: str = "sort"
+SKIP_KEY: str = "skip"
+LIMIT_KEY: str = "limit"
+PROJECTION_KEY: str = "projection"
+QUERY_STRING_PARAM_SEPARATOR: str = "&"
+EMPTY_STRING: str = ""
+FIELDS_KEY: str = "fields"
+TEXT_KEY: str = "$text"
+FILTER: str = "filter"