forexia-cot 1.0.0__py3-none-any.whl

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/__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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+forexia_cot/__init__.py,sha256=jJDpVeOsgFqLoPgiSfrkqGSDD-5rNgb-bp0CgsxBFOQ,3893
+forexia_cot/__main__.py,sha256=xC5U46JBTmoLD_9PmSv4f6IVVY0NCmX-eGgxlW53wHM,1323
+forexia_cot-1.0.0.dist-info/METADATA,sha256=ES5CHp_Aa-vNHntmkESfQ-EHzTtMJH9zKbjIY7Lk6KA,3361
+forexia_cot-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+forexia_cot-1.0.0.dist-info/entry_points.txt,sha256=yXehXfZggVpSEitilzAE6Jinla1ZDEDYDGXrlYh_ddM,58
+forexia_cot-1.0.0.dist-info/licenses/LICENSE,sha256=aLgD8_vL8T83utXdti9eLTRTIXrBWbblBifs-2D80kM,1102
+forexia_cot-1.0.0.dist-info/RECORD,,

forexia_cot-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

forexia_cot-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+forexia-cot = forexia_cot.__main__:main

forexia_cot-1.0.0.dist-info/licenses/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.