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.
Files changed (24) hide show
  1. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/PKG-INFO +25 -46
  2. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/README.md +24 -45
  3. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/examples/basic_usage.py +10 -14
  4. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/pyproject.toml +0 -5
  5. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/__init__.py +1 -1
  6. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/client.py +1 -48
  7. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/csv_export.py +2 -2
  8. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/tests/test_unit.py +0 -58
  9. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/.github/workflows/ci.yml +0 -0
  10. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/.github/workflows/publish.yml +0 -0
  11. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/.gitignore +0 -0
  12. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/.python-version +0 -0
  13. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/LICENSE +0 -0
  14. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/examples/websocket_usage.py +0 -0
  15. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/newsdata-logo.png +0 -0
  16. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/constants.py +0 -0
  17. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/exceptions.py +0 -0
  18. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/py.typed +0 -0
  19. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/src/newsdataapi/websocket.py +0 -0
  20. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/tests/__init__.py +0 -0
  21. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/tests/conftest.py +0 -0
  22. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/tests/test_integration.py +0 -0
  23. {newsdataapi-0.4.0 → newsdataapi-0.4.1}/tests/test_websocket.py +0 -0
  24. {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.0
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 (`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).
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.news(q="bitcoin", country="us", language="en")
90
+ response = client.latest_api(q="bitcoin", country="us", language="en")
91
91
  for article in response["results"]:
92
- print(article["title"], "-", article["url"])
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.news(q="bitcoin", country="us", language="en")
102
+ response = client.latest_api(q="bitcoin", country="us", language="en")
103
103
  for article in response["results"]:
104
- print(article["title"], "-", article["url"])
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
- | `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 |
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.news(q="news")
130
+ response = client.latest_api(q="news")
152
131
 
153
- # 2. Auto-merge — follow next_page cursors and return one combined dict.
154
- merged = client.news(q="news", scroll=True, max_result=200)
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.news(q="news", paginate=True, max_pages=5):
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 `next_page`.
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` 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.
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. 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:
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.news(q="news")
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`. 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.
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 `/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.
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 (`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).
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.news(q="bitcoin", country="us", language="en")
38
+ response = client.latest_api(q="bitcoin", country="us", language="en")
39
39
  for article in response["results"]:
40
- print(article["title"], "-", article["url"])
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.news(q="bitcoin", country="us", language="en")
50
+ response = client.latest_api(q="bitcoin", country="us", language="en")
51
51
  for article in response["results"]:
52
- print(article["title"], "-", article["url"])
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
- | `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 |
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.news(q="news")
78
+ response = client.latest_api(q="news")
100
79
 
101
- # 2. Auto-merge — follow next_page cursors and return one combined dict.
102
- merged = client.news(q="news", scroll=True, max_result=200)
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.news(q="news", paginate=True, max_pages=5):
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 `next_page`.
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` 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.
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. 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:
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.news(q="news")
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`. 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.
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 `/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.
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.news(q="bitcoin", country="us", language="en")
45
+ response = client.latest_api(q="bitcoin", country="us", language="en")
47
46
  results = response["results"]
48
47
  print(
49
- f"news: {len(results)} articles, "
50
- f"total available: {response.get('total_results')}"
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.crypto(q="ethereum", paginate=True, max_pages=3),
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 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(
59
+ # 3. Scroll — auto-follows nextPage cursors and merges into one dict.
60
+ merged = client.archive_api(
65
61
  q="apple",
66
- from_date=(now - datetime.timedelta(days=7)).strftime(date_format),
67
- to_date=(now - datetime.timedelta(days=1)).strftime(date_format),
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 news: {len(merged['results'])} articles")
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.news(q="news")
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
@@ -17,7 +17,7 @@ from .exceptions import (
17
17
  )
18
18
  from .websocket import NewsDataApiWebSocket
19
19
 
20
- __version__ = "0.4.0"
20
+ __version__ = "0.4.1"
21
21
 
22
22
  __all__ = [
23
23
  "NewsDataApiClient",
@@ -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 deprecated ``*count_api`` methods.
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 deprecated ``*_api`` methods, dict and list cell
25
- values are stringified instead.
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