currentsapi 0.1.0__py3-none-any.whl

currentsapi/__init__.py

@@ -0,0 +1,21 @@
+import sys
+
+__project__ = "currentsapi"
+__version__ = "0.1.0"
+__repo__ = "https://github.com/currentslab/currentsapi-python"
+
+from .client import CurrentsAPI
+
+__all__ = ["CurrentsAPI"]
+
+
+def print_version():
+    sv = sys.version_info
+    py_version = "{}.{}.{}".format(sv.major, sv.minor, sv.micro)
+    version_parts = __version__.split(".")
+    s = "{} version: [{}], Python {}".format(__project__, __version__, py_version)
+    s += "\nMajor version: {}  (breaking changes)".format(version_parts[0])
+    s += "\nMinor version: {}  (extra feature)".format(version_parts[1])
+    s += "\nMicro version: {} (commit count)".format(version_parts[2])
+    s += "\nFind out the most recent version at {}".format(__repo__)
+    return s

currentsapi/authentication.py

@@ -0,0 +1,21 @@
+from requests.auth import AuthBase
+
+def set_header_payload(auth_key):
+    
+    return {
+        'Authorization': auth_key,
+        'Content-Type': 'Application/JSON',
+    }
+
+
+class ApiAuth(AuthBase):
+    def __init__(self, api_key):
+        if not isinstance(api_key, str):
+            raise ValueError('api_key must be string')
+        self.api_key = api_key
+
+    def __call__(self, request):
+        request.headers.update(set_header_payload(self.api_key))
+        return request
+
+

currentsapi/client.py

@@ -0,0 +1,127 @@
+import datetime
+import requests
+from dateutil import parser
+
+from currentsapi import constants
+from currentsapi.authentication import ApiAuth
+
+
+class CurrentsAPIError(Exception):
+    """Raised when the Currents API returns an error response."""
+
+    def __init__(self, response):
+        self.response = response
+        super().__init__(str(response))
+
+    @property
+    def status(self):
+        return self.response.get("status")
+
+    @property
+    def code(self):
+        return self.response.get("code")
+
+    @property
+    def message(self):
+        return self.response.get("message")
+
+
+class CurrentsAPI:
+    def __init__(
+        self,
+        api_key,
+        domain=constants.DOMAIN,
+        version=constants.VERSION,
+        timeout=30,
+    ):
+        if not isinstance(api_key, str):
+            raise ValueError("api_key must be a string")
+        self.api_key = ApiAuth(api_key)
+        self.latest_endpoint = constants.LATEST_NEWS_URL % (domain, version)
+        self.search_endpoint = constants.SEARCH_URL % (domain, version)
+        self.available_languages_endpoint = constants.AVAILABLE_LANGUAGES_URL % (domain, version)
+        self.available_regions_endpoint = constants.AVAILABLE_REGIONS_URL % (domain, version)
+        self.available_category_endpoint = constants.AVAILABLE_CATEGORIES_URL % (domain, version)
+        self.timeout = timeout
+
+    def _get(self, endpoint, params=None):
+        r = requests.get(
+            endpoint,
+            auth=self.api_key,
+            timeout=self.timeout,
+            params=params or {},
+        )
+        if r.status_code != requests.codes.ok:
+            raise CurrentsAPIError(r.json())
+        return r.json()
+
+    def latest_news(self, language=None):
+        params = {}
+        if language:
+            if not isinstance(language, str):
+                raise ValueError("language must be a string")
+            params["language"] = language
+        return self._get(self.latest_endpoint, params)
+
+    def search(
+        self,
+        language=None,
+        keywords=None,
+        country=None,
+        category=None,
+        start_date=None,
+        end_date=None,
+    ):
+        params = {}
+
+        if keywords:
+            if not isinstance(keywords, str):
+                raise ValueError("keywords must be a string")
+            params["keywords"] = keywords
+
+        if country:
+            if not isinstance(country, str):
+                raise ValueError("country must be a string")
+            params["country"] = country
+
+        if language:
+            if not isinstance(language, str):
+                raise ValueError("language must be a string")
+            params["language"] = language
+
+        if category:
+            if not isinstance(category, str):
+                raise ValueError("category must be a string")
+            params["category"] = category
+
+        if start_date:
+            date = self._parse_date(start_date, "start_date")
+            params["start_date"] = date.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+        if end_date:
+            date = self._parse_date(end_date, "end_date")
+            params["end_date"] = date.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+        return self._get(self.search_endpoint, params)
+
+    def available_languages(self):
+        return self._get(self.available_languages_endpoint)
+
+    def available_regions(self):
+        return self._get(self.available_regions_endpoint)
+
+    def available_category(self):
+        return self._get(self.available_category_endpoint)
+
+    @staticmethod
+    def _parse_date(date_value, param_name):
+        if isinstance(date_value, str):
+            return parser.parse(date_value)
+        elif isinstance(date_value, datetime.date):
+            return date_value
+        else:
+            raise ValueError(
+                "{} must be a string parsable by dateutil or a datetime/date object".format(
+                    param_name
+                )
+            )

currentsapi/constants.py

@@ -0,0 +1,9 @@
+VERSION = "v1"
+
+DOMAIN = "api.currentsapi.services"
+
+LATEST_NEWS_URL = "https://%s/%s/latest-news"
+SEARCH_URL = "https://%s/%s/search"
+AVAILABLE_LANGUAGES_URL = "https://%s/%s/available/languages"
+AVAILABLE_REGIONS_URL = "https://%s/%s/available/regions"
+AVAILABLE_CATEGORIES_URL = "https://%s/%s/available/categories"

currentsapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: currentsapi
+Version: 0.1.0
+Summary: Official Python client for the Currents API
+Home-page: https://github.com/currentslab/currentsapi-python
+Author: Currents Dev
+Author-email: ray@currentsapi.services
+License: MIT
+Keywords: currentsapi,news,wrapper,currents,api
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: requests>=2.25.0
+Requires-Dist: python-dateutil>=2.8.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# currentsapi-python
+
+The official Python SDK for the [Currents API](https://currentsapi.services/en/docs/).
+
+## Installation
+
+Install the package from PyPI. The distribution name is `currentsapi` (this
+repository is `currentsapi-python`, and the Python import name is also
+`currentsapi`):
+
+```bash
+pip install currentsapi
+```
+
+Python 3.8+ is supported.
+
+## Usage
+
+Import the client and initialize it with your API key:
+
+```python
+from currentsapi import CurrentsAPI
+
+api = CurrentsAPI(api_key="YOUR_API_KEY")
+```
+
+## Endpoints
+
+### Latest News
+
+Retrieve the latest news headlines. Optionally filter by language:
+
+```python
+api.latest_news()
+api.latest_news(language="en")
+```
+
+### Search
+
+Search news articles with optional filters:
+
+```python
+api.search(keywords="OpenAI", language="en")
+api.search(country="US", category="technology", start_date="2024-01-01", end_date="2024-12-31")
+```
+
+Supported parameters:
+
+- `keywords` – search keywords
+- `language` – article language code
+- `country` – country code
+- `category` – news category
+- `start_date` – start date (`YYYY-MM-DD` or `datetime` object)
+- `end_date` – end date (`YYYY-MM-DD` or `datetime` object)
+
+### Available Resources
+
+```python
+api.available_languages()
+api.available_regions()
+api.available_category()
+```
+
+## Examples
+
+- [Generate a source-linked news briefing](examples/source_linked_briefing/README.md) from a live Search API response or a deterministic offline fixture.
+- [Build a company news monitor](examples/company_news_monitor/README.md) with
+  a JSON watchlist, bounded search window, local state, and deterministic fixture.
+
+## Authentication
+
+All requests are authenticated using an `Authorization` header. Pass your API key when instantiating the client:
+
+```python
+api = CurrentsAPI(api_key="YOUR_API_KEY")
+```
+
+Get your API key at [https://currentsapi.services/en/register](https://currentsapi.services/en/register).
+
+## License
+
+MIT License
+
+## Error handling
+
+Any non-200 API response raises `CurrentsAPIError`, which exposes the parsed
+response body:
+
+```python
+from currentsapi.client import CurrentsAPIError
+
+try:
+    api.latest_news()
+except CurrentsAPIError as exc:
+    print(exc.status, exc.code, exc.message)
+```

currentsapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+currentsapi/__init__.py,sha256=ertxbDc6JFUAIQmufsz6up2vyQwgdlOrgSIf4J8G6Qc,727
+currentsapi/authentication.py,sha256=XMaRNF5_44QoJfC7A7K2xZAkfuV2OdWHYSmwxAj9kZA,484
+currentsapi/client.py,sha256=KZKsIgakMDFCwma10vnaScTNGJl397VrCLPlwR8L6lI,3923
+currentsapi/constants.py,sha256=vrzOu2LZ3hzlsylwQSF1U1UJTaeH8fdELHco8j8rEO8,319
+currentsapi-0.1.0.dist-info/licenses/LICENSE.txt,sha256=SvtJMl4TBu84IwF3M-5g1SGh6NnMnZ3q6Jbx5so0cU0,1069
+currentsapi-0.1.0.dist-info/METADATA,sha256=eLhkqh3wHEs6L6-JiuBG_ezZU6tSgyuUctQCcZdqKig,3654
+currentsapi-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+currentsapi-0.1.0.dist-info/top_level.txt,sha256=-fNSY7QlDmXm6IUgjyx95khZ7dlYDry5tVhHzVqVJ9E,12
+currentsapi-0.1.0.dist-info/RECORD,,

currentsapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

currentsapi-0.1.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Matt Lisivick
+
+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.

currentsapi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+currentsapi