newsdataapi 0.1.30__tar.gz → 0.2.0__tar.gz

newsdataapi-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,86 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel in-progress runs for the same branch when a new push arrives.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: pytest (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Run unit tests
+        run: uv run --python ${{ matrix.python-version }} pytest
+
+  lint:
+    name: ruff + mypy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Ruff
+        run: uv run ruff check src/ tests/ examples/
+
+      - name: Mypy
+        run: uv run mypy src/
+
+  integration:
+    # Only run live API tests on the canonical repository, on push to main.
+    # Forks won't have the secret and would fail otherwise.
+    name: live API tests
+    runs-on: ubuntu-latest
+    needs: [test, lint]
+    if: github.repository == 'bytesview/python-client' && github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Run integration tests
+        env:
+          PYTEST_TOKEN: ${{ secrets.PYTEST_NEWSDATA_API }}
+        run: |
+          if [ -z "${PYTEST_TOKEN}" ]; then
+            echo "PYTEST_NEWSDATA_API secret not set; skipping integration tests."
+            exit 0
+          fi
+          uv run pytest -m integration

newsdataapi-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Run unit tests
+        run: uv run pytest
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    # OIDC trusted publishing — no API token required.
+    # One-time setup at:
+    #   https://pypi.org/manage/project/newsdataapi/settings/publishing/
+    # Workflow filename = "publish.yml", environment = "pypi".
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/newsdataapi
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

newsdataapi-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+# Python bytecode
+__pycache__/
+
+# Virtual env (uv)
+.venv/
+
+# Build artifacts (uv build / hatchling)
+dist/
+build/
+*.egg-info/
+
+# Tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+
+# Project scratch
+temp.py
+
+# Claude Code
+CLAUDE.md
+.claude/
+
+# IDE
+.vscode/

newsdataapi-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

{newsdataapi-0.1.30 → newsdataapi-0.2.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) [year] [fullname]
+Copyright (c) 2023-2026 NewsData.io
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

newsdataapi-0.2.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: newsdataapi
+Version: 0.2.0
+Summary: Official Python SDK for the NewsData.io REST API
+Project-URL: Homepage, https://newsdata.io
+Project-URL: Documentation, https://newsdata.io/documentation
+Project-URL: Repository, https://github.com/bytesview/python-client
+Project-URL: Issues, https://github.com/bytesview/python-client/issues
+Author-email: "NewsData.io" <contact@newsdata.io>
+License: MIT License
+        
+        Copyright (c) 2023-2026 NewsData.io
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: api,news,news-data,newsdata,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: requests<3,>=2.25
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+[![NewsData.io logo](https://raw.githubusercontent.com/bytesview/python-client/main/newsdata-logo.png)](https://newsdata.io)
+
+# NewsData.io Python Client
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/bytesview/python-client/ci.yml)](https://github.com/bytesview/python-client/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/bytesview/python-client/blob/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/newsdataapi?color=084298)](https://pypi.org/project/newsdataapi)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/newsdataapi)](https://pypi.org/project/newsdataapi)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/newsdataapi)](https://pypi.org/project/newsdataapi)
+
+</div>
+
+`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.
+
+## Installation
+
+```bash
+pip install newsdataapi
+```
+
+If you use [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add newsdataapi
+```
+
+Supports Python 3.8 through 3.14. The only runtime dependency is `requests`.
+
+## Quickstart
+
+```python
+from newsdataapi import NewsDataApiClient
+
+with NewsDataApiClient("YOUR_API_KEY") as client:
+    response = client.latest_api(q="bitcoin", country="us", language="en")
+    for article in response["results"]:
+        print(article["title"], "-", article["link"])
+```
+
+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:
+
+```python
+from newsdataapi import NewsDataApiClient
+
+client = NewsDataApiClient("YOUR_API_KEY")
+try:
+    response = client.latest_api(q="bitcoin", country="us", language="en")
+    for article in response["results"]:
+        print(article["title"], "-", article["link"])
+finally:
+    client.close()
+```
+
+## Endpoints
+
+| Method | Endpoint | Notes |
+|--------|----------|-------|
+| `latest_api()` | `/latest` | Real-time news |
+| `archive_api()` | `/archive` | Historical news |
+| `sources_api()` | `/sources` | Available news sources |
+| `crypto_api()` | `/crypto` | Cryptocurrency news |
+| `market_api()` | `/market` | Market / financial news |
+| `count_api(from_date, to_date)` | `/count` | Aggregate counts |
+| `crypto_count_api(from_date, to_date)` | `/crypto/count` | Aggregate crypto counts |
+| `market_count_api(from_date, to_date)` | `/market/count` | Aggregate market counts |
+
+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.
+
+See the [NewsData.io documentation](https://newsdata.io/documentation) for the full parameter reference.
+
+## Three ways to consume an endpoint
+
+```python
+# 1. Single request (the default).
+response = client.latest_api(q="news")
+
+# 2. Auto-merge — follow nextPage cursors and return one combined dict.
+merged = client.latest_api(q="news", scroll=True, max_result=200)
+
+# 3. Iterate one response per page (a generator).
+for page in client.latest_api(q="news", paginate=True, max_pages=5):
+    process(page["results"])
+```
+
+`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`.
+
+## Error handling
+
+```python
+from newsdataapi import (
+    NewsdataAPIError,
+    NewsdataAuthError,
+    NewsdataNetworkError,
+    NewsdataRateLimitError,
+)
+
+try:
+    client.latest_api(q="news")
+except NewsdataAuthError as e:
+    print(f"bad API key (HTTP {e.status_code})")
+except NewsdataRateLimitError as e:
+    print(f"rate limited; retry after {e.retry_after}s")
+except NewsdataAPIError as e:
+    print(f"API error {e.status_code}: {e.response_body}")
+except NewsdataNetworkError as e:
+    print(f"network failure: {e.original}")
+```
+
+The full hierarchy:
+
+```
+NewsdataException
+├── NewsdataValidationError      (also a ValueError; carries .param)
+├── NewsdataAPIError             (carries .status_code, .response_body)
+│   ├── NewsdataAuthError        (401 / 403)
+│   ├── NewsdataRateLimitError   (429; carries .retry_after)
+│   └── NewsdataServerError      (5xx)
+└── NewsdataNetworkError         (carries .original)
+```
+
+`NewsdataException` is always a valid catch-all.
+
+## Save results to CSV
+
+```python
+client.save_to_csv(response, folder_path="./out", filename="latest_news")
+
+# Or set folder_path once on the client and reuse:
+client = NewsDataApiClient(apikey, folder_path="./out")
+client.save_to_csv(response, filename="latest_news")
+```
+
+`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.
+
+The function is also importable as a standalone:
+
+```python
+from newsdataapi import save_to_csv
+save_to_csv(response, folder_path="./out", filename="latest_news")
+```
+
+## Configuration
+
+```python
+client = NewsDataApiClient(
+    apikey="...",
+    request_timeout=30,         # seconds; default 30
+    max_retries=5,              # default 5
+    retry_backoff=2.0,          # base seconds, exponential; default 2.0
+    retry_backoff_max=60.0,     # cap on a single retry sleep; default 60.0
+    pagination_delay=1.0,       # seconds between pages; default 1.0
+    max_result=None,            # cap on merged results in scroll mode; default None (no cap)
+    max_pages=None,             # cap on pages yielded in paginate mode; default None (no cap)
+    proxies={"https": "..."},   # passed to requests.Session.get
+    accept_language="en",       # Accept-Language header
+    include_headers=False,      # if True, returned dicts include response_headers
+    base_url="...",             # override for staging / proxied environments
+    session=my_session,         # inject your own requests.Session
+    folder_path="./out",        # default folder for save_to_csv; default None
+)
+```
+
+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.
+
+## Development
+
+This project uses [uv](https://github.com/astral-sh/uv) for environment and lock management.
+
+```bash
+git clone https://github.com/bytesview/python-client
+cd python-client
+uv sync                                # creates .venv, installs runtime + dev deps from uv.lock
+```
+
+Run the suite:
+
+```bash
+uv run pytest                                         # unit tests only (default)
+PYTEST_TOKEN=<api-key> uv run pytest -m integration   # live-API tests
+PYTEST_TOKEN=<api-key> uv run pytest -m ""            # all tests
+
+uv run ruff check src/ tests/ examples/
+uv run mypy src/
+```
+
+Dev dependencies live in PEP 735 `[dependency-groups].dev` (uv-native). Plain `pip install -e ".[dev]"` will not pick them up; if you can't use uv, install the contents of the `dev` group in `pyproject.toml` by hand.
+
+## License
+
+MIT. See the [LICENSE](LICENSE) file.

newsdataapi-0.2.0/README.md

@@ -0,0 +1,192 @@
+<div align="center">
+
+[![NewsData.io logo](https://raw.githubusercontent.com/bytesview/python-client/main/newsdata-logo.png)](https://newsdata.io)
+
+# NewsData.io Python Client
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/bytesview/python-client/ci.yml)](https://github.com/bytesview/python-client/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/bytesview/python-client/blob/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/newsdataapi?color=084298)](https://pypi.org/project/newsdataapi)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/newsdataapi)](https://pypi.org/project/newsdataapi)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/newsdataapi)](https://pypi.org/project/newsdataapi)
+
+</div>
+
+`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.
+
+## Installation
+
+```bash
+pip install newsdataapi
+```
+
+If you use [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add newsdataapi
+```
+
+Supports Python 3.8 through 3.14. The only runtime dependency is `requests`.
+
+## Quickstart
+
+```python
+from newsdataapi import NewsDataApiClient
+
+with NewsDataApiClient("YOUR_API_KEY") as client:
+    response = client.latest_api(q="bitcoin", country="us", language="en")
+    for article in response["results"]:
+        print(article["title"], "-", article["link"])
+```
+
+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:
+
+```python
+from newsdataapi import NewsDataApiClient
+
+client = NewsDataApiClient("YOUR_API_KEY")
+try:
+    response = client.latest_api(q="bitcoin", country="us", language="en")
+    for article in response["results"]:
+        print(article["title"], "-", article["link"])
+finally:
+    client.close()
+```
+
+## Endpoints
+
+| Method | Endpoint | Notes |
+|--------|----------|-------|
+| `latest_api()` | `/latest` | Real-time news |
+| `archive_api()` | `/archive` | Historical news |
+| `sources_api()` | `/sources` | Available news sources |
+| `crypto_api()` | `/crypto` | Cryptocurrency news |
+| `market_api()` | `/market` | Market / financial news |
+| `count_api(from_date, to_date)` | `/count` | Aggregate counts |
+| `crypto_count_api(from_date, to_date)` | `/crypto/count` | Aggregate crypto counts |
+| `market_count_api(from_date, to_date)` | `/market/count` | Aggregate market counts |
+
+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.
+
+See the [NewsData.io documentation](https://newsdata.io/documentation) for the full parameter reference.
+
+## Three ways to consume an endpoint
+
+```python
+# 1. Single request (the default).
+response = client.latest_api(q="news")
+
+# 2. Auto-merge — follow nextPage cursors and return one combined dict.
+merged = client.latest_api(q="news", scroll=True, max_result=200)
+
+# 3. Iterate one response per page (a generator).
+for page in client.latest_api(q="news", paginate=True, max_pages=5):
+    process(page["results"])
+```
+
+`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`.
+
+## Error handling
+
+```python
+from newsdataapi import (
+    NewsdataAPIError,
+    NewsdataAuthError,
+    NewsdataNetworkError,
+    NewsdataRateLimitError,
+)
+
+try:
+    client.latest_api(q="news")
+except NewsdataAuthError as e:
+    print(f"bad API key (HTTP {e.status_code})")
+except NewsdataRateLimitError as e:
+    print(f"rate limited; retry after {e.retry_after}s")
+except NewsdataAPIError as e:
+    print(f"API error {e.status_code}: {e.response_body}")
+except NewsdataNetworkError as e:
+    print(f"network failure: {e.original}")
+```
+
+The full hierarchy:
+
+```
+NewsdataException
+├── NewsdataValidationError      (also a ValueError; carries .param)
+├── NewsdataAPIError             (carries .status_code, .response_body)
+│   ├── NewsdataAuthError        (401 / 403)
+│   ├── NewsdataRateLimitError   (429; carries .retry_after)
+│   └── NewsdataServerError      (5xx)
+└── NewsdataNetworkError         (carries .original)
+```
+
+`NewsdataException` is always a valid catch-all.
+
+## Save results to CSV
+
+```python
+client.save_to_csv(response, folder_path="./out", filename="latest_news")
+
+# Or set folder_path once on the client and reuse:
+client = NewsDataApiClient(apikey, folder_path="./out")
+client.save_to_csv(response, filename="latest_news")
+```
+
+`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.
+
+The function is also importable as a standalone:
+
+```python
+from newsdataapi import save_to_csv
+save_to_csv(response, folder_path="./out", filename="latest_news")
+```
+
+## Configuration
+
+```python
+client = NewsDataApiClient(
+    apikey="...",
+    request_timeout=30,         # seconds; default 30
+    max_retries=5,              # default 5
+    retry_backoff=2.0,          # base seconds, exponential; default 2.0
+    retry_backoff_max=60.0,     # cap on a single retry sleep; default 60.0
+    pagination_delay=1.0,       # seconds between pages; default 1.0
+    max_result=None,            # cap on merged results in scroll mode; default None (no cap)
+    max_pages=None,             # cap on pages yielded in paginate mode; default None (no cap)
+    proxies={"https": "..."},   # passed to requests.Session.get
+    accept_language="en",       # Accept-Language header
+    include_headers=False,      # if True, returned dicts include response_headers
+    base_url="...",             # override for staging / proxied environments
+    session=my_session,         # inject your own requests.Session
+    folder_path="./out",        # default folder for save_to_csv; default None
+)
+```
+
+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.
+
+## Development
+
+This project uses [uv](https://github.com/astral-sh/uv) for environment and lock management.
+
+```bash
+git clone https://github.com/bytesview/python-client
+cd python-client
+uv sync                                # creates .venv, installs runtime + dev deps from uv.lock
+```
+
+Run the suite:
+
+```bash
+uv run pytest                                         # unit tests only (default)
+PYTEST_TOKEN=<api-key> uv run pytest -m integration   # live-API tests
+PYTEST_TOKEN=<api-key> uv run pytest -m ""            # all tests
+
+uv run ruff check src/ tests/ examples/
+uv run mypy src/
+```
+
+Dev dependencies live in PEP 735 `[dependency-groups].dev` (uv-native). Plain `pip install -e ".[dev]"` will not pick them up; if you can't use uv, install the contents of the `dev` group in `pyproject.toml` by hand.
+
+## License
+
+MIT. See the [LICENSE](LICENSE) file.