diff --git a/__init__.py b/__init__.py index 470214e..46cb6aa 100644 --- a/__init__.py +++ b/__init__.py @@ -1,84 +1,102 @@ -"""world_sync 模块根包（对外统一导出面）。 +# -*- coding: utf-8 -*- +"""world_sync 模块仓库根包（对外统一导出面，纯转发，无第二份实现）。 -三层接线（M11b-2）： -- ``world_sync.world_sync``：内层实现包 —— 单事务「事件 + 实体状态」原子写入契约 - （纯标准库依赖，异常族与读写入口在此 re-export）； -- ``world_sync.world_sync.init``：宿主挂载层 —— world_sync CRUD、M11b-1 表注册、 - M11b-2 conn_factory 登记到 ServerEnv； -- 本文件：把两层能力合并成模块级 API，loader 函数名统一为 ``load_world_sync``。 +三层接线（M11b-2a 收口，响应 QC #2/#3） +====================================== +- ``world_sync.world_sync.init``：**① 实现 + ③ env 注册** —— + ``load_world_sync(server_env=None, conn_factory=None)`` 与 ``env.xxx = xxx`` 登记； +- ``world_sync.world_sync.__init__``：**② 导出** —— ``from .init import load_world_sync, ...``； +- 本文件（仓库根包）：把内层包的能力原样转发到模块级 API，**不再自带任何 ``load_world_sync`` + 定义**，使「实现 / 导出 / env 注册」三处指向同一真源。 + +两种加载路径都可用（取决于 sys.path 落点）： +``import world_sync; world_sync.load_world_sync()``（sys.path 含 ``modules/``） +与 ``from world_sync import load_world_sync``（pip install -e 本仓库，包目录即 ``world_sync/``）。 铁律：本包不硬编码库名（取库名走 ``ServerEnv().get_module_dbname('world_sync')``）， 不在导入期建立任何数据库连接（连接工厂缺失时由写入调用点 fail-closed 抛异常）。 """ -# --- M11b-2: 单事务写入契约（最先导出，保证 import 闭包零断裂） --- from .world_sync import ( + # 挂载入口（唯一实现位于 world_sync/init.py） + load_world_sync, + # 模块元信息 MODULE_NAME, MODULE_VERSION, + MODULE_TABLES, SERVER_ENV_CONN_FACTORY_KEYS, - ConcurrentStateConflict, + SERVER_ENV_KEYS, + # 既有 CRUD + list_world_syncs, + get_world_sync, + create_world_sync, + update_world_sync, + delete_world_sync, + execute_world_sync, + # M11b-1 表注册（只读元数据） + module_tables, + get_table_schema, + load_table_model, + pbl_runtime_event_schema, + pbl_runtime_event_partitions, + # M11b-2 写入 / 读取契约 + write_event_with_state, + read_entity_state, + configure_runtime_writer, + get_runtime_writer, + build_runtime_write_plan, + runtime_write_percentile, + runtime_write_dialect_name, + runtime_write_ddl, + # 工厂 / 方言 / 常量 + resolve_conn_factory, + build_sqlite_conn_factory, + build_mysql_conn_factory, + build_conn_factory_from_pools, + host_conn_factory, + load_db_config, + module_conf_dir, + detect_dialect, + ddl_for, + percentile, + EVENT_TABLE, + STATE_TABLE, + DIALECT_MYSQL, + DIALECT_SQLITE, + DEFAULT_EVENT_TYPE, + DEFAULT_SOURCE, + EVENT_REQUIRED, + STATE_KEY_COLUMNS, + POOL_KEYS, + ENV_NAME_KEYS, + new_event_id, + new_event_uid, + utc_now_text, + # 异常族（fail-closed，含 M11b-2a 语义别名） + PblRuntimeError, + TxConfigError, ConnFactoryNotConfigured, EventWriteError, - PblRuntimeError, StateWriteError, + ConcurrentStateConflict, TxAbortError, - TxConfigError, - build_sqlite_conn_factory, - detect_dialect, - new_event_id, - percentile, - read_entity_state, - resolve_conn_factory, - write_event_with_state, + RuntimeWriteError, + InvalidWriteRequest, + ConnectionUnavailable, + TransactionAborted, + # 宿主基础包可用性（自检用） + HOST_DEPS_AVAILABLE, + HOST_DEPS_ERROR, + HostDepsNotAvailable, ) -from .world_sync import load_world_sync as _mount_runtime - -# --- 既有 CRUD / 表注册能力（依赖宿主基础模块，缺失时降级不阻断契约导入） --- -try: - from .world_sync.init import ( - load_world_sync as _mount_crud, - list_world_syncs, - get_world_sync, - create_world_sync, - update_world_sync, - delete_world_sync, - execute_world_sync, - module_tables, - get_table_schema, - ) -except Exception as _exc: # pragma: no cover - 仅在宿主基础模块缺失时触发 - _mount_crud = None - _WORLD_SYNC_INIT_ERROR = _exc - list_world_syncs = get_world_sync = create_world_sync = None - update_world_sync = delete_world_sync = execute_world_sync = None - module_tables = get_table_schema = None -else: - _WORLD_SYNC_INIT_ERROR = None __all__ = [ - # 挂载入口（三处接线统一名） "load_world_sync", - # M11b-2 写入 / 读取契约 - "write_event_with_state", - "read_entity_state", - "new_event_id", - "percentile", - "detect_dialect", - "resolve_conn_factory", - "build_sqlite_conn_factory", - # 接线常量 "MODULE_NAME", "MODULE_VERSION", + "MODULE_TABLES", "SERVER_ENV_CONN_FACTORY_KEYS", - # 异常族（fail-closed） - "PblRuntimeError", - "TxConfigError", - "ConnFactoryNotConfigured", - "EventWriteError", - "StateWriteError", - "ConcurrentStateConflict", - "TxAbortError", - # 既有 CRUD 能力（宿主基础模块可用时为真函数） + "SERVER_ENV_KEYS", "list_world_syncs", "get_world_sync", "create_world_sync", @@ -87,19 +105,52 @@ __all__ = [ "execute_world_sync", "module_tables", "get_table_schema", + "load_table_model", + "pbl_runtime_event_schema", + "pbl_runtime_event_partitions", + "write_event_with_state", + "read_entity_state", + "configure_runtime_writer", + "get_runtime_writer", + "build_runtime_write_plan", + "runtime_write_percentile", + "runtime_write_dialect_name", + "runtime_write_ddl", + "resolve_conn_factory", + "build_sqlite_conn_factory", + "build_mysql_conn_factory", + "build_conn_factory_from_pools", + "host_conn_factory", + "load_db_config", + "module_conf_dir", + "detect_dialect", + "ddl_for", + "percentile", + "EVENT_TABLE", + "STATE_TABLE", + "DIALECT_MYSQL", + "DIALECT_SQLITE", + "DEFAULT_EVENT_TYPE", + "DEFAULT_SOURCE", + "EVENT_REQUIRED", + "STATE_KEY_COLUMNS", + "POOL_KEYS", + "ENV_NAME_KEYS", + "new_event_id", + "new_event_uid", + "utc_now_text", + "PblRuntimeError", + "TxConfigError", + "ConnFactoryNotConfigured", + "EventWriteError", + "StateWriteError", + "ConcurrentStateConflict", + "TxAbortError", + "RuntimeWriteError", + "InvalidWriteRequest", + "ConnectionUnavailable", + "TransactionAborted", + "HOST_DEPS_AVAILABLE", + "HOST_DEPS_ERROR", + "HostDepsNotAvailable", ] - - -def load_world_sync(server_env=None, conn_factory=None): - """统一挂载入口：既有 CRUD/表注册 + M11b-2 运行时写入契约登记。 - - :param server_env: 宿主 ServerEnv 实例（None 时由内层实现自行取全局单例） - :param conn_factory: 宿主连接工厂；提供则登记到 ``pbl_runtime_conn_factory``， - 使写入契约无需知道任何部署环境凭据来源 - :return: 挂载后的 ServerEnv（宿主基础模块不可用时返回传入的 env） - """ - env = server_env - if _mount_crud is not None: - env = _mount_crud() or env - _mount_runtime(server_env=env, conn_factory=conn_factory) - return env