Metadata-Version: 2.4
Name: py-the-news-api
Version: 0.1.0
Summary: A Python wrapper for The News API.
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: httpx
Requires-Dist: pydantic
Dynamic: license-file

# The News API Python Wrapper

This package provides an asynchronous Python client for [The News API](https://www.thenewsapi.com/), allowing you to easily fetch headlines, top stories, all news, sources, and similar articles.

## Features

- Async API client using `httpx`
- Typed responses via Pydantic models
- Category validation
- Context manager support for resource management

## Endpoints

The client exposes the following endpoints:

- **get_headlines**: Get the latest headlines.
- **get_top_stories**: Fetch top stories with advanced filtering.
- **get_all_news**: Retrieve all news articles with search and filter options.
- **get_sources**: List available news sources.
- **get_similar_news**: Find articles similar to a given article UUID.
- **get_news_by_uuid**: Fetch a single article by its UUID.

## Installation

```bash
pip install py-the-news-api
```

## Usage

```python
import asyncio
from the_news_api.client import NewsAPIClient

async def main():
    async with NewsAPIClient(api_token="YOUR_API_TOKEN") as client:
        headlines = await client.get_headlines(language="en")
        print(headlines)

asyncio.run(main())
```

### Example: Fetch Top Stories

```python
async with NewsAPIClient(api_token="YOUR_API_TOKEN") as client:
    stories = await client.get_top_stories(categories=["tech", "science"], limit=5)
    for article in stories.articles:
        print(article.title)
```

## Category Filtering

Supported categories:

- `general`, `science`, `sports`, `business`, `health`, `entertainment`, `tech`, `politics`, `food`, `travel`

## License

MIT

## Links

- [The News API Documentation](https://www.thenewsapi.com/docs)
- [GitHub Repository](https://github.com/Karsten-Larson/the-news-api)
