labull-framework 3.0.4__tar.gz → 3.0.5__tar.gz

{labull_framework-3.0.4/labull_framework.egg-info → labull_framework-3.0.5}/PKG-INFO

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

{labull_framework-3.0.4 → labull_framework-3.0.5}/labull_framework/access.py

@@ -1,24 +1,32 @@
-"""权限码与权限包（组）的**声明 → 落库**那一半 —— 声明住在环境变量里。
-
-两个变量（格式就是契约，改它要连文档 / 示例 / 判据一起改）：
-
-    LABULL_PERMISSIONS=订单.models=approve:可以审批订单,close:可以关单;…
-                       └ 模型（app_label.Model）┘ └ codename:中文名 ┘
-
-    LABULL_GROUPS=财务=orders.approve,orders.close;出纳=orders.close
-
-🔴 **为什么 permission 的条目里要写模型**：`Permission` 的行主键是
-   `(content_type, codename)`，而 content_type 只能从一个**真实模型**拿到；
-   环境变量里只有 `app_label.codename` 的话，要么造一个伪模型（admin 里会多一行幽灵，
-   `remove_stale_contenttypes` 还会把它当垃圾清掉），要么就没有 content_type。
-   写模型名是最小的一处额外信息，换来的是 content_type 正确、与 `Meta.permissions` 同一行。
-🔴 权限码本身是 `app_label.codename`（与 `flow.py` 的 `permission:`、`has_perm()` 同一份口径）：
-   模型那一段只用来定位 content_type，**不进码**。
-🔴 同步**只增不删**：少一个组 / 少一个权限就"从库里删掉"是不做的 ——
-   删组会级联掉 `auth_user_groups` 里人的授权，那是人手动配的数据，不是派生值。
-   要删只能人自己在库里删（这是用户明确要的语义）。
-🔴 `sync()` **永不抛**：它是启动路径上的一件事（与 `auth/bootstrap.py` 同一个模式），
-   库连不上 / 表还没迁移都只该进日志与报告。
+"""权限码与权限包（组）的**声明 → 落库**那一半 —— 声明住在项目里的一份 YAML 文件。
+
+默认位置：`<BASE_DIR>/labull-access.yaml`（可以用 `LABULL_ACCESS_FILE` 指到别的路径）。
+文件长这样（一份普通 YAML，**不是**环境变量里那种一行塞完的串）：
+
+```yaml
+# 权限（可选；模型 Meta.permissions 里已经声明过的不必重复）
+permissions:
+  canvasdemo.Reimbursement:
+    review_reimbursement: 可以审批报销单
+    pay_reimbursement: 可以对报销单付款
+
+# 权限包（组）：组名 → 权限码
+groups:
+  财务:
+    - canvasdemo.review_reimbursement
+    - canvasdemo.pay_reimbursement
+  出纳:
+    - canvasdemo.pay_reimbursement
+```
+
+🔴 **为什么 permissions 里要写模型**：`Permission` 的行主键是 `(content_type, codename)`，
+   而 content_type 只能从一个**真实模型**拿到。写模型名换来的是 content_type 正确、
+   与 `Meta.permissions` 指向同一行；对外暴露的码仍是 `app_label.codename`。
+🔴 **不引 PyYAML**：这个仓库不引第三方运行时依赖，所以这里只认上面这一种子集
+   （`键:` / `键: 值` / 缩进两格的映射或 `- 项` 列表），不认识的写法**当场报错**。
+🔴 同步**只增不删**：少一个组 / 少一个权限**不会**从库里删掉 —— 删组会级联掉
+   `auth_user_groups` 里人的授权，那是人手动配的数据。要删只能人自己在库里删。
+🔴 `sync()` **永不抛**：它是启动路径上的一件事（与 `auth/bootstrap.py` 同一个模式）。
 🔴 组名只是**标签**：代码里任何判据都不许读组名（判权永远看 permission）。
 """
 
@@ -27,6 +35,7 @@ from __future__ import annotations
 import logging
 import re
 from dataclasses import dataclass, field
+from pathlib import Path
 from typing import Any
 
 from .env import read_env
@@ -34,28 +43,28 @@ from .permissions import PERMISSION_PATTERN
 
 logger = logging.getLogger(__name__)
 
-#: 权限声明（`app_label.Model=codename:中文名[,…]`；多个模型用 `;` 分隔）。
-PERMISSIONS_ENV = 'LABULL_PERMISSIONS'
+#: 声明文件的名字（默认落在项目的 `BASE_DIR` 下）。
+ACCESS_FILE_NAME = 'labull-access.yaml'
 
-#: 权限包（组）声明（`组名=app_label.codename[,…]`；多个包用 `;` 分隔）。
-GROUPS_ENV = 'LABULL_GROUPS'
+#: 把声明文件指到别处（路径；相对路径按 `BASE_DIR` 解析）。
+ACCESS_FILE_ENV = 'LABULL_ACCESS_FILE'
 
 #: 一个标识符（app_label / 模型名 / codename 共用这一份判据）。
 _IDENT = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*$')
 
-#: Django `Permission.codename` / `Group.name` 的上限（照抄模型那两列，抄错就会在写库时炸）。
+#: Django `Permission.codename` / `Permission.name` / `Group.name` 的上限（照抄模型那三列）。
 CODENAME_MAX = 100
 NAME_MAX = 255
 GROUP_NAME_MAX = 150
 
 
 class AccessError(ValueError):
-    """声明格式不对 —— 报文是中文原话，直接给人看（不走 `%` 模板）。"""
+    """声明文件写得不对 —— 报文是中文原话，直接给人看（带行号）。"""
 
 
 @dataclass(frozen=True)
 class PermissionSpec:
-    """一条权限声明：`app_label.Model=codename:中文名`。"""
+    """一条权限声明：`app_label.Model` → `codename: 中文名`。"""
 
     app_label: str
     model: str
@@ -76,6 +85,14 @@ class GroupSpec:
     permissions: tuple[str, ...] = ()
 
 
+@dataclass(frozen=True)
+class Declaration:
+    """一份声明文件的全部内容（`permissions:` / `groups:` 都可以整块不写）。"""
+
+    permissions: tuple[PermissionSpec, ...] = ()
+    groups: tuple[GroupSpec, ...] = ()
+
+
 @dataclass
 class Report:
     """一次同步的结论（命令打印它、启动日志挑着打；**空报告 = 什么都没发生**）。"""
@@ -117,154 +134,227 @@ class Report:
         for item in self.added:
             out.append(f'{prefix}把 {item} 放进权限包')
         for item in self.missing:
-            out.append(f'{prefix}✗ 权限包要的码不存在：{item}（先在模型 Meta.permissions / '
-                       f'{PERMISSIONS_ENV} 里声明，再 migrate）')
+            out.append(f'{prefix}✗ 权限包要的码不存在：{item}（先在模型的 Meta.permissions / '
+                       f'{ACCESS_FILE_NAME} 的 permissions 里声明，再 migrate）')
         return out
 
 
-def _split(raw: str) -> list[str]:
-    """按 `;` 切条目（空条目忽略 —— 结尾多一个 `;` 是手滑，不是错误）。"""
-    return [item.strip() for item in str(raw or '').split(';') if item.strip()]
+# ──────────────────────────── 读那一份 YAML（只认这一种子集） ────────────────────────────
 
 
-def _split_codes(raw: str) -> list[str]:
-    """按 `,` 切权限码（空段**报错**：`a,,b` 多半是手滑，跳过会让一个码悄悄没进包）。"""
-    items = [item.strip() for item in str(raw or '').split(',')]
-    if any(not item for item in items):
-        raise AccessError(f'权限码列表里有空段（{raw!r}）—— 用逗号分隔，别留空项')
-    return items
+def _strip_comment(line: str) -> str:
+    """去掉行尾注释（`#` 在引号里不算注释 —— 中文名里带 `#` 是合法的）。"""
+    quote = ''
+    for index, char in enumerate(line):
+        if quote:
+            if char == quote:
+                quote = ''
+        elif char in ('"', "'"):
+            quote = char
+        elif char == '#':
+            return line[:index]
+    return line
 
 
-def parse_permissions(raw: str) -> tuple[PermissionSpec, ...]:
-    """`LABULL_PERMISSIONS` 的值 → 声明（格式不对抛 `AccessError`，中文原话）。"""
-    specs: list[PermissionSpec] = []
-    seen: set[str] = set()
-    for entry in _split(raw):
-        if '=' not in entry:
-            raise AccessError(
-                f'`{PERMISSIONS_ENV}` 的条目 {entry!r} 不是 `app_label.Model=codename:中文名`'
-                f'（少了那个 `=`）'
-            )
-        target, codes = entry.split('=', 1)
-        target = target.strip()
-        model_parts = target.split('.')
-        if len(model_parts) != 2 or not all(_IDENT.match(part) for part in model_parts):
-            raise AccessError(
-                f'`{PERMISSIONS_ENV}` 里的 {target!r} 不是 `app_label.Model` 的形状 —— '
-                f'要写**真实的模型**（权限行必须挂在一个 content_type 上），例如 '
-                f'`canvasdemo.Reimbursement`'
-            )
-        app_label, model = model_parts
-        for item in _split_codes(codes):
-            if ':' not in item:
-                raise AccessError(
-                    f'`{PERMISSIONS_ENV}` 里 {target} 的 {item!r} 少了中文名 —— '
-                    f'写法是 `codename:中文名`（管理员在组里看到的就是它）'
-                )
-            codename, name = item.split(':', 1)
-            codename, name = codename.strip(), name.strip()
-            if not _IDENT.match(codename) or len(codename) > CODENAME_MAX:
-                raise AccessError(
-                    f'`{PERMISSIONS_ENV}` 里的 codename {codename!r} 不是标识符'
-                    f'（字母/数字/下划线，≤{CODENAME_MAX}）'
-                )
-            if not name or len(name) > NAME_MAX:
-                raise AccessError(
-                    f'`{PERMISSIONS_ENV}` 里 {target}.{codename} 的中文名要写、且 ≤{NAME_MAX} 字'
-                )
-            code = f'{app_label}.{codename}'
-            if code in seen:
-                raise AccessError(
-                    f'`{PERMISSIONS_ENV}` 里权限码 {code} 声明了两次（同一个码只能出现一次）'
-                )
-            seen.add(code)
-            specs.append(PermissionSpec(app_label=app_label, model=model, codename=codename, name=name))
-    return tuple(specs)
-
-
-def parse_groups(raw: str) -> tuple[GroupSpec, ...]:
-    """`LABULL_GROUPS` 的值 → 声明（格式不对抛 `AccessError`，中文原话）。"""
-    specs: list[GroupSpec] = []
-    seen: set[str] = set()
-    for entry in _split(raw):
-        if '=' not in entry:
-            raise AccessError(
-                f'`{GROUPS_ENV}` 的条目 {entry!r} 不是 `组名=app_label.codename[,…]`（少了那个 `=`）'
-            )
-        name, codes = entry.split('=', 1)
-        name = name.strip()
-        if not name or len(name) > GROUP_NAME_MAX:
-            raise AccessError(
-                f'`{GROUPS_ENV}` 里的组名 {name!r} 要写、且 ≤{GROUP_NAME_MAX} 字'
-                f'（Django `Group.name` 的上限）'
-            )
-        if name in seen:
-            raise AccessError(
-                f'`{GROUPS_ENV}` 里权限包「{name}」声明了两次 —— 一个包的所有码写在同一个条目里'
-            )
-        seen.add(name)
-        codes = codes.strip()
-        if codes:
-            items = _split_codes(codes)
-            for code in items:
-                if not PERMISSION_PATTERN.match(code):
-                    raise AccessError(
-                        f'`{GROUPS_ENV}` 里「{name}」的 {code!r} 不是 `app_label.codename` 的形状 —— '
-                        f'环境变量里没有"当前 app"这个概念，要写全（例如 canvasdemo.review_reimbursement）'
+def _value(text: str) -> str:
+    """一个标量值（去掉一对引号；`''` / `""` 是合法的空串）。"""
+    value = text.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+        return value[1:-1]
+    return value
+
+
+def _error(line_no: int, message: str) -> AccessError:
+    return AccessError(f'{ACCESS_FILE_NAME} 第 {line_no} 行：{message}')
+
+
+def parse_access(text: str) -> Declaration:
+    """把声明文件的正文读成 `Declaration`（格式不对抛 `AccessError`，带行号）。
+
+    只认这一种子集（**不引 YAML 库**）：
+
+    ```yaml
+    permissions:
+      app.Model:
+        codename: 中文名
+    groups:
+      组名:
+        - app_label.codename
+    ```
+    """
+    permissions: list[PermissionSpec] = []
+    groups: list[GroupSpec] = []
+    seen_codes: set[str] = set()
+    seen_groups: set[str] = set()
+    section = ''
+    model: tuple[str, str] | None = None       # (app_label, model)
+    group: str = ''                            # 当前正在收权限码的组名
+
+    for index, raw in enumerate(str(text or '').splitlines(), start=1):
+        line = _strip_comment(raw).rstrip()
+        if not line.strip():
+            continue
+        indent = len(line) - len(line.lstrip())
+        content = line.strip()
+
+        if indent == 0:
+            if not content.endswith(':'):
+                raise _error(index, f'顶层只许写 `permissions:` 或 `groups:`（读到 {content!r}）')
+            key = content[:-1].strip()
+            if key not in ('permissions', 'groups'):
+                raise _error(index, f'顶层不认识的键 `{key}`：只有 permissions / groups 两块')
+            section = key
+            model = None
+            group = ''
+            continue
+
+        if not section:
+            raise _error(index, '这一行缩进了，但上面还没有 `permissions:` / `groups:` 那一行')
+
+        if section == 'permissions':
+            if indent == 2:
+                target = content[:-1].strip() if content.endswith(':') else ''
+                parts = target.split('.')
+                if len(parts) != 2 or not all(_IDENT.match(part) for part in parts):
+                    raise _error(
+                        index,
+                        f'{content!r} 不是 `app_label.Model:` 的形状 —— 要写**真实的模型**'
+                        f'（权限行必须挂在一个 content_type 上），例如 `canvasdemo.Reimbursement:`',
+                    )
+                model = (parts[0], parts[1])
+                continue
+            if indent == 4:
+                if model is None:
+                    raise _error(index, '这一行上面少了 `app_label.Model:` 那一行')
+                if ':' not in content:
+                    raise _error(index, f'`{content}` 少了中文名（写法是 `codename: 中文名`）')
+                codename, name = content.split(':', 1)
+                codename, name = codename.strip(), _value(name)
+                if not _IDENT.match(codename) or len(codename) > CODENAME_MAX:
+                    raise _error(
+                        index,
+                        f'codename `{codename}` 不是标识符（字母/数字/下划线，≤{CODENAME_MAX}）',
                     )
-            specs.append(GroupSpec(name=name, permissions=tuple(items)))
-        else:
-            # 空包是合法的（先建组、权限后补）；只是它一个码都不带。
-            specs.append(GroupSpec(name=name, permissions=()))
-    return tuple(specs)
+                if not name or len(name) > NAME_MAX:
+                    raise _error(index, f'`{codename}` 的中文名要写、且 ≤{NAME_MAX} 字')
+                code = f'{model[0]}.{codename}'
+                if code in seen_codes:
+                    raise _error(index, f'权限码 `{code}` 写了两次（同一个码只能出现一次）')
+                seen_codes.add(code)
+                permissions.append(PermissionSpec(
+                    app_label=model[0], model=model[1], codename=codename, name=name,
+                ))
+                continue
+            raise _error(index, f'缩进不对（读到 {indent} 格）：permissions 下只许两格 / 四格')
+
+        # section == 'groups'
+        if indent == 2:
+            if not content.endswith(':'):
+                raise _error(index, f'{content!r} 不是 `组名:` 的形状（组名后面要冒号、值缩进在下面）')
+            name = content[:-1].strip()
+            if not name or len(name) > GROUP_NAME_MAX:
+                raise _error(index, f'组名要写、且 ≤{GROUP_NAME_MAX} 字（Django `Group.name` 的上限）')
+            if name in seen_groups:
+                raise _error(index, f'权限包「{name}」写了两次')
+            seen_groups.add(name)
+            group = name
+            groups.append(GroupSpec(name=name, permissions=()))
+            continue
+        if indent == 4:
+            if not group:
+                raise _error(index, '这一行上面少了 `组名:` 那一行')
+            if not content.startswith('- '):
+                raise _error(index, f'{content!r} 要写成 `- app_label.codename`（列表项）')
+            code = content[2:].strip()
+            if not PERMISSION_PATTERN.match(code):
+                raise _error(
+                    index,
+                    f'`{code}` 不是 `app_label.codename` 的形状 —— 要写全'
+                    f'（例如 canvasdemo.review_reimbursement）',
+                )
+            current = groups[-1]
+            groups[-1] = GroupSpec(name=current.name, permissions=(*current.permissions, code))
+            continue
+        raise _error(index, f'缩进不对（读到 {indent} 格）：groups 下只许两格 / 四格')
+
+    return Declaration(permissions=tuple(permissions), groups=tuple(groups))
 
 
-def declared_permissions() -> tuple[PermissionSpec, ...]:
-    """环境里声明的权限（格式错抛 `AccessError`；没配就是空）。"""
-    return parse_permissions(read_env(PERMISSIONS_ENV))
+# ──────────────────────────── 文件在哪 ────────────────────────────
 
 
-def declared_groups() -> tuple[GroupSpec, ...]:
-    """环境里声明的权限包（格式错抛 `AccessError`；没配就是空）。"""
-    return parse_groups(read_env(GROUPS_ENV))
+def _base_dir() -> Path | None:
+    """项目的 `BASE_DIR`（没设就退回当前工作目录 —— `manage.py` 通常就在项目根跑）。"""
+    try:
+        from django.conf import settings
+
+        base = getattr(settings, 'BASE_DIR', None)
+        if base:
+            return Path(base)
+    except Exception:  # noqa: BLE001 —— 没配 Django 时退回 cwd
+        pass
+    try:
+        return Path.cwd()
+    except Exception:  # noqa: BLE001
+        return None
 
 
-def declared_permission_codes() -> set[str]:
-    """声明的权限码（**不碰数据库**；格式坏掉就当空 —— 判据那一层另有地方报它）。"""
+def access_file() -> tuple[Path | None, bool]:
+    """声明文件在哪：`(路径, 是不是显式配的)`。
+
+    `LABULL_ACCESS_FILE` 配了就用它（相对路径按 `BASE_DIR` 解析）；没配就用
+    `<BASE_DIR>/labull-access.yaml`。取不到任何基准目录 ⇒ `(None, False)`。
+    """
+    raw = read_env(ACCESS_FILE_ENV).strip()
+    base = _base_dir()
+    if raw:
+        path = Path(raw)
+        if not path.is_absolute() and base is not None:
+            path = base / path
+        return path, True
+    if base is not None:
+        return base / ACCESS_FILE_NAME, False
+    return None, False
+
+
+def load() -> tuple[Declaration, list[str]]:
+    """读声明文件：`(声明, 错误清单)`。文件不在 ⇒ 空声明（默认位置）或一条错误（显式配的）。"""
+    path, explicit = access_file()
+    if path is None:
+        return Declaration(), []
+    if not path.is_file():
+        if explicit:
+            return Declaration(), [
+                f'{ACCESS_FILE_ENV} 指向 `{path}`，但那个文件不存在 —— 改对路径、或把这一项删掉'
+            ]
+        return Declaration(), []
     try:
-        return {spec.code for spec in declared_permissions()}
-    except AccessError:
-        return set()
+        return parse_access(path.read_text(encoding='utf-8-sig')), []
+    except AccessError as exc:
+        return Declaration(), [str(exc)]
+    except Exception as exc:  # noqa: BLE001 —— 读文件失败也只进错误清单（启动路径不抛）
+        return Declaration(), [f'读不了 `{path}`：{type(exc).__name__}: {exc}']
 
 
 def declaration_errors() -> list[str]:
-    """两个变量各自的格式问题（**不碰数据库**：系统检查用，`migrate` / `runserver` 就能看见）。"""
-    errors: list[str] = []
-    for env_name, parser in ((PERMISSIONS_ENV, parse_permissions), (GROUPS_ENV, parse_groups)):
-        raw = read_env(env_name)
-        if not raw:
-            continue
-        try:
-            parser(raw)
-        except AccessError as exc:
-            errors.append(str(exc))
-    return errors
+    """声明文件的**格式**问题（不碰数据库：系统检查用，`migrate` / `runserver` 就能看见）。"""
+    return load()[1]
+
+
+def declared_permission_codes() -> set[str]:
+    """声明文件里的权限码（**不碰数据库**；读不出来就当空 —— 判据那一层另有地方报它）。"""
+    return {spec.code for spec in load()[0].permissions}
 
 
 def known_group_names() -> set[str] | None:
-    """项目里"有哪些组"（声明的 ∪ 库里现有的）；取不到任何一处 ⇒ `None`（调用方跳过判据）。
+    """项目里"有哪些组"（声明文件里的 ∪ 库里现有的）；取不到任何一处 ⇒ `None`（调用方跳过判据）。
 
-    🔴 为什么要并上库里的：组是**只增不删**的 —— 没在 `LABULL_GROUPS` 里声明的组
-       （管理员手建的）照样合法；把"没声明"当成"不存在"会把它误判掉。
+    🔴 为什么要并上库里的：组是**只增不删**的 —— 没在文件里声明的组（管理员手建的）照样合法；
+       把"没声明"当成"不存在"会把它误判掉。
     """
-    names: set[str] = set()
-    known = False
-    if read_env(GROUPS_ENV).strip():
-        try:
-            names.update(spec.name for spec in declared_groups())
-            known = True
-        except AccessError:
-            pass
+    declaration, errors = load()
+    names = {spec.name for spec in declaration.groups}
+    known = bool(names) or not errors
     try:
         from django.contrib.auth.models import Group
 
@@ -276,13 +366,13 @@ def known_group_names() -> set[str] | None:
 
 
 def permissions_catalog() -> list[dict[str, str]]:
-    """项目里**声明过的业务权限**（按码排序）：`Meta.permissions` ∪ `.env` 的 `LABULL_PERMISSIONS`。
+    """项目里**声明过的业务权限**（按码排序）：`Meta.permissions` ∪ 声明文件的 `permissions:`。
 
     每条：`{'code', 'app_label', 'model', 'name', 'source'}`。
 
     🔴 Django 自动生成的 `add_/change_/delete_/view_` **不在里面**：那是模型级 CRUD，
        不是业务权限（拿它当业务权限目录是越界，见 `devkit` 的硬规矩第 1 条）。
-    🔴 不读数据库（导出不该依赖"这台机器上库迁移到哪一步了"）：真源是代码与环境变量。
+    🔴 不读数据库（导出不该依赖"这台机器上库迁移到哪一步了"）：真源是代码与声明文件。
     """
     rows: dict[str, dict[str, str]] = {}
     try:
@@ -299,36 +389,30 @@ def permissions_catalog() -> list[dict[str, str]]:
                     'name': str(name),
                     'source': 'Meta.permissions',
                 })
-    except Exception:  # noqa: BLE001 —— 没有 Django 时就只剩环境变量那一半
-        pass
-    try:
-        for spec in declared_permissions():
-            # 环境变量那一份**覆盖**同名码的展示信息（它是显式声明的，人写的那一份为准）。
-            rows[spec.code] = {
-                'code': spec.code,
-                'app_label': spec.app_label,
-                'model': spec.model,
-                'name': spec.name,
-                'source': PERMISSIONS_ENV,
-            }
-    except AccessError:
+    except Exception:  # noqa: BLE001 —— 没有 Django 时就只剩声明文件那一半
         pass
+    for spec in load()[0].permissions:
+        # 声明文件那一份**覆盖**同名码的展示信息（它是显式声明的，人写的那一份为准）。
+        rows[spec.code] = {
+            'code': spec.code,
+            'app_label': spec.app_label,
+            'model': spec.model,
+            'name': spec.name,
+            'source': ACCESS_FILE_NAME,
+        }
     return [rows[code] for code in sorted(rows)]
 
 
 def groups_catalog() -> list[dict[str, Any]]:
-    """环境里声明的权限包：`[{'name': 组名, 'permissions': [码, …]}, …]`（没配就是空）。
+    """声明文件里的权限包：`[{'name': 组名, 'permissions': [码, …]}, …]`（没配就是空）。
 
     🔴 只读**声明**、不读库：导出那一刻铺给块作者的是"这个项目声明了哪些包"；
        库里手建的组不进来（它们是操作动作，不是契约）。
     """
-    try:
-        return [
-            {'name': spec.name, 'permissions': list(spec.permissions)}
-            for spec in declared_groups()
-        ]
-    except AccessError:
-        return []
+    return [
+        {'name': spec.name, 'permissions': list(spec.permissions)}
+        for spec in load()[0].groups
+    ]
 
 
 def _model_class(app_label: str, model: str) -> Any:
@@ -348,13 +432,11 @@ def sync(*, dry_run: bool = False) -> Report:
     🔴 库还没迁移 / 连不上 ⇒ 结论进 `errors`，不抛：这是启动路径上的一件事。
     """
     report = Report(dry_run=dry_run)
-    try:
-        permission_specs = declared_permissions()
-        group_specs = declared_groups()
-    except AccessError as exc:
-        report.errors.append(str(exc))
+    declaration, errors = load()
+    report.errors.extend(errors)
+    if errors:
         return report
-    if not permission_specs and not group_specs:
+    if not declaration.permissions and not declaration.groups:
         return report
     try:
         from django.contrib.auth.models import Group, Permission
@@ -369,7 +451,7 @@ def sync(*, dry_run: bool = False) -> Report:
         #: dry-run 下"这一次会建出来"的那些码：组那一段要把它们当成"可用"，
         #: 否则一次全新环境的 dry-run 会把每个码都报成 missing（那是假错）。
         planned: set[str] = set()
-        for spec in permission_specs:
+        for spec in declaration.permissions:
             existing = Permission.objects.filter(
                 content_type__app_label=spec.app_label, codename=spec.codename,
             ).first()
@@ -397,7 +479,7 @@ def sync(*, dry_run: bool = False) -> Report:
                 report.permission_name_differs.append(spec.code)
 
         # ── ② 组：缺就建；权限只 add 缺的那些 ──
-        for spec in group_specs:
+        for spec in declaration.groups:
             group = Group.objects.filter(name=spec.name).first()
             if group is None:
                 if dry_run:

{labull_framework-3.0.4 → labull_framework-3.0.5}/labull_framework/env.py

@@ -224,22 +224,17 @@ ENV_ITEMS: tuple[EnvItem, ...] = (
         hint='LABULL_BLOCK_WORKERS=2',
         group='平台开关',
     ),
-    # ── 授权（权限码 / 权限包）：**声明在这里，落库由框架同步** ──
-    # 🔴 为什么是环境变量而不是迁移：迁移里的 `RunPython` 跑在 `create_permissions` **之前**，
+    # ── 授权（权限码 / 权限包）：**声明在项目里的一份 YAML 文件**，落库由框架同步 ──
+    # 🔴 为什么不是迁移：迁移里的 `RunPython` 跑在 `create_permissions` **之前**，
     #    要拿权限行去塞组就得自己再建一遍权限行（那是第二份真源）。这里只在启动时对一次账。
+    # 🔴 为什么不是环境变量：`group → 权限码` 是一张映射，塞进一行环境变量既难读、又容易写错
+    #    （见 `labull-access.yaml` 的写法）。
     # 🔴 同步**只增不删**：要删组 / 删权限，只能人自己在库里删（删组会级联掉人的授权）。
     EnvItem(
-        name='LABULL_PERMISSIONS',
-        brief='权限声明：`app_label.Model=codename:中文名[,codename:中文名…]`，多个模型用 `;` 分隔'
-              '（模型那一段只用来定位 content_type，对外暴露的码仍是 `app_label.codename`）',
-        hint='LABULL_PERMISSIONS=canvasdemo.Reimbursement=review_reimbursement:可以审批报销单',
-        group='授权（权限码 / 权限包）',
-    ),
-    EnvItem(
-        name='LABULL_GROUPS',
-        brief='权限包（组）声明：`组名=app_label.codename[,app_label.codename…]`，多个包用 `;` 分隔'
-              '（组名只是标签；启动时把组与它的权限同步进库，只增不删）',
-        hint='LABULL_GROUPS=财务=canvasdemo.review_reimbursement,canvasdemo.pay_reimbursement',
+        name='LABULL_ACCESS_FILE',
+        brief='授权声明文件的路径（默认就是 `BASE_DIR/labull-access.yaml`；相对路径按 `BASE_DIR` 解析）。'
+              '文件里写 `permissions:`（权限码 + 中文名）与 `groups:`（组名 → 权限码）',
+        hint='LABULL_ACCESS_FILE=config/labull-access.yaml',
         group='授权（权限码 / 权限包）',
     ),
     # ── 块的配置面 ──

{labull_framework-3.0.4 → labull_framework-3.0.5}/labull_framework/magic_block/devkit.py

@@ -1404,8 +1404,8 @@ def backend_lock_pyi(
         for item in virtuals:
             lines.extend(_table_block(item, virtual=True))
     # ── ⑥ 授权（权限码 / 权限包）：块里写 `permission:` 与 `requires.permissions` 用的就是它们 ──
-    # 🔴 这一段**不读数据库**：权限码来自模型的 `Meta.permissions` 与 `.env` 的 `LABULL_PERMISSIONS`，
-    #    权限包来自 `.env` 的 `LABULL_GROUPS` —— 导出不该依赖"这台机器上库迁移到哪一步了"。
+    # 🔴 这一段**不读数据库**：权限码来自模型的 `Meta.permissions` 与 `labull-access.yaml` 的
+    #    `permissions:`，权限包来自同一份文件的 `groups:` —— 导出不该依赖"这台机器上库迁移到哪一步了"。
     lines.append('')
     lines.append('# ── ⑥ 权限码与权限包（块里 `permission:` / 清单的 `requires.permissions` 用它们）──')
     lines.extend(_catalog_lines())
@@ -1417,7 +1417,7 @@ def _catalog_lines() -> list[str]:
     out: list[str] = []
     catalog = permissions_catalog()
     if catalog:
-        out.append('# 业务权限码（声明在模型的 `Meta.permissions` 或 `.env` 的 LABULL_PERMISSIONS）：')
+        out.append('# 业务权限码（声明在模型的 `Meta.permissions` 或 labull-access.yaml 的 permissions:）：')
         for row in catalog:
             out.append(f"#   {row['code']}  —— {row['name']}（{row['app_label']}.{row['model']}）")
     else:
@@ -1428,14 +1428,14 @@ def _catalog_lines() -> list[str]:
     groups = groups_catalog()
     if groups:
         out.append('#')
-        out.append('# 权限包（组名 → 权限码；来自 `.env` 的 LABULL_GROUPS，启动时框架会同步进库、只增不删）：')
+        out.append('# 权限包（组名 → 权限码；来自 labull-access.yaml 的 groups:，启动时框架会同步进库、只增不删）：')
         for item in groups:
             codes = '、'.join(item['permissions']) or '（空包）'
             out.append(f"#   {item['name']}：{codes}")
         out.append('# 🔴 组名只是标签：块里**不许**按组名判人，判权只看 permission 码。')
     else:
         out.append('#')
-        out.append('# （没有声明权限包：管理员只能逐个给人授权；要打包就在 `.env` 的 LABULL_GROUPS 里写）')
+        out.append('# （没有声明权限包：管理员只能逐个给人授权；要打包就在 labull-access.yaml 的 groups: 里写）')
     return out
 
 def _access_doc() -> str:
@@ -1466,14 +1466,14 @@ def _access_doc() -> str:
     else:
         out.append('')
         out.append('（这个项目没有声明权限包：管理员只能逐个给人授权；'
-                   '要打包就在 `.env` 的 `LABULL_GROUPS` 里写）')
+                   '要打包就在 `labull-access.yaml` 的 `groups:` 里写）')
     out.append('')
     out.append('**怎么引用它们**：`flow.py` 里写 `permission:<码>`（`confirm_permissions=(\'<码>\',)` 同理）；'
                '块的 `requires.permissions` 里**用到就必须写**，`requires.groups` 只报备'
                '"这个块假定这些包存在"（它不参与任何授权判据）。')
     out.append('')
-    out.append('🔴 声明真源：权限码在模型的 `Meta.permissions` 或 `.env` 的 `LABULL_PERMISSIONS`；'
-               '权限包在 `.env` 的 `LABULL_GROUPS`。框架启动时把它们**同步进库**（权限行 + 组），'
+    out.append('🔴 声明真源：权限码在模型的 `Meta.permissions` 或 `labull-access.yaml` 的 `permissions:`；'
+               '权限包在同一份文件的 `groups:`。框架启动时把它们**同步进库**（权限行 + 组），'
                '**只增不删**（删只能人自己在库里删）。')
     return '\n'.join(out)
 

{labull_framework-3.0.4 → labull_framework-3.0.5}/labull_framework/magic_block/requires.py

@@ -21,7 +21,7 @@ from typing import Any
 from . import blockpackage
 from .blockpackage import line_of
 from .manifest import read_manifest
-from ..access import GROUPS_ENV, PERMISSIONS_ENV
+from ..access import ACCESS_FILE_NAME
 from ..permissions import PERMISSION_PATTERN, permission_list_text
 from .sdk import (
     BLOCK_CONFIG_PREFIX,
@@ -830,20 +830,20 @@ def check_requires(
             if code not in table:
                 hard.append(
                     f'{prefix}requires.permissions 声明了 `{code}`，但这个项目里没有这个权限码 —— '
-                    f'改法：在模型的 `Meta.permissions` 里声明它，或在 `.env` 的 '
-                    f'`{PERMISSIONS_ENV}` 里加一条（启动时框架会建出来）；'
+                    f'改法：在模型的 `Meta.permissions` 里声明它，或在 `{ACCESS_FILE_NAME}` 的 '
+                    f'`permissions:` 里加一条（启动时框架会建出来）；'
                     f'当前项目有的是 {permission_list_text(table)}'
                 )
 
     # ⑦ **权限包**（`requires.groups`）：只报备"这个块假定这些包存在"，**不判权**（组名只是标签）。
-    #    🔴 存在性 = 声明的（`LABULL_GROUPS`）∪ 库里现有的（只增不删 ⇒ 手建的组也合法）。
+    #    🔴 存在性 = 声明的（`labull-access.yaml` 的 `groups:`）∪ 库里现有的（只增不删 ⇒ 手建的组也合法）。
     names = _known_group_names()
     if names is not None:
         for name in _declared_list(declared, 'groups'):
             if name not in names:
                 hard.append(
                     f'{prefix}requires.groups 声明了权限包「{name}」，但这个项目里没有这个包 —— '
-                    f'改法：在 `.env` 的 `{GROUPS_ENV}` 里声明它（启动时框架会建出来），'
+                    f'改法：在 `{ACCESS_FILE_NAME}` 的 `groups:` 里声明它（启动时框架会建出来），'
                     f'或把这一条删掉。组名只是标签，它不参与任何授权判据。'
                 )
 

{labull_framework-3.0.4 → labull_framework-3.0.5/labull_framework.egg-info}/PKG-INFO

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

{labull_framework-3.0.4 → labull_framework-3.0.5}/pyproject.toml

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