perexchange 1.0.0__tar.gz

perexchange-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+exclude tests/*
+prune tests

perexchange-1.0.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: perexchange
+Version: 1.0.0
+Summary: Library for fetching Peruvian exchange rates
+Author-email: David Duran <dadch1404@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: beautifulsoup4>=4.14.2
+Requires-Dist: httpx[http2]>=0.27.2
+Requires-Dist: lxml>=6.0.2
+
+# [pkg]: perexchange
+
+Core library for fetching PEN-USD exchange rates from Peruvian exchange houses. To install
+it, run:
+
+```bash
+pip install perexchange
+```
+
+The library provides a single async function that fetches rates from multiple sources
+concurrently:
+
+```python
+import asyncio
+import perexchange as px
+
+async def main():
+    rates = await px.fetch_rates()
+    best = min(rates, key=lambda r: r.buy_price)
+    print(f"{best.name}: S/{best.buy_price}")
+
+asyncio.run(main())
+```
+
+## Fetching rates
+
+Call `fetch_rates()` to retrieve current rates. By default it queries all available
+sources: cambioseguro, cuantoestaeldolar, tkambio, tucambista, and westernunion. The
+function returns a list of `ExchangeRate` objects.
+
+```python
+rates = await px.fetch_rates()
+```
+
+You can fetch from specific sources by passing a list of house names. This is useful when
+you only need rates from certain providers or want to reduce latency:
+
+```python
+rates = await px.fetch_rates(houses=["tkambio", "tucambista"])
+```
+
+The function accepts timeout and retry parameters. Timeout applies per house, not to the
+entire operation. Retries only trigger on network errors, not parsing failures:
+
+```python
+rates = await px.fetch_rates(timeout=15.0, max_retries=5)
+```
+
+Failed sources are silently skipped. The function returns whatever rates it successfully
+fetched, or an empty list if everything fails. Network errors trigger automatic retries
+with exponential backoff. Parsing errors fail immediately.
+
+## Working with rates
+
+Each `ExchangeRate` contains the house name, buy and sell prices, and a UTC timestamp. Buy
+price is what you pay in soles to buy dollars. Sell price is what you receive in soles
+when selling dollars. The object is a frozen dataclass:
+
+```python
+rate = rates[0]
+name = rate.name
+buy = rate.buy_price
+sell = rate.sell_price
+when = rate.timestamp
+spread = rate.spread
+```
+
+The spread property returns the difference between sell and buy prices. Some sources
+return multiple tiers with different rates based on transaction amount, like
+`tkambio_5000` and `tkambio_10000`.
+
+Find the best rates by sorting or filtering the list:
+
+```python
+best_buy = min(rates, key=lambda r: r.buy_price)
+best_sell = max(rates, key=lambda r: r.sell_price)
+recent = [r for r in rates if (datetime.now(timezone.utc) - r.timestamp).seconds < 300]
+```
+
+## Error handling
+
+Invalid house names raise `ValueError` immediately. All other failures are silent. Check
+the returned list to see what succeeded:
+
+```python
+try:
+    rates = await px.fetch_rates(houses=["nonexistent"])
+except ValueError as e:
+    print(f"Unknown house: {e}")
+
+rates = await px.fetch_rates()
+if not rates:
+    print("All sources failed")
+```
+
+The library doesn't distinguish between different failure types. A house might fail due to
+network issues, API changes, or parsing errors. Failed requests don't pollute your results
+or logs.

perexchange-1.0.0/perexchange/__init__.py

@@ -0,0 +1,16 @@
+"""
+Fetch PEN-USD exchange rates from Peruvian exchange houses.
+
+Example:
+    >>> import perexchange as px
+    >>> rates = await px.fetch_rates()
+    >>> best = min(rates, key=lambda r: r.buy_price)
+    >>> print(f"{best.name}: S/{best.buy_price}")
+"""
+
+from perexchange.core import fetch_rates
+from perexchange.models import ExchangeRate
+
+
+__version__ = "1.0.0"
+__all__ = ["ExchangeRate", "fetch_rates"]

perexchange-1.0.0/perexchange/core.py

@@ -0,0 +1,70 @@
+import asyncio
+
+from collections.abc import Sequence
+
+import httpx
+
+from perexchange.models import ExchangeRate
+from perexchange.scrapers import get_scrapers
+from perexchange.scrapers.base import ExchangeRateScraper
+
+
+async def fetch_rates(
+    houses: Sequence[str] | None = None,
+    *,
+    timeout: float = 10.0,
+    max_retries: int = 3,
+) -> list[ExchangeRate]:
+    """
+    Fetch current exchange rates from Peruvian exchange houses.
+
+    Args:
+        houses: Specific house names to fetch. If None, fetches all.
+                Available: cambiafx, cambioseguro, chapacambio, cuantoestaeldolar, dollarhouse,
+                           instakash, srcambio, tkambio, tucambista, westernunion, yanki
+        timeout: Request timeout per house (seconds)
+        max_retries: Retry attempts for failed requests
+
+    Returns:
+        List of ExchangeRate objects. Empty list if all houses fail.
+
+    Example:
+        >>> rates = await fetch_rates()
+        >>> rates = await fetch_rates(houses=["tkambio", "cambioseguro"])
+        >>> best = min(rates, key=lambda r: r.buy_price)
+        >>> print(f"Best: {best.name} at S/{best.buy_price}")
+
+    Note:
+        Failed houses are silently skipped. Network errors are retried,
+        parsing errors fail immediately.
+    """
+    scrapers = get_scrapers(houses)
+
+    tasks = [_safe_fetch(scraper, timeout, max_retries) for scraper in scrapers]
+    results = await asyncio.gather(*tasks)
+
+    all_rates = [rate for result in results for rate in result]
+
+    # Deduplicate by name, keeping the most recent rate for each house.
+    # This handles cases where cuantoestaeldolar (an aggregator) returns rates for houses
+    # we also scrape directly (e.g., chapacambio). We prioritize the most recent timestamp,
+    # which is typically from direct scrapers since they have fresher data.
+    # This is a temporary measure until cuantoestaeldolar is replaced with individual scrapers.
+    seen: dict[str, ExchangeRate] = {}
+    for rate in all_rates:
+        if rate.name not in seen or rate.timestamp > seen[rate.name].timestamp:
+            seen[rate.name] = rate
+
+    return list(seen.values())
+
+
+async def _safe_fetch(
+    scraper: ExchangeRateScraper,
+    timeout: float,
+    max_retries: int,
+) -> list[ExchangeRate]:
+    """Fetch from one scraper, return empty list on failure."""
+    try:
+        return await scraper(timeout=timeout, max_retries=max_retries)
+    except (httpx.HTTPError, ValueError):
+        return []

perexchange-1.0.0/perexchange/models.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass(frozen=True)
+class ExchangeRate:
+    name: str
+    buy_price: float  # Price to BUY dollars (sell soles)
+    sell_price: float  # Price to SELL dollars (buy soles)
+    timestamp: datetime
+
+    @property
+    def spread(self) -> float:
+        """Difference between buy and sell price."""
+        return self.sell_price - self.buy_price
+
+    def __repr__(self) -> str:
+        return (
+            f"ExchangeRate({self.name!r}, "
+            f"buy={self.buy_price:.4f}, sell={self.sell_price:.4f})"
+        )

perexchange-1.0.0/perexchange/scrapers/__init__.py

@@ -0,0 +1,68 @@
+from collections.abc import Sequence
+
+from perexchange.scrapers.base import ExchangeRateScraper
+from perexchange.scrapers.cambiafx import fetch_cambiafx
+from perexchange.scrapers.cambioseguro import fetch_cambioseguro
+from perexchange.scrapers.chapacambio import fetch_chapacambio
+from perexchange.scrapers.cuantoestaeldolar import fetch_cuantoestaeldolar
+from perexchange.scrapers.dollarhouse import fetch_dollarhouse
+from perexchange.scrapers.instakash import fetch_instakash
+from perexchange.scrapers.srcambio import fetch_srcambio
+from perexchange.scrapers.tkambio import fetch_tkambio
+from perexchange.scrapers.tucambista import fetch_tucambista
+from perexchange.scrapers.westernunion import fetch_westernunion
+from perexchange.scrapers.yanki import fetch_yanki
+
+
+_SCRAPERS: dict[str, ExchangeRateScraper] = {
+    "cambioseguro": fetch_cambioseguro,
+    "cambiafx": fetch_cambiafx,
+    "chapacambio": fetch_chapacambio,
+    "cuantoestaeldolar": fetch_cuantoestaeldolar,
+    "dollarhouse": fetch_dollarhouse,
+    "instakash": fetch_instakash,
+    "srcambio": fetch_srcambio,
+    "tkambio": fetch_tkambio,
+    "tucambista": fetch_tucambista,
+    "westernunion": fetch_westernunion,
+    "yanki": fetch_yanki,
+}
+
+
+def get_scrapers(houses: Sequence[str] | None = None) -> list[ExchangeRateScraper]:
+    """
+    Get scrapers for specified houses, or all if None.
+
+    Raises:
+        ValueError: If a house name is not recognized
+    """
+    if houses is None:
+        return list(_SCRAPERS.values())
+
+    scrapers = []
+    for house in houses:
+        house_lower = house.lower()
+        if house_lower not in _SCRAPERS:
+            available = ", ".join(sorted(_SCRAPERS.keys()))
+            msg = f"Unknown house: {house!r}. Available: {available}"
+            raise ValueError(msg)
+        scrapers.append(_SCRAPERS[house_lower])
+
+    return scrapers
+
+
+__all__ = [
+    "ExchangeRateScraper",
+    "fetch_cambiafx",
+    "fetch_cambioseguro",
+    "fetch_chapacambio",
+    "fetch_cuantoestaeldolar",
+    "fetch_dollarhouse",
+    "fetch_instakash",
+    "fetch_srcambio",
+    "fetch_tkambio",
+    "fetch_tucambista",
+    "fetch_westernunion",
+    "fetch_yanki",
+    "get_scrapers",
+]

perexchange-1.0.0/perexchange/scrapers/base.py

@@ -0,0 +1,87 @@
+import asyncio
+
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from typing import Protocol, TypeVar
+
+import httpx
+
+from perexchange.models import ExchangeRate
+
+
+T = TypeVar("T")
+
+
+class ExchangeRateScraper(Protocol):
+    """Protocol defining the interface all scrapers must implement."""
+
+    def __call__(
+        self,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        retry_delay: float = 0.5,
+    ) -> Awaitable[list[ExchangeRate]]:  # fmt: skip
+        ...
+
+
+@asynccontextmanager
+async def get_http_client(timeout: float) -> AsyncGenerator[httpx.AsyncClient, None]:
+    """
+    Create HTTP client with connection pooling.
+    """
+    async with httpx.AsyncClient(
+        timeout=timeout,
+        limits=httpx.Limits(max_keepalive_connections=5, max_connections=10),
+        http2=True,
+    ) as client:
+        yield client
+
+
+async def fetch_with_retry(
+    fetch_fn: Callable[[httpx.AsyncClient], Awaitable[T]],
+    timeout: float,
+    max_retries: int,
+    retry_delay: float,
+    error_context: str,
+) -> T:
+    """
+    Execute fetch function with exponential backoff retry logic.
+
+    Args:
+        fetch_fn: Async function that takes an httpx.AsyncClient and returns data
+        timeout: Request timeout in seconds
+        max_retries: Maximum number of retry attempts
+        retry_delay: Base delay between retries (doubles each attempt)
+        error_context: URL or context string for error messages
+
+    Returns:
+        Result from fetch_fn
+
+    Raises:
+        ValueError: On parsing errors (fails immediately, no retry)
+        httpx.HTTPError: On network errors after all retries exhausted
+    """
+    async with get_http_client(timeout) as client:
+        last_error = None
+
+        for attempt in range(max_retries):
+            try:
+                return await fetch_fn(client)
+
+            except httpx.HTTPError as e:
+                last_error = e
+                if attempt < max_retries - 1:
+                    await asyncio.sleep(retry_delay * (2**attempt))
+                continue
+
+            except (ValueError, KeyError, TypeError, AttributeError, IndexError) as e:
+                msg = (
+                    f"Failed to parse exchange rates from {error_context}. "
+                    "The structure may have changed."
+                )
+                raise ValueError(msg) from e
+
+        if last_error is None:
+            msg = "Failed to fetch rates: no attempts were made"
+            raise ValueError(msg)
+        raise last_error

perexchange-1.0.0/perexchange/scrapers/cambiafx.py

@@ -0,0 +1,54 @@
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+
+from perexchange.models import ExchangeRate
+from perexchange.scrapers.base import fetch_with_retry
+
+
+URL = "https://apiluna.cambiafx.pe/api/BackendPizarra/getTcCustomerNoAuth?idParCurrency=1&codePromo=CED"
+
+
+async def fetch_cambiafx(
+    timeout: float = 10.0,
+    max_retries: int = 3,
+    retry_delay: float = 0.5,
+) -> list[ExchangeRate]:
+    async def _fetch(client: httpx.AsyncClient) -> list[ExchangeRate]:
+        response = await client.get(URL)
+        response.raise_for_status()
+        return _parse_json(response.json())
+
+    return await fetch_with_retry(_fetch, timeout, max_retries, retry_delay, URL)
+
+
+def _parse_json(response_data: list[dict[str, Any]]) -> list[ExchangeRate]:
+    if not response_data:
+        msg = "No exchange rates data"
+        raise ValueError(msg)
+
+    timestamp = datetime.now(timezone.utc)
+    rates = []
+
+    # Take the first rate from the array
+    data = response_data[0]
+    try:
+        buy_price = float(data["tcBuy"])
+        sell_price = float(data["tcSale"])
+        if buy_price > 0 and sell_price > 0:
+            rate = ExchangeRate(
+                name="cambiafx",
+                buy_price=buy_price,
+                sell_price=sell_price,
+                timestamp=timestamp,
+            )
+            rates.append(rate)
+    except (KeyError, ValueError, TypeError):
+        pass
+
+    if not rates:
+        msg = "No valid exchange rates parsed"
+        raise ValueError(msg)
+
+    return rates

perexchange-1.0.0/perexchange/scrapers/cambioseguro.py

@@ -0,0 +1,73 @@
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+
+from perexchange.models import ExchangeRate
+from perexchange.scrapers.base import fetch_with_retry
+
+
+URL = "https://api.cambioseguro.com/api/v1.1/config/rates"
+
+
+async def fetch_cambioseguro(
+    timeout: float = 10.0,
+    max_retries: int = 3,
+    retry_delay: float = 0.5,
+) -> list[ExchangeRate]:
+    async def _fetch(client: httpx.AsyncClient) -> list[ExchangeRate]:
+        response = await client.get(URL)
+        response.raise_for_status()
+        return _parse_json(response.json())
+
+    return await fetch_with_retry(_fetch, timeout, max_retries, retry_delay, URL)
+
+
+def _parse_json(response_data: dict[str, Any]) -> list[ExchangeRate]:
+    timestamp = datetime.now(timezone.utc)
+    rates = []
+    data = response_data.get("data", {})
+
+    rate_configs = [
+        ("cambioseguro", "purchase_price", "sale_price"),
+        (
+            "cambioseguro_comparative",
+            "purchase_price_comparative",
+            "sale_price_comparative",
+        ),
+        ("cambioseguro_paralelo", "purchase_price_paralelo", "sale_price_paralelo"),
+    ]
+
+    for name, buy_key, sell_key in rate_configs:
+        rate = _try_create_rate(data, name, buy_key, sell_key, timestamp)
+        if rate:
+            rates.append(rate)
+
+    if not rates:
+        msg = "No valid exchange rates parsed"
+        raise ValueError(msg)
+
+    return rates
+
+
+def _try_create_rate(
+    data: dict[str, Any],
+    name: str,
+    buy_key: str,
+    sell_key: str,
+    timestamp: datetime,
+) -> ExchangeRate | None:
+    """Try to create a rate from data, return None if invalid."""
+    try:
+        buy_price = float(data[buy_key])
+        sell_price = float(data[sell_key])
+        if buy_price > 0 and sell_price > 0:
+            return ExchangeRate(
+                name=name,
+                buy_price=buy_price,
+                sell_price=sell_price,
+                timestamp=timestamp,
+            )
+    except (KeyError, ValueError, TypeError):
+        pass
+    return None

perexchange-1.0.0/perexchange/scrapers/chapacambio.py

@@ -0,0 +1,61 @@
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+
+from perexchange.models import ExchangeRate
+from perexchange.scrapers.base import fetch_with_retry
+
+
+URL = "https://chapacambio.com/wp-json/chapacambio/tasas"
+
+
+async def fetch_chapacambio(
+    timeout: float = 10.0,
+    max_retries: int = 3,
+    retry_delay: float = 0.5,
+) -> list[ExchangeRate]:
+    async def _fetch(client: httpx.AsyncClient) -> list[ExchangeRate]:
+        response = await client.get(URL)
+        response.raise_for_status()
+        return _parse_json(response.json())
+
+    return await fetch_with_retry(_fetch, timeout, max_retries, retry_delay, URL)
+
+
+def _parse_json(response_data: list[dict[str, Any]]) -> list[ExchangeRate]:
+    rates = []
+    for item in response_data:
+        rate = _try_create_rate(item)
+        if rate:
+            rates.append(rate)
+
+    if not rates:
+        msg = "No valid exchange rates parsed"
+        raise ValueError(msg)
+
+    return rates
+
+
+def _try_create_rate(data: dict[str, Any]) -> ExchangeRate | None:
+    """Try to create a rate from data, return None if invalid."""
+    try:
+        buy_price = float(data["MontoCompra"])
+        sell_price = float(data["MontoVenta"])
+        if buy_price > 0 and sell_price > 0:
+            timestamp_str = data.get("updateAt")
+            if timestamp_str:
+                timestamp = datetime.fromisoformat(timestamp_str).replace(
+                    tzinfo=timezone.utc
+                )
+            else:
+                timestamp = datetime.now(timezone.utc)
+            return ExchangeRate(
+                name="chapacambio",
+                buy_price=buy_price,
+                sell_price=sell_price,
+                timestamp=timestamp,
+            )
+    except (KeyError, ValueError, TypeError):
+        pass
+    return None

perexchange-1.0.0/perexchange/scrapers/cuantoestaeldolar.py

@@ -0,0 +1,94 @@
+from datetime import datetime, timezone
+
+import httpx
+
+from bs4 import BeautifulSoup
+from bs4.element import Tag
+
+from perexchange.models import ExchangeRate
+from perexchange.scrapers.base import fetch_with_retry
+
+
+URL = "https://cuantoestaeldolar.pe/cambio-de-dolar-online"
+
+
+async def fetch_cuantoestaeldolar(
+    timeout: float = 10.0,
+    max_retries: int = 3,
+    retry_delay: float = 0.5,
+) -> list[ExchangeRate]:
+    async def _fetch(client: httpx.AsyncClient) -> list[ExchangeRate]:
+        response = await client.get(URL)
+        response.raise_for_status()
+        return _parse_html(response.text)
+
+    return await fetch_with_retry(_fetch, timeout, max_retries, retry_delay, URL)
+
+
+def _parse_html(html_content: str) -> list[ExchangeRate]:
+    soup = BeautifulSoup(html_content, "lxml")
+    change_buttons = soup.find_all("a", string="CAMBIAR")  # type: ignore[call-overload]
+
+    if not change_buttons:
+        msg = "No exchange houses found in HTML"
+        raise ValueError(msg)
+
+    timestamp = datetime.now(timezone.utc)
+    rates = []
+
+    for button in change_buttons:
+        try:
+            rate = _extract_rate_from_card(button, timestamp)
+            if rate:
+                rates.append(rate)
+        except (AttributeError, ValueError, TypeError, IndexError):
+            continue
+
+    if not rates:
+        msg = "No valid exchange rates parsed"
+        raise ValueError(msg)
+
+    return rates
+
+
+def _extract_rate_from_card(button: Tag, timestamp: datetime) -> ExchangeRate | None:
+    parent = button.find_parent("div")
+    if not parent:
+        return None
+    card = parent.find_parent("div")
+    if not card:
+        return None
+
+    img_tag = card.find("img")
+    if not img_tag:
+        return None
+    alt_attr = img_tag.get("alt")
+    name = alt_attr.strip() if isinstance(alt_attr, str) else None
+    if not name:
+        return None
+
+    buy_block = card.select_one('div[class*="_content_buy__"]')
+    sell_block = card.select_one('div[class*="_content_sale__"]')
+
+    if not buy_block or not sell_block:
+        return None
+
+    buy_rate_elem = buy_block.find(
+        "p", class_=lambda c: c and c.startswith("ValueCurrency_item_cost__")
+    )
+    buy_price = float(buy_rate_elem.text) if buy_rate_elem else None
+
+    sell_rate_elem = sell_block.find(
+        "p", class_=lambda c: c and c.startswith("ValueCurrency_item_cost__")
+    )
+    sell_price = float(sell_rate_elem.text) if sell_rate_elem else None
+
+    if not buy_price or not sell_price or buy_price <= 0 or sell_price <= 0:
+        return None
+
+    return ExchangeRate(
+        name=name,
+        buy_price=buy_price,
+        sell_price=sell_price,
+        timestamp=timestamp,
+    )