labull-framework 0.1.5__tar.gz → 0.1.7__tar.gz

{labull_framework-0.1.5/labull_framework.egg-info → labull_framework-0.1.7}/PKG-INFO

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

labull_framework-0.1.7/labull_framework/magic_block/blockpackage.py

@@ -0,0 +1,191 @@
+"""块包里的**每一个 `.py` 都当入口独立加载**（不止 `backend_open.py`）。
+
+🔴 这是块包"能拆文件"的全部机制，只有两条：
+   ① **包内每个 `.py` 各自独立执行**（宿主是 `exec(compile(正文), 文件名, 'exec')`）；
+   ② **文件之间不许互相引用** —— 谁都不 import 包里的另一个文件（`sibling_imports()` 查这一条）。
+      于是不需要模块注册、不需要依赖排序、不需要清理别名：每个文件就是一个独立模块，
+      与 `backend_open.py` 的待遇完全一样。
+
+🔴 为什么要"不许互相引用"这条规矩：块后端的正文**在库里**，不在磁盘上、也不在 `sys.path` 上。
+   要想让 `from helper import x` 成立，就得先把包内文件注册成真模块（注册壳 → 依赖排序 →
+   别名共享 → 用完摘干净）——那套能跑通，但每一步都有坑（见 `probe-module-loader.py` 的血泪）。
+   而"各写各的"把这一整类复杂度消掉了：想分文件就分，但每个文件要能独立站住
+   （公共逻辑各写一份，或者放进**项目**里的公共模块 —— 那是普通 Python，随便 import）。
+
+🔴 路由判据要扫**所有 `.py`**：`api.open.d.ts`、权限、404 报文都照它。
+   所以 `blockpackage.route_names_of()` 与运行期 `registry` 用的是同一份扫描。
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from typing import Any
+
+#: 块后端的入口文件（**契约**：这个名字不变；它同时是"主文件"）。
+ENTRY_FILE = 'backend_open.py'
+
+
+def python_files(files: dict[str, str] | None) -> list[tuple[str, str]]:
+    """包内全部 `.py`：`[(包内相对路径, 正文)]`，按路径排序（结果可复现）。"""
+    out: list[tuple[str, str]] = []
+    for name, body in sorted((files or {}).items()):
+        if isinstance(body, str) and str(name).endswith('.py'):
+            out.append((str(name), body))
+    return out
+
+
+@dataclass
+class LoadedBlock:
+    """一次加载的结果。
+
+    · `namespaces`：每个 `.py` 各一份命名空间（键是包内相对路径）；
+    · `classes`：**包里所有文件**里定义的类（`类名 → 类`）—— 路由判据要它；
+    · `errors`：逐条"哪个文件怎么了"（作者一眼看得出是哪一份的问题）。
+    """
+
+    namespaces: dict[str, dict[str, Any]] = field(default_factory=dict)
+    classes: dict[str, type] = field(default_factory=dict)
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    @property
+    def namespace(self) -> dict[str, Any]:
+        """主文件那份命名空间（老调用点用得多；主文件不在包里就是空的）。"""
+        return self.namespaces.get(ENTRY_FILE, {})
+
+
+def load_block(files: dict[str, str], tag: str = '') -> LoadedBlock:
+    """把包内每个 `.py` 各执行一次（互不影响），收集它们的类。
+
+    :param tag: 只用来给每份正文起个可读的 `__name__`（块 uuid 最好）。
+    🔴 **一个文件炸了不影响别的文件**：错误收进 `result.errors`（带文件名），其余照常加载 ——
+       否则"有个小笔误"会把整个块的路由一起弄没。
+    """
+    result = LoadedBlock()
+    for relative, source in python_files(files):
+        namespace: dict[str, Any] = {'__name__': f'{relative[:-3].replace("/", ".") or tag or "block"}'}
+        try:
+            exec(compile(source, relative, 'exec'), namespace)
+        except BaseException as exc:  # noqa: BLE001 —— 逐文件报，不让它带崩别的文件
+            result.errors.append(f'{relative} 加载失败：{type(exc).__name__}: {exc}')
+            continue
+        result.namespaces[relative] = namespace
+        for name, value in namespace.items():
+            # 只看**这个文件自己定义**的公开类（`import` 进来的名字也在命名空间里，但它们
+            # 属于别的文件 —— 那样同一个类会被扫两遍、还可能把项目里的类当成路由类）。
+            if isinstance(value, type) and not name.startswith('_') and value.__module__ == namespace['__name__']:
+                result.classes.setdefault(name, value)
+    return result
+
+
+# ──────────────────────────── 静态那一半：不执行也能列出路由 / 查规矩 ────────────────────────────
+
+
+def _decorator_name(node: ast.AST) -> str:
+    """装饰器叫什么（认 `@MagicBackendAPI(...)` 与 `@sdk.MagicBackendAPI(...)` 两种写法）。"""
+    target = node.func if isinstance(node, ast.Call) else node
+    if isinstance(target, ast.Name):
+        return target.id
+    if isinstance(target, ast.Attribute):
+        return target.attr
+    return ''
+
+
+def route_names_of(files: dict[str, str]) -> list[str]:
+    """**不执行任何代码**，把包内所有 `.py` 里带装饰器的 `类名.方法名` 列出来。
+
+    🔴 与运行期那份路由表必须**说同一件事**（`api.open.d.ts`、权限、404 报文都照它）——
+       所以这里扫的是同样那批文件：**每一个 `.py`**。
+    🔴 只扫**顶层类**：`routes_of_namespace` 也是这个口径（类体里再嵌套的类不算路由）。
+    """
+    out: list[str] = []
+    for relative, source in python_files(files):
+        try:
+            tree = ast.parse(source, filename=relative)
+        except SyntaxError:
+            continue  # 语法那一条由 `check_backend` 报
+        for cls in [node for node in tree.body if isinstance(node, ast.ClassDef)]:
+            for node in cls.body:
+                if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    continue
+                if any(_decorator_name(item) == 'MagicBackendAPI' for item in node.decorator_list):
+                    route = f'{cls.name}.{node.name}'
+                    if route not in out:
+                        out.append(route)
+    return out
+
+
+def route_meta_of(files: dict[str, str]) -> dict[str, str]:
+    """`类名.方法名 → 声明的权限`（只看包内文件；这是 `api.open.d.ts` 与权限表的同一来源）。"""
+    out: dict[str, str] = {}
+    for relative, source in python_files(files):
+        try:
+            tree = ast.parse(source, filename=relative)
+        except SyntaxError:
+            continue
+        for cls in [node for node in tree.body if isinstance(node, ast.ClassDef)]:
+            for node in cls.body:
+                if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    continue
+                if not any(_decorator_name(item) == 'MagicBackendAPI' for item in node.decorator_list):
+                    continue
+                permission = ''
+                for decorator in node.decorator_list:
+                    if _decorator_name(decorator) != 'MagicBackendAPI' or not isinstance(decorator, ast.Call):
+                        continue
+                    for keyword in decorator.keywords:
+                        if keyword.arg == 'permission' and isinstance(keyword.value, ast.Constant):
+                            permission = str(keyword.value.value or '')
+                out[f'{cls.name}.{node.name}'] = permission
+    return out
+
+
+def sibling_imports(files: dict[str, str]) -> list[tuple[str, str, str]]:
+    """包内文件**互相引用**的那些 import：`[(哪个文件, import 的名字, 它指向包里的哪个文件)]`。
+
+    🔴 这条是规矩（"文件和文件之间不能互相引用"），不是风格建议：块后端的正文在库里、
+       不在磁盘上，跨文件 import 要靠一整套模块注册与依赖排序才成立，而那套东西脆弱得多。
+       与其让作者踩，不如**在保存 / 体检 / 提交前就报出来**。
+    🔴 判据只认"指向包内某个 `.py`"的 import：`orders.models`（项目里）与 `json`（标准库）不在此列。
+       ⚠️ 只按**名字**判（不执行），所以 `import helper` 与 `from helper import x` 都算。
+    """
+    #: 包内所有 `.py` 的"模块候选名"：`helper.py` ⇒ `helper`，`lib/util.py` ⇒ `lib.util`。
+    known: dict[str, str] = {}
+    for relative, _body in python_files(files):
+        stem = relative[:-3]
+        if stem.endswith('/__init__'):
+            stem = stem[: -len('/__init__')]
+        if not stem:
+            continue
+        known[stem] = relative
+        known[stem.split('/')[-1]] = relative
+
+    out: list[tuple[str, str, str]] = []
+    for relative, source in python_files(files):
+        try:
+            tree = ast.parse(source, filename=relative)
+        except SyntaxError:
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom):
+                if node.level:
+                    continue  # 相对 import（`from . import x`）在块里本来就不成立，另有判据
+                candidates = [node.module or '']
+                candidates.extend(f'{node.module}.{alias.name}' if node.module else alias.name
+                                  for alias in node.names if alias.name != '*')
+            elif isinstance(node, ast.Import):
+                candidates = [alias.name for alias in node.names]
+            else:
+                continue
+            for name in candidates:
+                hit = known.get(name) or known.get(name.split('.')[0])
+                if hit is not None and hit != relative:
+                    # 同一个 import 会给出两个候选（`helper` 与 `helper.VALUE`）⇒ 按目标去重，
+                    # 不然作者会看到同一件事报两遍。
+                    if not any(item[0] == relative and item[2] == hit for item in out):
+                        out.append((relative, name, hit))
+    return out

{labull_framework-0.1.5 → labull_framework-0.1.7}/labull_framework/magic_block/deepcheck.py

@@ -277,24 +277,57 @@ def main():
         return _unavailable('Django 设置没配好，这一块这一次没验')
 
     source = json.loads(os.environ['LABULL_DEEP_SOURCE'])
+    # 🔴 整包一起验（块包可以拆文件）：`LABULL_DEEP_FILES` 是 `{包内相对路径: 正文}`。
+    # ⚠️ **子进程里没有父进程模块级的那些名字、也没有 wrapper 里的 `_parent`**：
+    #    要什么就自己 import（这一段顶上只 import 了 `...sdk` 那几个）。
+    #    写一个不存在的名字会让整层深检**静默失效**（`NameError` 被 `_unavailable` 吞成一句说明，
+    #    保存于是全放行）—— 这里真踩过，而且是"改动前能报的错、改动后不报了"这种最难发现的形态。
+    from labull_framework.magic_block import blockpackage as _blockpackage
+    _main_file = os.environ.get('LABULL_DEEP_MAIN_FILE') or 'backend_open.py'
     try:
-        tree = ast.parse(source, filename='backend_open.py')
-    except SyntaxError:
-        return _unavailable('正文有语法错，引用深检没跑（语法那一条已经报了）')
+        raw_package = json.loads(os.environ.get('LABULL_DEEP_FILES') or '{}')
+    except ValueError:
+        raw_package = {}
+    package: dict[str, str] = (
+        {str(name): str(body) for name, body in raw_package.items()} if isinstance(raw_package, dict) else {}
+    )
+    package.setdefault(_main_file, source)
+    # 🔴 包内文件**互相引用**要先报出来（规矩，不是风格）：块后端的正文在库里、不在磁盘上，
+    #    `from helper import x` 那种写法在块里**不成立**（平台按"每个 .py 各自独立加载"来跑）。
+    #    不报的话症状是运行期 `ModuleNotFoundError`，而那时人已经不知道该看哪儿了。
+    for where, name, target in _blockpackage.sibling_imports(package):
+        _STATIC.append(_issue(
+            'backend',
+            f'{where} 里 import 了包内的 {name}（就是 {target}）：**块里文件之间不能互相引用** —— '
+            f'平台把每个 .py 各自独立加载（谁都不认识谁）。要么把那段逻辑复制到这份文件里，'
+            f'要么放进**项目**里的公共模块再 import（那是普通 Python，随便用）。',
+        ))
 
     module_name = str(os.environ.get('LABULL_DEEP_MODULE') or 'backend_open')
-    try:
-        _static_check(tree, module_name, apps)
-    except Exception as exc:
-        # 判据自己崩了不是这个块的错，但要说出来（否则就是"静默地什么都没验"）。
-        _STATIC.append(_issue('backend', '引用深检自己失败了（不是这个块的问题）：%s: %s'
-                              % (type(exc).__name__, exc)))
+
+    # 🔴 **每一份 `.py` 都静态过一遍**（不只主文件）：拆出去的文件里 `Order.no` 这种写法
+    #    同样要在保存时现形。`_imported_models` 只对"导入了模型"的文件起作用，
+    #    其余文件白跑一遍也不报 —— 所以这里不必挑文件。
+    for relative, body in sorted(package.items()):
+        if not relative.endswith('.py'):
+            continue
+        try:
+            tree = ast.parse(body, filename=relative)
+        except SyntaxError:
+            continue  # 语法那一条已经由上层报了
+        try:
+            _static_check(tree, module_name, apps)
+        except Exception as exc:
+            # 判据自己崩了不是这个块的错，但要说出来（否则就是"静默地什么都没验"）。
+            _STATIC.append(_issue('backend', '引用深检自己失败了（不是这个块的问题）：%s: %s'
+                                  % (type(exc).__name__, exc)))
+            break
 
     # 🔴 试跑那一层会用到的几个函数（撒样例行 / 取主键 / 错该算谁头上）是**从外面注入**的
     #    （见 `deep_check()` 里那个 wrapper）：它们只有一份实现（本模块模块级那几个），
     #    这里**不许再抄一份** —— 抄一份的下场是"保存时说合法、体检时说非法"。
     if str(os.environ.get('LABULL_DEEP_PROBE') or '') == '1':
-        probe(source, module_name, apps)
+        probe(source, module_name, apps, package)
     return _result()
 
 
@@ -444,7 +477,7 @@ def _label(value):
 #    是块自己的代码炸了"时才归给块。
 
 
-def probe(source, module_name, apps):
+def probe(source, module_name, apps, package=None):
     # 🔴 **换库必须在加载那份正文之前**（真踩过）：块正文一跑，它 import 的东西就可能已经把
     #    `default` 那条连接建起来了（Django 的 ORM 是懒连接，但 import 期就可能碰它），
     #    之后再换库就会留下一条"连着真库"的连接 —— 建表于是撞在真库上、探针整层静默失效。
@@ -452,9 +485,9 @@ def probe(source, module_name, apps):
     for note in _mirror_database():
         _NOTES.append(note)
         return
-    handlers = _handlers(source, module_name)
+    handlers = _handlers(source, module_name, package, _main_file)
     if handlers is None:
-        _NOTES.append('这一份正文加载不起来，试跑那一层没跑（静态那几条照样算）')
+        _NOTES.append('这一包加载不起来，试跑那一层没跑（静态那几条照样算）')
         return
     if not handlers:
         return
@@ -505,22 +538,26 @@ def _mirror_database():
     return []
 
 
-def _handlers(source, module_name):
-    """把这份正文加载一次，回 `[(路由名, 绑好的 handler, 建类时的异常)]`。
+def _handlers(source, module_name, package=None, main_file='backend_open.py'):
+    """把这一**包**加载一次，回 `[(路由名, 绑好的 handler, 建类时的异常)]`。
 
+    :param package: `{包内相对路径: 正文}`（包内每个 `.py` 都会被加载一次）。
+    :param main_file: 主文件的相对路径（**不许在这里写死**：本函数会被编译进子进程执行，
+        而父进程模块级的那个常量在子进程里不存在 —— 写死/引用都会 `NameError`，
+        整层深检于是静默失效，真踩过）。
     ⚠️ 由调用方保证**在这之前已经换过库**（顺序是判据，见 `probe()`）。
     """
     try:
+        from labull_framework.magic_block import blockpackage
         from labull_framework.magic_block.sdk import routes_of_namespace
     except Exception:
         return None
-    namespace = {'__name__': module_name}
-    try:
-        exec(compile(source, 'backend_open.py', 'exec'), namespace)
-    except Exception:
+    files = {str(name): str(body) for name, body in (package or {}).items()}
+    files.setdefault(main_file, source)
+    loaded = blockpackage.load_block(files, tag=module_name or 'probe')
+    if loaded.errors:
         return None
-    classes = dict((key, value) for key, value in namespace.items()
-                   if isinstance(value, type) and not key.startswith('_'))
+    classes = loaded.classes
     try:
         meta = routes_of_namespace(classes)
     except Exception:
@@ -680,6 +717,9 @@ def deep_check(
         'for _name in ("_seed_rows", "_filled", "_blamable", "_needs_params", "_failure_message",\n'
         '              "_route_models"):\n'
         '    space[_name] = getattr(_parent, _name)\n'
+        # ⚠️ `_main_file` 也要注入：`probe()` 是**父进程的函数**、在子进程的命名空间里执行，
+        #    所以它只能读子进程的全局（先前漏了这一条 ⇒ `NameError` ⇒ 试跑那一层静默不跑）。
+        'space["_main_file"] = os.environ.get("LABULL_DEEP_MAIN_FILE") or "backend_open.py"\n'
         'exec(compile(os.environ["LABULL_DEEP_CHECK"], "labull_deepcheck.py", "exec"), space)\n'
         'print("LABULL_DEEP_RESULT" + json.dumps(space["_RESULT_"], ensure_ascii=False))\n'
     )
@@ -690,6 +730,15 @@ def deep_check(
     env['LABULL_DEEP_PATH'] = env['PYTHONPATH']
     env['LABULL_DEEP_CHECK'] = _CHECK
     env['LABULL_DEEP_SOURCE'] = json.dumps(src, ensure_ascii=False)
+    # 🔴 主文件名由父进程告诉子进程（子进程里**没有**父进程模块级的 `BLOCK_BACKEND_FILE`）。
+    env['LABULL_DEEP_MAIN_FILE'] = BLOCK_BACKEND_FILE
+    # 🔴 **整包**一起递（不只主文件）：拆过文件的块要靠兄弟文件才加载得起来，
+    #    否则保存时说"加载不起来"，而它明明在包里。
+    env['LABULL_DEEP_FILES'] = json.dumps(
+        {name: body for name, body in (files or {}).items()
+         if isinstance(body, str) and name.endswith('.py')},
+        ensure_ascii=False,
+    )
     env['LABULL_DEEP_PROBE'] = '1' if probe else '0'
     env['LABULL_DEEP_PROBE_LIMIT'] = str(PROBE_LIMIT)
     params = (files or {}).get(PROBE_PARAMS_FILE)