newsdataapi 0.3.5__tar.gz → 0.4.0__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.3.5 → newsdataapi-0.4.0}/PKG-INFO +49 -26
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/README.md +48 -25
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/examples/basic_usage.py +14 -10
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/pyproject.toml +5 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/src/newsdataapi/__init__.py +1 -1
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/src/newsdataapi/client.py +647 -19
- newsdataapi-0.4.0/src/newsdataapi/constants.py +43 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/src/newsdataapi/csv_export.py +35 -1
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/src/newsdataapi/exceptions.py +6 -4
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/src/newsdataapi/websocket.py +1 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/tests/test_integration.py +45 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/tests/test_unit.py +593 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/tests/test_websocket.py +14 -0
- newsdataapi-0.3.5/src/newsdataapi/constants.py +0 -34
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/.github/workflows/ci.yml +0 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/.github/workflows/publish.yml +0 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/.gitignore +0 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/.python-version +0 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/LICENSE +0 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/examples/websocket_usage.py +0 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/newsdata-logo.png +0 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/src/newsdataapi/py.typed +0 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/tests/__init__.py +0 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/tests/conftest.py +0 -0
- {newsdataapi-0.3.5 → newsdataapi-0.4.0}/uv.lock +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: newsdataapi
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.4.0
|
|
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 (`news`, `market`, `crypto`, `sources`, `count/news`, `count/market`, `count/crypto`) 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.news(q="bitcoin", country="us", language="en")
|
|
91
91
|
for article in response["results"]:
|
|
92
|
-
print(article["title"], "-", article["
|
|
92
|
+
print(article["title"], "-", article["url"])
|
|
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.news(q="bitcoin", country="us", language="en")
|
|
103
103
|
for article in response["results"]:
|
|
104
|
-
print(article["title"], "-", article["
|
|
104
|
+
print(article["title"], "-", article["url"])
|
|
105
105
|
finally:
|
|
106
106
|
client.close()
|
|
107
107
|
```
|
|
@@ -110,34 +110,55 @@ finally:
|
|
|
110
110
|
|
|
111
111
|
| Method | Endpoint | Notes |
|
|
112
112
|
|--------|----------|-------|
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `market_count_api(from_date, to_date)` | `/market/count` | Aggregate market counts |
|
|
113
|
+
| `news()` | `/2/news` | Latest news, or historical news with `from_date` / `to_date` |
|
|
114
|
+
| `market()` | `/2/market` | Market / financial news |
|
|
115
|
+
| `crypto()` | `/2/crypto` | Cryptocurrency news |
|
|
116
|
+
| `sources()` | `/2/sources` | Available news sources |
|
|
117
|
+
| `count_news()` | `/2/count/news` | News counts per time interval |
|
|
118
|
+
| `count_market()` | `/2/count/market` | Market news counts per time interval |
|
|
119
|
+
| `count_crypto()` | `/2/count/crypto` | Crypto news counts per time interval |
|
|
121
120
|
|
|
122
|
-
All
|
|
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.
|
|
123
124
|
|
|
124
125
|
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.
|
|
125
126
|
|
|
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
|
+
|
|
126
147
|
## Three ways to consume an endpoint
|
|
127
148
|
|
|
128
149
|
```python
|
|
129
150
|
# 1. Single request (the default).
|
|
130
|
-
response = client.
|
|
151
|
+
response = client.news(q="news")
|
|
131
152
|
|
|
132
|
-
# 2. Auto-merge — follow
|
|
133
|
-
merged = client.
|
|
153
|
+
# 2. Auto-merge — follow next_page cursors and return one combined dict.
|
|
154
|
+
merged = client.news(q="news", scroll=True, max_result=200)
|
|
134
155
|
|
|
135
156
|
# 3. Iterate one response per page (a generator).
|
|
136
|
-
for page in client.
|
|
157
|
+
for page in client.news(q="news", paginate=True, max_pages=5):
|
|
137
158
|
process(page["results"])
|
|
138
159
|
```
|
|
139
160
|
|
|
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 `
|
|
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 `next_page`.
|
|
141
162
|
|
|
142
163
|
## Real-time news (WebSocket)
|
|
143
164
|
|
|
@@ -152,9 +173,9 @@ response = ws.websocket_register(q="bitcoin", language="en")
|
|
|
152
173
|
registration_id = response["results"]["registration_id"]
|
|
153
174
|
```
|
|
154
175
|
|
|
155
|
-
`websocket_register`
|
|
176
|
+
`websocket_register` takes the same parameter names as the deprecated `*_api()` methods (`q`, `qInTitle`, `country`, `excludecountry`, `domainurl`, `full_content`, …), not the names `news()` uses. 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.
|
|
156
177
|
|
|
157
|
-
Then stream
|
|
178
|
+
Then stream. Each yielded response has `status`, `totalResults` and `results` keys, and its articles carry the same fields the deprecated `*_api()` methods return (`article_id`, `link`, `pubDate`, …), not the `news()` layout:
|
|
158
179
|
|
|
159
180
|
```python
|
|
160
181
|
for response in ws.stream(registration_id):
|
|
@@ -229,7 +250,7 @@ from newsdataapi import (
|
|
|
229
250
|
)
|
|
230
251
|
|
|
231
252
|
try:
|
|
232
|
-
client.
|
|
253
|
+
client.news(q="news")
|
|
233
254
|
except NewsdataAuthError as e:
|
|
234
255
|
print(f"bad API key (HTTP {e.status_code})")
|
|
235
256
|
except NewsdataApiKeyLimitExceededError:
|
|
@@ -276,7 +297,7 @@ client = NewsDataApiClient(apikey, folder_path="./out")
|
|
|
276
297
|
client.save_to_csv(response, filename="latest_news")
|
|
277
298
|
```
|
|
278
299
|
|
|
279
|
-
`save_to_csv` returns a `pathlib.Path`.
|
|
300
|
+
`save_to_csv` returns a `pathlib.Path`. Nested fields get one column each, named with dots (`source.name`, `ai.sentiment.label`); lists are comma-joined, and lists of objects are written as JSON. Responses from the deprecated `*_api()` methods keep the old format: dict and list cells 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.
|
|
280
301
|
|
|
281
302
|
The function is also importable as a standalone:
|
|
282
303
|
|
|
@@ -300,13 +321,15 @@ client = NewsDataApiClient(
|
|
|
300
321
|
proxies={"https": "..."}, # passed with every request
|
|
301
322
|
accept_language="en", # Accept-Language header
|
|
302
323
|
include_headers=False, # if True, returned dicts include response_headers
|
|
303
|
-
base_url="...", # override for staging / proxied environments
|
|
324
|
+
base_url="...", # API root; override for staging / proxied environments
|
|
304
325
|
session=my_session, # inject your own requests.Session
|
|
305
326
|
folder_path="./out", # default folder for save_to_csv; default None
|
|
306
327
|
)
|
|
307
328
|
```
|
|
308
329
|
|
|
309
|
-
|
|
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 `/1/...` or `/2/...` itself. Before 0.4.0 it included the version (`https://newsdata.io/api/1/`), so drop the trailing `/1/` if you override it.
|
|
331
|
+
|
|
332
|
+
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.
|
|
310
333
|
|
|
311
334
|
## Development
|
|
312
335
|
|
|
@@ -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 (`news`, `market`, `crypto`, `sources`, `count/news`, `count/market`, `count/crypto`) 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.news(q="bitcoin", country="us", language="en")
|
|
39
39
|
for article in response["results"]:
|
|
40
|
-
print(article["title"], "-", article["
|
|
40
|
+
print(article["title"], "-", article["url"])
|
|
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.news(q="bitcoin", country="us", language="en")
|
|
51
51
|
for article in response["results"]:
|
|
52
|
-
print(article["title"], "-", article["
|
|
52
|
+
print(article["title"], "-", article["url"])
|
|
53
53
|
finally:
|
|
54
54
|
client.close()
|
|
55
55
|
```
|
|
@@ -58,34 +58,55 @@ finally:
|
|
|
58
58
|
|
|
59
59
|
| Method | Endpoint | Notes |
|
|
60
60
|
|--------|----------|-------|
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
68
|
-
| `market_count_api(from_date, to_date)` | `/market/count` | Aggregate market counts |
|
|
61
|
+
| `news()` | `/2/news` | Latest news, or historical news with `from_date` / `to_date` |
|
|
62
|
+
| `market()` | `/2/market` | Market / financial news |
|
|
63
|
+
| `crypto()` | `/2/crypto` | Cryptocurrency news |
|
|
64
|
+
| `sources()` | `/2/sources` | Available news sources |
|
|
65
|
+
| `count_news()` | `/2/count/news` | News counts per time interval |
|
|
66
|
+
| `count_market()` | `/2/count/market` | Market news counts per time interval |
|
|
67
|
+
| `count_crypto()` | `/2/count/crypto` | Crypto news counts per time interval |
|
|
69
68
|
|
|
70
|
-
All
|
|
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.
|
|
71
72
|
|
|
72
73
|
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.
|
|
73
74
|
|
|
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
|
+
|
|
74
95
|
## Three ways to consume an endpoint
|
|
75
96
|
|
|
76
97
|
```python
|
|
77
98
|
# 1. Single request (the default).
|
|
78
|
-
response = client.
|
|
99
|
+
response = client.news(q="news")
|
|
79
100
|
|
|
80
|
-
# 2. Auto-merge — follow
|
|
81
|
-
merged = client.
|
|
101
|
+
# 2. Auto-merge — follow next_page cursors and return one combined dict.
|
|
102
|
+
merged = client.news(q="news", scroll=True, max_result=200)
|
|
82
103
|
|
|
83
104
|
# 3. Iterate one response per page (a generator).
|
|
84
|
-
for page in client.
|
|
105
|
+
for page in client.news(q="news", paginate=True, max_pages=5):
|
|
85
106
|
process(page["results"])
|
|
86
107
|
```
|
|
87
108
|
|
|
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 `
|
|
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 `next_page`.
|
|
89
110
|
|
|
90
111
|
## Real-time news (WebSocket)
|
|
91
112
|
|
|
@@ -100,9 +121,9 @@ response = ws.websocket_register(q="bitcoin", language="en")
|
|
|
100
121
|
registration_id = response["results"]["registration_id"]
|
|
101
122
|
```
|
|
102
123
|
|
|
103
|
-
`websocket_register`
|
|
124
|
+
`websocket_register` takes the same parameter names as the deprecated `*_api()` methods (`q`, `qInTitle`, `country`, `excludecountry`, `domainurl`, `full_content`, …), not the names `news()` uses. 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.
|
|
104
125
|
|
|
105
|
-
Then stream
|
|
126
|
+
Then stream. Each yielded response has `status`, `totalResults` and `results` keys, and its articles carry the same fields the deprecated `*_api()` methods return (`article_id`, `link`, `pubDate`, …), not the `news()` layout:
|
|
106
127
|
|
|
107
128
|
```python
|
|
108
129
|
for response in ws.stream(registration_id):
|
|
@@ -177,7 +198,7 @@ from newsdataapi import (
|
|
|
177
198
|
)
|
|
178
199
|
|
|
179
200
|
try:
|
|
180
|
-
client.
|
|
201
|
+
client.news(q="news")
|
|
181
202
|
except NewsdataAuthError as e:
|
|
182
203
|
print(f"bad API key (HTTP {e.status_code})")
|
|
183
204
|
except NewsdataApiKeyLimitExceededError:
|
|
@@ -224,7 +245,7 @@ client = NewsDataApiClient(apikey, folder_path="./out")
|
|
|
224
245
|
client.save_to_csv(response, filename="latest_news")
|
|
225
246
|
```
|
|
226
247
|
|
|
227
|
-
`save_to_csv` returns a `pathlib.Path`.
|
|
248
|
+
`save_to_csv` returns a `pathlib.Path`. Nested fields get one column each, named with dots (`source.name`, `ai.sentiment.label`); lists are comma-joined, and lists of objects are written as JSON. Responses from the deprecated `*_api()` methods keep the old format: dict and list cells 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.
|
|
228
249
|
|
|
229
250
|
The function is also importable as a standalone:
|
|
230
251
|
|
|
@@ -248,13 +269,15 @@ client = NewsDataApiClient(
|
|
|
248
269
|
proxies={"https": "..."}, # passed with every request
|
|
249
270
|
accept_language="en", # Accept-Language header
|
|
250
271
|
include_headers=False, # if True, returned dicts include response_headers
|
|
251
|
-
base_url="...", # override for staging / proxied environments
|
|
272
|
+
base_url="...", # API root; override for staging / proxied environments
|
|
252
273
|
session=my_session, # inject your own requests.Session
|
|
253
274
|
folder_path="./out", # default folder for save_to_csv; default None
|
|
254
275
|
)
|
|
255
276
|
```
|
|
256
277
|
|
|
257
|
-
|
|
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 `/1/...` or `/2/...` itself. Before 0.4.0 it included the version (`https://newsdata.io/api/1/`), so drop the trailing `/1/` if you override it.
|
|
279
|
+
|
|
280
|
+
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.
|
|
258
281
|
|
|
259
282
|
## Development
|
|
260
283
|
|
|
@@ -16,6 +16,7 @@ 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
|
|
19
20
|
import os
|
|
20
21
|
from pathlib import Path
|
|
21
22
|
|
|
@@ -42,29 +43,32 @@ def main() -> None:
|
|
|
42
43
|
# the block exits. You can also call ``client.close()`` yourself.
|
|
43
44
|
with NewsDataApiClient(apikey, folder_path=out_dir) as client:
|
|
44
45
|
# 1. Single request — the most common pattern.
|
|
45
|
-
response = client.
|
|
46
|
+
response = client.news(q="bitcoin", country="us", language="en")
|
|
46
47
|
results = response["results"]
|
|
47
48
|
print(
|
|
48
|
-
f"
|
|
49
|
-
f"total available: {response.get('
|
|
49
|
+
f"news: {len(results)} articles, "
|
|
50
|
+
f"total available: {response.get('total_results')}"
|
|
50
51
|
)
|
|
51
52
|
|
|
52
53
|
# 2. Pagination — yields one response per page, capped at max_pages.
|
|
53
54
|
for page_index, page in enumerate(
|
|
54
|
-
client.
|
|
55
|
+
client.crypto(q="ethereum", paginate=True, max_pages=3),
|
|
55
56
|
start=1,
|
|
56
57
|
):
|
|
57
58
|
print(f" crypto page {page_index}: {len(page['results'])} articles")
|
|
58
59
|
|
|
59
|
-
# 3. Scroll — auto-follows
|
|
60
|
-
|
|
60
|
+
# 3. Scroll — auto-follows next_page cursors and merges into one dict.
|
|
61
|
+
# ``from_date`` / ``to_date`` select historical news.
|
|
62
|
+
now = datetime.datetime.now(tz=datetime.timezone.utc)
|
|
63
|
+
date_format = "%Y-%m-%d 00:00:00"
|
|
64
|
+
merged = client.news(
|
|
61
65
|
q="apple",
|
|
62
|
-
from_date=
|
|
63
|
-
to_date=
|
|
66
|
+
from_date=(now - datetime.timedelta(days=7)).strftime(date_format),
|
|
67
|
+
to_date=(now - datetime.timedelta(days=1)).strftime(date_format),
|
|
64
68
|
scroll=True,
|
|
65
69
|
max_result=50,
|
|
66
70
|
)
|
|
67
|
-
print(f"scrolled
|
|
71
|
+
print(f"scrolled news: {len(merged['results'])} articles")
|
|
68
72
|
|
|
69
73
|
# 4. Persist results to CSV. ``folder_path`` was set on the client, so
|
|
70
74
|
# we don't pass it again here.
|
|
@@ -81,7 +85,7 @@ def example_error_handling(apikey: str) -> None:
|
|
|
81
85
|
"""
|
|
82
86
|
with NewsDataApiClient(apikey) as client:
|
|
83
87
|
try:
|
|
84
|
-
client.
|
|
88
|
+
client.news(q="news")
|
|
85
89
|
except NewsdataAuthError as e:
|
|
86
90
|
print(f"API key rejected (HTTP {e.status_code})")
|
|
87
91
|
except NewsdataRateLimitError as e:
|
|
@@ -91,6 +91,11 @@ 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
|
+
]
|
|
94
99
|
|
|
95
100
|
[tool.ruff]
|
|
96
101
|
line-length = 100
|