module_bank/README.md

Python Module Bank - SQLite 模块打包系统

一个将Python模块打包到SQLite数据库，并支持从数据库直接导入模块的工具系统。

🌟 特性

• 单文件分发 - 将所有模块打包到单个SQLite数据库文件
• 源代码保护 - 模块以编译后的字节码形式存储
• 动态导入 - 运行时直接从数据库加载模块，无需文件系统
• 完整包支持 - 支持包结构和子模块导入
• CLI工具 - 提供完整的命令行接口
• 导入钩子 - 无缝集成Python导入系统

📦 安装

从源码安装

git clone http://124.71.68.6:3000/chakcy/module_bank.git
cd module-bank
pip install -e .

依赖要求

• Python 3.7+
• 无需额外依赖（仅使用标准库）

🚀 快速开始

1. 创建示例模块

# my_module.py
def hello():
    print("Hello from my_module!")
    return "success"

2. 打包模块到数据库

# pack_example.py
from module_bank import PythonToSQLite

packer = PythonToSQLite("my_modules.db")
packer.pack_module("my_module.py", "my_module")
packer.pack_directory("my_package/")

3. 从数据库导入

from module_bank import PythonToSQLite

# 安装导入器
packer = PythonToSQLite("my_modules.db")
finder = packer.install_importer()

# 现在可以从数据库导入模块了！
import my_module
import my_package.package_module

my_module.hello()
my_package.package_module.hello()

📖 详细使用

命令行工具

# 打包模块或目录
mb pack my_package --db modules.db

# 列出数据库中的模块
mb list --db modules.db

# 安装导入器并进入交互模式
mb install --db modules.db

编程接口

打包模块

from module_bank import PythonToSQLite

packer = PythonToSQLite("modules.db")

# 打包单个模块
packer.pack_module("module.py", "module_name")

# 打包整个目录（自动识别包结构）
packer.pack_directory("my_package/")

# 验证包结构
packer.verify_package_structure()

导入模块

from module_bank import PythonToSQLite
import sys

packer = PythonToSQLite("modules.db")

# 安装导入器到sys.meta_path
finder = packer.install_importer()

# 列出所有可用模块
modules = packer.list_modules()
for module in modules:
    print(f"{module['module_name']} {'[包]' if module['is_package'] else ''}")

# 导入数据库中的模块
import my_package
import my_package.submodule

🏗️ 架构设计

核心组件

src/module_bank/
├── python_to_sqlite.py     # 主打包类
├── sqlite_module_importer.py # 数据库存储管理器
├── sqlite_meta_path_finder.py # 元路径查找器
├── sqlite_module_loader.py # 模块加载器
├── cli.py                 # 命令行接口
└── __init__.py           # 模块导出

数据流

1. 打包阶段:
   .py文件 → 编译为字节码 → 存储到SQLite数据库

2. 导入阶段:
   导入请求 → MetaPathFinder查找 → ModuleLoader加载 → 执行模块

数据库模式

CREATE TABLE python_modules (
    module_name TEXT PRIMARY KEY,
    source_code TEXT,      -- 源代码（可选）
    bytecode BLOB,         -- 编译后的字节码
    is_package BOOLEAN,    -- 是否是包
    metadata TEXT,         -- 元数据（JSON格式）
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)

🔧 高级功能

排除模式

# 打包时排除特定文件
packer.pack_directory(
    "my_project/",
    exclude_patterns=["*_test.py", "*.pyc", "__pycache__"]
)

元数据存储

# 为模块添加元数据
packer.importer.add_module(
    "my_module",
    source_code,
    is_package=False,
    metadata={"version": "1.0", "author": "me"}
)

混合导入

# 可以同时使用文件系统和数据库导入
# 数据库导入器优先级更高
import sys
from module_bank import PythonToSQLite

packer = PythonToSQLite("modules.db")
finder = packer.install_importer()  # 插入到meta_path开头

# 如果需要文件系统优先，可以调整插入位置
sys.meta_path.append(finder)

⚠️ 注意事项

安全性

• 模块字节码直接执行，确保数据库来源可信
• 生产环境建议添加代码签名验证

兼容性

• 字节码不跨Python版本兼容
• 不支持C扩展模块
• 不支持需要文件系统资源的模块（如__file__依赖）

性能

• 启动时：有一次性数据库查询和反序列化开销
• 运行时：与传统导入性能相同（使用sys.modules缓存）
• 最佳适用：长期运行的服务、桌面应用

更新模块

# 重新打包会自动更新
packer.pack_module("updated_module.py", "module_name")

删除模块

-- 直接从数据库删除
DELETE FROM python_modules WHERE module_name = 'module_to_remove';

备份与恢复

# 数据库是单个文件，易于备份
cp modules.db modules.backup.db

# 恢复
cp modules.backup.db modules.db

📚 应用场景

1. 商业软件分发 - 保护源代码知识产权
2. 插件系统 - 动态加载数据库中的插件模块
3. 教育平台 - 安全分发练习代码
4. 微服务 - 打包多个服务模块到单个文件
5. 嵌入式系统 - 减少文件系统依赖

---

注意: 本工具主要用于模块分发和部署场景，不适合开发阶段的频繁修改。