https://github.com/goperigon/perigon-python
Perigon Python SDK generated with openapi-generator
https://github.com/goperigon/perigon-python
news news-api perigon python sdk sdk-python
Last synced: about 1 month ago
JSON representation
Perigon Python SDK generated with openapi-generator
- Host: GitHub
- URL: https://github.com/goperigon/perigon-python
- Owner: goperigon
- License: mit
- Created: 2025-05-02T21:24:26.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-10-15T16:26:14.000Z (4 months ago)
- Last Synced: 2025-10-16T12:43:38.418Z (4 months ago)
- Topics: news, news-api, perigon, python, sdk, sdk-python
- Language: Python
- Homepage: https://docs.perigon.io
- Size: 294 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Perigon Python SDK
Python client for the Perigon API
A modern, fully‑typed Python SDK for the Perigon API, generated from the official OpenAPI specification.
Works in **CPython 3.8+**, **PyPy**, serverless runtimes, notebooks, and async frameworks.
## Table of Contents
---
## ✨ Features
- **Type‑hinted** request/response models powered by Pydantic
- **Async and sync support** - choose the right approach for your application
- Ships with **PEP 561 type hints** for excellent IDE integration
- Generated directly from , so it's always in sync
---
## 📦 Installation
```bash
pip install perigon
# poetry add perigon
# pipx install perigon
```
---
## 🚀 Quick start
### 1. Instantiate the client
```python
from perigon import V1Api, ApiClient
# Create client with API key
api = V1Api(ApiClient(api_key="YOUR_API_KEY"))
# Alternative: environment variable or callable
# api = V1Api(ApiClient(api_key=os.environ["PERIGON_API_KEY"]))
# api = V1Api(ApiClient(api_key=lambda: get_api_key_from_vault()))
```
### 2. Make calls
```python
# 🔍 Search recent news articles (sync)
articles = api.search_articles(q="artificial intelligence", size=5)
print(articles.num_results, articles.articles[0].title)
# 👤 Look up a journalist by ID (sync)
journalist = api.get_journalist_by_id(id="123456")
print(journalist.name)
# 🔄 Use async variant for async applications
import asyncio
async def fetch_data():
# Search articles asynchronously
articles = await api.search_articles_async(q="technology", size=5)
# Look up journalist asynchronously
journalist = await api.get_journalist_by_id_async(id="123456")
return articles, journalist
# Run in async context
articles, journalist = asyncio.run(fetch_data())
```
> All methods return **typed objects** with full IDE autocompletion support.
---
## 🧑💻 Endpoint examples
### Articles – search and filter news (`/v1/all`)
**Docs →** [https://docs.perigon.io/docs/overview](https://docs.perigon.io/docs/overview)
```python
# Simple query
articles = api.search_articles(q="technology", size=5)
# With date range
articles = api.search_articles(
q="business",
var_from="2025-04-01", # Note: 'from' is a reserved keyword in Python
to="2025-04-08"
)
# Restrict to specific sources
articles = api.search_articles(source=["nytimes.com"])
```
### Companies – fetch structured company data (`/v1/companies`)
**Docs →** [https://docs.perigon.io/docs/company-data](https://docs.perigon.io/docs/company-data)
```python
results = api.search_companies(name="Apple", size=5)
```
### Journalists – search and detail look‑up (`/v1/journalists`)
**Docs →** [https://docs.perigon.io/docs/journalist-data](https://docs.perigon.io/docs/journalist-data)
```python
# Search for journalists
results = api.search_journalists1(name="Kevin", size=1)
# Get detailed information
journalist = api.get_journalist_by_id(id=results.journalists[0].id)
```
### Stories – discover related article clusters (`/v1/stories`)
**Docs →** [https://docs.perigon.io/docs/stories-overview](https://docs.perigon.io/docs/stories-overview)
```python
stories = api.search_stories(q="climate change", size=5)
```
### Vector search – semantic retrieval (`/v1/vector`)
**Docs →** [https://docs.perigon.io/docs/vector-endpoint](https://docs.perigon.io/docs/vector-endpoint)
```python
from perigon.models.article_search_params import ArticleSearchParams
results = api.vector_search_articles(
article_search_params=ArticleSearchParams(
prompt="Latest advancements in artificial intelligence",
size=5
)
)
```
### Summarizer – generate an instant summary (`/v1/summarizer`)
**Docs →** [https://docs.perigon.io/docs/search-summarizer](https://docs.perigon.io/docs/search-summarizer)
```python
from perigon.models.summary_body import SummaryBody
summary = api.search_summarizer(
summary_body=SummaryBody(prompt="Key developments"),
q="renewable energy",
size=10
).summary
print(summary)
```
### Topics – explore taxonomy (`/v1/topics`)
**Docs →** [https://docs.perigon.io/docs/topics](https://docs.perigon.io/docs/topics)
```python
topics = api.search_topics(size=10)
```
### Wikipedia – search and filter pages (`/v1/wikipedia`)
**Docs →** [https://docs.perigon.io/docs/wikipedia](https://docs.perigon.io/docs/wikipedia)
```python
# Search Wikipedia pages
wikipedia_result = api.search_wikipedia(
q="machine learning",
size=3,
sort_by="relevance"
)
# Filter by specific criteria
wikipedia_result = api.search_wikipedia(
q="artificial intelligence",
pageviews_from=100, # Only popular pages
)
```
### Wikipedia vector search – semantic retrieval (`/v1/vector/wikipedia`)
**Docs →** [https://docs.perigon.io/docs/vector-wikipedia](https://docs.perigon.io/docs/vector-wikipedia)
```python
from perigon.models.wikipedia_search_params import WikipediaSearchParams
results = api.vector_search_wikipedia(
wikipedia_search_params=WikipediaSearchParams(
prompt="artificial intelligence and neural networks in computing",
size=3,
pageviews_from=100
)
)
```
| Action | Code Example |
| --- | --- |
| Filter by source | `api.search_articles(source=["nytimes.com"])` |
| Limit by date range | `api.search_articles(q="business", var_from="2025-04-01", to="2025-04-08")` |
| Company lookup | `api.search_companies(name="Apple", size=5)` |
| Summarize any query | `api.search_summarizer(summary_body=SummaryBody(prompt="Key points"), q="renewable energy", size=20)` |
| Semantic / vector search | `api.vector_search_articles(article_search_params=ArticleSearchParams(prompt="advancements in AI", size=5))` |
| Retrieve available taxonomic topics | `api.search_topics(size=10)` |
| Search Wikipedia pages | `api.search_wikipedia(q="machine learning", size=3, sort_by="relevance")` |
| Wikipedia semantic search | `api.vector_search_wikipedia(wikipedia_search_params=WikipediaSearchParams(prompt="artificial intelligence", size=3))` |
---
## 🔄 Async Support
All methods have async counterparts with the `_async` suffix:
```python
import asyncio
from perigon import V1Api, ApiClient
async def main():
api = V1Api(ApiClient(api_key="YOUR_API_KEY"))
# Concurrent API calls
articles_task = api.search_articles_async(q="technology", size=5)
journalist_task = api.get_journalist_by_id_async(id="123456")
# Gather results
articles, journalist = await asyncio.gather(articles_task, journalist_task)
return articles, journalist
# Run the async function
articles, journalist = asyncio.run(main())
```
---
## 🪪 License
MIT © Perigon