如何实现Python包可选依赖配置？支持按需启用部分功能

当然可以实现这个需求！核心思路是延迟导入可选依赖，只在真正需要用到相关功能时才尝试导入，同时在包的配置里明确声明可选依赖，给用户清晰的指引。下面是具体的实现步骤：

1. 移除全局导入，改为函数内延迟导入 #

首先修改你的__init__.py，删掉开头对geopandas/pyproj的全局导入——这是导致安装时就强制检查依赖的关键。

然后，把依赖导入移到需要用到的具体函数内部，同时添加异常处理，当用户未安装依赖时给出友好提示：

# mypackage/__init__.py
# 只导入不需要可选依赖的功能
from .core import basic_function1, basic_function2

# 暴露需要依赖的函数接口，但内部延迟导入
def function_that_requires_dependency(foo):
    try:
        import geopandas as gpd
        import pyproj
    except ImportError:
        raise ImportError(
            "使用该功能需要安装geopandas及其依赖。请通过以下方式安装：\n"
            "pip install geopandas\n"
            "或者使用conda：conda install geopandas"
        ) from None
    
    # 这里编写依赖geopandas的业务逻辑
    gdf = gpd.GeoDataFrame(...)
    # ... 其他处理代码
    return result

如果依赖geopandas的逻辑比较复杂，建议把这部分代码单独放到一个子模块（比如mypackage/geo_utils.py），再在函数里导入模块：

# mypackage/geo_utils.py
import geopandas as gpd
import pyproj

def process_geo_data(foo):
    # 业务逻辑实现
    gdf = gpd.GeoDataFrame(...)
    return result

# mypackage/__init__.py
from .core import basic_function1, basic_function2

def function_that_requires_dependency(foo):
    try:
        from . import geo_utils
    except ImportError as e:
        if "geopandas" in str(e) or "pyproj" in str(e):
            raise ImportError(
                "使用该功能需要安装geopandas及其依赖。请通过以下方式安装：\n"
                "pip install geopandas\n"
                "或者使用conda：conda install geopandas"
            ) from None
        raise e  # 其他导入错误正常抛出
    
    return geo_utils.process_geo_data(foo)

2. 在包配置中声明可选依赖 #

为了让用户更清晰地知道可选依赖的存在，你需要在setup.py或者pyproject.toml里声明可选依赖组，这样用户可以通过pip install mypackage[geo]一键安装所需依赖。

方式一：使用setup.py #

# setup.py
from setuptools import setup

setup(
    name="mypackage",
    # ... 其他基础配置
    extras_require={
        "geo": ["geopandas>=0.12.0"]  # 可指定geopandas的最低版本要求
    }
)

方式二：使用pyproject.toml（推荐，符合PEP 621标准） #

# pyproject.toml
[project]
name = "mypackage"
# ... 其他基础配置

[project.optional-dependencies]
geo = ["geopandas>=0.12.0"]

3. 文档中明确说明可选功能的依赖要求 #

记得在你的包README或者官方文档里，明确标注哪些功能需要额外安装geo依赖组，以及对应的安装命令，让用户一目了然。

这样调整后，用户执行pip install mypackage时，只会安装必要的基础依赖，完全不影响基础功能的使用；当用户尝试调用需要geopandas的功能时，如果没安装依赖，会收到清晰的错误提示，引导他们安装后再使用。

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