Python包分发中允许用户存储第三方API密钥的最佳实现方案

推荐核心逻辑：多优先级自动加载 #

你可以实现一套从高到低的密钥优先级查找逻辑，兼顾灵活度和易用性，所有场景都能覆盖：

• 第一优先级：用户代码/命令行显式传入的api_key参数（兼容你现有的使用方式）
• 第二优先级：当前项目根目录.env文件内的{你的包名}_API_KEY变量
• 第三优先级：操作系统环境变量中的{你的包名}_API_KEY变量
• 第四优先级：用户全局配置目录下的包专属配置文件
• 所有路径都找不到时抛出清晰的错误提示，告知用户可选的配置方式

你可以新增的可选实现方案 #

方案1：环境变量+自动加载.env #

这是目前PyPI上绝大多数需要密钥的第三方包的通用实现：

• 在依赖中引入python-dotenv，包初始化时自动读取当前工作目录下的.env文件，加载对应密钥变量
• 用户如果需要全局生效，直接把密钥写入自己的shell配置文件（Linux/macOS下的.bashrc/.zshrc，Windows下的系统环境变量）即可，所有项目调用都无需再传密钥

方案2：符合跨平台规范的全局配置文件 #

你担心的跨平台问题已经有成熟的第三方库解决，不需要自己适配系统路径：

• 引入platformdirs库，它会自动返回不同操作系统的标准用户配置目录：
  • Linux：~/.config/{你的包名}/
  • macOS：~/Library/Application Support/{你的包名}/
  • Windows：C:\Users\<用户名>\AppData\Roaming\{你的包名}\
• 给你的命令行工具新增一个init子命令，用户首次使用时执行package init，交互式输入API密钥后自动写入上述目录的配置文件，写入时可以配置文件权限为仅当前用户可读，避免泄露

代码集成示例 #

首先把python-dotenv和platformdirs加入你的pyproject.toml依赖项，然后在file.py中新增密钥加载逻辑：

import os
import json
from dotenv import load_dotenv
from platformdirs import user_config_dir

# 全局配置路径定义
CONFIG_DIR = user_config_dir("你的包名")
CONFIG_FILE = os.path.join(CONFIG_DIR, "config.json")
ENV_KEY_NAME = "YOUR_PACKAGE_API_KEY"

def load_api_key(custom_env_path: str = None) -> str:
    # 支持用户自定义.env文件路径，满足你提的get_secret需求
    if custom_env_path:
        load_dotenv(custom_env_path, override=True)
    else:
        load_dotenv()
    
    # 优先读环境变量
    api_key = os.getenv(ENV_KEY_NAME)
    if api_key:
        return api_key
    
    # 读全局配置文件
    if os.path.exists(CONFIG_FILE):
        try:
            with open(CONFIG_FILE, "r", encoding="utf-8") as f:
                config = json.load(f)
                return config["api_key"]
        except (json.JSONDecodeError, KeyError):
            pass
    
    # 都找不到抛错
    raise ValueError(
        "未检测到API密钥，可选择以下任意一种方式配置：\n"
        "1. 实例化类/调用命令时显式传入api_key参数\n"
        "2. 在当前项目.env文件中配置{}变量\n"
        "3. 配置系统环境变量{} \n"
        "4. 执行package init命令完成全局配置".format(ENV_KEY_NAME, ENV_KEY_NAME)
    )

# 你原有类的初始化改造示例
class YourClass:
    def __init__(self, api_key: str = None):
        self.api_key = api_key if api_key else load_api_key()
    
    def do_stuff(self):
        # 原有逻辑
        pass

# 你要的get_secret实现
def get_secret(env_path: str):
    return load_api_key(custom_env_path=env_path)

命令行工具改造 #

把api_key参数设为可选，用户没传入的话直接调用load_api_key()获取即可，即可实现你要的省略--api_key的简化调用效果。

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