mongo-2-sql 0.1.3__tar.gz → 0.1.5__tar.gz

{mongo_2_sql-0.1.3 → mongo_2_sql-0.1.5}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Bao Bingbo
+Copyright (c) 2026 baobingbo
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

{mongo_2_sql-0.1.3 → mongo_2_sql-0.1.5}/PKG-INFO

@@ -1,9 +1,13 @@
 Metadata-Version: 2.4
 Name: mongo-2-sql
-Version: 0.1.3
+Version: 0.1.5
 Summary: A library to convert MongoDB aggregation pipelines to SQL parser
 Author-email: Bao Bingbo <baob2@outlook.com>
 License: MIT License
+Project-URL: Homepage, https://github.com/baobingbo/mongo-2-sql
+Project-URL: Documentation, https://github.com/baobingbo/mongo-2-sql#readme
+Project-URL: Repository, https://github.com/baobingbo/mongo-2-sql.git
+Project-URL: Issues, https://github.com/baobingbo/mongo-2-sql/issues
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -17,12 +21,29 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typing-extensions>=4.0.0; python_version < "3.10"
+Requires-Dist: sqlparse>=0.5.5
 Dynamic: license-file
 
 # Mongo to SQL
 
 Mongo to SQL 是一个将 MongoDB 聚合管道转换为 SQL 查询语句的工具。
 
+## 项目仓库
+
+- **GitHub**: [baobingbo/mongo-2-sql](https://github.com/baobingbo/mongo-2-sql)
+
+## 版本更新 v0.1.5
+
+### 新增功能
+
+#### 1. $addFields 阶段表达式与字面量语义
+- `$addFields` 使用独立的 `AddFieldsExpressionParser`，不再复用 `$project` 的解析逻辑，避免跨阶段耦合
+- `$addFields` 支持三类值：
+  - **字面量值**: 如 `{"score": 1}`, `{ "flag": true }`, `{ "text": "hello" }`，会直接转换为 `1 AS score`、`TRUE AS flag`、`'hello' AS text`
+  - **字段引用**: 如 `{ "cat": "$category" }`，会转换为 `t.category AS cat`
+  - **表达式**: 如 `{ "total": { "$add": [1, "$price"] } }` 或 `{ "isBig": { "$gt": ["$amount", 100] } }`
+- **仅 `$project` 阶段中**，`{"field": 1}` / `{"field": 0}` 仍然表示“包含/排除字段”；其他阶段（包括 `$addFields`）中，`1` 始终被视为字面量数值 1
+
 ## 功能特性
 
 - **阶段基础方法支持**: 支持 `$match`, `$project`, `$group`, `$sort`, `$limit`, `$lookup`, `$unwind` 等常用阶段
@@ -111,6 +132,52 @@ ORDER BY count DESC
 LIMIT 10
 ```
 
+### CTE 处理（复杂聚合管道）
+
+当管道包含多次 $project、$group 或 $addFields 阶段时，系统会自动使用 CTE 方式处理：
+
+```python
+from mongo_2_sql import convert_mongo_pipeline_to_sql
+
+# 复杂管道：多次投影和分组
+pipeline = [
+    { "$match": { "status": "active", "age": { "$gte": 18 } } },
+    { "$project": { "name": 1, "category": 1, "amount": 1 } },
+    { "$group": { "_id": "$category", "totalAmount": { "$sum": "$amount" }, "count": { "$sum": 1 } } },
+    { "$project": { "_id": 1, "totalAmount": 1, "count": 1 } },
+    { "$match": { "totalAmount": { "$gte": 18 } } },
+    { "$sort": { "totalAmount": -1 } },
+    { "$limit": 5 }
+]
+
+sql, metadata = convert_mongo_pipeline_to_sql(pipeline, "transactions")
+print(sql)
+```
+
+输出（自动使用 CTE 格式化）：
+```sql
+WITH cte_1 AS
+  (SELECT t.category AS _id,
+          SUM(t.amount) AS totalAmount,
+          COUNT(*) AS COUNT
+   FROM transactions AS t
+   WHERE 1=1
+     AND (t.status = 'active')
+     AND (t.age >= 18)
+   GROUP BY t.category),
+     cte_2 AS
+  (SELECT t._id AS _id,
+          t.totalAmount AS totalAmount,
+          t.count AS COUNT
+   FROM cte_1 AS t)
+SELECT *
+FROM cte_2 AS t
+WHERE 1=1
+  AND (t.totalAmount >= 18)
+ORDER BY t.totalAmount DESC
+LIMIT 5
+```
+
 ### 面向对象用法
 
 ```python
@@ -297,7 +364,27 @@ FROM products AS t
 GROUP BY t.category
 ```
 
-### 示例 5: 字符串连接
+### 示例 5: 字段重命名
+
+```python
+pipeline = [
+    { 
+        "$project": { 
+            "product_name": "$name",
+            "total_value": { "$multiply": ["$price", "$quantity"] }
+        } 
+    }
+]
+```
+
+```sql
+SELECT 
+    t.name AS product_name,
+    (t.price * t.quantity) AS total_value
+FROM products AS t
+```
+
+### 示例 6: 字符串连接
 
 ```python
 pipeline = [
@@ -319,7 +406,7 @@ SELECT
 FROM users AS t
 ```
 
-### 示例 6: JOIN 查询
+### 示例 7: JOIN 查询
 
 ```python
 pipeline = [
@@ -479,6 +566,28 @@ MIT License - 详见 [LICENSE](LICENSE) 文件
 
 ## 变更日志
 
+### v0.1.5 (2025-02-23)
+
+**新增功能:**
+- addFields阶段独立解析器（AddFieldsExpressionParser），与 project 解耦
+- 支持字面量值、字段引用、表达式三类语义
+- 统一数值 1 为字面量（仅 $project 阶段保留包含/排除语义）
+
+### v0.1.4 (2025-02-13)
+
+**新增功能:**
+- CTE 统一处理框架，支持 $addFields、$project、$group 阶段切片
+- ExpressionResolver 统一表达式解析器，避免 stage 间耦合
+- BaseExpressionParser 基础解析器类，减少代码重复
+- SQL 格式化输出（使用 sqlparse）
+- Project 阶段字段重命名支持
+- Stage 解耦架构设计
+
+**问题修复:**
+- 修复 `_id` 字段双引号问题
+- 修复聚合后字段引用错误
+- 修复模块导入路径问题
+
 ### v0.1.3 (2025-02-07)
 
 **改进:**