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.
Files changed (25) hide show
  1. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/PKG-INFO +49 -26
  2. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/README.md +48 -25
  3. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/examples/basic_usage.py +14 -10
  4. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/pyproject.toml +5 -0
  5. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/src/newsdataapi/__init__.py +1 -1
  6. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/src/newsdataapi/client.py +647 -19
  7. newsdataapi-0.4.0/src/newsdataapi/constants.py +43 -0
  8. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/src/newsdataapi/csv_export.py +35 -1
  9. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/src/newsdataapi/exceptions.py +6 -4
  10. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/src/newsdataapi/websocket.py +1 -0
  11. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/tests/test_integration.py +45 -0
  12. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/tests/test_unit.py +593 -0
  13. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/tests/test_websocket.py +14 -0
  14. newsdataapi-0.3.5/src/newsdataapi/constants.py +0 -34
  15. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/.github/workflows/ci.yml +0 -0
  16. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/.github/workflows/publish.yml +0 -0
  17. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/.gitignore +0 -0
  18. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/.python-version +0 -0
  19. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/LICENSE +0 -0
  20. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/examples/websocket_usage.py +0 -0
  21. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/newsdata-logo.png +0 -0
  22. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/src/newsdataapi/py.typed +0 -0
  23. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/tests/__init__.py +0 -0
  24. {newsdataapi-0.3.5 → newsdataapi-0.4.0}/tests/conftest.py +0 -0
  25. {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.5
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 (`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).
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.latest_api(q="bitcoin", country="us", language="en")
90
+ response = client.news(q="bitcoin", country="us", language="en")
91
91
  for article in response["results"]:
92
- print(article["title"], "-", article["link"])
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.latest_api(q="bitcoin", country="us", language="en")
102
+ response = client.news(q="bitcoin", country="us", language="en")
103
103
  for article in response["results"]:
104
- print(article["title"], "-", article["link"])
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
- | `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 |
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 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).
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.latest_api(q="news")
151
+ response = client.news(q="news")
131
152
 
132
- # 2. Auto-merge — follow nextPage cursors and return one combined dict.
133
- merged = client.latest_api(q="news", scroll=True, max_result=200)
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.latest_api(q="news", paginate=True, max_pages=5):
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 `nextPage`.
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` 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.
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 — each yielded response has the familiar `status` / `totalResults` / `results` shape:
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.latest_api(q="news")
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`. 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.
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
- Defaults sleep about a minute total across all retries (2 s → 4 s → 8 s → 16 s → 32 s, capped at 60 s); 429 responses honor `Retry-After` (both integer-seconds and HTTP-date forms are parsed). The API key is redacted in log output.
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 (`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).
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.latest_api(q="bitcoin", country="us", language="en")
38
+ response = client.news(q="bitcoin", country="us", language="en")
39
39
  for article in response["results"]:
40
- print(article["title"], "-", article["link"])
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.latest_api(q="bitcoin", country="us", language="en")
50
+ response = client.news(q="bitcoin", country="us", language="en")
51
51
  for article in response["results"]:
52
- print(article["title"], "-", article["link"])
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
- | `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 |
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 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).
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.latest_api(q="news")
99
+ response = client.news(q="news")
79
100
 
80
- # 2. Auto-merge — follow nextPage cursors and return one combined dict.
81
- merged = client.latest_api(q="news", scroll=True, max_result=200)
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.latest_api(q="news", paginate=True, max_pages=5):
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 `nextPage`.
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` 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.
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 — each yielded response has the familiar `status` / `totalResults` / `results` shape:
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.latest_api(q="news")
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`. 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.
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
- Defaults sleep about a minute total across all retries (2 s → 4 s → 8 s → 16 s → 32 s, capped at 60 s); 429 responses honor `Retry-After` (both integer-seconds and HTTP-date forms are parsed). The API key is redacted in log output.
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.latest_api(q="bitcoin", country="us", language="en")
46
+ response = client.news(q="bitcoin", country="us", language="en")
46
47
  results = response["results"]
47
48
  print(
48
- f"latest: {len(results)} articles, "
49
- f"total available: {response.get('totalResults')}"
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.crypto_api(q="ethereum", paginate=True, max_pages=3),
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 nextPage cursors and merges into one dict.
60
- merged = client.archive_api(
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="2024-01-01 00:00:00",
63
- to_date="2024-01-31 00:00:00",
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 archive: {len(merged['results'])} articles")
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.latest_api(q="news")
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
@@ -17,7 +17,7 @@ from .exceptions import (
17
17
  )
18
18
  from .websocket import NewsDataApiWebSocket
19
19
 
20
- __version__ = "0.3.5"
20
+ __version__ = "0.4.0"
21
21
 
22
22
  __all__ = [
23
23
  "NewsDataApiClient",