eltoque-python 0.1.0__tar.gz → 0.1.1__tar.gz

{eltoque_python-0.1.0 → eltoque_python-0.1.1}/CHANGELOG.md

@@ -8,6 +8,19 @@ version (`1.0.beta`).
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-10-23
+
+### Added
+
+- `scripts/live_check.py`: opt-in single-request check against the real API that prints only the
+  response shape (never provider values), plus `docs/live-testing.md` with the validation
+  checklist for the first authorized run.
+
+### Changed
+
+- README header now shows the project logo (absolute URL, so it also renders on PyPI) and
+  documents `pip install eltoque-python`.
+
 ## [0.1.0] - 2026-10-22
 
 First release. Unpublished until the repository owner approves it (see docs/publishing.md).

{eltoque_python-0.1.0 → eltoque_python-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: eltoque-python
-Version: 0.1.0
+Version: 0.1.1
 Summary: Unofficial, typed Python client for the official elTOQUE exchange-rate API.
 Project-URL: Homepage, https://github.com/Alejo2075/eltoque-python
 Project-URL: Source, https://github.com/Alejo2075/eltoque-python
@@ -26,7 +26,9 @@ Requires-Python: >=3.11
 Requires-Dist: httpx<1,>=0.28
 Description-Content-Type: text/markdown
 
-# eltoque-python
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Alejo2075/eltoque-python/main/assets/logo.png" alt="eltoque-python" width="480">
+</p>
 
 **Unofficial Python SDK for elTOQUE exchange-rate data.**
 A modern, typed client for the official elTOQUE exchange-rate API, with sync and async interfaces.
@@ -255,10 +257,12 @@ uv run python -m build
 uv run twine check dist/*
 ```
 
-Optional live check, only with your own authorized token (never run in CI):
+Optional live check, only with your own authorized token (never run in CI). One request; the
+script prints the response shape, never provider values. See
+[docs/live-testing.md](docs/live-testing.md):
 
 ```bash
-ELTOQUE_API_TOKEN=... ELTOQUE_ALLOW_LIVE_TESTS=1 uv run pytest -m integration --no-cov
+ELTOQUE_API_TOKEN=... ELTOQUE_ALLOW_LIVE_TESTS=1 python scripts/live_check.py
 ```
 
 ## Security and legal

{eltoque_python-0.1.0 → eltoque_python-0.1.1}/README.md

@@ -1,4 +1,6 @@
-# eltoque-python
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Alejo2075/eltoque-python/main/assets/logo.png" alt="eltoque-python" width="480">
+</p>
 
 **Unofficial Python SDK for elTOQUE exchange-rate data.**
 A modern, typed client for the official elTOQUE exchange-rate API, with sync and async interfaces.
@@ -227,10 +229,12 @@ uv run python -m build
 uv run twine check dist/*
 ```
 
-Optional live check, only with your own authorized token (never run in CI):
+Optional live check, only with your own authorized token (never run in CI). One request; the
+script prints the response shape, never provider values. See
+[docs/live-testing.md](docs/live-testing.md):
 
 ```bash
-ELTOQUE_API_TOKEN=... ELTOQUE_ALLOW_LIVE_TESTS=1 uv run pytest -m integration --no-cov
+ELTOQUE_API_TOKEN=... ELTOQUE_ALLOW_LIVE_TESTS=1 python scripts/live_check.py
 ```
 
 ## Security and legal

eltoque_python-0.1.1/docs/live-testing.md

@@ -0,0 +1,70 @@
+# Validating against the real API
+
+The test suite never touches the real elTOQUE API. This page is the checklist for the first time
+you have **your own approved token** (request it at <https://tasas-token.eltoque.com/>). It is
+meant to close the items listed as unverified in [api-contract.md](api-contract.md).
+
+Ground rules: use only your own application's token, keep the number of requests tiny (default
+limit: 60/minute, 10/second), never commit tokens or real responses, and do not redistribute
+the data (see the [terms of use](https://eltoque.com/api-tasas-de-eltoque-terminos-y-condiciones-de-uso)).
+
+## 1. Smoke check: does the client work? (1 request)
+
+```bash
+export ELTOQUE_API_TOKEN="your-application-token"
+export ELTOQUE_ALLOW_LIVE_TESTS=1
+python scripts/live_check.py
+```
+
+It refuses to run unless both variables are set, makes **one** request and prints:
+
+- the HTTP status and rate-limit headers (`limit`, `remaining`, `reset`);
+- the **shape** of the JSON (types, keys, list sizes, decimal places) and **no values**.
+
+Exit codes: `0` ok, `1` the API or network failed (error class and message shown), `2` not
+authorized to run.
+
+Or run the opt-in pytest check (also one request): `uv run pytest -m integration --no-cov`.
+
+## 2. Record what you learn
+
+From the shape output, fill in the "Unverified / unknown" checklist in
+[api-contract.md](api-contract.md) with a validation date:
+
+- [ ] Top-level type (object or list) and field names; which are currencies.
+- [ ] Types and decimal places of the rate values (decides `Decimal` vs. `float`).
+- [ ] Whether there are timestamps, and in which format.
+- [ ] What `X-RateLimit-Reset` means (compare it with the current time on two consecutive calls).
+
+Paste only the value-free shape. Review it first: object keys are printed as-is.
+
+## 3. Time zone and ranges (2-3 more requests, done by hand)
+
+The API does not document its time zone. With a short Python session:
+
+```python
+import os
+from datetime import datetime, timedelta
+
+from eltoque import ElToqueClient
+
+with ElToqueClient(os.environ["ELTOQUE_API_TOKEN"]) as client:
+    now = datetime.now()  # your local, naive time
+    r1 = client.get_rates(now - timedelta(hours=2), now - timedelta(hours=1))
+    print(type(r1.data), r1.rate_limit)
+```
+
+Compare windows shifted by the suspected offset and see which returns data for the period you
+expect. Also confirm what happens with a window of exactly 24 hours (expected: HTTP 400, which the
+SDK already rejects before sending) and with only one bound (the SDK refuses this today).
+
+## 4. Turn findings into code (Milestone B, release 0.2.0)
+
+1. Update `docs/api-contract.md` with the sanitized shape and the date.
+2. Add `Decimal`-based typed models **only for confirmed fields**, keeping `RatesResponse.data` as
+   the untouched escape hatch. Use synthetic fixtures that mimic the confirmed shape.
+3. If the time zone is confirmed, document it in the README and decide whether timezone-aware
+   datetimes can be supported.
+4. Tests, changelog (`Added`), version bump, then follow [publishing.md](publishing.md).
+
+You can ask Claude Code to do step 4 from your sanitized notes.

eltoque_python-0.1.1/src/eltoque/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

eltoque_python-0.1.1/tests/test_live_check.py

@@ -0,0 +1,86 @@
+"""The live-check helper must be inert without authorization and never leak provider values."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import httpx
+import pytest
+
+SCRIPT = Path(__file__).resolve().parent.parent / "scripts" / "live_check.py"
+spec = importlib.util.spec_from_file_location("live_check", SCRIPT)
+assert spec is not None
+assert spec.loader is not None
+live_check = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(live_check)
+
+
+@pytest.mark.parametrize(
+    "env",
+    [{}, {"ELTOQUE_API_TOKEN": "fake.token"}, {"ELTOQUE_ALLOW_LIVE_TESTS": "1"}],
+)
+def test_refuses_without_both_variables(
+    env: dict[str, str], monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.delenv("ELTOQUE_API_TOKEN", raising=False)
+    monkeypatch.delenv("ELTOQUE_ALLOW_LIVE_TESTS", raising=False)
+    for key, value in env.items():
+        monkeypatch.setenv(key, value)
+
+    def boom(*args: object, **kwargs: object) -> None:
+        raise AssertionError("no network allowed")
+
+    monkeypatch.setattr(httpx.HTTPTransport, "handle_request", boom)
+    assert live_check.main() == 2
+    assert "Refusing" in capsys.readouterr().err
+
+
+def test_prints_shape_but_never_values(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("ELTOQUE_API_TOKEN", "fake.token")
+    monkeypatch.setenv("ELTOQUE_ALLOW_LIVE_TESTS", "1")
+    payload = {"rates": [{"code": "SECRETVALUE", "price": 365.25}], "n": 3, "ok": True, "x": None}
+    calls = []
+
+    def handle(self: httpx.HTTPTransport, request: httpx.Request) -> httpx.Response:
+        calls.append(request)
+        return httpx.Response(200, json=payload, headers={"X-RateLimit-Remaining": "59"})
+
+    monkeypatch.setattr(httpx.HTTPTransport, "handle_request", handle)
+    assert live_check.main() == 0
+    out = capsys.readouterr().out
+    assert len(calls) == 1
+    assert "SECRETVALUE" not in out
+    assert "365.25" not in out
+    assert "fake.token" not in out
+    assert "float(decimals=2)" in out
+    assert '"remaining": 59' in out
+
+
+def test_api_error_exits_nonzero_without_leaking(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("ELTOQUE_API_TOKEN", "fake.token")
+    monkeypatch.setenv("ELTOQUE_ALLOW_LIVE_TESTS", "1")
+    monkeypatch.setattr(
+        httpx.HTTPTransport,
+        "handle_request",
+        lambda self, request: httpx.Response(401, text="fake.token rejected"),
+    )
+    assert live_check.main() == 1
+    captured = capsys.readouterr()
+    assert "ElToqueAuthenticationError" in captured.err
+    assert "fake.token" not in captured.err + captured.out
+
+
+def test_shape_limits_depth_and_size() -> None:
+    deep: object = 1
+    for _ in range(20):
+        deep = [deep]
+    assert "<max depth>" in str(live_check.describe_shape(deep))
+    big = {f"k{i}": i for i in range(100)}
+    assert live_check.describe_shape(big)["<more keys>"] == 100 - live_check.MAX_ITEMS
+    assert live_check.describe_shape(1e-7) == "float(decimals=exp)"
+    assert live_check.describe_shape(object()) == "object"

{eltoque_python-0.1.0 → eltoque_python-0.1.1}/tests/test_public_api.py

@@ -1,8 +1,10 @@
+import re
+
 import eltoque
 
 
 def test_version_is_exposed() -> None:
-    assert eltoque.__version__ == "0.1.0"
+    assert re.fullmatch(r"\d+\.\d+\.\d+", eltoque.__version__)
 
 
 def test_all_names_resolve() -> None:

eltoque_python-0.1.0/src/eltoque/_version.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"