Metadata-Version: 2.4
Name: reuters-private-api
Version: 0.1.0
Summary: Minimal Python client for Reuters public mobile JSON endpoints
Author-email: 11philip22 <philipwoldhek@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/11philip22/reuters-private-api
Project-URL: Repository, https://github.com/11philip22/reuters-private-api
Project-URL: Issues, https://github.com/11philip22/reuters-private-api/issues
Keywords: reuters,news,api,httpx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.28
Dynamic: license-file

<div align="center">

# Reuters Private API

[![PyPI](https://img.shields.io/pypi/v/reuters-private-api?style=flat-square)](https://pypi.org/project/reuters-private-api/)
![Python](https://img.shields.io/badge/Python-%3E%3D3.9-3776ab?style=flat-square&logo=python&logoColor=white)
![License](https://img.shields.io/pypi/l/reuters-private-api?style=flat-square)
[![Downloads](https://img.shields.io/pypi/dm/reuters-private-api?style=flat-square)](https://pypi.org/project/reuters-private-api/)

*A small Python client and API map for Reuters' public mobile JSON endpoints.*

[Features](#features) - [Installation](#installation) - [Quick Start](#quick-start) - [API](#api) - [API Notes](#api-notes) - [Development](#development)

</div>

This repository turns the Reuters Android API mapping work into a minimal Python package. It can read public section pages, follow the mobile "fetch more" pagination flow, and fetch public article details while keeping the original JSON payload available for callers that need fields beyond the typed dataclasses.

> [!IMPORTANT]
> This is an unofficial client for public Reuters web/mobile endpoints observed from the Android app. Endpoints can change, and Reuters may reject or challenge automated traffic. Use it responsibly and respect Reuters' terms.

## Features

- Iterate Reuters category and section article summaries from paths such as `/world/americas/`.
- Optionally follow category pagination through Reuters' `fetch_more` endpoint.
- Fetch public article detail payloads, including authors, timing metadata, and body content elements.
- Return frozen dataclasses with common fields plus the raw Reuters JSON.
- Include API mapping notes for mobile REST, GraphQL/identity behavior, and the Android widget feed.

## Installation

Requires Python 3.9 or newer.

```bash
python -m pip install reuters-private-api
```

For local development, use an editable install:

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
```

## Quick Start

```python
from itertools import islice

from reuters_private_api import ReutersClient

client = ReutersClient()

summaries = list(islice(client.iter_articles("/world/americas/", load_more=True), 10))

for summary in summaries:
    print(summary.display_time, summary.title)
    print(summary.url)

article = client.get_article(summaries[0].url)
print(article.title)
print(article.read_minutes)

for element in article.content_elements:
    print(element.get("type"), element.get("content"))
```

> [!TIP]
> Pass Reuters URL paths, not full URLs. Use `/world/americas/` or `/world/example-2026-08-13/`; full `https://...` URLs are rejected on purpose.

## API

### `ReutersClient(timeout=30, client=None)`

Creates an HTTP client configured for Reuters' public JSON endpoints. You can pass your own `httpx.Client` to control retries, proxies, custom transports, or shared connection pooling.

### `iter_articles(category_path, load_more=False)`

Yields `ArticleSummary` objects for a Reuters category path.

```python
for article in client.iter_articles("/world/", load_more=True):
    print(article.id, article.title)
```

When `load_more=True`, the client follows the Reuters category pagination endpoint until Reuters returns an empty page. Results are de-duplicated by article ID.

### `get_article(article_path)`

Fetches one public article detail payload and returns an `Article`.

```python
summary = next(client.iter_articles("/business/"))
article = client.get_article(summary.url)
```

### Data Models

| Type | Fields |
| --- | --- |
| `ArticleSummary` | `id`, `url`, `title`, `description`, `display_time`, `section`, `section_url`, `authors`, `thumbnail`, `raw` |
| `Article` | `id`, `url`, `title`, `description`, `display_time`, `published_time`, `updated_time`, `word_count`, `read_minutes`, `authors`, `content_elements`, `raw` |

## API Notes

The detailed mapping is in [`docs/apis`](https://github.com/11philip22/reuters-private-api/tree/master/docs/apis):

- [`mobile-rest.md`](https://github.com/11philip22/reuters-private-api/blob/master/docs/apis/mobile-rest.md) covers the public mobile JSON endpoints, category pagination, article detail responses, menu/config routes, markets quotes, and geo helper.
- [`graphql-identity.md`](https://github.com/11philip22/reuters-private-api/blob/master/docs/apis/graphql-identity.md) documents the observed GraphQL transport, public search/feed behavior, authenticated-field boundaries, and embedded operation inventory.
- [`native-widget.md`](https://github.com/11philip22/reuters-private-api/blob/master/docs/apis/native-widget.md) describes the Android widget feed and parsing behavior.

## Development

The package is intentionally small: `reuters_private_api/client.py` contains the HTTP behavior, and `reuters_private_api/types.py` contains the dataclasses.

Run a quick syntax check with:

```bash
python -m compileall reuters_private_api
```
