labull-framework 0.1.35__tar.gz → 1.0.0__tar.gz

{labull_framework-0.1.35 → labull_framework-1.0.0}/MANIFEST.in

@@ -18,5 +18,7 @@ include pyproject.toml
 
 # 包内数据（`canvas/views.py` 运行期真的会读这三个）。
 recursive-include labull_framework/canvas/static *.css *.js *.html
-recursive-include labull_framework *.pyi py.typed
 recursive-include labull_framework/migrations *.py
+# ⚠️ 这里曾经有一行 `recursive-include labull_framework *.pyi py.typed` —— 已删：
+#    库里一个 `*.pyi` / `py.typed` 都没有（`backend.lock.pyi` 是**导出时生成、只落进用户开发目录**的），
+#    `pyproject.toml` 那边也写着"刻意不加 py.typed"。一行匹配不到任何东西的规则只是噪声。

{labull_framework-0.1.35/labull_framework.egg-info → labull_framework-1.0.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: labull-framework
-Version: 0.1.35
+Version: 1.0.0
 Summary: Labull Framework: a pluggable Django app with Authing OIDC login and magic blocks
 Author: Labull Framework
 License-Expression: MIT
 Keywords: django,authing,oidc,sso,magic-block
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: Django
 Classifier: Framework :: Django :: 4.2
 Classifier: Framework :: Django :: 5.0
@@ -95,6 +95,7 @@ CORS_ORIGIN=http://localhost:5173
 |---|---|
 | **谁是管理员** | 配 `BOOTSTRAP_ADMIN_WORK_IDS=工号,工号` —— 它是**声明式**的名单：启动时名单里的人补上 `is_staff`，**名单之外的一律清掉**（没配就是"一个管理员都没有"）。它不碰 `is_superuser`，所以别拿超管当后门 |
 | **看数据模型那一页** | 设 `LABULL_SCHEMA_CANVAS=on`，浏览器打开 `/` |
+| **让块的依赖声明拦住保存** | 设 `LABULL_REQUIRES=error`（默认 `warn`：判据照跑、**只提示不拦保存**；`off` 整段不跑） |
 | **导出一份模型形状** | `python manage.py labull_contract --out .labull/contract.json` |
 
 ## magic block
@@ -104,7 +105,10 @@ CORS_ORIGIN=http://localhost:5173
 ```
 我的块/
 ├─ index.open.html        入口（必备）
-├─ magic-block.open.yaml  清单（必备）：id / module / name / brief 四个键必填 + detail（详情介绍）可选
+├─ magic-block.open.yaml  清单（必备）：`id` / `module` / `name` / `brief` 四个键必填
+│                         + `requires`（依赖声明：用了哪些模型 / pip 包 / settings 键 / `BLOCK_*`）可选
+├─ README.open.md         **业务功能说明**（Markdown，可选）：这一段的家就是这份文件，不在清单里
+├─ requires.open.yaml     依赖声明的**草稿**（导出铺下来的：正文进清单的 `requires`，注释是扫代码的建议）
 ├─ 任意 js / css
 ├─ excluded/_*            你自己的地盘（测试 / 草稿）：**照样进库，执行时忽略**
 └─ backend_open.py        块自己的后端（可选）

{labull_framework-0.1.35 → labull_framework-1.0.0}/README-pypi.md

@@ -67,6 +67,7 @@ CORS_ORIGIN=http://localhost:5173
 |---|---|
 | **谁是管理员** | 配 `BOOTSTRAP_ADMIN_WORK_IDS=工号,工号` —— 它是**声明式**的名单：启动时名单里的人补上 `is_staff`，**名单之外的一律清掉**（没配就是"一个管理员都没有"）。它不碰 `is_superuser`，所以别拿超管当后门 |
 | **看数据模型那一页** | 设 `LABULL_SCHEMA_CANVAS=on`，浏览器打开 `/` |
+| **让块的依赖声明拦住保存** | 设 `LABULL_REQUIRES=error`（默认 `warn`：判据照跑、**只提示不拦保存**；`off` 整段不跑） |
 | **导出一份模型形状** | `python manage.py labull_contract --out .labull/contract.json` |
 
 ## magic block
@@ -76,7 +77,10 @@ CORS_ORIGIN=http://localhost:5173
 ```
 我的块/
 ├─ index.open.html        入口（必备）
-├─ magic-block.open.yaml  清单（必备）：id / module / name / brief 四个键必填 + detail（详情介绍）可选
+├─ magic-block.open.yaml  清单（必备）：`id` / `module` / `name` / `brief` 四个键必填
+│                         + `requires`（依赖声明：用了哪些模型 / pip 包 / settings 键 / `BLOCK_*`）可选
+├─ README.open.md         **业务功能说明**（Markdown，可选）：这一段的家就是这份文件，不在清单里
+├─ requires.open.yaml     依赖声明的**草稿**（导出铺下来的：正文进清单的 `requires`，注释是扫代码的建议）
 ├─ 任意 js / css
 ├─ excluded/_*            你自己的地盘（测试 / 草稿）：**照样进库，执行时忽略**
 └─ backend_open.py        块自己的后端（可选）

{labull_framework-0.1.35 → labull_framework-1.0.0}/labull_framework/env.py

@@ -14,7 +14,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Mapping
 
-from .magic_block.sdk import BLOCK_DEEPCHECK, BLOCK_PROBE
+from .magic_block.sdk import BLOCK_DEEPCHECK, BLOCK_PROBE, BLOCK_REQUIRES
 
 #: 给块的配置前缀：`BLOCK_OCR_KEY=abc` ⇒ 块后端里 `ctx.config['OCR_KEY'] == 'abc'`。
 #: 🔴 这是**白名单**（不是黑名单）：想让块读一项，就给那个变量加这个前缀，不用改库的代码。
@@ -200,6 +200,23 @@ ENV_ITEMS: tuple[EnvItem, ...] = (
         hint=f'{BLOCK_PROBE}=off',
         group='平台开关',
     ),
+    # 🔴 依赖声明（`requires`）那一层的开关（名字的真源在 `magic_block/sdk.py`）：
+    #    默认 `warn` —— 存量块的清单里一个声明都没有，一上线就硬报错等于让每个块集体停用。
+    EnvItem(
+        name=BLOCK_REQUIRES,
+        brief='块「依赖声明」（requires）那一层的开关：off 整段不跑 / warn（默认）只提示不拦 / error 变成硬判据',
+        hint=f'{BLOCK_REQUIRES}=error',
+        group='平台开关',
+    ),
+    # 🔴 体检那条链一次开几个口子（名字的真源在 `magic_block/parallel.py` 的 `ENV_WORKERS`）。
+    #    ⚠️ 它是**性能旋钮、不是判据**：写错一个数（0 / 64 / 一句乱码）会被夹到 1..8，不该让体检报错。
+    #    它在这里的意义是"使用者的清单里能看见这个开关"（`backend.lock.pyi` 就是按 ENV_ITEMS 铺的）。
+    EnvItem(
+        name='LABULL_BLOCK_WORKERS',
+        brief='启动体检 / 全量校验一次开几个子进程（默认 4，夹在 1..8）：机器小就往下调，写 1 退回串行',
+        hint='LABULL_BLOCK_WORKERS=2',
+        group='平台开关',
+    ),
     # ── 块的配置面 ──
     EnvItem(
         name=f'{BLOCK_CONFIG_PREFIX}*',

{labull_framework-0.1.35 → labull_framework-1.0.0}/labull_framework/magic_block/blockpackage.py

@@ -13,7 +13,10 @@
 
 🔴 为什么要"不许互相引用"这条规矩：块后端的正文**在库里**，不在磁盘上、也不在 `sys.path` 上。
    要想让 `from helper import x` 成立，就得先把包内文件注册成真模块（注册壳 → 依赖排序 →
-   别名共享 → 用完摘干净）——那套能跑通，但每一步都有坑（见 `probe-module-loader.py` 的血泪）。
+   别名共享 → 用完摘干净）——那套**试过两次都放弃**了：一次是"假文件系统 + `sys.path_hooks`"，
+   它在现场会**带坏真模块的首次导入**（`labull_framework.magic_block.sdk` 报 ModuleNotFoundError）；
+   另一次是"自己造模块对象塞进 `sys.modules`"，它跑得通，但"用完就摘"那一步既脆弱又没必要
+   （块里那几个文件本来就不该互相认识）。
    而"各写各的"把这一整类复杂度消掉了：想分文件就分，但每个文件要能独立站住
    （公共逻辑各写一份，或者放进**项目**里的公共模块 —— 那是普通 Python，随便 import）。
 

{labull_framework-0.1.35 → labull_framework-1.0.0}/labull_framework/magic_block/deepcheck.py

@@ -31,10 +31,14 @@
      ② 同一个名字在多处是**不同模型的实例**时，整个名字跳过（`{名字: {模型, …}}`），
         不许"后者覆盖前者"（那会拿 B 的属性去套 A 的实例）。
 
-🔴 **判据只有一份、整层跑在子进程里**（与 `validate` 那次试加载同一个进程、同一次超时）：
+🔴 **判据只有一份、整层跑在子进程里**（主路上它**和试加载同一趟**：`trial=True`）：
    深检要真的把项目模型注册进来（`django.setup()` + `apps.get_models()`），而宿主进程的
    app registry 是迁移与请求**正在用**的那一份 —— 在进程内试跑块代码等于拿生产赌。
    ⚠️ 子进程里一律用**只读 / 内存**的那条数据库连接（别名 `probe`），真库一根头发都不动。
+   🔴 试加载（"这包加载得起来吗"）搭这趟一起做的理由：两件都要 `django.setup()`，
+      分两个进程就是把那份冷启动付两遍（一次块判定 1.4s ⇒ 0.7s）。
+      ⚠️ 从前那趟**没有 `django.setup()`**，于是模块级 `from orders.models import Order`
+      （Django 最正常的写法）会被判成 `AppRegistryNotReady` —— 一条假错，已修。
 
 🔴 **整包与判据正文一律走 stdin**（`subproc.run_child()` 的 `payload`），**不走环境变量**：
    这一包有多大是作者说了算的（实测有两个块 349 KB / 336 KB），而 Linux 对**单个**环境字符串
@@ -415,6 +419,27 @@ def main():
         {str(name): str(body) for name, body in raw_package.items()} if isinstance(raw_package, dict) else {}
     )
     package.setdefault(_main_file, source)
+    # 🔴 **试加载那一半**（`_GIVEN['trial']`）：在同一趟子进程里先把包加载一次。
+    #
+    # 🔴 为什么并进来（而不是像从前那样另起一个子进程）：两件都要 `django.setup()`，
+    #    分两个进程就是把那份冷启动付两遍 —— 实测一次块判定 1.4s ⇒ 0.7s，
+    #    而保存与体检都走这一条路（`validate.check_backend`）。
+    # 🔴 顺带修掉一条**假错**：从前这一半跑在一个**没有 `django.setup()`** 的子进程里，
+    #    于是"模块级写 `from orders.models import Order`"（Django 最正常的写法）会被判成
+    #    `AppRegistryNotReady: Apps aren't loaded yet.` —— 而块运行期本来就在 app registry
+    #    已经就绪的进程里（`registry` 是在宿主进程里加载它的）。这里 `django.setup()` 已经跑过。
+    # ⚠️ 加载不过 ⇒ **只报那一条**（与从前一致）：加载都不过的包，深检那些结论没有意义。
+    if _GIVEN.get('trial'):
+        try:
+            _loaded = _blockpackage.load_block(package, tag=str(_GIVEN.get('tag') or 'trial'))
+        except Exception as exc:
+            _STATIC.append(_issue('backend', '%s 加载失败（顶层与装饰器不许出错）：%s: %s'
+                                  % (_main_file, type(exc).__name__, exc)))
+            return _result()
+        if _loaded.errors:
+            _STATIC.append(_issue('backend', '%s 加载失败（顶层与装饰器不许出错）：%s'
+                                  % (_main_file, '；'.join(_loaded.errors))))
+            return _result()
     # 🔴 包内文件**互相引用**要先报出来（规矩，不是风格）：块后端的正文在库里、不在磁盘上，
     #    `from helper import x` 那种写法在块里**不成立**（平台按"每个 .py 各自独立加载"来跑）。
     #    不报的话症状是运行期 `ModuleNotFoundError`，而那时人已经不知道该看哪儿了。
@@ -451,6 +476,9 @@ def main():
     # 🔴 试跑那一层会用到的几个函数（撒样例行 / 取主键 / 错该算谁头上）是**从外面注入**的
     #    （见 `deep_check()` 里那个 wrapper）：它们只有一份实现（模块级那几个），
     #    这里**不许再抄一份** —— 抄一份的下场是"保存时说合法、体检时说非法"。
+    # 🔴 依赖声明的"声明的东西存不存在"也在这里跑（同一个进程、同一次 `django.setup()`）：
+    #    它要问的就是 app registry / 包元数据 / settings，而这三样只有这个进程里是活的。
+    _requires_check()
     probing = bool(_GIVEN.get('probe'))
     if probing:
         probe(source, module_name, apps, package)
@@ -472,6 +500,187 @@ def _any_probe_note():
     return False
 
 
+# ──────────────────────────── 依赖声明：声明的东西**真的存在吗** ────────────────────────────
+#
+# 🔴 判据只问**活的现实**：app registry / `importlib.metadata` / `django.conf.settings`。
+#    **绝不读 `backend.lock.pyi` 那类生成物**：生成物是快照、可能过期，registry 是当下的事实。
+#    （那条纪律见 docs/magic-block-requires.md 第 10.2 节：一份真源、两个消费者。）
+# 🔴 声明由**父进程**从清单里读出来递进来（`_GIVEN['requires']`）：这一半跟深检**同一次子进程**
+#    走，所以不额外起进程；`LABULL_REQUIRES=off` 时父进程根本不递（整段不跑）。
+# 🔴 **"代码用了却没声明"不在这里**（那一半是纯 `ast`，落在 `validate.check_requires`）：
+#    两半分开放，是因为这一半要运行环境、那一半不要 —— 混在一起会让"没 Django 时连静态判据都没跑"。
+
+_REQUIRES = _GIVEN.get('requires') if isinstance(_GIVEN.get('requires'), dict) else None
+
+
+def _declared(key):
+    """`requires.<key>` 那一串字符串（父进程已经规范化过；形状不对就当空）。"""
+    if not _REQUIRES:
+        return []
+    declared = _REQUIRES.get('declared')
+    items = declared.get(key) if isinstance(declared, dict) else None
+    if not isinstance(items, list):
+        return []
+    return [str(item) for item in items if str(item or '').strip()]
+
+
+def _prefix():
+    """报文前缀（`模块/可读名：`）—— 与别处的报文一样，三项俱全（在哪 / 声明在哪 / 怎么改）。"""
+    label = str((_REQUIRES or {}).get('label') or '')
+    return ('%s：' % label) if label else ''
+
+
+def _public_names(cls, limit=12):
+    """这个模型上**项目自己写的**方法 / 属性名（报文里那串"有：…"）。
+
+    🔴 只列项目自己定义的：`django.db.models.Model` 上那一堆（`save` / `objects` / `pk` …）
+       列出来只会把真正该看的名字淹掉（人要看的是"这个方法不叫 log_event 了吗"）。
+    """
+    from django.db import models as _models
+
+    inherited = set(dir(_models.Model))
+    out = []
+    for klass in getattr(cls, '__mro__', ()):
+        if str(getattr(klass, '__module__', '')).startswith('django.'):
+            continue
+        for key in vars(klass):
+            if key.startswith('_') or key in inherited or key in out:
+                continue
+            out.append(key)
+    return out[:limit]
+
+
+def _model_of(path):
+    """按**完整路径**取那个类，回 `(类, 取不到的原因)`。
+
+    🔴 先 `import` 那个模块再 `getattr`（不是按类名猜）：声明给的是完整路径，
+       所以判据可以**不猜** —— 这正是它比 `deepcheck` 那套"按类名匹配"准的地方。
+    ⚠️ 兜底再问一次 app registry（`core.models.WorkflowModel` ⇒ `apps.get_model('core', 'WorkflowModel')`）：
+       有的项目把模型放在包的 `__init__` 里，import 那一步会拿到别的东西。
+    """
+    import importlib
+
+    text = str(path)
+    module_path, _, name = text.rpartition('.')
+    why = '要写成完整的模块路径，例如 core.models.WorkflowModel'
+    if module_path:
+        try:
+            module = importlib.import_module(module_path)
+        except Exception as exc:
+            why = '%s: %s' % (type(exc).__name__, exc)
+        else:
+            found = getattr(module, name, None)
+            if isinstance(found, type):
+                return found, ''
+            why = '那个模块里没有 %s' % name
+    parts = [item for item in text.split('.') if item]
+    if len(parts) >= 2:
+        try:
+            from django.apps import apps as _apps
+
+            found = _apps.get_model(parts[0], parts[-1])
+        except Exception:
+            found = None
+        if found is not None:
+            return found, ''
+    return None, why
+
+
+def _requires_hard():
+    """"声明了但它不存在"的逐条报文（**确定**的那一档）。
+
+    ⚠️ 这里**不分档**（`warn` / `error` 是父进程的事）：这一层只报"事实"，
+       分档只有一处判据（`validate.requires_mode()`），两处各判一次迟早漂。
+    """
+    import importlib
+    from importlib import metadata
+
+    from django.conf import settings
+
+    out = []
+    if not _REQUIRES:
+        return out
+    head = _prefix()
+
+    for module in _declared('models'):
+        try:
+            importlib.import_module(module)
+        except Exception as exc:
+            out.append(
+                '%srequires.models 里的 %s 导不进来：%s: %s —— '
+                '改法：确认这个模块在目标项目里存在；换了项目就要跟着改声明。'
+                % (head, module, type(exc).__name__, exc)
+            )
+
+    surface = (_REQUIRES.get('declared') or {}).get('surface')
+    for path, attrs in (surface.items() if isinstance(surface, dict) else ()):
+        cls, why = _model_of(path)
+        if cls is None:
+            out.append(
+                '%srequires.surface 里的 %s 取不到：%s —— '
+                '改法：确认这个模型在目标项目里存在（要写完整的模块路径）。' % (head, path, why)
+            )
+            continue
+        for attr in (attrs if isinstance(attrs, list) else ()):
+            name = str(attr)
+            if hasattr(cls, name):
+                continue
+            near = _public_names(cls)
+            listed = ('（这个模型上有：%s）' % ' / '.join(near)) if near else ''
+            out.append(
+                '%srequires.surface 声明了 %s.%s，但这个模型上没有它%s —— '
+                '改法：把声明改成真实存在的方法名，或改代码。' % (head, path, name, listed)
+            )
+
+    for dist in _declared('packages'):
+        try:
+            metadata.version(dist)
+        except metadata.PackageNotFoundError:
+            out.append(
+                '%srequires.packages 里的 %s 没装 —— '
+                '改法：pip install %s，或把它从声明里删掉（删掉之后代码里再用会被报错）。'
+                % (head, dist, dist)
+            )
+        except Exception as exc:
+            # ⚠️ 取不到元数据**不是"没装"**（那可能是这个环境自己的毛病）：只记说明，不当结论。
+            _NOTES.append(
+                '%srequires.packages 里的 %s 这一次没验（读包元数据失败：%s: %s）'
+                % (head, dist, type(exc).__name__, exc)
+            )
+
+    for key in _declared('settings'):
+        if not hasattr(settings, key):
+            out.append(
+                '%srequires.settings 里的 %s 在 settings 里不存在 —— '
+                '改法：确认这个设置键在目标项目里真的配了'
+                '（这一项声明的是"我依赖这个键存在"，不判它的值）。' % (head, key)
+            )
+    return out
+
+
+def _requires_check():
+    """跑一遍依赖声明的"存不存在"，并按开关落位（`warn` ⇒ 只进备注）。
+
+    ⚠️ 判据自己崩了**不算这个块的错**（软失败口径见文件头）：只记一句说明。
+    """
+    if not _REQUIRES:
+        return
+    try:
+        hard = _requires_hard()
+    except Exception as exc:
+        _NOTES.append('依赖声明的"存不存在"这一半没跑（不是这个块的问题）：%s: %s'
+                      % (type(exc).__name__, exc))
+        return
+    if not hard:
+        return
+    if str(_REQUIRES.get('mode') or 'warn') == 'error':
+        for message in hard:
+            _STATIC.append(_issue('requires', message))
+        return
+    for message in hard:
+        _NOTES.append('（提示，不影响保存）%s' % message)
+
+
 # ──────────────────────────── 静态判据：点了什么名 ────────────────────────────
 
 
@@ -1176,6 +1385,9 @@ def deep_check(
     files: dict[str, str] | None = None,
     probe: bool = True,
     deleted: dict[str, Any] | None = None,
+    requires: dict[str, Any] | None = None,
+    trial: bool = False,
+    tag: str = '',
 ) -> tuple[list[tuple[str, str]], list[str]]:
     """深检一份块后端正文：`([(stage, issue)], [没验到的说明])`。
 
@@ -1187,6 +1399,14 @@ def deep_check(
            不给 / 给空 ⇒ 这一条判据不报（`None` 与"空"同义）。
         ⚠️ 调用方（`validate.check_block`）会先算一次再递进来：算它要读 git，
            而体检是对每个块各问一次的（见 `canvas.data` 里那段缓存的说明）。
+    :param requires: 依赖声明那一层（形状见 `validate.requires_payload()`：
+        `{'declared': …, 'label': …, 'mode': …}`）。不给 ⇒ 那一条判据不跑。
+        🔴 它搭**这一次**子进程走：判"声明的东西存不存在"要 app registry / 包元数据 / settings，
+           而这三样只在子进程里是活的 —— 另开一个进程等于给每个块的保存与体检白加 0.4 秒。
+    :param trial: **顺带把包加载一次**（"试加载"那一半，见 `_CHECK` 里那一段）。
+        🔴 默认 `False`：只有 `validate.check_backend` 会让它一起做（一次子进程做完两件事，
+           省掉一次 `django.setup()`）；直接调 `deep_check` 的调用点照旧只做深检。
+    :param tag: 试加载时给包内模块起前缀用的（传块 uuid 更稳）。只在 `trial=True` 时用得上。
 
     🔴 只回**拿得准的问题**：环境交不出来时回 `([], ['没验…'])` —— 说明进日志，不落库、不停用。
     🔴 **正文与整包走 stdin**（不是环境变量、也不是 argv）：这一包有多大是作者说了算的，
@@ -1251,6 +1471,14 @@ def deep_check(
             # ⚠️ 参数是**小数据**（作者写的一段 JSON），但仍走同一个通道：这一层"数据只有一条路"
             #    （少一条通道就少一处"某个调用点还塞环境变量"的复发空间）。
             'params': params if params.strip() else '',
+            # 🔴 依赖声明那一层：**声明本身**（父进程从清单里读出来、规范化过的）+ 报文前缀 + 开关。
+            #    它是**数据**、不是代码：子进程里那份判据是平台自己的（`_requires_check()`）。
+            'requires': requires if isinstance(requires, dict) else None,
+            # 🔴 试加载那一半要不要在**这一趟**里做（见 `_CHECK` 里那一段）：
+            #    `validate.check_backend` 默认让子进程一起做（省一次 `django.setup()`）；
+            #    `LABULL_DEEPCHECK=off` 时父进程自己另起一个只做加载的子进程。
+            'trial': bool(trial),
+            'tag': str(tag or ''),
         },
         ensure_ascii=False,
     )
@@ -1276,8 +1504,8 @@ def deep_check(
             [
                 (
                     'backend',
-                    f'{BLOCK_BACKEND_FILE} 引用深检超过 {DEEP_TIMEOUT} 秒没有结束，已中止'
-                    '（handler 里不许有死循环 / 长轮询；耗时的事请改成先落状态再异步处理）',
+                    f'{BLOCK_BACKEND_FILE} 试加载 / 引用深检超过 {DEEP_TIMEOUT} 秒没有结束，已中止'
+                    '（顶层与 handler 里都不许有死循环 / 长轮询；耗时的事请改成先落状态再异步处理）',
                 )
             ],
             [],