rate-api-python 1.0.0__py3-none-any.whl

rate_api/__init__.py

@@ -0,0 +1,183 @@
+"""Official Python client for the Rate-API.com exchange-rate & crypto API.
+
+Uses only the standard library (urllib) — no dependencies.
+
+    from rate_api import RateApiClient
+    rates = RateApiClient("YOUR_API_KEY").latest("USD", ["EUR", "GBP"])
+"""
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+__version__ = "1.0.0"
+__all__ = ["RateApiClient", "RateApiError", "RateLimitError", "RateApiTimeoutError"]
+
+
+class RateApiError(Exception):
+    def __init__(self, message, status=None, type=None, request_id=None):
+        super().__init__(message)
+        self.status = status        # HTTP status (None for network/timeout)
+        self.type = type            # stable error.type slug from the API
+        self.request_id = request_id  # X-Request-Id for support correlation
+
+
+class RateLimitError(RateApiError):
+    """Raised on HTTP 429; carries retry_after (seconds)."""
+    def __init__(self, message, status=None, type=None, request_id=None, retry_after=60):
+        super().__init__(message, status, type, request_id)
+        self.retry_after = retry_after
+
+
+class RateApiTimeoutError(RateApiError):
+    """Raised when a request exceeds the timeout."""
+
+
+class RateApiClient:
+    def __init__(self, api_key, base_url="https://rate-api.com/api/v1", timeout=15, max_retries=2):
+        if not api_key:
+            raise RateApiError("An API key is required.")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    def latest(self, base="USD", symbols=None):
+        return self._get("latest", self._with_symbols({"base": base}, symbols))
+
+    def convert(self, from_currency, to_currency, amount):
+        return self._get("convert", {"from": from_currency, "to": to_currency, "amount": amount})
+
+    def historical(self, date, base="USD", symbols=None):
+        return self._get("historical", self._with_symbols({"date": date, "base": base}, symbols))
+
+    def pair(self, from_currency, to_currency):
+        return self._get(f"pair/{urllib.parse.quote(from_currency)}/{urllib.parse.quote(to_currency)}")
+
+    def timeseries(self, start_date, end_date, base="USD", symbols=None):
+        return self._get("timeseries", self._with_symbols(
+            {"start_date": start_date, "end_date": end_date, "base": base}, symbols))
+
+    def fluctuation(self, start_date, end_date, base="USD", symbols=None):
+        return self._get("fluctuation", self._with_symbols(
+            {"start_date": start_date, "end_date": end_date, "base": base}, symbols))
+
+    def crypto(self, symbols=None):
+        query = {"symbols": ",".join(symbols)} if symbols else {}
+        return self._get("crypto", query)
+
+    def currencies(self):
+        return self._get("currencies")
+
+    def health(self):
+        return self._request(f"{self.base_url}/health", {})
+
+    # ---- v2 endpoints (resolve to /api/v2 regardless of the configured base) ----
+
+    def _v2_base(self):
+        if self.base_url.endswith("/v1"):
+            return self.base_url[:-3] + "/v2"
+        return self.base_url.replace("/v1/", "/v2/")
+
+    def latest_v2(self, base="USD", symbols=None, include_metadata=False, include_change=False, precision=None):
+        """v2 latest with metadata / 24h change / precision options."""
+        query = self._with_symbols({"base": base}, symbols)
+        if include_metadata:
+            query["include_metadata"] = "true"
+        if include_change:
+            query["include_change"] = "true"
+        if precision is not None:
+            query["precision"] = precision
+        return self._request(f"{self._v2_base()}/{self.api_key}/latest", query)
+
+    def historical_compare(self, date, compare_date=None, base="USD", symbols=None):
+        """v2 historical with an optional compare_date for per-currency deltas (Pro+)."""
+        query = self._with_symbols({"date": date, "base": base}, symbols)
+        if compare_date:
+            query["compare_date"] = compare_date
+        return self._request(f"{self._v2_base()}/{self.api_key}/historical", query)
+
+    def batch_convert(self, conversions):
+        """v2 batch conversion: list of {"from","to","amount"} dicts (Pro+). Max 100."""
+        return self._request(f"{self._v2_base()}/{self.api_key}/batch-convert", {}, method="POST", body=conversions)
+
+    def alerts(self):
+        """List your configured rate alerts (Business+). Manage them in the dashboard."""
+        return self._request(f"{self._v2_base()}/{self.api_key}/alerts", {})
+
+    @staticmethod
+    def _with_symbols(query, symbols):
+        if symbols:
+            query["symbols"] = ",".join(symbols)
+        return query
+
+    def _get(self, endpoint, query=None):
+        return self._request(f"{self.base_url}/{self.api_key}/{endpoint}", query or {})
+
+    @staticmethod
+    def _retry_after(headers, default=60):
+        try:
+            return int(headers.get("Retry-After", default))
+        except (TypeError, ValueError):
+            return default
+
+    def _backoff(self, attempt, headers):
+        ra = self._retry_after(headers, default=0)
+        return min(ra, 30) if ra else min(2 ** (attempt - 1), 8)
+
+    def _request(self, url, query, method="GET", body=None):
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+        headers = {
+            "Accept": "application/json",
+            "X-API-Key": self.api_key,
+            "User-Agent": "rate-api-python/1.0",
+        }
+        data_bytes = None
+        if body is not None:
+            data_bytes = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        attempt = 0
+        while True:
+            req = urllib.request.Request(url, data=data_bytes, method=method, headers=headers)
+            status = None
+            resp_headers = {}
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    status = resp.status
+                    resp_headers = dict(resp.headers)
+                    data = json.loads(resp.read().decode("utf-8"))
+            except urllib.error.HTTPError as e:
+                status = e.code
+                resp_headers = dict(e.headers or {})
+                # Retry transient statuses, honoring Retry-After.
+                if status in (429, 503) and attempt < self.max_retries:
+                    attempt += 1
+                    time.sleep(self._backoff(attempt, resp_headers))
+                    continue
+                try:
+                    data = json.loads(e.read().decode("utf-8"))  # API returns JSON error bodies
+                except Exception:
+                    raise RateApiError(f"HTTP {status}", status)
+            except OSError as e:  # URLError, socket.timeout, TimeoutError all subclass OSError
+                if attempt < self.max_retries:
+                    attempt += 1
+                    time.sleep(self._backoff(attempt, {}))
+                    continue
+                reason = str(getattr(e, "reason", e))
+                if isinstance(e, TimeoutError) or "timed out" in reason.lower():
+                    raise RateApiTimeoutError(f"Request timed out after {self.timeout}s")
+                raise RateApiError(f"Request failed: {reason}")
+
+            if isinstance(data, dict) and data.get("success") is False:
+                err = data.get("error") or {}
+                msg = err.get("message") or data.get("message") or "Unknown API error"
+                etype = err.get("type")
+                rid = data.get("request_id") or resp_headers.get("X-Request-Id")
+                if status == 429:
+                    raise RateLimitError(msg, status, etype, rid, self._retry_after(resp_headers))
+                raise RateApiError(msg, status, etype, rid)
+            return data

rate_api_python-1.0.0.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: rate-api-python
+Version: 1.0.0
+Summary: Official Python client for the Rate-API.com exchange-rate & crypto API
+License: MIT
+Project-URL: Homepage, https://rate-api.com
+Project-URL: Documentation, https://rate-api.com/en/docs
+Project-URL: Repository, https://github.com/Vilgar/rate-api.com
+Keywords: exchange-rate,currency,forex,crypto,api,rate-api
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# rate-api-python
+
+Official Python client for [Rate-API.com](https://rate-api.com). Standard library only — no dependencies. Python 3.8+.
+
+## Install
+
+```bash
+pip install rate-api-python
+```
+
+## Usage
+
+```python
+from rate_api import RateApiClient, RateApiError
+
+client = RateApiClient("YOUR_API_KEY")
+
+rates = client.latest("USD", ["EUR", "GBP"])
+print(rates["rates"]["EUR"])
+
+client.convert("USD", "EUR", 100)                 # Pro+
+client.historical("2026-01-15", "USD", ["EUR"])   # Pro+
+client.timeseries("2026-01-01", "2026-01-31")     # Business+
+client.crypto(["BTC", "ETH"])                      # Pro+
+client.health()                                    # public
+
+try:
+    client.timeseries("2020-01-01", "2026-12-31")
+except RateApiError as e:
+    print(e, e.status)   # "Date range too large. Maximum is 366 days." 400
+```
+
+## v2 features
+
+The client exposes the v2 endpoints directly (they resolve to `/api/v2` regardless of base URL):
+
+```python
+# Latest with 24h change, metadata and precision
+r = client.latest_v2("USD", ["EUR", "GBP"], include_change=True, include_metadata=True, precision=4)
+print(r["changes_pct"]["EUR"])
+
+# Historical comparison between two dates (Pro+)
+cmp = client.historical_compare("2026-01-15", "2026-01-01", "USD", ["EUR"])
+
+# Batch conversion — up to 100 pairs in one call (Pro+)
+batch = client.batch_convert([
+    {"from": "USD", "to": "EUR", "amount": 100},
+    {"from": "GBP", "to": "JPY", "amount": 50},
+])
+
+# Your configured rate alerts (Business+)
+alerts = client.alerts()
+```
+
+## License
+
+MIT

rate_api_python-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+rate_api/__init__.py,sha256=J9mVlZ0hKr_S1jq3mnXNBnZFTwa5ro_EswEcR1IipXo,7806
+rate_api_python-1.0.0.dist-info/licenses/LICENSE,sha256=nCjIn_oDw98qUrGtfT5o19Qk02nDpkr3xbKgFtu3Z0A,1069
+rate_api_python-1.0.0.dist-info/METADATA,sha256=0Z9I8Lyh_JiGDXwFhCX6fPobnXUnUaFug01nTh1VCkY,2030
+rate_api_python-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rate_api_python-1.0.0.dist-info/top_level.txt,sha256=y8GBQa9yzwxT17UjU9xreA4yPbHqup7c0ryMbx1gYzI,9
+rate_api_python-1.0.0.dist-info/RECORD,,

rate_api_python-1.0.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
+

rate_api_python-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rate-API.com
+
+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.

rate_api_python-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rate_api