serper-wrapper 0.1.0

Python package for calling Serper API with support for disk and MongoDB caching

Serper Wrapper

一个用于调用Serper API的Python包，支持磁盘和MongoDB缓存功能。

功能特点

• 提供简单易用的接口调用Serper API
• 支持磁盘缓存和MongoDB缓存
• 可配置缓存过期时间
• 磁盘缓存支持最大缓存大小限制和自动清理旧缓存
• 支持自定义搜索参数（国家、语言、时间范围等）
• 支持Python 3.7及以上版本
• 集成Prometheus指标监控，支持PushGateway推送
• 内置MongoDB支持，优化的连接池管理

安装

pip install serper-wrapper

基本使用

from serper_wrapper import SerperClient

# 创建客户端实例
client = SerperClient(
    api_key="your_serper_api_key",  # 替换为你的Serper API密钥
    cache_type="disk",  # 可选: "disk", "mongo", "none"
    cache_expiration=3600,  # 缓存过期时间（秒）
    max_cache_size_mb=4096  # 最大缓存大小（MB）
)

# 简单搜索（需要提供source参数标识调用来源）
results = client.search("apple inc", source="my_app")

# 带自定义参数的搜索
results = client.search(
    query="apple inc",
    source="product_page",  # 调用来源标识
    country="jp",  # 日本
    language="ja",  # 日语
    time_period="1w",  # 过去一周
    num_results=20,
    page=1,
    use_cache=True  # 使用缓存
)

# 清空缓存
client.clear_cache()

使用MongoDB缓存

from serper_wrapper import SerperClient

# 创建使用MongoDB缓存的客户端实例
client = SerperClient(
    api_key="your_serper_api_key",
    cache_type="mongo",
    cache_expiration=3600,
    mongo_uri="mongodb://localhost:27017",
    mongo_db="serper_cache",
    mongo_collection="cache"
)

# 使用方式与磁盘缓存相同
results = client.search("apple inc", source="my_app")

MongoDB高级配置

from serper_wrapper.cache.mongo_cache import MongoCache

# 创建带有自定义连接池配置的MongoDB缓存
mongo_cache = MongoCache(
    mongo_uri="mongodb://localhost:27017",
    db_name="serper_cache",
    collection_name="cache",
    expiration_time=7200,  # 2小时过期
    connect_on_init=True,  # 初始化时建立连接
    max_pool_size=50,      # 最大连接数
    min_pool_size=5        # 最小连接数
)

# 使用自定义缓存创建客户端
client = SerperClient(
    api_key="your_serper_api_key",
    cache_type="none"  # 使用none，因为我们会手动设置缓存
)
client.cache = mongo_cache

# 现在可以使用带有优化连接池的客户端
results = client.search("apple inc", source="my_app")

# 使用完毕后关闭连接
mongo_cache.close()

自定义搜索

from serper_wrapper import SerperClient

client = SerperClient(api_key="your_serper_api_key")

# 完全自定义搜索参数
custom_payload = {
    "q": "apple inc",
    "gl": "us",
    "hl": "en",
    "num": 30,
    "tbs": "qdr:d"  # 过去24小时
}

# 必须提供source参数表示调用来源
results = client.custom_search(custom_payload, source="custom_search_page")

启用Prometheus指标监控

from serper_wrapper import SerperClient

# 创建带指标监控的客户端实例
client = SerperClient(
    api_key="your_serper_api_key",
    metrics_gateway="http://localhost:9091",  # Prometheus PushGateway地址
    metrics_job="serper_api_client"  # 作业名称
)

# 每次调用search或custom_search时，都会自动收集并推送指标
results = client.search("apple inc", source="metrics_example")

可用的Prometheus指标

• serper_search_total: 搜索请求计数器，带标签：
  • source: 调用来源
  • cache_hit: 是否命中缓存
  • country: 搜索国家
  • language: 搜索语言
• serper_search_duration_seconds: 搜索耗时直方图，带标签：
  • source: 调用来源
  • cache_hit: 是否命中缓存
• serper_search_errors_total: 搜索错误计数器，带标签：
  • source: 调用来源
  • error_type: 错误类型

Serper API参数说明

• q: 搜索查询内容
• gl: 搜索国家，例如"us"、"jp"、"cn"等
• hl: 搜索语言，例如"en"、"zh-cn"、"ja"等
• tbs: 搜索时间范围
  • qdr:h: 过去1小时
  • qdr:d: 过去24小时
  • qdr:w: 过去7天
  • qdr:m: 过去一个月
  • qdr:y: 过去一年
• num: 搜索结果数量，最大为100
• page: 搜索结果页码

许可证

MIT