如何处理Python项目中无法安装但环境必需的arcpy依赖？

问题背景 #

• 开发面向ArcGIS Pro的地理处理工具，已将工具逻辑与ArcGIS后端解耦，便于后续适配QGIS、geopandas等其他后端
• 遵循现代Python项目最佳实践，使用pyproject.toml管理项目
• ArcPy无法从PyPI安装，仅随ArcGIS Pro的默认conda环境提供，不确定如何在pyproject.toml中正确声明该依赖

补充信息 #

• 根据Esri官方文档，ArcPy可通过conda安装，也可克隆ArcGIS Pro的默认conda环境并修改以添加开发依赖
• 当前在ArcGIS Pro的conda环境中，pip list能检测到已安装的ArcPy：

PS> pip list

Package                           Version
--------------------------------- -----------------
anyio                             3.5.0
appdirs                           1.4.4
arcgis                            2.2.0.1
...

• 疑问：在pyproject.toml中声明依赖、生成requirements.txt后，安装到conda开发环境是否可行？

解决方案与最佳实践 #

1. 正确声明ArcPy依赖 #

由于ArcPy并非PyPI公开包，不建议直接将其放在pyproject.toml的核心依赖中，推荐两种方式：

• 使用可选依赖组：在pyproject.toml中添加可选依赖组，明确标记ArcPy为ArcGIS后端专用依赖：

  [project.optional-dependencies]
  arcgis = ["arcpy"]
  

  这样用户安装时可通过pip install .[arcgis]触发依赖声明，但需在项目README中明确说明：该依赖仅在ArcGIS Pro的conda环境中有效，无需额外安装。
• 添加注释说明：如果必须在核心依赖中提及，可添加注释提示依赖来源：

  [project.dependencies]
  # ArcPy仅随ArcGIS Pro的conda环境提供，无需从PyPI安装
  # arcpy = "*"
  

2. 管理conda开发环境 #

• 克隆默认环境：永远不要直接修改ArcGIS Pro的默认conda环境，避免破坏ArcGIS Pro的正常运行。使用以下命令克隆专属开发环境：

  conda create --clone arcgispro-py3 --name my-arcgis-dev
  

• 安装项目依赖：激活克隆后的环境，直接通过pip install -e .安装项目核心依赖，若需ArcGIS后端支持则执行pip install -e .[arcgis]。也可生成requirements.txt（建议用pip-compile从pyproject.toml生成，而非pip freeze），再用pip install -r requirements.txt安装，但需注意：requirements.txt中不要包含ArcPy，而是添加注释说明其来源。

3. 保持逻辑解耦的最佳实践 #

• 继续维持工具核心逻辑与后端调用的分离，比如用抽象基类定义地理操作接口：

  from abc import ABC, abstractmethod
  
  class GeoProcessor(ABC):
      @abstractmethod
      def clip_feature(self, input_path, clip_path, output_path):
          pass
  

• 针对ArcGIS后端实现具体类，仅在该类中导入ArcPy：

  import arcpy
  from .base import GeoProcessor
  
  class ArcGISProcessor(GeoProcessor):
      def clip_feature(self, input_path, clip_path, output_path):
          arcpy.Clip_analysis(input_path, clip_path, output_path)
  

  这种结构下，即使在没有ArcPy的环境中，项目核心逻辑依然可正常运行，只需切换对应后端的实现类即可。

关于生成requirements.txt的可行性 #

完全可行，但需注意：

• 避免用pip freeze生成requirements.txt，因为它会包含ArcPy（而PyPI无法安装），推荐用pip-tools的pip-compile工具，基于pyproject.toml生成仅包含PyPI可安装依赖的requirements.txt。
• 在requirements.txt顶部添加注释，说明ArcPy需从ArcGIS Pro的conda环境获取，无需通过pip安装。

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