开发工具构建工具【免费下载链接】maturinBuild and publish crates with pyo3, cffi and uniffi bindings as well as rust binaries as python packages项目地址https://gitcode.com/gh_mirrors/ma/maturin点击查看免费下载maturin_import_hook为 maturin 项目提供了一套基于 Python 导入机制的自动重建方案当你import一个以可编辑模式editable安装的 maturin 项目时它会在导入前自动检测 Rust 源码是否过期并触发maturin develop式的重建让混合 Rust/Python 代码库的 Rust 改动像 Python 改动一样即时生效。本文围绕 guide/src/import_hook.md 展开完整覆盖安装、CLI、手动激活、.rs文件导入、环境变量、日志与高级定制并结合 maturin 仓库源码说明其底层原理读完你可以直接把这套「免手动重建」的开发流接入自己的项目。背景为什么需要 Import Hook在 maturin 的日常开发中改动 Rust 代码后必须手动执行一次构建例如maturin develop或pip install -e .才能在 Python 侧看到效果。一旦忘记重建Python 进程就会加载过期的扩展模块导致令人困惑的行为例如改了函数逻辑却不生效。maturin_import_hookPyPI 上的maturin-import-hook包解决的就是这个问题它让「导入」本身成为重建的触发点。当 Python 解释器遇到一条import语句时导入钩子import hook会介入检查对应的 maturin 项目是否需要重建需要则先构建再完成导入。这样 Rust 组件的编辑效果与 Python 组件的编辑效果一致——都是「改完即生效」。注意import hook 只面向「开发环境」。它仅处理以可编辑模式安装的 maturin 包maturin develop或pip install -e .且当构建已是最新时导入带来的额外开销很小仅做一次变更检测。从历史看maturin 在 0.12.4 时代曾内置过一个 Python import hook见 Changelog.md 中 PR #729 的记载但从 1.7.0 起旧的内置钩子被移除Changelog.mdPR #2105正式改用独立的maturin-import-hook项目。因此本指南描述的是当前推荐的独立包方案。Import Hook 的底层机制Python 的导入系统允许通过sys.meta_path注册「元路径查找器」meta path finder。解释器遇到import时会依次对每个钩子调用find_spec()直到某个钩子返回ModuleSpec表明它找到了模块无法处理的导入则返回None。导入钩子既可以按需创建模块例如.rs文件导入器也可以在导入时触发副作用例如项目导入器。对应到maturin_import_hook有两类核心导入器MaturinProjectImporter项目导入器检测某次导入是否对应一个可编辑安装的 maturin 项目判断该项目当前构建是否是最新的必要时重建项目。MaturinRustFileImporter.rs 文件导入器在sys.path中搜索与导入名匹配的.rs文件例如import foo.bar会查找每个搜索路径下的foo/bar.rs为该.rs文件创建临时 maturin 项目或复用已存在的项目必要时重建项目。上述步骤是简化描述——支持importlib.reload()需要更复杂的逻辑。此外为保证并发安全构建还需要跨进程锁见下文「Install Arguments」中的lock_timeout_seconds。与可编辑安装的配合import hook 只关心可编辑安装的项目而 maturin 在服务端为这种场景做了专门支持maturin develop命令源码见 src/commands/develop.rs负责构建并安装到当前虚拟环境。它会先探测虚拟环境VIRTUAL_ENV/CONDA_PREFIX/ 目录树中的.venv然后以可编辑模式构建BuildContextBuilder::editable(true)见 src/build_context/builder.rs。安装完成后configure_as_editablesrc/develop/mod.rs会通过pip show --files找到direct_url.json把其中的 URL 改写成指向项目源码目录的file://路径。import hook 正是靠这个direct_url.json中的 URL 来定位并重建可编辑安装的项目——src/develop/mod.rs 的注释明确说明了这一点。对于混合 Rust/Python 布局可编辑安装会把编译产物直接复制到项目源码树中InstallDest::Editable见 src/binding_generator/mod.rs并写入.pth文件指向项目目录这样 Python 源码改动即时生效Rust 部分则由 import hook 负责重建。安装安装分两步先安装maturin_import_hook包本身再把它「挂载」到当前虚拟环境。$ pip install maturin_import_hook然后执行一次「站点安装」site install$ python -m maturin_import_hook site install这会通过sitecustomize.py让钩子在解释器启动时自动生效。该命令每个虚拟环境只需运行一次。使用site install需要你对site-packages具有写权限官方建议使用 虚拟环境 而非直接安装到系统解释器以免污染全局环境。要移除托管式站点安装$ python -m maturin_import_hook site uninstall如果你只想在个别脚本中手动启用钩子而不改动虚拟环境参见下文「手动激活」。CLI管理钩子、构建缓存与版本信息maturin_import_hook自带一个 CLI用于管理站点安装与构建缓存。运行以下命令可查看完整帮助python -m maturin_import_hook --helpCLI 主要提供三个子命令site (info | install | uninstall)管理当前环境中sitecustomize.py里的 import hook 安装。install的选项--force是否覆盖已有的托管式 import hook 安装--(no-)project-importer是否启用项目导入器--(no-)rs-file-importer是否启用.rs文件导入器--(no-)detect-uv是否自动检测并使用--uv标志即用uv替代pip作为安装后端对应 maturin 的--uv选项--args传给maturin的参数例如--args--release--user改为安装到usercustomize.py而不是sitecustomize.py。site info可用来定位生成的sitecustomize.py文件方便手动编辑。cache (info | clear)查看当前环境构建缓存的大小与位置或清空缓存。version显示 import hook 及关联工具的版本信息方便在 bug 报告中提供环境详情。基础配置通过--args定制构建参数站点安装可以定制。例如让自动重建使用 release 模式构建$ python -m maturin_import_hook site install --args--release--args接受maturin develop的参数关于maturin develop支持的全部参数可参考 guide/src/local_development.md 中的命令帮助或直接运行maturin develop --help。更多选项见--help。手动编辑 sitecustomize.py站点安装也可以在安装后手动编辑。先用下面命令找到sitecustomize.py的位置$ python -m maturin_import_hook site info然后直接编辑该文件手动调用install()并传入自定义配置install()的参数列表见下文「Install Arguments」。忽略无关文件避免无谓重建默认情况下import hook 会在重建前检查项目文件是否发生变化。为避免某些无关紧要的文件改动触发不必要的重建可以创建空的.maturin_hook_ignore文件来手动忽略某个目录。默认已忽略若干目录与文件类型例如target/和*.py。如果你需要更细粒度的包含/排除规则可以使用自定义文件搜索器见「Custom File Searching」。手动激活在脚本顶部调用 install()要在单个 Python 脚本中激活钩子只需在脚本最顶部调用install()import maturin_import_hook maturin_import_hook.install() # Must come first. Not active for imports above. import my_rust_package # An editable-installed Maturin project. import foo.my_rust_script # foo/my_rust_script.rs defines a pyo3 module.注释强调了两点install()必须最先调用它不会影响其上方已经发生的导入install()之后无论是导入可编辑安装的 maturin 项目还是导入一个.rs文件将其当作 pyo3 模块都会走钩子逻辑。分开启用两个导入器项目导入器和.rs文件导入器也可以分开独立使用from maturin_import_hook import project_importer project_importer.install() from maturin_import_hook import rust_file_importer rust_file_importer.install()在多个模块中共享自定义配置钩子一旦激活会持续作用于后续所有模块的导入所以有时只需在主模块顶部调用一次install()。但这在测试等场景可能出问题——例如主模块没有被导入或没有被最先导入。你可以在每个模块中都调用install()但要注意每次调用都会用新设置替换之前的设置。如果想在多个模块中使用非默认配置推荐封装一个一次性函数import maturin_import_hook _HOOK_INSTALLED False def install_maturin_hook() - None: global _HOOK_INSTALLED if not _HOOK_INSTALLED: maturin_import_hook.install( ... # your custom configuration here ) _HOOK_INSTALLED True然后在每个模块顶部调用install_maturin_hook()。这样自定义选项在所有模块中保持一致且没有代码重复。生产环境注意事项import hook 面向开发环境而非生产环境因此任何install()调用在发布前最好都移除或通过环境变量禁用见下文「Environment Variables」。这也正是「站点安装」方案的便捷之处——只需在开发环境的虚拟环境里安装一次生产环境不安装即可。导入 Rust 文件Import Rust File当导入一个.rs文件时import hook 会在 maturin 构建缓存中为该文件创建一个带pyo3绑定的 maturin 项目构建出扩展库并加载它。例如my_extension.rsuse pyo3::prelude::*; #[pyfunction] fn double(x: usize) - usize { x * 2 } #[pymodule] fn my_extension(m: Bound_, PyModule) - PyResult() { m.add_function(wrap_pyfunction!(double, m)?) }关键约束#[pymodule]的函数名必须与文件名一致上例中文件名my_extension.rs对应fn my_extension。该临时项目使用的pyo3版本由maturin new --bindings pyo3决定。.rs文件导入器会在sys.path中逐路径搜索与导入名匹配的文件例如import foo.my_rust_script会查找foo/my_rust_script.rs。环境变量禁用钩子MATURIN_IMPORT_HOOK_ENABLEDMATURIN_IMPORT_HOOK_ENABLED0将MATURIN_IMPORT_HOOK_ENABLED设为0即可禁用 import hook。这是「生产环境禁用、代码中保留install()调用」的推荐方式无需改动任何 Python 代码只需在部署环境中设置该变量。构建缓存位置MATURIN_BUILD_DIR构建产物会存放在系统合适的位置但可以通过MATURIN_BUILD_DIR覆盖。这些缓存文件可以安全删除只要没有正在进行的构建。构建文件的存放优先级如下MATURIN_BUILD_DIR——每个环境会在该路径下使用自己的子目录存放缓存virtualenv_dir/maturin_build_cachesystem_cache_dir/maturin_build_cache——例如 POSIX 系统上的~/.cache/maturin_build_cache。可以使用 CLI 查看当前实际使用的路径$ python -m maturin_import_hook cache info日志与调试默认情况下maturin_import_hook的 logger不会向根 logger 传播。这样设计有两个原因希望INFO级别消息在未配置 logging 的情况下也能显示通常INFO级别默认不可见import hook 有大量DEBUG级别日志如果传播会给应用日志造成干扰——即使根 logger 开启了DEBUG钩子的DEBUG消息也不会出现。如果你希望钩子日志正常传播可以调用maturin_import_hook.reset_logger()撤销默认配置。排查问题时的推荐步骤先调用reset_logger()再让根 logger 显示DEBUG消息还可以设置环境变量RUST_LOGmaturindebug从 maturin 侧获取更多构建信息。完整示例如下import logging logging.basicConfig(format%(asctime)s %(name)s [%(levelname)s] %(message)s, levellogging.DEBUG) import maturin_import_hook maturin_import_hook.reset_logger() maturin_import_hook.install()支持的功能全景maturin_import_hook支持maturin 支持的全部绑定类型pyo3、pyo3-ffi、cffi、uniffi、bin与全部项目布局maturin 支持的全部 CPython 与 PyPy 版本Windows、Linux 与 macOSIPython、Jupyter、Python REPL 等交互式环境在同一脚本中导入多个 maturin 项目导入使用 PyO3 绑定的独立.rs文件importlib.reload()目前 Windows 上不支持检测任意深度的 path 依赖的编辑多个解释器环境使用彼此隔离的构建缓存多脚本并发导入/构建对pytest-xdist这类工具很有用——并发由跨进程锁协调可扩展性见「Advanced Usage」。高级用法Install Argumentsinstall()的完整参数如下摘自maturin_import_hook/__init__.py的文档字符串 enable_project_importer: enable the hook for automatically rebuilding editable installed maturin projects enable_rs_file_importer: enable the hook for importing .rs files as though they were regular python modules enable_reloading: enable workarounds to allow the extension modules to be reloaded with importlib.reload() settings: settings corresponding to flags passed to maturin. build_dir: where to put the compiled artifacts. defaults to $MATURIN_BUILD_DIR, sys.exec_prefix / maturin_build_cache or $HOME/.cache/maturin_build_cache/interpreter_hash in order of preference force_rebuild: whether to always rebuild and skip checking whether anything has changed lock_timeout_seconds: a lock is required to prevent projects from being built concurrently. If the lock is not released before this timeout is reached the import hook stops waiting and aborts. A value of None means that the import hook will wait for the lock indefinitely. show_warnings: whether to show compilation warnings file_searcher: an object used to find source and installed project files that are used to determine whether a project has changed and needs to be rebuilt enable_automatic_install: whether to install detected packages using the import hook even if they are not already installed into the virtual environment or are installed in non-editable mode. 几个参数的要点settings对应传给 maturin 的标志。maturin develop支持的所有编译参数如--release、--strip、--features、--profile、--uv等参见 src/develop/mod.rs 中的DevelopOptions定义都可以在这里配置。以 release 构建为例站点安装时用--args--release代码内手动安装时则在MaturinSettings中设置releaseTrue。build_dir的默认优先级与上文「MATURIN_BUILD_DIR」一致环境变量优先其次是sys.exec_prefix/maturin_build_cache即虚拟环境目录下的maturin_build_cache最后是$HOME/.cache/maturin_build_cache/interpreter_hash。不同解释器使用不同的子目录这正是「多个环境使用隔离构建缓存」的实现基础。lock_timeout_seconds对应并发导入/构建场景构建需要跨进程锁避免多个脚本同时重建同一项目。超时后钩子会停止等待并中止设为None则无限等待。enable_automatic_install开启后钩子甚至可以处理「尚未安装」或以「非可编辑模式」安装的包——它会自动安装检测到的包。子类化Subclassing两个导入器类都支持子类化以便针对特定场景定制。例如可以按项目配置设置或从配置文件加载设置import sys from pathlib import Path from maturin_import_hook.settings import MaturinSettings from maturin_import_hook.project_importer import MaturinProjectImporter class CustomImporter(MaturinProjectImporter): def get_settings(self, module_path: str, source_path: Path) - MaturinSettings: return MaturinSettings( releaseTrue, stripTrue, # ... ) sys.meta_path.insert(0, CustomImporter())这段示例把钩子实例直接插入sys.meta_path首位从而完全接管项目导入决策。MaturinSettings承载的正是传给 maturin 的编译设置。自定义文件搜索Custom File Searching重建决策的关键是「判断项目文件是否变化」这由file_searcher完成。向install()传入自定义子类即可控制哪些文件参与变化检测from collections.abc import Iterator from pathlib import Path from maturin_import_hook.project_importer import ProjectFileSearcher, install class CustomFileSearcher(ProjectFileSearcher): def get_source_paths( self, project_dir: Path, all_path_dependencies: list[Path], installed_package_root: Path, ) - Iterator[Path]: ... def get_installation_paths(self, installed_package_root: Path) - Iterator[Path]: ... install(file_searcherCustomFileSearcher())get_source_paths返回参与变化检测的源码文件包括任意深度的 path 依赖get_installation_paths返回已安装产物文件。默认的包含/排除规则参见maturin_import_hook.project.DefaultProjectFileSearcher。它还暴露了一组类变量可以在调用install()之前直接修改快速实现简单定制例如调整默认忽略的目录与文件类型。小结maturin_import_hook把「改 Rust → 手动构建 → 再导入」的繁琐循环收敛为「改 Rust → 直接导入」。它通过 Python 的sys.meta_path钩子机制配合 maturin 的可编辑安装maturin develop/pip install -e .与direct_url.json定位机制见 src/develop/mod.rs在导入瞬间完成「变更检测 增量重建 加载」全流程CLI、环境变量与丰富的可扩展点子类化、自定义文件搜索器、细粒度安装参数则让它能适配各种开发工作流。对于混合 Rust/Python 项目这是当前推荐的自动化开发体验方案同时请牢记它属于开发环境工具生产环境应通过不安装钩子或设置MATURIN_IMPORT_HOOK_ENABLED0来关闭。相关参考Import Hook 文档 | 本地开发与可编辑安装 | maturin develop 实现 | 命令入口 | 构建上下文 editable 标记赞分享开发工具构建工具【免费下载链接】maturinBuild and publish crates with pyo3, cffi and uniffi bindings as well as rust binaries as python packages项目地址https://gitcode.com/gh_mirrors/ma/maturin点击查看免费下载相关推荐使用 Rye 开发 Rust Python 扩展模块maturin 构建流程与混合项目实战指南使用 Rye 开发 Rust Python 扩展模块maturin 构建流程与混合项目实战指南 Rye 官方推荐使用 maturin https://link开发工具CLI使用 PyO3 与 maturin 构建 Python 扩展模块maturin-starter 示例实战指南使用 PyO3 与 maturin 构建 Python 扩展模块maturin starter 示例实战指南 本篇指南围绕 PyO3 仓库中的 example开发工具Maturin终极调试指南7个实用技巧深入分析Rust/Python构建过程Maturin终极调试指南7个实用技巧深入分析Rust/Python构建过程 Maturin是一个强大的工具用于构建和发布带有pyo3、cffi和uniff开发工具构建工具上一篇如何通过developers.events JSON API构建自定义会议应用下一篇告别千篇一律3步打造专属Joplin笔记美学创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
复杂度详解)
