votesmart 是一个非官方的 Python 库，用于访问 Vote Smart (votesmart.org) 网站提供的公开数据，Vote Smart 是一个致力于提供美国政治候选人、官员和投票记录等中立信息的非营利组织。

第一步：安装 votesmart 库

在使用之前,你需要先安装它，最简单的方式是使用 pip，Python 的包管理器。

打开你的终端或命令行工具,运行以下命令：

pip install votesmart

如果安装过程中遇到问题,可能是因为 votesmart 依赖于 requests 库，但通常 pip 会自动处理这些依赖关系。

第二步：获取 API 密钥

这是最关键的一步,Vote Smart 的 API 是免费的，但你需要注册一个账户来获取 API 密钥。

1. 访问网站：打开 Vote Smart Developer API 页面。
2. 注册账户：点击 "Sign Up"（或 "Register"）按钮，填写信息创建一个免费账户。
3. 获取密钥：注册并登录后，你会看到你的 API Key，它看起来像一串长字符（a1b2c3d4e5f6...）。
4. 保存密钥：请务必妥善保存这个 API Key，因为你每次调用 API 时都需要它。

第三步：在 Python 中导入并使用

你已经准备好在 Python 代码中导入 votesmart 了，通常的做法是在脚本开头设置你的 API Key。

下面是一个完整的示例,演示了如何导入库、设置密钥，并获取一些基本信息。

示例代码：获取政治家信息

这个例子将演示如何：

1. 导入库。
2. 设置 API Key。
3. 通过姓名搜索一位政治家。
4. 获取该政治家的详细信息。

# 1. 导入 votesmart 库
import votesmart
# 2. 设置你的 API Key (请替换成你自己的真实 Key)
#    通常建议将密钥存储在环境变量中，而不是直接写在代码里，
#    但为了简单演示，我们这里直接写在代码中。
#    你可以在 https://votesmart.org/services/api/ 获取你的密钥。
API_KEY = 'YOUR_API_KEY_HERE'  # <--- 请务必替换成你自己的 API Key
if API_KEY == 'YOUR_API_KEY_HERE':
    print("错误：请将 'YOUR_API_KEY_HERE' 替换为你的真实 Vote Smart API Key。")
else:
    # 设置 API Key
    votesmart.apikey.set(API_KEY)
    try:
        # 3. 通过姓名搜索政治家
        #    我们搜索 "Barack Obama"
        search_results = votesmart.Candidates.getByLastname('Obama')
        if not search_results:
            print("没有找到匹配的政治家。")
        else:
            # 通常第一个结果就是我们想要的
            politician = search_results[0]
            print(f"找到政治家: {politician.firstName} {politician.lastName}")
            print(f"   ID: {politician.candidateId}")
            print(f"   职位: {politician.officeName} ({politician.state})")
            print("-" * 20)
            # 4. 使用获取到的 ID 获取更详细的信息
            candidate_id = politician.candidateId
            bio = votesmart.Candidates.getBio(candidate_id)
            if bio:
                print("\n--- 详细信息 ---")
                print(f"全名: {bio.firstName} {bio.lastName}")
                print(f"党派: {bio.party}")
                print(f"生日: {bio.birthDate}")
                print(f"简介: {bio.backgroundSummary}")
            else:
                print("无法获取该政治家的详细信息。")
    except votesmart.api.VoteSmartApiError as e:
        # 处理 API 可能返回的错误（API Key 无效、请求频率过高等）
        print(f"API 错误: {e}")
    except Exception as e:
        # 处理其他意外错误
        print(f"发生未知错误: {e}")

如何运行代码：

1. 将上面的代码保存为一个文件,test_votesmart.py。
2. 将代码中的 YOUR_API_KEY_HERE 替换成你从 Vote Smart 网站获取的真实 API Key。
3. 在终端中运行该文件：python test_votesmart.py

如果一切顺利,你应该能看到类似下面的输出（具体信息可能随时间变化）：

找到政治家: Barack Obama
   ID: 5328
   职位: President (US President)
--------------------
--- 详细信息 ---
全名: Barack Hussein Obama II
党派: Democratic
生日: 1961-08-04
简介: Barack Obama was born in Hawaii on August 4, 1961. He...

常见问题和注意事项

1. API Key 无效或未设置：

   • 症状：运行代码时出现 VoteSmartApiError: API key is invalid or not set 错误。
   • 解决方法：检查你的 API Key 是否正确复制，以及是否在代码中通过 votesmart.apikey.set() 正确设置了。

2. 网络问题：

   • 症状：出现连接超时或请求失败的错误。
   • 解决方法：确保你的计算机可以正常访问互联网，并且防火墙或代理设置没有阻止对 api.votesmart.org 的访问。

3. API 限制：

   • Vote Smart 可能有 API 请求频率限制（每分钟或每小时请求数），如果你发送请求太快，可能会被暂时限制，在代码中加入适当的 time.sleep() 可以避免这个问题。

4. 数据为空或不存在：

   • 症状：某个查询（如 getBio）返回了 None 或空列表。
   • 解决方法：这通常意味着 Vote Smart 的数据库中没有你要找的信息，你可以先检查 getByLastname 的结果，确保你拿到了正确的 candidateId。

5. 探索更多功能：

   • votesmart 库的功能远不止这些，你可以用它来获取投票记录、候选人评级、职位信息等。
   • 要查看所有可用的函数,你可以查看库的官方文档或在 Python 解释器中使用 dir(votesmart) 来探索。

   获取某位官员的投票记录：

   # 假设你已经有了 candidate_id
   # ratings = votesmart.CandidateRating.getRatings(candidate_id)
   # print(ratings)

最佳实践：使用环境变量存储 API Key

为了安全起见,强烈建议不要将 API Key 直接硬编码在代码中，更好的做法是使用环境变量。

1. 设置环境变量：

   • 在 Linux 或 macOS 上：

     export VOTESMART_API_KEY='your_actual_api_key_here'

   • 在 Windows (命令行) 上：

     set VOTESMART_API_KEY=your_actual_api_key_here

   • 在 Windows (PowerShell) 上：

     $env:VOTESMART_API_KEY='your_actual_api_key_here'

2. 修改 Python 代码： 使用 os 模块来读取环境变量。

   import votesmart
   import os
   # 从环境变量中读取 API Key
   api_key = os.getenv('VOTESMART_API_KEY')
   if not api_key:
       print("错误：环境变量 VOTESMART_API_KEY 未设置。")
   else:
       votesmart.apikey.set(api_key)
       # ... 其余代码保持不变 ...

这样,你的代码更加安全，也方便在不同环境中部署。