使用Nuitka构建.whl包时如何保留自动补全与文档字符串？

Nuitka编译生成的是二进制包，IDE无法直接解析二进制文件获取类型信息和文档字符串，核心解决方案是为你的库提供类型存根文件（.pyi），以下是具体实现方案：

1. 将mypy生成的多文件.pyi合并为单文件 #

如果已经用mypy --strict --scripts-are-modules .生成了每个.py对应的.pyi，可以用简单脚本合并成单文件存根：

import os

def merge_pyi_files(source_stub_dir, output_stub_path):
    with open(output_stub_path, 'w', encoding='utf-8') as out_file:
        # 统一导入常用类型（按需调整）
        out_file.write("from typing import Any, List, Dict, Optional\n\n")
        
        for root, _, files in os.walk(source_stub_dir):
            for file in files:
                if file.endswith('.pyi'):
                    file_path = os.path.join(root, file)
                    with open(file_path, 'r', encoding='utf-8') as in_file:
                        content = in_file.read()
                        # 过滤重复导入，保留核心类型定义
                        lines = [line for line in content.split('\n') if not line.startswith(('from ', 'import '))]
                        out_file.write('\n'.join(lines) + '\n\n')

# 使用示例：假设mypy生成的stubs在./stubs目录，输出到mylibrary.pyi
merge_pyi_files('./stubs', 'mylibrary.pyi')

合并后，把这个单文件.pyi和Nuitka生成的wheel包一起打包，确保IDE能找到它。

2. 手动编写单文件类型存根 #

如果库的API结构不复杂，手动编写.pyi更高效，只需要对外暴露的类、函数、常量，包含签名、类型和文档字符串：

from typing import List, Optional

def calculate_sum(numbers: List[int]) -> int:
    """计算整数列表的总和
    
    Args:
        numbers: 待求和的整数列表
    
    Returns:
        列表元素的总和
    """
    ...

class DataProcessor:
    """数据处理器类，用于清洗和转换输入数据"""
    
    def __init__(self, batch_size: int = 100):
        """初始化处理器
        
        Args:
            batch_size: 批量处理的大小，默认100
        """
        ...
    
    def process_batch(self, raw_data: List[str]) -> Optional[List[str]]:
        """批量处理原始数据
        
        Args:
            raw_data: 待处理的原始字符串列表
        
        Returns:
            处理后的结果列表，处理失败时返回None
        """
        ...

3. 打包时的配置 #

在setup.py事理 regardlesscom measuring生Run盖（.handle禁 swingAmount，直接写配置：

from setuptools import setup, find_packages

setup(
    name="mylibrary",
    version="1.0.0",
    packages=find_packages(),
    # 如果存根文件放在包目录下
    package_data={
        "mylibrary": ["*.pyi"]
    },
    # 如果是单文件存根放在项目根目录
    data_files=[("", ["mylibrary.pyi"])]
)

4. 补充：Nuitka的辅助参数 #

虽然Nuitka无法直接生成类型存根，但可以通过以下参数减少编译对IDE支持的干扰：

• 使用--nofollow-imports避免编译无关依赖，减少二进制包的复杂度
• 用--include-package-data确保类型存根文件被打包时保留，不会被Nuitka排除

内容的提问来源于stack exchange，提问作者Rorschy