newsdataapi 0.4.0__tar.gz → 0.4.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/PKG-INFO +25 -46
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/README.md +24 -45
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/examples/basic_usage.py +10 -14
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/pyproject.toml +0 -5
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/__init__.py +1 -1
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/client.py +1 -48
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/csv_export.py +2 -2
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/tests/test_unit.py +0 -58
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/.github/workflows/ci.yml +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/.github/workflows/publish.yml +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/.gitignore +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/.python-version +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/LICENSE +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/examples/websocket_usage.py +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/newsdata-logo.png +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/constants.py +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/exceptions.py +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/py.typed +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/websocket.py +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/tests/__init__.py +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/tests/conftest.py +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/tests/test_integration.py +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/tests/test_websocket.py +0 -0
- {newsdataapi-0.4.0 → newsdataapi-0.4.1}/uv.lock +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: newsdataapi
|
|
3
|
-
Version: 0.4.
|
|
3
|
+
Version: 0.4.1
|
|
4
4
|
Summary: Official Python client (SDK) for the Newsdata.io News API — fetch real-time, historical, crypto, and stock-market news via REST, with validation, retries, pagination, and typed exceptions.
|
|
5
5
|
Project-URL: Homepage, https://newsdata.io
|
|
6
6
|
Project-URL: Documentation, https://newsdata.io/documentation
|
|
@@ -65,7 +65,7 @@ Description-Content-Type: text/markdown
|
|
|
65
65
|
|
|
66
66
|
</div>
|
|
67
67
|
|
|
68
|
-
`newsdataapi` is the official Python SDK for the [NewsData.io](https://newsdata.io) REST API. It wraps every endpoint (`
|
|
68
|
+
`newsdataapi` is the official Python SDK for the [NewsData.io](https://newsdata.io) REST API. It wraps every endpoint (`latest`, `archive`, `sources`, `crypto`, `market`, `count`, `crypto/count`, `market/count`) with consistent retry, pagination, and error handling. It also covers the real-time WebSocket service end to end with `NewsDataApiWebSocket`: register, list, and delete queries, and stream the matching news as it is published (sync or asyncio).
|
|
69
69
|
|
|
70
70
|
## Installation
|
|
71
71
|
|
|
@@ -87,9 +87,9 @@ Supports Python 3.8 through 3.14. The runtime dependencies are `requests` (REST)
|
|
|
87
87
|
from newsdataapi import NewsDataApiClient
|
|
88
88
|
|
|
89
89
|
with NewsDataApiClient("YOUR_API_KEY") as client:
|
|
90
|
-
response = client.
|
|
90
|
+
response = client.latest_api(q="bitcoin", country="us", language="en")
|
|
91
91
|
for article in response["results"]:
|
|
92
|
-
print(article["title"], "-", article["
|
|
92
|
+
print(article["title"], "-", article["link"])
|
|
93
93
|
```
|
|
94
94
|
|
|
95
95
|
The context-manager form closes the underlying HTTP session cleanly when the block exits. If you prefer not to use `with`, create the client directly and call `client.close()` yourself:
|
|
@@ -99,9 +99,9 @@ from newsdataapi import NewsDataApiClient
|
|
|
99
99
|
|
|
100
100
|
client = NewsDataApiClient("YOUR_API_KEY")
|
|
101
101
|
try:
|
|
102
|
-
response = client.
|
|
102
|
+
response = client.latest_api(q="bitcoin", country="us", language="en")
|
|
103
103
|
for article in response["results"]:
|
|
104
|
-
print(article["title"], "-", article["
|
|
104
|
+
print(article["title"], "-", article["link"])
|
|
105
105
|
finally:
|
|
106
106
|
client.close()
|
|
107
107
|
```
|
|
@@ -110,55 +110,34 @@ finally:
|
|
|
110
110
|
|
|
111
111
|
| Method | Endpoint | Notes |
|
|
112
112
|
|--------|----------|-------|
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
113
|
+
| `latest_api()` | `/latest` | Real-time news |
|
|
114
|
+
| `archive_api()` | `/archive` | Historical news |
|
|
115
|
+
| `sources_api()` | `/sources` | Available news sources |
|
|
116
|
+
| `crypto_api()` | `/crypto` | Cryptocurrency news |
|
|
117
|
+
| `market_api()` | `/market` | Market / financial news |
|
|
118
|
+
| `count_api(from_date, to_date)` | `/count` | Aggregate counts |
|
|
119
|
+
| `crypto_count_api(from_date, to_date)` | `/crypto/count` | Aggregate crypto counts |
|
|
120
|
+
| `market_count_api(from_date, to_date)` | `/market/count` | Aggregate market counts |
|
|
120
121
|
|
|
121
|
-
All parameters are keyword-only. Most accept either a single string or a `list[str]`; lists are comma-joined for the API. The real-time WebSocket endpoints are covered by `NewsDataApiWebSocket` (see below).
|
|
122
|
-
|
|
123
|
-
The count methods return `total_results` and a `results` list with one `{"date_time": ..., "count": ...}` entry per `interval` (`month`, `day` or `hour`). They page like the news methods, so `scroll` and `paginate` work on them too.
|
|
122
|
+
All endpoint parameters are keyword-only (except the required `from_date` / `to_date` on the count endpoints). Most accept either a single string or a `list[str]`; lists are comma-joined for the API. The real-time WebSocket endpoints are covered by `NewsDataApiWebSocket` (see below).
|
|
124
123
|
|
|
125
124
|
See the [NewsData.io documentation](https://newsdata.io/documentation) — or the [OpenAPI 3.1 spec](https://newsdata.io/openapi.json) — for the full parameter reference.
|
|
126
125
|
|
|
127
|
-
## Upgrading from 0.3.x
|
|
128
|
-
|
|
129
|
-
The old `*_api()` methods still work, but they are deprecated and will be removed in a future release. Each one emits a `DeprecationWarning` naming its replacement:
|
|
130
|
-
|
|
131
|
-
| Old | New |
|
|
132
|
-
|-----|-----|
|
|
133
|
-
| `latest_api()`, `archive_api()` | `news()` |
|
|
134
|
-
| `crypto_api()`, `market_api()`, `sources_api()` | `crypto()`, `market()`, `sources()` |
|
|
135
|
-
| `count_api()`, `crypto_count_api()`, `market_count_api()` | `count_news()`, `count_crypto()`, `count_market()` |
|
|
136
|
-
| `qInTitle`, `qInMeta` | `q_in_title`, `q_in_meta` |
|
|
137
|
-
| `domainurl`, `excludedomainurl`, `excludedomain` | `source_url`, `exclude_source_url`, `exclude_source_url` |
|
|
138
|
-
| `domain` | `source_url`, with the source's URL (`bbc.com`) instead of its id (`bbc`) |
|
|
139
|
-
| `prioritydomain` | `source_priority` |
|
|
140
|
-
| `excludecountry`, `excludecategory`, `excludelanguage` | `exclude_country`, `exclude_category`, `exclude_language` |
|
|
141
|
-
| `excludefield`, `removeduplicate` | `exclude_field`, `remove_duplicate` |
|
|
142
|
-
| `full_content` | `content` |
|
|
143
|
-
| `totalResults`, `nextPage` in the response | `total_results`, `next_page` |
|
|
144
|
-
|
|
145
|
-
The article layout changed too: for example `url` replaces `link`, and related fields are grouped under `media`, `source` and `ai`. On the count methods `from_date` and `to_date` are now optional keyword arguments.
|
|
146
|
-
|
|
147
126
|
## Three ways to consume an endpoint
|
|
148
127
|
|
|
149
128
|
```python
|
|
150
129
|
# 1. Single request (the default).
|
|
151
|
-
response = client.
|
|
130
|
+
response = client.latest_api(q="news")
|
|
152
131
|
|
|
153
|
-
# 2. Auto-merge — follow
|
|
154
|
-
merged = client.
|
|
132
|
+
# 2. Auto-merge — follow nextPage cursors and return one combined dict.
|
|
133
|
+
merged = client.latest_api(q="news", scroll=True, max_result=200)
|
|
155
134
|
|
|
156
135
|
# 3. Iterate one response per page (a generator).
|
|
157
|
-
for page in client.
|
|
136
|
+
for page in client.latest_api(q="news", paginate=True, max_pages=5):
|
|
158
137
|
process(page["results"])
|
|
159
138
|
```
|
|
160
139
|
|
|
161
|
-
`scroll` and `paginate` are mutually exclusive. `scroll=True` truncates strictly to `max_result`; `paginate=True` stops at `max_pages` or when the API returns no `
|
|
140
|
+
`scroll` and `paginate` are mutually exclusive. `scroll=True` truncates strictly to `max_result`; `paginate=True` stops at `max_pages` or when the API returns no `nextPage`.
|
|
162
141
|
|
|
163
142
|
## Real-time news (WebSocket)
|
|
164
143
|
|
|
@@ -173,9 +152,9 @@ response = ws.websocket_register(q="bitcoin", language="en")
|
|
|
173
152
|
registration_id = response["results"]["registration_id"]
|
|
174
153
|
```
|
|
175
154
|
|
|
176
|
-
`websocket_register`
|
|
155
|
+
`websocket_register` accepts the familiar filter parameters (`q`, `country`, `language`, `domain`, …). Registering an identical query twice raises `NewsdataAPIError` with `status_code=409` — the existing id is in `e.response_body["results"]["registration_id"]`. `websocket_fetch()` lists every registered query, and `websocket_delete(registration_id)` removes one.
|
|
177
156
|
|
|
178
|
-
Then stream
|
|
157
|
+
Then stream — each yielded response has the familiar `status` / `totalResults` / `results` shape:
|
|
179
158
|
|
|
180
159
|
```python
|
|
181
160
|
for response in ws.stream(registration_id):
|
|
@@ -250,7 +229,7 @@ from newsdataapi import (
|
|
|
250
229
|
)
|
|
251
230
|
|
|
252
231
|
try:
|
|
253
|
-
client.
|
|
232
|
+
client.latest_api(q="news")
|
|
254
233
|
except NewsdataAuthError as e:
|
|
255
234
|
print(f"bad API key (HTTP {e.status_code})")
|
|
256
235
|
except NewsdataApiKeyLimitExceededError:
|
|
@@ -297,7 +276,7 @@ client = NewsDataApiClient(apikey, folder_path="./out")
|
|
|
297
276
|
client.save_to_csv(response, filename="latest_news")
|
|
298
277
|
```
|
|
299
278
|
|
|
300
|
-
`save_to_csv` returns a `pathlib.Path`.
|
|
279
|
+
`save_to_csv` returns a `pathlib.Path`. Cell values that are dicts or lists are stringified (`key:value,key:value` for dicts, comma-joined for lists). Quoting is delegated to the standard `csv.DictWriter`, so the output round-trips correctly through any CSV reader.
|
|
301
280
|
|
|
302
281
|
The function is also importable as a standalone:
|
|
303
282
|
|
|
@@ -327,7 +306,7 @@ client = NewsDataApiClient(
|
|
|
327
306
|
)
|
|
328
307
|
```
|
|
329
308
|
|
|
330
|
-
`base_url` (and `set_base_url()`) is the API root without a version segment; the default is `https://newsdata.io/api`, and the client adds
|
|
309
|
+
`base_url` (and `set_base_url()`) is the API root without a version segment; the default is `https://newsdata.io/api`, and the client adds the version itself. Before 0.4.0 it included the version (`https://newsdata.io/api/1/`), so drop the trailing `/1/` if you override it.
|
|
331
310
|
|
|
332
311
|
A request that fails with a server error, a rate limit, or a network error is attempted 5 times by default, sleeping 2 s, 4 s, 8 s and 16 s between attempts (30 s in total; a single sleep never exceeds `retry_backoff_max`). A 429 response is instead retried after the server's `Retry-After` plus one second (both integer-seconds and HTTP-date forms are parsed); when `Retry-After` is longer than `retry_backoff_max`, the client does not wait and raises `NewsdataRateLimitError` with `retry_after` set. The API key is redacted in log output.
|
|
333
312
|
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
|
|
14
14
|
</div>
|
|
15
15
|
|
|
16
|
-
`newsdataapi` is the official Python SDK for the [NewsData.io](https://newsdata.io) REST API. It wraps every endpoint (`
|
|
16
|
+
`newsdataapi` is the official Python SDK for the [NewsData.io](https://newsdata.io) REST API. It wraps every endpoint (`latest`, `archive`, `sources`, `crypto`, `market`, `count`, `crypto/count`, `market/count`) with consistent retry, pagination, and error handling. It also covers the real-time WebSocket service end to end with `NewsDataApiWebSocket`: register, list, and delete queries, and stream the matching news as it is published (sync or asyncio).
|
|
17
17
|
|
|
18
18
|
## Installation
|
|
19
19
|
|
|
@@ -35,9 +35,9 @@ Supports Python 3.8 through 3.14. The runtime dependencies are `requests` (REST)
|
|
|
35
35
|
from newsdataapi import NewsDataApiClient
|
|
36
36
|
|
|
37
37
|
with NewsDataApiClient("YOUR_API_KEY") as client:
|
|
38
|
-
response = client.
|
|
38
|
+
response = client.latest_api(q="bitcoin", country="us", language="en")
|
|
39
39
|
for article in response["results"]:
|
|
40
|
-
print(article["title"], "-", article["
|
|
40
|
+
print(article["title"], "-", article["link"])
|
|
41
41
|
```
|
|
42
42
|
|
|
43
43
|
The context-manager form closes the underlying HTTP session cleanly when the block exits. If you prefer not to use `with`, create the client directly and call `client.close()` yourself:
|
|
@@ -47,9 +47,9 @@ from newsdataapi import NewsDataApiClient
|
|
|
47
47
|
|
|
48
48
|
client = NewsDataApiClient("YOUR_API_KEY")
|
|
49
49
|
try:
|
|
50
|
-
response = client.
|
|
50
|
+
response = client.latest_api(q="bitcoin", country="us", language="en")
|
|
51
51
|
for article in response["results"]:
|
|
52
|
-
print(article["title"], "-", article["
|
|
52
|
+
print(article["title"], "-", article["link"])
|
|
53
53
|
finally:
|
|
54
54
|
client.close()
|
|
55
55
|
```
|
|
@@ -58,55 +58,34 @@ finally:
|
|
|
58
58
|
|
|
59
59
|
| Method | Endpoint | Notes |
|
|
60
60
|
|--------|----------|-------|
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
61
|
+
| `latest_api()` | `/latest` | Real-time news |
|
|
62
|
+
| `archive_api()` | `/archive` | Historical news |
|
|
63
|
+
| `sources_api()` | `/sources` | Available news sources |
|
|
64
|
+
| `crypto_api()` | `/crypto` | Cryptocurrency news |
|
|
65
|
+
| `market_api()` | `/market` | Market / financial news |
|
|
66
|
+
| `count_api(from_date, to_date)` | `/count` | Aggregate counts |
|
|
67
|
+
| `crypto_count_api(from_date, to_date)` | `/crypto/count` | Aggregate crypto counts |
|
|
68
|
+
| `market_count_api(from_date, to_date)` | `/market/count` | Aggregate market counts |
|
|
68
69
|
|
|
69
|
-
All parameters are keyword-only. Most accept either a single string or a `list[str]`; lists are comma-joined for the API. The real-time WebSocket endpoints are covered by `NewsDataApiWebSocket` (see below).
|
|
70
|
-
|
|
71
|
-
The count methods return `total_results` and a `results` list with one `{"date_time": ..., "count": ...}` entry per `interval` (`month`, `day` or `hour`). They page like the news methods, so `scroll` and `paginate` work on them too.
|
|
70
|
+
All endpoint parameters are keyword-only (except the required `from_date` / `to_date` on the count endpoints). Most accept either a single string or a `list[str]`; lists are comma-joined for the API. The real-time WebSocket endpoints are covered by `NewsDataApiWebSocket` (see below).
|
|
72
71
|
|
|
73
72
|
See the [NewsData.io documentation](https://newsdata.io/documentation) — or the [OpenAPI 3.1 spec](https://newsdata.io/openapi.json) — for the full parameter reference.
|
|
74
73
|
|
|
75
|
-
## Upgrading from 0.3.x
|
|
76
|
-
|
|
77
|
-
The old `*_api()` methods still work, but they are deprecated and will be removed in a future release. Each one emits a `DeprecationWarning` naming its replacement:
|
|
78
|
-
|
|
79
|
-
| Old | New |
|
|
80
|
-
|-----|-----|
|
|
81
|
-
| `latest_api()`, `archive_api()` | `news()` |
|
|
82
|
-
| `crypto_api()`, `market_api()`, `sources_api()` | `crypto()`, `market()`, `sources()` |
|
|
83
|
-
| `count_api()`, `crypto_count_api()`, `market_count_api()` | `count_news()`, `count_crypto()`, `count_market()` |
|
|
84
|
-
| `qInTitle`, `qInMeta` | `q_in_title`, `q_in_meta` |
|
|
85
|
-
| `domainurl`, `excludedomainurl`, `excludedomain` | `source_url`, `exclude_source_url`, `exclude_source_url` |
|
|
86
|
-
| `domain` | `source_url`, with the source's URL (`bbc.com`) instead of its id (`bbc`) |
|
|
87
|
-
| `prioritydomain` | `source_priority` |
|
|
88
|
-
| `excludecountry`, `excludecategory`, `excludelanguage` | `exclude_country`, `exclude_category`, `exclude_language` |
|
|
89
|
-
| `excludefield`, `removeduplicate` | `exclude_field`, `remove_duplicate` |
|
|
90
|
-
| `full_content` | `content` |
|
|
91
|
-
| `totalResults`, `nextPage` in the response | `total_results`, `next_page` |
|
|
92
|
-
|
|
93
|
-
The article layout changed too: for example `url` replaces `link`, and related fields are grouped under `media`, `source` and `ai`. On the count methods `from_date` and `to_date` are now optional keyword arguments.
|
|
94
|
-
|
|
95
74
|
## Three ways to consume an endpoint
|
|
96
75
|
|
|
97
76
|
```python
|
|
98
77
|
# 1. Single request (the default).
|
|
99
|
-
response = client.
|
|
78
|
+
response = client.latest_api(q="news")
|
|
100
79
|
|
|
101
|
-
# 2. Auto-merge — follow
|
|
102
|
-
merged = client.
|
|
80
|
+
# 2. Auto-merge — follow nextPage cursors and return one combined dict.
|
|
81
|
+
merged = client.latest_api(q="news", scroll=True, max_result=200)
|
|
103
82
|
|
|
104
83
|
# 3. Iterate one response per page (a generator).
|
|
105
|
-
for page in client.
|
|
84
|
+
for page in client.latest_api(q="news", paginate=True, max_pages=5):
|
|
106
85
|
process(page["results"])
|
|
107
86
|
```
|
|
108
87
|
|
|
109
|
-
`scroll` and `paginate` are mutually exclusive. `scroll=True` truncates strictly to `max_result`; `paginate=True` stops at `max_pages` or when the API returns no `
|
|
88
|
+
`scroll` and `paginate` are mutually exclusive. `scroll=True` truncates strictly to `max_result`; `paginate=True` stops at `max_pages` or when the API returns no `nextPage`.
|
|
110
89
|
|
|
111
90
|
## Real-time news (WebSocket)
|
|
112
91
|
|
|
@@ -121,9 +100,9 @@ response = ws.websocket_register(q="bitcoin", language="en")
|
|
|
121
100
|
registration_id = response["results"]["registration_id"]
|
|
122
101
|
```
|
|
123
102
|
|
|
124
|
-
`websocket_register`
|
|
103
|
+
`websocket_register` accepts the familiar filter parameters (`q`, `country`, `language`, `domain`, …). Registering an identical query twice raises `NewsdataAPIError` with `status_code=409` — the existing id is in `e.response_body["results"]["registration_id"]`. `websocket_fetch()` lists every registered query, and `websocket_delete(registration_id)` removes one.
|
|
125
104
|
|
|
126
|
-
Then stream
|
|
105
|
+
Then stream — each yielded response has the familiar `status` / `totalResults` / `results` shape:
|
|
127
106
|
|
|
128
107
|
```python
|
|
129
108
|
for response in ws.stream(registration_id):
|
|
@@ -198,7 +177,7 @@ from newsdataapi import (
|
|
|
198
177
|
)
|
|
199
178
|
|
|
200
179
|
try:
|
|
201
|
-
client.
|
|
180
|
+
client.latest_api(q="news")
|
|
202
181
|
except NewsdataAuthError as e:
|
|
203
182
|
print(f"bad API key (HTTP {e.status_code})")
|
|
204
183
|
except NewsdataApiKeyLimitExceededError:
|
|
@@ -245,7 +224,7 @@ client = NewsDataApiClient(apikey, folder_path="./out")
|
|
|
245
224
|
client.save_to_csv(response, filename="latest_news")
|
|
246
225
|
```
|
|
247
226
|
|
|
248
|
-
`save_to_csv` returns a `pathlib.Path`.
|
|
227
|
+
`save_to_csv` returns a `pathlib.Path`. Cell values that are dicts or lists are stringified (`key:value,key:value` for dicts, comma-joined for lists). Quoting is delegated to the standard `csv.DictWriter`, so the output round-trips correctly through any CSV reader.
|
|
249
228
|
|
|
250
229
|
The function is also importable as a standalone:
|
|
251
230
|
|
|
@@ -275,7 +254,7 @@ client = NewsDataApiClient(
|
|
|
275
254
|
)
|
|
276
255
|
```
|
|
277
256
|
|
|
278
|
-
`base_url` (and `set_base_url()`) is the API root without a version segment; the default is `https://newsdata.io/api`, and the client adds
|
|
257
|
+
`base_url` (and `set_base_url()`) is the API root without a version segment; the default is `https://newsdata.io/api`, and the client adds the version itself. Before 0.4.0 it included the version (`https://newsdata.io/api/1/`), so drop the trailing `/1/` if you override it.
|
|
279
258
|
|
|
280
259
|
A request that fails with a server error, a rate limit, or a network error is attempted 5 times by default, sleeping 2 s, 4 s, 8 s and 16 s between attempts (30 s in total; a single sleep never exceeds `retry_backoff_max`). A 429 response is instead retried after the server's `Retry-After` plus one second (both integer-seconds and HTTP-date forms are parsed); when `Retry-After` is longer than `retry_backoff_max`, the client does not wait and raises `NewsdataRateLimitError` with `retry_after` set. The API key is redacted in log output.
|
|
281
260
|
|
|
@@ -16,7 +16,6 @@ It also shows the typed exception hierarchy in :func:`example_error_handling`.
|
|
|
16
16
|
|
|
17
17
|
from __future__ import annotations
|
|
18
18
|
|
|
19
|
-
import datetime
|
|
20
19
|
import os
|
|
21
20
|
from pathlib import Path
|
|
22
21
|
|
|
@@ -43,32 +42,29 @@ def main() -> None:
|
|
|
43
42
|
# the block exits. You can also call ``client.close()`` yourself.
|
|
44
43
|
with NewsDataApiClient(apikey, folder_path=out_dir) as client:
|
|
45
44
|
# 1. Single request — the most common pattern.
|
|
46
|
-
response = client.
|
|
45
|
+
response = client.latest_api(q="bitcoin", country="us", language="en")
|
|
47
46
|
results = response["results"]
|
|
48
47
|
print(
|
|
49
|
-
f"
|
|
50
|
-
f"total available: {response.get('
|
|
48
|
+
f"latest: {len(results)} articles, "
|
|
49
|
+
f"total available: {response.get('totalResults')}"
|
|
51
50
|
)
|
|
52
51
|
|
|
53
52
|
# 2. Pagination — yields one response per page, capped at max_pages.
|
|
54
53
|
for page_index, page in enumerate(
|
|
55
|
-
client.
|
|
54
|
+
client.crypto_api(q="ethereum", paginate=True, max_pages=3),
|
|
56
55
|
start=1,
|
|
57
56
|
):
|
|
58
57
|
print(f" crypto page {page_index}: {len(page['results'])} articles")
|
|
59
58
|
|
|
60
|
-
# 3. Scroll — auto-follows
|
|
61
|
-
|
|
62
|
-
now = datetime.datetime.now(tz=datetime.timezone.utc)
|
|
63
|
-
date_format = "%Y-%m-%d 00:00:00"
|
|
64
|
-
merged = client.news(
|
|
59
|
+
# 3. Scroll — auto-follows nextPage cursors and merges into one dict.
|
|
60
|
+
merged = client.archive_api(
|
|
65
61
|
q="apple",
|
|
66
|
-
from_date=
|
|
67
|
-
to_date=
|
|
62
|
+
from_date="2024-01-01 00:00:00",
|
|
63
|
+
to_date="2024-01-31 00:00:00",
|
|
68
64
|
scroll=True,
|
|
69
65
|
max_result=50,
|
|
70
66
|
)
|
|
71
|
-
print(f"scrolled
|
|
67
|
+
print(f"scrolled archive: {len(merged['results'])} articles")
|
|
72
68
|
|
|
73
69
|
# 4. Persist results to CSV. ``folder_path`` was set on the client, so
|
|
74
70
|
# we don't pass it again here.
|
|
@@ -85,7 +81,7 @@ def example_error_handling(apikey: str) -> None:
|
|
|
85
81
|
"""
|
|
86
82
|
with NewsDataApiClient(apikey) as client:
|
|
87
83
|
try:
|
|
88
|
-
client.
|
|
84
|
+
client.latest_api(q="news")
|
|
89
85
|
except NewsdataAuthError as e:
|
|
90
86
|
print(f"API key rejected (HTTP {e.status_code})")
|
|
91
87
|
except NewsdataRateLimitError as e:
|
|
@@ -91,11 +91,6 @@ addopts = [
|
|
|
91
91
|
"--strict-markers",
|
|
92
92
|
"-m", "not integration",
|
|
93
93
|
]
|
|
94
|
-
# The v1 methods are deprecated but most of the suite still exercises them;
|
|
95
|
-
# keep their warning out of the test summary.
|
|
96
|
-
filterwarnings = [
|
|
97
|
-
"ignore:.*is deprecated and will be removed in a future release:DeprecationWarning",
|
|
98
|
-
]
|
|
99
94
|
|
|
100
95
|
[tool.ruff]
|
|
101
96
|
line-length = 100
|
|
@@ -5,7 +5,6 @@ from __future__ import annotations
|
|
|
5
5
|
import logging
|
|
6
6
|
import os
|
|
7
7
|
import time
|
|
8
|
-
import warnings
|
|
9
8
|
from collections.abc import Iterator, Mapping
|
|
10
9
|
from datetime import datetime, timezone
|
|
11
10
|
from email.utils import parsedate_to_datetime
|
|
@@ -361,16 +360,6 @@ def _redact_url(url: str, param: str = "apikey") -> str:
|
|
|
361
360
|
return urlunparse(parsed._replace(query=urlencode(pairs)))
|
|
362
361
|
|
|
363
362
|
|
|
364
|
-
def _warn_deprecated(old: str, new: str) -> None:
|
|
365
|
-
"""Warn that the v1 method ``old`` is deprecated in favor of ``new``."""
|
|
366
|
-
warnings.warn(
|
|
367
|
-
f"{old}() is deprecated and will be removed in a future release; "
|
|
368
|
-
f"use {new}() instead.",
|
|
369
|
-
DeprecationWarning,
|
|
370
|
-
stacklevel=3, # point at the code that called the deprecated method
|
|
371
|
-
)
|
|
372
|
-
|
|
373
|
-
|
|
374
363
|
# ---------------------------------------------------------------------------
|
|
375
364
|
# Client.
|
|
376
365
|
# ---------------------------------------------------------------------------
|
|
@@ -384,17 +373,13 @@ class NewsDataApiClient:
|
|
|
384
373
|
with NewsDataApiClient("YOUR_API_KEY") as client:
|
|
385
374
|
response = client.news(q="bitcoin", country="us")
|
|
386
375
|
|
|
387
|
-
The ``*_api`` methods (:meth:`latest_api`, :meth:`archive_api`, ...) are
|
|
388
|
-
deprecated; use :meth:`news`, :meth:`market`, :meth:`crypto`,
|
|
389
|
-
:meth:`sources` and the ``count_*`` methods instead.
|
|
390
|
-
|
|
391
376
|
The client owns a single :class:`requests.Session` for connection
|
|
392
377
|
pooling. Pass ``session=...`` to inject your own (it will not be closed
|
|
393
378
|
by the client). Use the context manager (``with``) form, or call
|
|
394
379
|
:meth:`close` explicitly, to release the session.
|
|
395
380
|
|
|
396
381
|
All endpoint parameters are keyword-only except for the required
|
|
397
|
-
``from_date`` / ``to_date`` on the
|
|
382
|
+
``from_date`` / ``to_date`` on the ``*count_api`` methods.
|
|
398
383
|
Most parameters accept either a single string or a ``list[str]``; lists
|
|
399
384
|
are comma-joined before being sent to the API.
|
|
400
385
|
"""
|
|
@@ -560,15 +545,11 @@ class NewsDataApiClient:
|
|
|
560
545
|
) -> dict[str, Any] | Iterator[dict[str, Any]]:
|
|
561
546
|
"""Fetch latest news.
|
|
562
547
|
|
|
563
|
-
.. deprecated:: 0.4.0
|
|
564
|
-
Use :meth:`news` instead.
|
|
565
|
-
|
|
566
548
|
See https://newsdata.io/documentation for parameter descriptions.
|
|
567
549
|
|
|
568
550
|
Returns a dict by default, the merged dict if ``scroll=True``, or
|
|
569
551
|
an iterator of per-page dicts if ``paginate=True``.
|
|
570
552
|
"""
|
|
571
|
-
_warn_deprecated("latest_api", "news")
|
|
572
553
|
return self._dispatch(
|
|
573
554
|
constants.LATEST_ENDPOINT,
|
|
574
555
|
{
|
|
@@ -658,12 +639,8 @@ class NewsDataApiClient:
|
|
|
658
639
|
) -> dict[str, Any] | Iterator[dict[str, Any]]:
|
|
659
640
|
"""Fetch news from the archive.
|
|
660
641
|
|
|
661
|
-
.. deprecated:: 0.4.0
|
|
662
|
-
Use :meth:`news` instead.
|
|
663
|
-
|
|
664
642
|
See https://newsdata.io/documentation for parameter descriptions.
|
|
665
643
|
"""
|
|
666
|
-
_warn_deprecated("archive_api", "news")
|
|
667
644
|
return self._dispatch(
|
|
668
645
|
constants.ARCHIVE_ENDPOINT,
|
|
669
646
|
{
|
|
@@ -721,13 +698,9 @@ class NewsDataApiClient:
|
|
|
721
698
|
) -> dict[str, Any]:
|
|
722
699
|
"""List available news sources.
|
|
723
700
|
|
|
724
|
-
.. deprecated:: 0.4.0
|
|
725
|
-
Use :meth:`sources` instead.
|
|
726
|
-
|
|
727
701
|
Sources is a single-page endpoint; ``scroll`` and ``paginate`` are
|
|
728
702
|
not supported.
|
|
729
703
|
"""
|
|
730
|
-
_warn_deprecated("sources_api", "sources")
|
|
731
704
|
params = _validate_params(
|
|
732
705
|
{
|
|
733
706
|
"country": country,
|
|
@@ -778,12 +751,8 @@ class NewsDataApiClient:
|
|
|
778
751
|
) -> dict[str, Any] | Iterator[dict[str, Any]]:
|
|
779
752
|
"""Fetch cryptocurrency news.
|
|
780
753
|
|
|
781
|
-
.. deprecated:: 0.4.0
|
|
782
|
-
Use :meth:`crypto` instead.
|
|
783
|
-
|
|
784
754
|
See https://newsdata.io/documentation for parameter descriptions.
|
|
785
755
|
"""
|
|
786
|
-
_warn_deprecated("crypto_api", "crypto")
|
|
787
756
|
return self._dispatch(
|
|
788
757
|
constants.CRYPTO_ENDPOINT,
|
|
789
758
|
{
|
|
@@ -866,12 +835,8 @@ class NewsDataApiClient:
|
|
|
866
835
|
) -> dict[str, Any] | Iterator[dict[str, Any]]:
|
|
867
836
|
"""Fetch market / financial news.
|
|
868
837
|
|
|
869
|
-
.. deprecated:: 0.4.0
|
|
870
|
-
Use :meth:`market` instead.
|
|
871
|
-
|
|
872
838
|
See https://newsdata.io/documentation for parameter descriptions.
|
|
873
839
|
"""
|
|
874
|
-
_warn_deprecated("market_api", "market")
|
|
875
840
|
return self._dispatch(
|
|
876
841
|
constants.MARKET_ENDPOINT,
|
|
877
842
|
{
|
|
@@ -958,16 +923,12 @@ class NewsDataApiClient:
|
|
|
958
923
|
) -> dict[str, Any] | Iterator[dict[str, Any]]:
|
|
959
924
|
"""Fetch aggregate counts of news for a date range.
|
|
960
925
|
|
|
961
|
-
.. deprecated:: 0.4.0
|
|
962
|
-
Use :meth:`count_news` instead.
|
|
963
|
-
|
|
964
926
|
``from_date`` and ``to_date`` are required. Returns a dict by
|
|
965
927
|
default, the merged dict if ``scroll=True`` (concatenates per-bucket
|
|
966
928
|
rows from every page; the final aggregate dict, if any, is captured
|
|
967
929
|
under the ``aggregate`` key of the merged response), or an iterator
|
|
968
930
|
of per-page dicts if ``paginate=True``.
|
|
969
931
|
"""
|
|
970
|
-
_warn_deprecated("count_api", "count_news")
|
|
971
932
|
return self._dispatch(
|
|
972
933
|
constants.COUNT_ENDPOINT,
|
|
973
934
|
{
|
|
@@ -1045,15 +1006,11 @@ class NewsDataApiClient:
|
|
|
1045
1006
|
) -> dict[str, Any] | Iterator[dict[str, Any]]:
|
|
1046
1007
|
"""Fetch aggregate counts of crypto news for a date range.
|
|
1047
1008
|
|
|
1048
|
-
.. deprecated:: 0.4.0
|
|
1049
|
-
Use :meth:`count_crypto` instead.
|
|
1050
|
-
|
|
1051
1009
|
``from_date`` and ``to_date`` are required. Returns a dict by
|
|
1052
1010
|
default, the merged dict if ``scroll=True`` (final aggregate dict,
|
|
1053
1011
|
if any, captured under ``aggregate`` key), or an iterator of
|
|
1054
1012
|
per-page dicts if ``paginate=True``.
|
|
1055
1013
|
"""
|
|
1056
|
-
_warn_deprecated("crypto_count_api", "count_crypto")
|
|
1057
1014
|
return self._dispatch(
|
|
1058
1015
|
constants.CRYPTO_COUNT_ENDPOINT,
|
|
1059
1016
|
{
|
|
@@ -1129,15 +1086,11 @@ class NewsDataApiClient:
|
|
|
1129
1086
|
) -> dict[str, Any] | Iterator[dict[str, Any]]:
|
|
1130
1087
|
"""Fetch aggregate counts of market news for a date range.
|
|
1131
1088
|
|
|
1132
|
-
.. deprecated:: 0.4.0
|
|
1133
|
-
Use :meth:`count_market` instead.
|
|
1134
|
-
|
|
1135
1089
|
``from_date`` and ``to_date`` are required. Returns a dict by
|
|
1136
1090
|
default, the merged dict if ``scroll=True`` (final aggregate dict,
|
|
1137
1091
|
if any, captured under ``aggregate`` key), or an iterator of
|
|
1138
1092
|
per-page dicts if ``paginate=True``.
|
|
1139
1093
|
"""
|
|
1140
|
-
_warn_deprecated("market_count_api", "count_market")
|
|
1141
1094
|
return self._dispatch(
|
|
1142
1095
|
constants.MARKET_COUNT_ENDPOINT,
|
|
1143
1096
|
{
|
|
@@ -21,8 +21,8 @@ def save_to_csv(
|
|
|
21
21
|
"""Write ``response['results']`` to a CSV file inside ``folder_path``.
|
|
22
22
|
|
|
23
23
|
Nested fields get one column each, named with dots (``source.name``).
|
|
24
|
-
In responses from the
|
|
25
|
-
|
|
24
|
+
In responses from the ``*_api`` methods, dict and list cell values are
|
|
25
|
+
stringified instead.
|
|
26
26
|
|
|
27
27
|
Args:
|
|
28
28
|
response: A response dict from the NewsData API. Expected to have a
|
|
@@ -9,7 +9,6 @@ from __future__ import annotations
|
|
|
9
9
|
|
|
10
10
|
import csv
|
|
11
11
|
import sys
|
|
12
|
-
import warnings
|
|
13
12
|
from datetime import datetime, timedelta, timezone
|
|
14
13
|
from email.utils import format_datetime
|
|
15
14
|
from pathlib import Path
|
|
@@ -1909,63 +1908,6 @@ def test_v2_scroll_and_paginate_mutually_exclusive(client: NewsDataApiClient) ->
|
|
|
1909
1908
|
client.news(scroll=True, paginate=True)
|
|
1910
1909
|
|
|
1911
1910
|
|
|
1912
|
-
# ===========================================================================
|
|
1913
|
-
# v1 deprecation
|
|
1914
|
-
# ===========================================================================
|
|
1915
|
-
|
|
1916
|
-
|
|
1917
|
-
@pytest.mark.parametrize(
|
|
1918
|
-
("method_name", "endpoint_path", "args", "replacement"),
|
|
1919
|
-
[
|
|
1920
|
-
("latest_api", "latest", (), "news"),
|
|
1921
|
-
("archive_api", "archive", (), "news"),
|
|
1922
|
-
("sources_api", "sources", (), "sources"),
|
|
1923
|
-
("crypto_api", "crypto", (), "crypto"),
|
|
1924
|
-
("market_api", "market", (), "market"),
|
|
1925
|
-
("count_api", "count", ("2024-01-01", "2024-01-31"), "count_news"),
|
|
1926
|
-
("crypto_count_api", "crypto/count", ("2024-01-01", "2024-01-31"), "count_crypto"),
|
|
1927
|
-
("market_count_api", "market/count", ("2024-01-01", "2024-01-31"), "count_market"),
|
|
1928
|
-
],
|
|
1929
|
-
)
|
|
1930
|
-
def test_v1_methods_warn_deprecated(
|
|
1931
|
-
client: NewsDataApiClient,
|
|
1932
|
-
mocked_responses: responses.RequestsMock,
|
|
1933
|
-
method_name: str,
|
|
1934
|
-
endpoint_path: str,
|
|
1935
|
-
args: tuple[str, ...],
|
|
1936
|
-
replacement: str,
|
|
1937
|
-
) -> None:
|
|
1938
|
-
"""Each v1 method warns once, names its replacement, and still works."""
|
|
1939
|
-
mocked_responses.get(
|
|
1940
|
-
f"https://newsdata.io/api/1/{endpoint_path}",
|
|
1941
|
-
json={"status": "success", "results": []},
|
|
1942
|
-
status=200,
|
|
1943
|
-
)
|
|
1944
|
-
with pytest.warns(
|
|
1945
|
-
DeprecationWarning,
|
|
1946
|
-
match=rf"^{method_name}\(\) is deprecated .* use {replacement}\(\) instead\.$",
|
|
1947
|
-
) as record:
|
|
1948
|
-
response = getattr(client, method_name)(*args)
|
|
1949
|
-
assert response["status"] == "success"
|
|
1950
|
-
# Exactly one warning, attributed to the calling code (this file).
|
|
1951
|
-
assert [w.filename for w in record if w.category is DeprecationWarning] == [__file__]
|
|
1952
|
-
|
|
1953
|
-
|
|
1954
|
-
def test_v2_methods_do_not_warn(
|
|
1955
|
-
client: NewsDataApiClient,
|
|
1956
|
-
mocked_responses: responses.RequestsMock,
|
|
1957
|
-
) -> None:
|
|
1958
|
-
mocked_responses.get(
|
|
1959
|
-
NEWS_V2_URL,
|
|
1960
|
-
json={"status": "success", "total_results": 0, "results": []},
|
|
1961
|
-
status=200,
|
|
1962
|
-
)
|
|
1963
|
-
with warnings.catch_warnings(record=True) as record:
|
|
1964
|
-
warnings.simplefilter("always")
|
|
1965
|
-
client.news(q="x")
|
|
1966
|
-
assert not [w for w in record if "is deprecated" in str(w.message)]
|
|
1967
|
-
|
|
1968
|
-
|
|
1969
1911
|
# ===========================================================================
|
|
1970
1912
|
# WebSocket query management (register / fetch / delete)
|
|
1971
1913
|
# ===========================================================================
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|