Libraries

The official Python library for NewsMesh provides a simple, type-safe way to interact with the API. It includes both synchronous and asynchronous clients, automatic retries, and pagination helpers.

View on PyPI →

Installation

pip install newsmesh

For async support (requires Python 3.8+):

pip install newsmesh[async]

Quick Start

from newsmesh import NewsMeshClient
client = NewsMeshClient("your-api-key")

# Get trending articles
trending = client.get_trending(limit=10)
for article in trending:
    print(f"{article.title} - {article.source}")

# Get latest tech news from the US
latest = client.get_latest(category="technology", country="us")

# Search articles
results = client.search("climate change", sort_by="relevant")

# Get single article by ID
article = client.get_article("article-id-123")

Available Methods

• get_trending(limit): Get trending articles
• get_latest(limit, category, country, from_date, to_date, cursor): Get latest articles
• search(query, limit, from_date, to_date, sort_by, cursor): Search articles
• get_article(article_id): Get a single article by ID
• paginate(method, **kwargs): Auto-paginate through results

Async Usage

For async applications, use AsyncNewsMeshClient:

import asyncio
from newsmesh import AsyncNewsMeshClient

async def main():
    async with AsyncNewsMeshClient("your-api-key") as client:
        # Get trending articles
        trending = await client.get_trending()

        # Search articles
        results = await client.search("technology")

        # Concurrent requests
        trending, latest = await asyncio.gather(
            client.get_trending(),
            client.get_latest(category="business")
        )

asyncio.run(main())

Pagination

Use the paginate() helper to automatically iterate through all results:

# Automatic pagination
for article in client.paginate("get_latest", category="politics"):
    print(article.title)

# With async client
async for article in client.paginate("search", query="climate"):
    print(article.title)

Or handle pagination manually:

response = client.get_latest(limit=25)
while response.has_more:
    for article in response:
        print(article.title)
    response = client.get_latest(cursor=response.next_cursor)

Error Handling

The library raises specific exceptions for different error types:

from newsmesh import (
    NewsMeshClient,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    ValidationError,
)

client = NewsMeshClient("your-api-key")

try:
    article = client.get_article("invalid-id")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited")
except NotFoundError:
    print("Article not found")
except ValidationError as e:
    print(f"Invalid request: {e.message}")

Exception Types

• NewsMeshError: Base exception class
• AuthenticationError: Invalid or missing API key (401)
• ForbiddenError: Access forbidden (403)
• NotFoundError: Article not found (404)
• ValidationError: Invalid parameters (400)
• RateLimitError: Rate limit exceeded (429)
• ServerError: Server error (5xx)

See the API Reference for full endpoint documentation.