labull-framework 0.1.4.2__tar.gz → 0.1.4.3__tar.gz

{labull_framework-0.1.4.2/labull_framework.egg-info → labull_framework-0.1.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labull-framework
-Version: 0.1.4.2
+Version: 0.1.4.3
 Summary: Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks
 Author: Labull Framework
 License-Expression: MIT

{labull_framework-0.1.4.2 → labull_framework-0.1.4.3}/labull_framework/canvas/data.py

@@ -156,8 +156,11 @@ def _file_of(field: Any) -> dict[str, Any] | None:
     }
 
 
-def _shape_field(field: Any, model: Any) -> dict[str, Any]:
-    """一个字段在画布上的全部信息（**唯一一处**拼这个字典）。"""
+def _shape_field(field: Any, model: Any, enums: dict[str, dict[str, Any]] | None = None) -> dict[str, Any]:
+    """一个字段在画布上的全部信息（**唯一一处**拼这个字典）。
+
+    :param enums: `_enums_of(model)` 那一份（类名 → 中文名 / 成员）；不给就只有取值，没有类名。
+    """
     kind = _kind_of(field)
     item: dict[str, Any] = {
         'name': field.name,
@@ -171,6 +174,10 @@ def _shape_field(field: Any, model: Any) -> dict[str, Any]:
         'brief': _brief(field),
         'briefLine': _brief_line(field),
         'enum': _enum_of(field),
+        # 🔴 这个字段用的是**哪个枚举类**（`Order.Status`），认不出就是 None。
+        #    取值那一半在 `enum` 里，类名这一半只能这么补：字段上没有任何回指（见 `_choice_items`）。
+        #    导出（`devkit._field_lines`）靠它写出 `Order.Status.OPEN` 那种真能用的写法。
+        'enumRef': _enum_ref(field, enums or {}),
         'file': _file_of(field),
         # 默认值也要能看（`default=Status.OPEN` 这类信息在页面上很有用）。
         'default': _default_of(field),
@@ -248,6 +255,9 @@ def shape() -> dict[str, list[dict[str, Any]]]:
         label = str(model._meta.app_label)
         fields: list[dict[str, Any]] = []
         relations: list[dict[str, Any]] = []
+        # 🔴 枚举类**先扫一遍**：每个带 choices 的字段要在这一步认出"它用的是哪个类"（`enumRef`）。
+        #    放在字段循环之前是判据：`_shape_field` 拿它当参数，顺序反了就只能再扫一遍模型。
+        enums = _enums_of(model)
         for field in model._meta.get_fields():
             if getattr(field, 'many_to_many', False):
                 target = field.related_model
@@ -286,7 +296,7 @@ def shape() -> dict[str, list[dict[str, Any]]]:
                 relations.append(
                     _relation_of(field, kind, '1', target, column=str(field.attname))
                 )
-            fields.append(_shape_field(field, model))
+            fields.append(_shape_field(field, model, enums))
         tables.append(
             {
                 'name': model.__name__,
@@ -295,6 +305,10 @@ def shape() -> dict[str, list[dict[str, Any]]]:
                 'verbose': _verbose(model),
                 'brief': _brief(model),
                 'briefLine': _brief_line(model),
+                # 🔴 这张表**自己定义**的那几个枚举类（类名 → 中文名 / 成员）。
+                #    它是**只增不减**的信息：画布不读它，导出（`devkit`）靠它写出 `Order.Status.OPEN`
+                #    那种写法。见 `_enums_of()` 顶上那段（为什么必须扫模型类体）。
+                'enums': enums,
                 'fields': fields,
                 'relations': relations,
             }
@@ -358,16 +372,87 @@ def _type_of(field: Any) -> str:
     return 'text'
 
 
+def _choice_items(field: Any) -> list[tuple[Any, Any]]:
+    """一个带 choices 的字段：`[(取值, 中文名)]`（**只有这一处**做那个归一化）。
+
+    🔴 Django 已经把 choices 归一化过了：`TextChoices` 那份「取值 → 中文名」在 `field.choices` 上
+       只剩一个**普通列表**（实测 `[('open', '进行中'), …]`，连元素都不是 `ChoiceItem`）——
+       **回指枚举类的那条线索在字段上根本不存在**，类名与成员名只能回到模型类体上去扫（见 `_enums_of`）。
+    🔴 归一化收成这一份：字段那一层与类那一层要比"取值是不是同一批"，两边各做一遍就会出现
+       "看着一样、比不相等"（`'1'` 与 `1`、`ChoiceItem` 与元组）—— 而那种漂没人会立刻发现。
+    """
+    out: list[tuple[Any, Any]] = []
+    for item in list(getattr(field, 'choices', None) or []):
+        if isinstance(item, (tuple, list)) and len(item) == 2:
+            out.append((item[0], item[1]))
+    return out
+
+
 def _enum_of(field: Any) -> dict[str, Any] | None:
-    """枚举列：`TextChoices` 在 `_meta` 里只剩「取值 → 中文名」这两样。"""
-    choices = list(getattr(field, 'choices', None) or [])
-    if not choices:
+    """枚举列：取值与它们的中文名（`TextChoices` 在 `_meta` 里只剩这两样）。"""
+    items = _choice_items(field)
+    if not items:
         return None
-    values = [str(value) for value, _ in choices]
-    labels = {str(value): str(label) for value, label in choices}
+    values = [str(value) for value, _label in items]
+    labels = {str(value): str(label) for value, label in items}
     return {'values': values, 'labels': labels}
 
 
+def _enum_ref(field: Any, enums: dict[str, dict[str, Any]]) -> str | None:
+    """这个字段用的是模型上哪个枚举类（`Order.Status` ⇒ 回 `'Order.Status'`）；认不出就 `None`。
+
+    🔴 为什么要它：作者在块里写的是 `Order.Status.OPEN`（类属性），而字段那一层只剩「取值 → 中文名」——
+       导出里不写类名，作者就只能照值写 `Order.Status.open`，而那种写法在**保存时的引用深检**里
+       会被判 `missing`（`deepcheck._resolve()` 是按类属性往下走的）—— 导出与深检因此对不上。
+    🔴 匹配只按**取值那一批**（`_choice_items` 那一份归一化）：字段可以只取枚举的一个子集，
+       所以"字段取值 ⊆ 枚举成员"也算命中 —— 但**两个类都能容下时必须都不认**（回 `None`）：
+       挑一个猜错的类比不写更坏（作者会照着一个假的类名写）。
+    """
+    values = [str(value) for value, _label in _choice_items(field)]
+    if not values:
+        return None
+    wanted = set(values)
+    hits = [
+        name
+        for name, item in enums.items()
+        if wanted <= {str(member['value']) for member in item['members']}
+    ]
+    return hits[0] if len(hits) == 1 else None
+
+
+def _enum_name(value: Any) -> str:
+    """枚举类的名字（Django 的 `QualifiedName` 是 `str` 的子类 ⇒ 这里给的就是 `Order.Status`）。"""
+    return str(getattr(value, '__qualname__', None) or getattr(value, '__name__', '') or '').strip()
+
+
+def _enums_of(model: Any) -> dict[str, dict[str, Any]]:
+    """这张表的类体里定义的那几个枚举类：`{'Order.Status': {'labels', 'members'}}`。
+
+    🔴 **必须扫模型类体**（`vars(model)`）：`field` 上没有任何属性回指那个枚举类（见 `_choice_items`），
+       而块作者在 `backend_open.py` 里用的正是类属性（`Order.Status.OPEN`）—— 导出要写的就是这个名字。
+    🔴 判据用 `models.Choices`（基类），**不是**猜 `__members__`：`TextChoices` / `IntegerChoices`
+       都是它的子类，而写死的 `choices` 列表（`[('a', '甲')]`）**不是** —— 那种字段照旧只有取值。
+    🔴 用 `vars()` 而不是 `dir()`：`dir()` 会把 django 塞给类的那些东西一起列出来，而 `vars()` 就是
+       这个模型**自己**写了什么（继承来的枚举类不属于这张表）。
+    🔴 **全部收进来**，包括一个字段都没用到的：导出是"清单"，不是"用到了才给"（少写一格信息
+       比多写一格更坏 —— 作者是拿它当字典查的）。
+    """
+    from django.db import models
+
+    out: dict[str, dict[str, Any]] = {}
+    for value in vars(model).values():
+        if not isinstance(value, type) or not issubclass(value, models.Choices) or value is models.Choices:
+            continue
+        name = _enum_name(value)
+        if not name:
+            continue
+        out[name] = {
+            'labels': {str(member.value): str(member.label) for member in value},
+            'members': [{'name': str(member.name), 'value': str(member.value)} for member in value],
+        }
+    return out
+
+
 def payload() -> dict[str, Any]:
     """画布整包：当前形状 + 与 git 那份比出来的三态 + 头部那行 git 信息 + 布局。
 

{labull_framework-0.1.4.2 → labull_framework-0.1.4.3}/labull_framework/canvas/static/canvas.js

@@ -387,9 +387,13 @@ function svgEl(tag, attrs = {}) {
  */
 function boundaryLayer(bounds) {
   const group = svgEl('g', { class: 'boundary-layer' });
-  // 🔴 边界与总线要**向上下无限延展**（用户明确要的：「左侧边界应该是向上也是无限延展」）：
-  //    上下各多加 `BOUNDARY_SPAN`，拖到哪、缩到多小，它们都还在 —— 不跟着内容高度走。
-  const top = -BOUNDARY_SPAN;
+  /* 🔴 边界 / 总线 / 那块淡色底：**只向下延展，不向上**（用户明确要的：
+   *    「向上其实不需要无限延展……只要向下和向右延展即可」）。
+   *    上端钉在**内容顶端之上一点点**（`bounds.top` 里已经留了标签的位置）——
+   *    上面本来就没有卡片，再画上去只是一条没意义的虚线加一大块灰底。
+   *    下端仍留 `BOUNDARY_SPAN`：往下是真会继续长的（表一张张往下排），
+   *    拖下去、缩下去时它不能"中途断掉"。 */
+  const top = bounds ? bounds.top : 0;
   const bottom = (bounds ? bounds.top + bounds.height : canvas.clientHeight || 900) + BOUNDARY_SPAN;
   // 边界**左边**那一块：没有内容、也过不去，铺一层很淡的底把它标出来。
   group.append(svgEl('rect', {
@@ -401,8 +405,8 @@ function boundaryLayer(bounds) {
   group.append(svgEl('line', {
     x1: RAIL_X, y1: top, x2: RAIL_X, y2: bottom, class: 'boundary-rail',
   }));
-  // ⚠️ 标签**不能**跟着 `top` 跑到 -20000 去：它们钉在内容最上面那张卡片之上（一眼能找到边界）。
-  const labelY = (bounds ? bounds.top : 0) + 16;
+  // 两个标签钉在**上端**（也就是内容最上面那张卡片之上），一眼能看到边界是什么。
+  const labelY = top + 16;
   const edge = svgEl('text', { x: BOUNDARY_X + 8, y: labelY, class: 'boundary-label' });
   edge.textContent = '边界（左边没有内容）';
   const rail = svgEl('text', { x: RAIL_X + 8, y: labelY + 16, class: 'boundary-label is-rail' });

{labull_framework-0.1.4.2 → labull_framework-0.1.4.3}/labull_framework/canvas/static/page.html

@@ -7,7 +7,7 @@
   <!-- ⚠️ `?v=` 是**给浏览器的缓存换钥匙**：这两个静态件在"这一页是公开的"之后尤其容易被缓存住，
        改了正文而人不刷新（或刷新了也还是旧的），症状是"代码明明改了、页面却没变"（真踩过）。
        改这两个文件时把版本号往上加一位。 -->
-  <link rel="stylesheet" href="canvas/asset/canvas.css?v=48">
+  <link rel="stylesheet" href="canvas/asset/canvas.css?v=49">
 </head>
 <body>
   <header class="bar">
@@ -52,6 +52,6 @@
     拖动表可排版（拖完自动存）；空白处按住拖 = 平移，Ctrl + 滚轮 = 缩放；
     点表标题展开备注与关联，点字段行展开枚举取值 / 文件去向 / 关联目标，点线上的关联键名看它的备注。
   </p>
-  <script src="canvas/asset/canvas.js?v=48"></script>
+  <script src="canvas/asset/canvas.js?v=49"></script>
 </body>
 </html>

{labull_framework-0.1.4.2 → labull_framework-0.1.4.3}/labull_framework/magic_block/devkit.py

@@ -158,8 +158,54 @@ def _api_lines() -> list[str]:
     ]
 
 
+def _enum_short(text: Any) -> str:
+    """枚举引用的**最后一段**（`Order.Status` ⇒ `Status`）。
+
+    🔴 类名要写在 `class Order:` 的类体里（`Status = Status`），写成 `Order.Status = Order.Status`
+       的话那个类属性就变成一个字符串注解了 —— 而作者真正用的是 `Order.Status.OPEN`。
+    """
+    return str(text or '').split('.')[-1]
+
+
+def _enum_classes(table: dict[str, Any], used: set[str]) -> list[str]:
+    """这张表自己定义的那几个枚举类（**类体**写法，作者照它写 `Order.Status.OPEN`）。
+
+    🔴 为什么非要有这一块：字段那一行只剩「取值 → 中文名」，**类名与成员名一个都没有** ——
+       作者照值写 `Order.Status.open`，而保存时的引用深检（`deepcheck._resolve()`）是按类属性
+       往下走的，当场判 `missing`。导出与深检必须说同一件事。
+    🔴 `used` 是"真的有字段在用它"的那几个：一个都没用到的也照写（导出是清单，不是用到了才给），
+       但那几行挂一句说明，免得人以为漏了。
+    """
+    out: list[str] = []
+    for name, item in (table.get('enums') or {}).items():
+        short = _enum_short(name)
+        members = item.get('members') or []
+        labels = item.get('labels') or {}
+        if not short or not members:
+            continue
+        out.append(f'    class {short}:')
+        if name not in used:
+            out.append('        # ⚠️ 这张表里现在没有字段在用它（照旧写出来：它是可以用到的取值集合）')
+        for member in members:
+            member_name = str(member.get('name') or '')
+            if not member_name:
+                continue
+            value = str(member.get('value'))
+            label = _flat(labels.get(value)) or value
+            out.append(f'        {member_name} = {value!r}  # {label}')
+        out.append('')
+    if out:
+        out.insert(0, '    # ── 枚举：这些取值按**类属性**用（`Order.Status.OPEN`），不是 `Order.Status.open` ──')
+    return out
+
+
 def _field_lines(field: dict[str, Any]) -> str:
-    """一个模型字段那一行（类型 + 一行备注）。关联字段的类型是目标模型的名字。"""
+    """一个模型字段那一行（类型 + 一行备注）。关联字段的类型是目标模型的名字。
+
+    🔴 枚举字段这一行的判据：**类型写 `str`（库里就是一列 varchar），可用取值写成类属性**。
+       注释里给全名（`Order.Status`，有的话）与「成员名=取值=中文名」—— 作者照着写就同时过
+       编辑器的补全与保存时的引用深检。
+    """
     kind = str(field.get('kind') or '')
     name = str(field.get('name') or '')
     if not name:
@@ -188,7 +234,19 @@ def _field_lines(field: dict[str, Any]) -> str:
     values = enum.get('values') or []
     if values:
         labels = enum.get('labels') or {}
-        notes.append('取值：' + ' / '.join(f'{value}={_flat(labels.get(value)) or value}' for value in values))
+        # 🔴 成员名（`OPEN`）与取值（`open`）是**两件事**：值能当字符串存，而代码里要用的是成员名。
+        #    形状里有 `enumRef`（类名）与那张表的 `enums`（成员表）时，就把成员名一起摆出来。
+        enum_ref = str(field.get('enumRef') or '')
+        members = ((field.get('_enums') or {}).get(enum_ref) or {}).get('members') or []
+        by_value = {str(member.get('value')): str(member.get('name') or '') for member in members}
+        short = _enum_short(enum_ref)
+        where = f'{short}.' if short else ''
+        notes.append(
+            '取值：'
+            + ' / '.join(
+                f'{where}{by_value.get(value) or value}={_flat(labels.get(value)) or value}' for value in values
+            )
+        )
     comment = f'  # {" · ".join(notes)}' if notes else ''
     return f'    {name}: {annotation}{comment}'
 
@@ -214,7 +272,7 @@ def _relation_lines(table: dict[str, Any]) -> list[str]:
 
 
 def _table_block(table: dict[str, Any]) -> list[str]:
-    """一张表那一块（类名 / 备注 / 真实 import / 字段 / 关联）。"""
+    """一张表那一块（类名 / 备注 / 真实 import / 枚举类 / 字段 / 关联）。"""
     name = str(table.get('name') or '')
     module = str(table.get('module') or '')
     if not name:
@@ -224,8 +282,14 @@ def _table_block(table: dict[str, Any]) -> list[str]:
     out = [f'class {name}:', f'    """{brief}（{where}）"""' if brief else f'    """{where}"""']
     if module:
         out.append(f'    # 一般这样 import：from {module}.models import {name}')
-    for field in table.get('fields') or []:
-        line = _field_lines(field if isinstance(field, dict) else {})
+    enums = table.get('enums') or {}
+    fields = [field for field in (table.get('fields') or []) if isinstance(field, dict)]
+    # 🔴 枚举类与字段那一半**必须对上**：`_field_lines` 要拿成员表把「取值 → 成员名」写全，
+    #    而成员表在 table 那一层。传进去比让每个字段自己去找一份可靠（也就不会有第二份匹配逻辑）。
+    used = {str(field.get('enumRef') or '') for field in fields if field.get('enumRef')}
+    out.extend(_enum_classes(table, used))
+    for field in fields:
+        line = _field_lines({**field, '_enums': enums})
         if line:
             out.append(line)
     out.extend(_relation_lines(table))
@@ -246,7 +310,7 @@ def backend_lock_pyi(tables: list[dict[str, Any]] | None = None, items: tuple[En
         '  ② 能抛的六个 HTTP 语义错误；',
         '  ③ 服务端交给 handler 的 ctx（就那 4 个键）；',
         '  ④ 平台读哪些环境变量（**只有名字与说明，没有值**）；',
-        '  ⑤ 项目里现在有哪些模型、每个字段是什么、枚举有哪些取值。',
+        '  ⑤ 项目里现在有哪些模型、每个字段是什么、枚举有哪些**成员与取值**。',
         '',
         f'🔴 它不参与运行：块后端真正 import 的是 {sdk.LIB_SDK}，模型走每张表下面那行注释的路径。',
         '🔴 块包必备件：' + ' / '.join((BLOCK_ENTRY, BLOCK_MANIFEST)) + f'；块自己的后端是 {BLOCK_BACKEND_FILE}（可选）。',
@@ -296,6 +360,7 @@ def backend_lock_pyi(tables: list[dict[str, Any]] | None = None, items: tuple[En
             '#   没配的键**不存在**（先判 `"OCR_KEY" in ctx.config`），别的变量一个都不给块。',
             '',
             '# ── ⑤ 项目里的模型（照 .labull/contract.json 那份模型形状生成） ──',
+            '# 枚举按**类属性**用（`Order.Status.OPEN`）：成员名不是取值 —— `Order.Status.open` 不存在。',
         ]
     )
     if not tables:

{labull_framework-0.1.4.2 → labull_framework-0.1.4.3/labull_framework.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labull-framework
-Version: 0.1.4.2
+Version: 0.1.4.3
 Summary: Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks
 Author: Labull Framework
 License-Expression: MIT

{labull_framework-0.1.4.2 → labull_framework-0.1.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "labull-framework"
-version = "0.1.4.2"
+version = "0.1.4.3"
 description = "Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks"
 readme = "README-pypi.md"
 requires-python = ">=3.10"