pexels-python
一个功能完整、高性能的 Pexels API Python 客户端库。
✨ 特性
- 🔄 自动重试机制:对 429 限流错误自动重试,支持指数退避策略
- 🚀 异步支持:基于 httpx 的异步客户端,支持并发请求
- 📄 分页迭代器:自动翻页生成器,轻松处理大量数据
- 💾 智能缓存:支持内存和 Redis 缓存,提升性能
- 🛡️ 丰富异常:详细的异常类型和错误上下文信息
- 📝 美化日志:集成 Rich 的彩色日志输出
- 🎯 类型注解:完整的类型提示支持
- 🧪 完善测试:高覆盖率的测试套件
📦 安装
使用 Poetry 管理:
poetry add pexels-python
或本地开发:
poetry install
🚀 快速开始
基础使用
from pexels_python import PexelsClient
client = PexelsClient(api_key="YOUR_PEXELS_API_KEY")
# 搜索照片
photos = client.search_photos("cats", per_page=5)
print(f"找到 {photos['total_results']} 张照片")
# 精选照片
curated = client.curated_photos(per_page=5)
print(f"获取 {len(curated['photos'])} 张精选照片")
# 搜索视频
videos = client.search_videos("nature", per_page=5)
print(f"找到 {len(videos['videos'])} 个视频")
异步使用
import asyncio
from pexels_python import AsyncPexelsClient
async def main():
async with AsyncPexelsClient(api_key="YOUR_API_KEY") as client:
# 并发搜索
photos_task = client.search_photos("mountains", per_page=5)
videos_task = client.search_videos("ocean", per_page=5)
photos, videos = await asyncio.gather(photos_task, videos_task)
print(f"照片: {len(photos['photos'])}, 视频: {len(videos['videos'])}")
asyncio.run(main())
分页迭代
from pexels_python import iter_search_photos
# 自动翻页获取所有结果
for photo in iter_search_photos(client, "sunset", per_page=10, max_items=100):
print(f"照片 ID: {photo['id']}, 摄影师: {photo['photographer']}")
重试和缓存
from pexels_python import PexelsClient, RetryConfig, CacheManager
# 配置重试策略
retry_config = RetryConfig(
max_retries=3,
base_delay=1.0,
exponential_base=2.0
)
# 配置缓存
cache_manager = CacheManager.create_memory_cache(
max_size=100,
ttl=300 # 5分钟
)
client = PexelsClient(
api_key="YOUR_API_KEY",
retry_config=retry_config,
cache_manager=cache_manager
)
🛡️ 错误处理
本库提供了丰富的异常类型:
from pexels_python import (
PexelsClient,
PexelsAuthError,
PexelsRateLimitError,
PexelsBadRequestError,
PexelsNotFoundError,
PexelsServerError
)
client = PexelsClient(api_key="YOUR_API_KEY")
try:
photos = client.search_photos("test")
except PexelsAuthError as e:
print(f"认证失败: {e.message}")
except PexelsRateLimitError as e:
print(f"限流错误,建议等待 {e.retry_after} 秒")
except PexelsBadRequestError as e:
print(f"请求参数错误: {e.message}")
except PexelsNotFoundError as e:
print(f"资源不存在: {e.message}")
except PexelsServerError as e:
print(f"服务器错误: {e.message}")
📝 日志配置
from pexels_python import set_debug, set_info
# 启用调试日志,显示详细的请求/响应信息
set_debug()
# 设置为信息级别
set_info()
📚 示例代码
查看 examples/ 目录获取更多示例:
basic_usage.py- 基础功能演示async_usage.py- 异步客户端使用pagination_example.py- 分页功能演示retry_and_cache_example.py- 重试和缓存功能
运行示例:
# 设置 API 密钥
export PEXELS_API_KEY="your_api_key_here"
# 运行基础示例
poetry run python examples/basic_usage.py
# 运行异步示例
poetry run python examples/async_usage.py
🧪 测试
运行测试套件:
# 运行所有测试
poetry run python -m pytest tests/ -v
# 运行特定测试
poetry run python -m pytest tests/test_client.py -v
# 运行异步测试
poetry run python -m pytest tests/test_async_client.py -v
📖 API 文档
主要类
PexelsClient- 同步客户端AsyncPexelsClient- 异步客户端PaginationIterator- 分页迭代器RetryConfig- 重试配置CacheManager- 缓存管理器
主要方法
照片相关:
search_photos(query, ...)- 搜索照片curated_photos(...)- 获取精选照片get_photo(photo_id)- 获取单张照片
视频相关:
search_videos(query, ...)- 搜索视频popular_videos(...)- 获取热门视频get_video(video_id)- 获取单个视频
分页迭代器:
iter_search_photos(...)- 照片搜索迭代器iter_curated_photos(...)- 精选照片迭代器iter_search_videos(...)- 视频搜索迭代器iter_popular_videos(...)- 热门视频迭代器
🔧 配置选项
重试配置
RetryConfig(
max_retries=3, # 最大重试次数
base_delay=1.0, # 基础延迟(秒)
max_delay=60.0, # 最大延迟(秒)
exponential_base=2.0, # 指数退避基数
jitter=True # 是否添加随机抖动
)
缓存配置
# 内存缓存
CacheManager.create_memory_cache(
max_size=100, # 最大缓存项数
ttl=300 # 生存时间(秒)
)
# Redis 缓存
CacheManager.create_redis_cache(
host="localhost",
port=6379,
db=0,
ttl=300
)
🤝 贡献
欢迎提交 Issue 和 Pull Request!
📄 许可
MIT License
Metadata
Release files for pexels-python 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pexels_python-0.1.0.tar.gz | 19.8 kB | Without provenance | Details for pexels_python-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pexels_python-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for pexels_python-0.1.0-py3-none-any.whl |
Total release size: 46.8 kB
Release files / pexels_python-0.1.0.tar.gz
| Download URL | pexels_python-0.1.0.tar.gz |
|---|---|
| Size | 19.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
df9020a9d460d4ddacc506f1cb85f7ad88085eb9a11b0aa162b089e96767357d
|
|
BLAKE2b-256 checksum How to use checksums |
3202417a0bbdab62650143c981c016a14d439d2cfcc5a734cece961115de1df3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.11.2 Linux/6.1.0-10-amd64
|
Release files / pexels_python-0.1.0-py3-none-any.whl
| Download URL | pexels_python-0.1.0-py3-none-any.whl |
|---|---|
| Size | 27.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0823fba5b8bc287f668d903952d0b8e5c9f4238293d06f3d25a5a6f99251d7c2
|
|
BLAKE2b-256 checksum How to use checksums |
8cd64ff41b44190e1b5abd383c90dbc5a990c739796e8ad98992ec8855c7e998
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.3 CPython/3.11.2 Linux/6.1.0-10-amd64
|
Security for pexels-python 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.