forexia-cot 1.0.0__tar.gz

forexia_cot-1.0.0/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

forexia_cot-1.0.0/LICENSE

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

forexia_cot-1.0.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: forexia-cot
+Version: 1.0.0
+Summary: CFTC Commitments of Traders (COT) data for FX futures and gold, legacy and TFF reports: positions, net and net as a share of open interest. Weekly, since 2010.
+Project-URL: Homepage, https://github.com/ForexiaPro/cot-data
+Project-URL: Source, https://github.com/ForexiaPro/cot-data/tree/main/python
+Project-URL: COT report, https://forexiapro.com/cot-report/?via=cot-data
+Author: Forexia
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cftc,commitments of traders,cot,cot report,forex,futures,gold,positioning
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Provides-Extra: pandas
+Requires-Dist: pandas; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# forexia-cot
+
+The CFTC's weekly **Commitments of Traders (COT)** report for FX futures, the US dollar index and gold: **positions only** (long, short, net, net as a share of open interest), legacy and TFF reports, weekly since 2010. Reads the files of [github.com/ForexiaPro/cot-data](https://github.com/ForexiaPro/cot-data), updated every Friday after the CFTC's release.
+
+Standard library only. pandas is optional.
+
+```sh
+pip install forexia-cot
+forexia-cot          # this week's table: net non-commercial, weekly change, % of open interest
+forexia-cot gbp      # the pound's last eight weeks
+```
+
+```python
+import forexia_cot as cot
+
+cot.get_cot("EUR")                       # every legacy report since 2010, oldest first (a list of dicts)
+cot.get_cot("USDJPY", report="tff")      # the yen future's TFF groups
+cot.get_cot("gold", since="2024-01-01")
+cot.latest()                             # this week, every market and group
+
+df = cot.cot_frame("EUR")                # pip install "forexia-cot[pandas]"
+df.noncommercial_net.plot()
+```
+
+Markets: `EUR`, `GBP`, `JPY`, `CHF`, `CAD`, `AUD`, `NZD`, `MXN`, `USD` (the dollar index), `XAU` (gold; legacy only). `EURUSD`, `USDJPY`, `gold` and `DXY` work too.
+
+Columns: `date` (the Tuesday the positions were counted), `open_interest`, then for each group `_long`, `_short`, `_net`, `_net_pct_oi` (net as a share of open interest, in per cent); non-commercial also has `_spreading`. Legacy groups: `noncommercial`, `commercial`, `nonreportable`. TFF groups: `dealer`, `asset_manager`, `leveraged_funds`, `other_reportable`, `nonreportable`. Positions are contracts in the future's terms: long `JPY` is long the yen, so short USDJPY.
+
+For Forexia's COT index and weekly reading of these positions, see [forexiapro.com/cot-report](https://forexiapro.com/cot-report/?via=cot-data).
+
+## Licence
+
+The code is MIT. The figures are the CFTC's Commitments of Traders (public domain), compiled by Forexia: [forexiapro.com/cot-report](https://forexiapro.com/cot-report/?via=cot-data).
+
+---
+
+Part of the Forexia network: [InterestRateDecision.com](https://interestratedecision.com/?via=cot-data) · [Forexia Academy](https://forexiapro.com/?via=cot-data) · [TradingSignalBot](https://tradingsignalbot.com/?via=cot-data) · [PropSim](https://github.com/PropSim-Enterprise) · [OpenCharts](https://github.com/dylanpersonguy/OpenCharts)

forexia_cot-1.0.0/README.md

@@ -0,0 +1,37 @@
+# forexia-cot
+
+The CFTC's weekly **Commitments of Traders (COT)** report for FX futures, the US dollar index and gold: **positions only** (long, short, net, net as a share of open interest), legacy and TFF reports, weekly since 2010. Reads the files of [github.com/ForexiaPro/cot-data](https://github.com/ForexiaPro/cot-data), updated every Friday after the CFTC's release.
+
+Standard library only. pandas is optional.
+
+```sh
+pip install forexia-cot
+forexia-cot          # this week's table: net non-commercial, weekly change, % of open interest
+forexia-cot gbp      # the pound's last eight weeks
+```
+
+```python
+import forexia_cot as cot
+
+cot.get_cot("EUR")                       # every legacy report since 2010, oldest first (a list of dicts)
+cot.get_cot("USDJPY", report="tff")      # the yen future's TFF groups
+cot.get_cot("gold", since="2024-01-01")
+cot.latest()                             # this week, every market and group
+
+df = cot.cot_frame("EUR")                # pip install "forexia-cot[pandas]"
+df.noncommercial_net.plot()
+```
+
+Markets: `EUR`, `GBP`, `JPY`, `CHF`, `CAD`, `AUD`, `NZD`, `MXN`, `USD` (the dollar index), `XAU` (gold; legacy only). `EURUSD`, `USDJPY`, `gold` and `DXY` work too.
+
+Columns: `date` (the Tuesday the positions were counted), `open_interest`, then for each group `_long`, `_short`, `_net`, `_net_pct_oi` (net as a share of open interest, in per cent); non-commercial also has `_spreading`. Legacy groups: `noncommercial`, `commercial`, `nonreportable`. TFF groups: `dealer`, `asset_manager`, `leveraged_funds`, `other_reportable`, `nonreportable`. Positions are contracts in the future's terms: long `JPY` is long the yen, so short USDJPY.
+
+For Forexia's COT index and weekly reading of these positions, see [forexiapro.com/cot-report](https://forexiapro.com/cot-report/?via=cot-data).
+
+## Licence
+
+The code is MIT. The figures are the CFTC's Commitments of Traders (public domain), compiled by Forexia: [forexiapro.com/cot-report](https://forexiapro.com/cot-report/?via=cot-data).
+
+---
+
+Part of the Forexia network: [InterestRateDecision.com](https://interestratedecision.com/?via=cot-data) · [Forexia Academy](https://forexiapro.com/?via=cot-data) · [TradingSignalBot](https://tradingsignalbot.com/?via=cot-data) · [PropSim](https://github.com/PropSim-Enterprise) · [OpenCharts](https://github.com/dylanpersonguy/OpenCharts)

forexia_cot-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "forexia-cot"
+version = "1.0.0"
+description = "CFTC Commitments of Traders (COT) data for FX futures and gold, legacy and TFF reports: positions, net and net as a share of open interest. Weekly, since 2010."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Forexia" }]
+keywords = ["cot", "cot report", "commitments of traders", "cftc", "forex", "positioning", "futures", "gold"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Intended Audience :: Science/Research",
+]
+dependencies = []
+
+[project.optional-dependencies]
+pandas = ["pandas"]
+
+[project.scripts]
+forexia-cot = "forexia_cot.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/ForexiaPro/cot-data"
+Source = "https://github.com/ForexiaPro/cot-data/tree/main/python"
+"COT report" = "https://forexiapro.com/cot-report/?via=cot-data"

forexia_cot-1.0.0/src/forexia_cot/__init__.py

@@ -0,0 +1,95 @@
+"""CFTC Commitments of Traders (COT) positions for FX futures and gold.
+
+Weekly legacy and TFF reports since 2010 for EUR, GBP, JPY, CHF, CAD, AUD, NZD,
+MXN, the US dollar index and gold, read from github.com/ForexiaPro/cot-data.
+Standard library only; pandas is optional.
+
+CFTC Commitments of Traders (public domain). Compiled by Forexia:
+https://forexiapro.com/cot-report/
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from typing import Any, Callable, Optional
+
+__version__ = "1.0.0"
+__all__ = ["BASE", "MARKETS", "REPORTS", "COT_REPORT", "market_of", "get_cot", "latest", "markets", "cot_frame"]
+
+BASE = "https://raw.githubusercontent.com/ForexiaPro/cot-data/main/data"
+MARKETS = ("EUR", "GBP", "JPY", "CHF", "CAD", "AUD", "NZD", "MXN", "USD", "XAU")
+REPORTS = ("legacy", "tff")
+COT_REPORT = "https://forexiapro.com/cot-report/?via=cot-data"
+
+_ALIASES = {"GOLD": "XAU", "XAUUSD": "XAU", "DXY": "USD", "DX": "USD", "USDX": "USD", "EURO": "EUR"}
+
+Fetch = Callable[[str], str]
+
+
+def _fetch(url: str) -> str:
+    req = urllib.request.Request(url, headers={"User-Agent": f"forexia-cot-python/{__version__}"})
+    with urllib.request.urlopen(req, timeout=30) as res:
+        return res.read().decode("utf-8")
+
+
+def _get(path: str, fetch: Optional[Fetch] = None, base: str = BASE) -> Any:
+    return json.loads((fetch or _fetch)(f"{base}{path}"))
+
+
+def market_of(name: str) -> str:
+    """A market id from what people type: "eur", "EURUSD", "USDJPY", "gold", "DXY"."""
+    s = "".join(c for c in str(name).upper() if c.isalpha())
+    if s in MARKETS:
+        return s
+    if s in _ALIASES:
+        return _ALIASES[s]
+    if len(s) == 6:
+        a, b = s[:3], s[3:]
+        if a == "USD" and b in MARKETS:
+            return b
+        if b == "USD" and a in MARKETS:
+            return a
+    raise ValueError(f'unknown market "{name}" (one of {", ".join(MARKETS)})')
+
+
+def _rows(file: dict) -> list[dict[str, Any]]:
+    cols = file["columns"]
+    return [dict(zip(cols, r)) for r in file["rows"]]
+
+
+def get_cot(market: str, report: str = "legacy", since: Optional[str] = None, fetch: Optional[Fetch] = None, base: str = BASE) -> list[dict[str, Any]]:
+    """Every weekly report of a market since 2010, oldest first.
+
+    ``report`` is ``"legacy"`` (non-commercial, commercial, non-reportable) or
+    ``"tff"`` (dealer, asset manager, leveraged funds, other reportable,
+    non-reportable; not for gold). ``since`` keeps rows on or after a date
+    (YYYY-MM-DD). Positions are contracts in the future's terms: long EUR is
+    long the euro, long JPY is long the yen (short USDJPY).
+    """
+    mid = market_of(market)
+    if report not in REPORTS:
+        raise ValueError(f'unknown report "{report}" (legacy or tff)')
+    if report == "tff" and mid == "XAU":
+        raise ValueError("gold is not in the TFF report; use legacy")
+    rows = _rows(_get(f"/{report}/{mid}.json", fetch, base))
+    return [r for r in rows if since is None or r["date"] >= since]
+
+
+def latest(fetch: Optional[Fetch] = None, base: str = BASE) -> dict[str, Any]:
+    """The latest report of every market: net, weekly change and share of open interest of each group."""
+    return _get("/latest.json", fetch, base)
+
+
+def markets(fetch: Optional[Fetch] = None, base: str = BASE) -> list[dict[str, Any]]:
+    """The markets, their CFTC codes and the dates each report covers."""
+    return _get("/markets.json", fetch, base)["markets"]
+
+
+def cot_frame(market: str, report: str = "legacy", since: Optional[str] = None, fetch: Optional[Fetch] = None):
+    """The reports as a pandas DataFrame indexed by date (needs pandas)."""
+    import pandas as pd  # optional
+
+    df = pd.DataFrame(get_cot(market, report, since, fetch))
+    df["date"] = pd.to_datetime(df["date"])
+    return df.set_index("date")

forexia_cot-1.0.0/src/forexia_cot/__main__.py

@@ -0,0 +1,35 @@
+"""forexia-cot: this week's positioning, or one market's last weeks."""
+
+from __future__ import annotations
+
+import sys
+
+from . import COT_REPORT, get_cot, latest
+
+
+def _fmt(x) -> str:
+    return "" if x is None else f"{x:,}" if isinstance(x, int) else str(x)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if args:
+        rows = get_cot(args[0], args[1] if len(args) > 1 else "legacy")[-8:]
+        group = "noncommercial" if "noncommercial_net" in rows[-1] else "leveraged_funds"
+        label = "net " + group.replace("_", " ")
+        print(f"{'date':<12}{label:>22}{'% of OI':>10}")
+        for r in rows:
+            print(f"{r['date']:<12}{_fmt(r[group + '_net']):>22}{_fmt(r[group + '_net_pct_oi']):>10}")
+    else:
+        data = latest()
+        print(f"COT report of {data['report_date']} (non-commercial, legacy)")
+        print(f"{'market':<8}{'net':>12}{'1w':>10}{'% of OI':>10}")
+        for m in data["markets"]:
+            nc = m["legacy"]["noncommercial"]
+            print(f"{m['id']:<8}{_fmt(nc['net']):>12}{_fmt(nc['net_change_1w']):>10}{_fmt(nc['net_pct_oi']):>10}")
+    print(f"\nForexia's COT index and weekly reading: {COT_REPORT}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

forexia_cot-1.0.0/tests/fixtures/latest.json

@@ -0,0 +1,500 @@
+{
+  "report_date": "2026-10-27",
+  "released": "2026-10-30T19:30:00.000Z",
+  "source": "CFTC Commitments of Traders (public domain). Compiled by Forexia: https://forexiapro.com/cot-report/?via=cot-data",
+  "markets": [
+    {
+      "id": "EUR",
+      "name": "Euro FX",
+      "code": "099741",
+      "report_date": "2026-10-27",
+      "open_interest": 868188,
+      "legacy": {
+        "noncommercial": {
+          "net": -143894,
+          "net_change_1w": -9370,
+          "net_pct_oi": -16.57
+        },
+        "commercial": {
+          "net": 114484,
+          "net_change_1w": 9589,
+          "net_pct_oi": 13.19
+        },
+        "nonreportable": {
+          "net": 29410,
+          "net_change_1w": -219,
+          "net_pct_oi": 3.39
+        }
+      },
+      "tff": {
+        "dealer": {
+          "net": -138016,
+          "net_change_1w": 17702,
+          "net_pct_oi": -15.9
+        },
+        "asset_manager": {
+          "net": 173249,
+          "net_change_1w": -17172,
+          "net_pct_oi": 19.96
+        },
+        "leveraged_funds": {
+          "net": -71574,
+          "net_change_1w": -2734,
+          "net_pct_oi": -8.24
+        },
+        "other_reportable": {
+          "net": 6931,
+          "net_change_1w": 2423,
+          "net_pct_oi": 0.8
+        },
+        "nonreportable": {
+          "net": 29410,
+          "net_change_1w": -219,
+          "net_pct_oi": 3.39
+        }
+      },
+      "released": "2026-10-30T19:30:00.000Z"
+    },
+    {
+      "id": "GBP",
+      "name": "British pound",
+      "code": "096742",
+      "report_date": "2026-10-27",
+      "open_interest": 253937,
+      "legacy": {
+        "noncommercial": {
+          "net": -79414,
+          "net_change_1w": 1006,
+          "net_pct_oi": -31.27
+        },
+        "commercial": {
+          "net": 89898,
+          "net_change_1w": -5610,
+          "net_pct_oi": 35.4
+        },
+        "nonreportable": {
+          "net": -10484,
+          "net_change_1w": 4604,
+          "net_pct_oi": -4.13
+        }
+      },
+      "tff": {
+        "dealer": {
+          "net": 121697,
+          "net_change_1w": -3423,
+          "net_pct_oi": 47.92
+        },
+        "asset_manager": {
+          "net": -128893,
+          "net_change_1w": 5728,
+          "net_pct_oi": -50.76
+        },
+        "leveraged_funds": {
+          "net": 17195,
+          "net_change_1w": -6909,
+          "net_pct_oi": 6.77
+        },
+        "other_reportable": {
+          "net": 485,
+          "net_change_1w": 0,
+          "net_pct_oi": 0.19
+        },
+        "nonreportable": {
+          "net": -10484,
+          "net_change_1w": 4604,
+          "net_pct_oi": -4.13
+        }
+      },
+      "released": "2026-10-30T19:30:00.000Z"
+    },
+    {
+      "id": "JPY",
+      "name": "Japanese yen",
+      "code": "097741",
+      "report_date": "2026-10-27",
+      "open_interest": 374026,
+      "legacy": {
+        "noncommercial": {
+          "net": 101591,
+          "net_change_1w": 31713,
+          "net_pct_oi": 27.16
+        },
+        "commercial": {
+          "net": -105090,
+          "net_change_1w": -34003,
+          "net_pct_oi": -28.1
+        },
+        "nonreportable": {
+          "net": 3499,
+          "net_change_1w": 2290,
+          "net_pct_oi": 0.94
+        }
+      },
+      "tff": {
+        "dealer": {
+          "net": -130739,
+          "net_change_1w": -31449,
+          "net_pct_oi": -34.95
+        },
+        "asset_manager": {
+          "net": 91191,
+          "net_change_1w": 12088,
+          "net_pct_oi": 24.38
+        },
+        "leveraged_funds": {
+          "net": -14630,
+          "net_change_1w": 8260,
+          "net_pct_oi": -3.91
+        },
+        "other_reportable": {
+          "net": 50679,
+          "net_change_1w": 8811,
+          "net_pct_oi": 13.55
+        },
+        "nonreportable": {
+          "net": 3499,
+          "net_change_1w": 2290,
+          "net_pct_oi": 0.94
+        }
+      },
+      "released": "2026-10-30T19:30:00.000Z"
+    },
+    {
+      "id": "CHF",
+      "name": "Swiss franc",
+      "code": "092741",
+      "report_date": "2026-10-27",
+      "open_interest": 135489,
+      "legacy": {
+        "noncommercial": {
+          "net": -20049,
+          "net_change_1w": -1899,
+          "net_pct_oi": -14.8
+        },
+        "commercial": {
+          "net": 33633,
+          "net_change_1w": -384,
+          "net_pct_oi": 24.82
+        },
+        "nonreportable": {
+          "net": -13584,
+          "net_change_1w": 2283,
+          "net_pct_oi": -10.03
+        }
+      },
+      "tff": {
+        "dealer": {
+          "net": 56207,
+          "net_change_1w": 1564,
+          "net_pct_oi": 41.48
+        },
+        "asset_manager": {
+          "net": -25067,
+          "net_change_1w": 468,
+          "net_pct_oi": -18.5
+        },
+        "leveraged_funds": {
+          "net": -17502,
+          "net_change_1w": -3895,
+          "net_pct_oi": -12.92
+        },
+        "other_reportable": {
+          "net": -54,
+          "net_change_1w": -420,
+          "net_pct_oi": -0.04
+        },
+        "nonreportable": {
+          "net": -13584,
+          "net_change_1w": 2283,
+          "net_pct_oi": -10.03
+        }
+      },
+      "released": "2026-10-30T19:30:00.000Z"
+    },
+    {
+      "id": "CAD",
+      "name": "Canadian dollar",
+      "code": "090741",
+      "report_date": "2026-10-27",
+      "open_interest": 360941,
+      "legacy": {
+        "noncommercial": {
+          "net": -66424,
+          "net_change_1w": 8285,
+          "net_pct_oi": -18.4
+        },
+        "commercial": {
+          "net": 74260,
+          "net_change_1w": -12588,
+          "net_pct_oi": 20.57
+        },
+        "nonreportable": {
+          "net": -7836,
+          "net_change_1w": 4303,
+          "net_pct_oi": -2.17
+        }
+      },
+      "tff": {
+        "dealer": {
+          "net": 95809,
+          "net_change_1w": -4989,
+          "net_pct_oi": 26.54
+        },
+        "asset_manager": {
+          "net": -1325,
+          "net_change_1w": 4074,
+          "net_pct_oi": -0.37
+        },
+        "leveraged_funds": {
+          "net": -96747,
+          "net_change_1w": -5634,
+          "net_pct_oi": -26.8
+        },
+        "other_reportable": {
+          "net": 10099,
+          "net_change_1w": 2246,
+          "net_pct_oi": 2.8
+        },
+        "nonreportable": {
+          "net": -7836,
+          "net_change_1w": 4303,
+          "net_pct_oi": -2.17
+        }
+      },
+      "released": "2026-10-30T19:30:00.000Z"
+    },
+    {
+      "id": "AUD",
+      "name": "Australian dollar",
+      "code": "232741",
+      "report_date": "2026-10-27",
+      "open_interest": 325008,
+      "legacy": {
+        "noncommercial": {
+          "net": -128315,
+          "net_change_1w": -1023,
+          "net_pct_oi": -39.48
+        },
+        "commercial": {
+          "net": 111235,
+          "net_change_1w": -3690,
+          "net_pct_oi": 34.23
+        },
+        "nonreportable": {
+          "net": 17080,
+          "net_change_1w": 4713,
+          "net_pct_oi": 5.26
+        }
+      },
+      "tff": {
+        "dealer": {
+          "net": 55637,
+          "net_change_1w": -4637,
+          "net_pct_oi": 17.12
+        },
+        "asset_manager": {
+          "net": -125237,
+          "net_change_1w": 3502,
+          "net_pct_oi": -38.53
+        },
+        "leveraged_funds": {
+          "net": 48414,
+          "net_change_1w": -4083,
+          "net_pct_oi": 14.9
+        },
+        "other_reportable": {
+          "net": 4106,
+          "net_change_1w": 505,
+          "net_pct_oi": 1.26
+        },
+        "nonreportable": {
+          "net": 17080,
+          "net_change_1w": 4713,
+          "net_pct_oi": 5.26
+        }
+      },
+      "released": "2026-10-30T19:30:00.000Z"
+    },
+    {
+      "id": "NZD",
+      "name": "New Zealand dollar",
+      "code": "112741",
+      "report_date": "2026-10-27",
+      "open_interest": 129053,
+      "legacy": {
+        "noncommercial": {
+          "net": -57690,
+          "net_change_1w": 459,
+          "net_pct_oi": -44.7
+        },
+        "commercial": {
+          "net": 59546,
+          "net_change_1w": -876,
+          "net_pct_oi": 46.14
+        },
+        "nonreportable": {
+          "net": -1856,
+          "net_change_1w": 417,
+          "net_pct_oi": -1.44
+        }
+      },
+      "tff": {
+        "dealer": {
+          "net": 68000,
+          "net_change_1w": 718,
+          "net_pct_oi": 52.69
+        },
+        "asset_manager": {
+          "net": -46841,
+          "net_change_1w": 2472,
+          "net_pct_oi": -36.3
+        },
+        "leveraged_funds": {
+          "net": -22554,
+          "net_change_1w": -3274,
+          "net_pct_oi": -17.48
+        },
+        "other_reportable": {
+          "net": 3251,
+          "net_change_1w": -333,
+          "net_pct_oi": 2.52
+        },
+        "nonreportable": {
+          "net": -1856,
+          "net_change_1w": 417,
+          "net_pct_oi": -1.44
+        }
+      },
+      "released": "2026-10-30T19:30:00.000Z"
+    },
+    {
+      "id": "MXN",
+      "name": "Mexican peso",
+      "code": "095741",
+      "report_date": "2026-10-27",
+      "open_interest": 279359,
+      "legacy": {
+        "noncommercial": {
+          "net": 20843,
+          "net_change_1w": 3820,
+          "net_pct_oi": 7.46
+        },
+        "commercial": {
+          "net": -21166,
+          "net_change_1w": -3340,
+          "net_pct_oi": -7.58
+        },
+        "nonreportable": {
+          "net": 323,
+          "net_change_1w": -480,
+          "net_pct_oi": 0.12
+        }
+      },
+      "tff": {
+        "dealer": {
+          "net": 12757,
+          "net_change_1w": -2495,
+          "net_pct_oi": 4.57
+        },
+        "asset_manager": {
+          "net": -25201,
+          "net_change_1w": -1137,
+          "net_pct_oi": -9.02
+        },
+        "leveraged_funds": {
+          "net": 68335,
+          "net_change_1w": 4521,
+          "net_pct_oi": 24.46
+        },
+        "other_reportable": {
+          "net": -56214,
+          "net_change_1w": -409,
+          "net_pct_oi": -20.12
+        },
+        "nonreportable": {
+          "net": 323,
+          "net_change_1w": -480,
+          "net_pct_oi": 0.12
+        }
+      },
+      "released": "2026-10-30T19:30:00.000Z"
+    },
+    {
+      "id": "USD",
+      "name": "US dollar index",
+      "code": "098662",
+      "report_date": "2026-10-27",
+      "open_interest": 48263,
+      "legacy": {
+        "noncommercial": {
+          "net": 14121,
+          "net_change_1w": -923,
+          "net_pct_oi": 29.26
+        },
+        "commercial": {
+          "net": -16088,
+          "net_change_1w": 926,
+          "net_pct_oi": -33.33
+        },
+        "nonreportable": {
+          "net": 1967,
+          "net_change_1w": -3,
+          "net_pct_oi": 4.08
+        }
+      },
+      "tff": {
+        "dealer": {
+          "net": -19547,
+          "net_change_1w": 432,
+          "net_pct_oi": -40.5
+        },
+        "asset_manager": {
+          "net": 16713,
+          "net_change_1w": -307,
+          "net_pct_oi": 34.63
+        },
+        "leveraged_funds": {
+          "net": 3158,
+          "net_change_1w": -25,
+          "net_pct_oi": 6.54
+        },
+        "other_reportable": {
+          "net": -2291,
+          "net_change_1w": -97,
+          "net_pct_oi": -4.75
+        },
+        "nonreportable": {
+          "net": 1967,
+          "net_change_1w": -3,
+          "net_pct_oi": 4.08
+        }
+      },
+      "released": "2026-10-30T19:30:00.000Z"
+    },
+    {
+      "id": "XAU",
+      "name": "Gold",
+      "code": "088691",
+      "report_date": "2026-10-27",
+      "open_interest": 396810,
+      "legacy": {
+        "noncommercial": {
+          "net": 186451,
+          "net_change_1w": -13414,
+          "net_pct_oi": 46.99
+        },
+        "commercial": {
+          "net": -215624,
+          "net_change_1w": 19958,
+          "net_pct_oi": -54.34
+        },
+        "nonreportable": {
+          "net": 29173,
+          "net_change_1w": -6544,
+          "net_pct_oi": 7.35
+        }
+      },
+      "released": "2026-10-30T19:30:00.000Z"
+    }
+  ]
+}

forexia_cot-1.0.0/tests/fixtures/legacy-EUR.json

@@ -0,0 +1 @@
+{"market":"EUR","name":"Euro FX","cftc_code":"099741","exchange":"CME","report":"legacy","source":"CFTC Commitments of Traders, Legacy - Futures Only (publicreporting.cftc.gov, dataset 6dca-aqww)","first":"2026-10-13","last":"2026-10-27","columns":["date","open_interest","noncommercial_long","noncommercial_short","noncommercial_spreading","noncommercial_net","noncommercial_net_pct_oi","commercial_long","commercial_short","commercial_net","commercial_net_pct_oi","nonreportable_long","nonreportable_short","nonreportable_net","nonreportable_net_pct_oi"],"rows":[["2026-10-13",874541,222929,360502,45685,-137573,-15.73,521361,410136,111225,12.72,84566,58218,26348,3.01],["2026-10-20",877940,226421,360945,43294,-134524,-15.32,522461,417566,104895,11.95,85764,56135,29629,3.37],["2026-10-27",868188,230646,374540,49306,-143894,-16.57,504851,390367,114484,13.19,83385,53975,29410,3.39]]}

forexia_cot-1.0.0/tests/fixtures/markets.json

@@ -0,0 +1,217 @@
+{
+  "markets": [
+    {
+      "id": "EUR",
+      "name": "Euro FX",
+      "code": "099741",
+      "exchange": "CME",
+      "reports": {
+        "legacy": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/legacy/EUR.csv",
+          "json": "data/legacy/EUR.json"
+        },
+        "tff": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/tff/EUR.csv",
+          "json": "data/tff/EUR.json"
+        }
+      }
+    },
+    {
+      "id": "GBP",
+      "name": "British pound",
+      "code": "096742",
+      "exchange": "CME",
+      "reports": {
+        "legacy": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/legacy/GBP.csv",
+          "json": "data/legacy/GBP.json"
+        },
+        "tff": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/tff/GBP.csv",
+          "json": "data/tff/GBP.json"
+        }
+      }
+    },
+    {
+      "id": "JPY",
+      "name": "Japanese yen",
+      "code": "097741",
+      "exchange": "CME",
+      "reports": {
+        "legacy": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/legacy/JPY.csv",
+          "json": "data/legacy/JPY.json"
+        },
+        "tff": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/tff/JPY.csv",
+          "json": "data/tff/JPY.json"
+        }
+      }
+    },
+    {
+      "id": "CHF",
+      "name": "Swiss franc",
+      "code": "092741",
+      "exchange": "CME",
+      "reports": {
+        "legacy": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/legacy/CHF.csv",
+          "json": "data/legacy/CHF.json"
+        },
+        "tff": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/tff/CHF.csv",
+          "json": "data/tff/CHF.json"
+        }
+      }
+    },
+    {
+      "id": "CAD",
+      "name": "Canadian dollar",
+      "code": "090741",
+      "exchange": "CME",
+      "reports": {
+        "legacy": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/legacy/CAD.csv",
+          "json": "data/legacy/CAD.json"
+        },
+        "tff": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/tff/CAD.csv",
+          "json": "data/tff/CAD.json"
+        }
+      }
+    },
+    {
+      "id": "AUD",
+      "name": "Australian dollar",
+      "code": "232741",
+      "exchange": "CME",
+      "reports": {
+        "legacy": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/legacy/AUD.csv",
+          "json": "data/legacy/AUD.json"
+        },
+        "tff": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/tff/AUD.csv",
+          "json": "data/tff/AUD.json"
+        }
+      }
+    },
+    {
+      "id": "NZD",
+      "name": "New Zealand dollar",
+      "code": "112741",
+      "exchange": "CME",
+      "reports": {
+        "legacy": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/legacy/NZD.csv",
+          "json": "data/legacy/NZD.json"
+        },
+        "tff": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/tff/NZD.csv",
+          "json": "data/tff/NZD.json"
+        }
+      }
+    },
+    {
+      "id": "MXN",
+      "name": "Mexican peso",
+      "code": "095741",
+      "exchange": "CME",
+      "reports": {
+        "legacy": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/legacy/MXN.csv",
+          "json": "data/legacy/MXN.json"
+        },
+        "tff": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/tff/MXN.csv",
+          "json": "data/tff/MXN.json"
+        }
+      }
+    },
+    {
+      "id": "USD",
+      "name": "US dollar index",
+      "code": "098662",
+      "exchange": "ICE Futures U.S.",
+      "reports": {
+        "legacy": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/legacy/USD.csv",
+          "json": "data/legacy/USD.json"
+        },
+        "tff": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/tff/USD.csv",
+          "json": "data/tff/USD.json"
+        }
+      }
+    },
+    {
+      "id": "XAU",
+      "name": "Gold",
+      "code": "088691",
+      "exchange": "COMEX",
+      "reports": {
+        "legacy": {
+          "first": "2010-01-05",
+          "last": "2026-10-27",
+          "weeks": 878,
+          "csv": "data/legacy/XAU.csv",
+          "json": "data/legacy/XAU.json"
+        }
+      }
+    }
+  ]
+}

forexia_cot-1.0.0/tests/test_client.py

@@ -0,0 +1,70 @@
+import io
+import json
+import pathlib
+import unittest
+from contextlib import redirect_stdout
+
+import forexia_cot as cot
+from forexia_cot.__main__ import main
+
+FIXTURES = pathlib.Path(__file__).parent / "fixtures"
+FILES = {
+    "/legacy/EUR.json": (FIXTURES / "legacy-EUR.json").read_text(encoding="utf-8"),
+    "/latest.json": (FIXTURES / "latest.json").read_text(encoding="utf-8"),
+    "/markets.json": (FIXTURES / "markets.json").read_text(encoding="utf-8"),
+}
+
+
+def fetch(url: str) -> str:
+    path = url[len(cot.BASE):]
+    if path not in FILES:
+        raise FileNotFoundError(path)
+    return FILES[path]
+
+
+class Markets(unittest.TestCase):
+    def test_names(self):
+        self.assertEqual(cot.market_of("eur"), "EUR")
+        self.assertEqual(cot.market_of("EUR/USD"), "EUR")
+        self.assertEqual(cot.market_of("USDJPY"), "JPY")
+        self.assertEqual(cot.market_of("gold"), "XAU")
+        self.assertEqual(cot.market_of("DXY"), "USD")
+        with self.assertRaises(ValueError):
+            cot.market_of("BTC")
+
+
+class Client(unittest.TestCase):
+    def test_get_cot(self):
+        rows = cot.get_cot("EUR", fetch=fetch)
+        self.assertEqual(len(rows), 3)
+        self.assertEqual(rows[-1]["date"], "2026-10-27")
+        self.assertEqual(rows[-1]["noncommercial_net"], -143894)
+        self.assertEqual(rows[-1]["noncommercial_net_pct_oi"], -16.57)
+        self.assertNotIn("noncommercial_extreme", rows[-1])
+        self.assertEqual(len(cot.get_cot("EURUSD", since="2026-10-20", fetch=fetch)), 2)
+        with self.assertRaises(ValueError):
+            cot.get_cot("XAU", report="tff", fetch=fetch)
+
+    def test_latest_and_markets(self):
+        eur = next(m for m in cot.latest(fetch)["markets"] if m["id"] == "EUR")
+        self.assertEqual(eur["legacy"]["noncommercial"], {"net": -143894, "net_change_1w": -9370, "net_pct_oi": -16.57})
+        self.assertNotIn("extremes", cot.latest(fetch))
+        self.assertEqual(len(cot.markets(fetch)), 10)
+
+    def test_cli(self):
+        original = cot.latest
+        try:
+            import forexia_cot.__main__ as m
+
+            m.latest = lambda: json.loads(FILES["/latest.json"])
+            out = io.StringIO()
+            with redirect_stdout(out):
+                main([])
+            self.assertIn("EUR", out.getvalue())
+            self.assertIn("via=cot-data", out.getvalue())
+        finally:
+            m.latest = original
+
+
+if __name__ == "__main__":
+    unittest.main()