fastapi-unirate 0.1.0__tar.gz

fastapi_unirate-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,63 @@
+name: release
+
+on:
+  push:
+    tags: ["v*.*.*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Verify tag matches package version
+        id: version
+        run: |
+          PKG_VERSION=$(grep -E '^version = ' pyproject.toml | head -1 | sed -E 's/version = "(.*)"/\1/')
+          TAG_VERSION=${GITHUB_REF#refs/tags/v}
+          echo "package version: $PKG_VERSION"
+          echo "tag version: $TAG_VERSION"
+          if [ "${{ github.event_name }}" = "push" ] && [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "Tag $TAG_VERSION does not match pyproject.toml version $PKG_VERSION" >&2
+            exit 1
+          fi
+          echo "version=$PKG_VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fastapi-unirate
+    permissions:
+      id-token: write  # Required for PyPI Trusted Publisher (OIDC)
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fastapi_unirate-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,40 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-groups --python ${{ matrix.python-version }}
+
+      - name: Lint
+        run: |
+          uv run --group lint ruff check fastapi_unirate tests
+          uv run --group lint ruff format fastapi_unirate tests --diff
+
+      - name: Type check
+        run: uv run --group typing mypy fastapi_unirate tests
+
+      - name: Run unit tests
+        run: uv run --group test pytest tests/ -v

fastapi_unirate-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+.venv/
+venv/
+env/
+
+build/
+dist/
+*.egg-info/
+*.egg
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+.DS_Store
+.idea/
+.vscode/
+
+uv.lock

fastapi_unirate-0.1.0/LICENSE

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

fastapi_unirate-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: fastapi-unirate
+Version: 0.1.0
+Summary: FastAPI integration for the UniRate currency-exchange API — async dependency, lifespan manager, Money Pydantic type, and response-conversion middleware.
+Project-URL: Homepage, https://github.com/UniRate-API/fastapi-unirate
+Project-URL: Repository, https://github.com/UniRate-API/fastapi-unirate
+Project-URL: Issues, https://github.com/UniRate-API/fastapi-unirate/issues
+Project-URL: Provider, https://unirateapi.com
+Author: Unirate Team
+License: MIT
+License-File: LICENSE
+Keywords: currency,exchange-rates,fastapi,fintech,forex,money,unirate
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+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.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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: fastapi<2.0,>=0.100
+Requires-Dist: httpx<1.0,>=0.25
+Requires-Dist: pydantic<3.0,>=2.0
+Description-Content-Type: text/markdown
+
+# fastapi-unirate
+
+[![PyPI](https://img.shields.io/pypi/v/fastapi-unirate.svg)](https://pypi.org/project/fastapi-unirate/)
+[![Python](https://img.shields.io/pypi/pyversions/fastapi-unirate.svg)](https://pypi.org/project/fastapi-unirate/)
+[![License](https://img.shields.io/pypi/l/fastapi-unirate.svg)](https://github.com/UniRate-API/fastapi-unirate/blob/main/LICENSE)
+
+FastAPI integration for the [UniRate](https://unirateapi.com) currency-exchange API:
+
+- **Async dependency** — `Depends(get_unirate_client)` plus a typed
+  `UniRateDep` alias for path-operation signatures.
+- **Lifespan helper** — one shared `httpx.AsyncClient`-backed UniRate client
+  per app, opened on startup and closed on shutdown.
+- **`Money` Pydantic type** — amount + currency pair that round-trips
+  through OpenAPI schemas.
+- **`CurrencyConversionMiddleware`** — auto-rewrites Money-shaped values in
+  JSON responses to a request-scoped target currency
+  (`?currency=EUR`).
+
+UniRate covers 593+ fiat, crypto, and commodity codes. Latest rates and
+conversion are on the free tier; historical endpoints
+(`convert_historical`) require Pro.
+
+## Install
+
+```bash
+pip install fastapi-unirate
+```
+
+Or with uv / Poetry:
+
+```bash
+uv add fastapi-unirate
+poetry add fastapi-unirate
+```
+
+## Quick start
+
+```python
+import os
+
+from fastapi import FastAPI
+from fastapi_unirate import (
+    CurrencyConversionMiddleware,
+    Money,
+    UniRateDep,
+    unirate_lifespan,
+)
+
+app = FastAPI(lifespan=unirate_lifespan())  # reads UNIRATE_API_KEY from env
+app.add_middleware(CurrencyConversionMiddleware)
+
+
+@app.get("/products/widget")
+async def get_widget() -> dict[str, Money]:
+    return {"price": Money(amount=19.99, currency="USD")}
+
+
+@app.get("/rate/{base}/{quote}")
+async def rate(base: str, quote: str, client: UniRateDep) -> dict[str, float]:
+    return {"rate": await client.get_rate(base, quote)}
+```
+
+Then:
+
+```
+$ curl localhost:8000/products/widget
+{"price":{"amount":19.99,"currency":"USD"}}
+
+$ curl localhost:8000/products/widget?currency=EUR
+{"price":{"amount":18.42,"currency":"EUR"}}
+
+$ curl localhost:8000/rate/USD/JPY
+{"rate":151.83}
+```
+
+The middleware finds every `{"amount": <number>, "currency": "<code>"}`
+shape — top-level, nested, or inside lists — and rewrites it. Conversions
+are de-duplicated per request and run concurrently.
+
+## Configuration
+
+`unirate_lifespan` accepts overrides:
+
+```python
+app = FastAPI(
+    lifespan=unirate_lifespan(
+        api_key="...",                         # default: $UNIRATE_API_KEY
+        base_url="https://api.unirateapi.com", # default: production
+        timeout=15.0,                          # default: 30s
+    )
+)
+```
+
+`CurrencyConversionMiddleware` accepts the query-parameter name and an
+explicit client (mostly for testing):
+
+```python
+app.add_middleware(
+    CurrencyConversionMiddleware,
+    query_param="display_currency",
+)
+```
+
+## Why a middleware?
+
+The dossier sketched two integration shapes — DI and middleware — and
+both pull their weight:
+
+- The DI provider is the right tool when a handler explicitly wants to
+  call `convert()` or `get_rate()`.
+- The middleware is the right tool when a service has a stable
+  `Money`-shaped response and wants to expose
+  *one* `?currency=` knob to clients without rewriting every handler.
+
+You can use either, or both together (as in the quick-start example).
+
+## Errors
+
+The client raises `UniRateAPIError` on non-2xx responses (with
+`status_code` set). Common cases:
+
+| HTTP | Meaning                                         |
+|------|-------------------------------------------------|
+| 401  | Missing or invalid API key                      |
+| 403  | Pro subscription required (historical, commodities) |
+| 404  | Currency not found                              |
+| 429  | Rate limit exceeded                             |
+
+The middleware swallows `UniRateAPIError` and passes the original
+response through unchanged — so an upstream UniRate outage never becomes
+a 500 on your service.
+
+## Compatibility
+
+- Python 3.9 – 3.13
+- FastAPI ≥ 0.100
+- Pydantic ≥ 2.0
+
+## Related
+
+- [`unirate-api`](https://pypi.org/project/unirate-api/) — sync UniRate
+  Python client (this package vendors a small async equivalent so it
+  doesn't pull in `requests`).
+- [`langchain-unirate`](https://pypi.org/project/langchain-unirate/) —
+  LangChain partner package.
+- Other UniRate integrations: dbt, Airflow, n8n, Raycast, MCP server.
+  Full list at <https://unirateapi.com>.
+
+## License
+
+MIT

fastapi_unirate-0.1.0/README.md

@@ -0,0 +1,151 @@
+# fastapi-unirate
+
+[![PyPI](https://img.shields.io/pypi/v/fastapi-unirate.svg)](https://pypi.org/project/fastapi-unirate/)
+[![Python](https://img.shields.io/pypi/pyversions/fastapi-unirate.svg)](https://pypi.org/project/fastapi-unirate/)
+[![License](https://img.shields.io/pypi/l/fastapi-unirate.svg)](https://github.com/UniRate-API/fastapi-unirate/blob/main/LICENSE)
+
+FastAPI integration for the [UniRate](https://unirateapi.com) currency-exchange API:
+
+- **Async dependency** — `Depends(get_unirate_client)` plus a typed
+  `UniRateDep` alias for path-operation signatures.
+- **Lifespan helper** — one shared `httpx.AsyncClient`-backed UniRate client
+  per app, opened on startup and closed on shutdown.
+- **`Money` Pydantic type** — amount + currency pair that round-trips
+  through OpenAPI schemas.
+- **`CurrencyConversionMiddleware`** — auto-rewrites Money-shaped values in
+  JSON responses to a request-scoped target currency
+  (`?currency=EUR`).
+
+UniRate covers 593+ fiat, crypto, and commodity codes. Latest rates and
+conversion are on the free tier; historical endpoints
+(`convert_historical`) require Pro.
+
+## Install
+
+```bash
+pip install fastapi-unirate
+```
+
+Or with uv / Poetry:
+
+```bash
+uv add fastapi-unirate
+poetry add fastapi-unirate
+```
+
+## Quick start
+
+```python
+import os
+
+from fastapi import FastAPI
+from fastapi_unirate import (
+    CurrencyConversionMiddleware,
+    Money,
+    UniRateDep,
+    unirate_lifespan,
+)
+
+app = FastAPI(lifespan=unirate_lifespan())  # reads UNIRATE_API_KEY from env
+app.add_middleware(CurrencyConversionMiddleware)
+
+
+@app.get("/products/widget")
+async def get_widget() -> dict[str, Money]:
+    return {"price": Money(amount=19.99, currency="USD")}
+
+
+@app.get("/rate/{base}/{quote}")
+async def rate(base: str, quote: str, client: UniRateDep) -> dict[str, float]:
+    return {"rate": await client.get_rate(base, quote)}
+```
+
+Then:
+
+```
+$ curl localhost:8000/products/widget
+{"price":{"amount":19.99,"currency":"USD"}}
+
+$ curl localhost:8000/products/widget?currency=EUR
+{"price":{"amount":18.42,"currency":"EUR"}}
+
+$ curl localhost:8000/rate/USD/JPY
+{"rate":151.83}
+```
+
+The middleware finds every `{"amount": <number>, "currency": "<code>"}`
+shape — top-level, nested, or inside lists — and rewrites it. Conversions
+are de-duplicated per request and run concurrently.
+
+## Configuration
+
+`unirate_lifespan` accepts overrides:
+
+```python
+app = FastAPI(
+    lifespan=unirate_lifespan(
+        api_key="...",                         # default: $UNIRATE_API_KEY
+        base_url="https://api.unirateapi.com", # default: production
+        timeout=15.0,                          # default: 30s
+    )
+)
+```
+
+`CurrencyConversionMiddleware` accepts the query-parameter name and an
+explicit client (mostly for testing):
+
+```python
+app.add_middleware(
+    CurrencyConversionMiddleware,
+    query_param="display_currency",
+)
+```
+
+## Why a middleware?
+
+The dossier sketched two integration shapes — DI and middleware — and
+both pull their weight:
+
+- The DI provider is the right tool when a handler explicitly wants to
+  call `convert()` or `get_rate()`.
+- The middleware is the right tool when a service has a stable
+  `Money`-shaped response and wants to expose
+  *one* `?currency=` knob to clients without rewriting every handler.
+
+You can use either, or both together (as in the quick-start example).
+
+## Errors
+
+The client raises `UniRateAPIError` on non-2xx responses (with
+`status_code` set). Common cases:
+
+| HTTP | Meaning                                         |
+|------|-------------------------------------------------|
+| 401  | Missing or invalid API key                      |
+| 403  | Pro subscription required (historical, commodities) |
+| 404  | Currency not found                              |
+| 429  | Rate limit exceeded                             |
+
+The middleware swallows `UniRateAPIError` and passes the original
+response through unchanged — so an upstream UniRate outage never becomes
+a 500 on your service.
+
+## Compatibility
+
+- Python 3.9 – 3.13
+- FastAPI ≥ 0.100
+- Pydantic ≥ 2.0
+
+## Related
+
+- [`unirate-api`](https://pypi.org/project/unirate-api/) — sync UniRate
+  Python client (this package vendors a small async equivalent so it
+  doesn't pull in `requests`).
+- [`langchain-unirate`](https://pypi.org/project/langchain-unirate/) —
+  LangChain partner package.
+- Other UniRate integrations: dbt, Airflow, n8n, Raycast, MCP server.
+  Full list at <https://unirateapi.com>.
+
+## License
+
+MIT

fastapi_unirate-0.1.0/examples/example_app.py

@@ -0,0 +1,49 @@
+"""End-to-end FastAPI demo for fastapi-unirate.
+
+Run:
+
+    UNIRATE_API_KEY=... uvicorn examples.example_app:app
+
+Then:
+
+    curl http://127.0.0.1:8000/products/widget
+    curl 'http://127.0.0.1:8000/products/widget?currency=EUR'
+    curl http://127.0.0.1:8000/rate/USD/JPY
+    curl http://127.0.0.1:8000/convert/USD/EUR/100
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from fastapi_unirate import (
+    CurrencyConversionMiddleware,
+    Money,
+    UniRateDep,
+    unirate_lifespan,
+)
+
+app = FastAPI(
+    title="fastapi-unirate example",
+    lifespan=unirate_lifespan(),
+)
+app.add_middleware(CurrencyConversionMiddleware)
+
+
+@app.get("/products/widget")
+async def get_widget() -> dict[str, Money]:
+    """Demonstrates the conversion middleware: hit ?currency=EUR to rewrite."""
+    return {"price": Money(amount=19.99, currency="USD")}
+
+
+@app.get("/rate/{base}/{quote}")
+async def get_rate(base: str, quote: str, client: UniRateDep) -> dict[str, float]:
+    """Demonstrates the dependency: directly call the client."""
+    return {"rate": await client.get_rate(base, quote)}
+
+
+@app.get("/convert/{base}/{quote}/{amount}")
+async def convert(
+    base: str, quote: str, amount: float, client: UniRateDep
+) -> dict[str, float]:
+    return {"result": await client.convert(base, quote, amount)}

fastapi_unirate-0.1.0/fastapi_unirate/__init__.py

@@ -0,0 +1,22 @@
+"""FastAPI integration for the UniRate currency-exchange API."""
+
+from fastapi_unirate.client import UniRateAPIError, UniRateClient
+from fastapi_unirate.dependencies import (
+    UniRateDep,
+    get_unirate_client,
+    unirate_lifespan,
+)
+from fastapi_unirate.middleware import CurrencyConversionMiddleware
+from fastapi_unirate.models import Money
+
+__all__ = [
+    "CurrencyConversionMiddleware",
+    "Money",
+    "UniRateAPIError",
+    "UniRateClient",
+    "UniRateDep",
+    "get_unirate_client",
+    "unirate_lifespan",
+]
+
+__version__ = "0.1.0"