finbrain-python 0.1.6__tar.gz → 0.1.8__tar.gz

{finbrain_python-0.1.6 → finbrain_python-0.1.8}/.github/workflows/ci.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        python: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
     steps:
       - uses: actions/checkout@v4
         with:

{finbrain_python-0.1.6 → finbrain_python-0.1.8}/CHANGELOG.md

@@ -7,9 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.7] - 2025-10-02
+
+### Added
+
+- **Insider Transactions Plotting**: `fb.plot.insider_transactions()` - Overlay insider buy/sell markers on user-provided price charts
+- **House Trades Plotting**: `fb.plot.house_trades()` - Visualize U.S. House member trades on price charts
+- **Transaction Plotting Example**: `examples/transactions_plotting_example.py` demonstrating integration with various price data sources
+- **Plotting Tests**: Extended `tests/test_plotting.py` with 8 new test cases for transaction plotting
+
+### Changed
+
+- **Price Data Flexibility**: Plotting methods now auto-detect multiple price column formats (`close`, `Close`, `price`, `Price`, `adj_close`, `Adj Close`)
+- **MultiIndex Support**: Transaction plotting methods now handle yfinance's MultiIndex column format (from `yf.download()`)
+- **Timezone Handling**: Automatic timezone normalization to handle timezone-aware price data (e.g., from yfinance)
+
+### Fixed
+
+- **Column Detection**: Fixed `KeyError` when house trades API returns `type` column instead of `transaction`
+- **yfinance Compatibility**: Fixed price line not displaying when using `yf.download()` due to MultiIndex columns
+
 ## [0.1.6] - 2025-10-02
 
 ### Added
+
 - **Async Support**: Full async/await implementation using `httpx`
   - `AsyncFinBrainClient` with context manager support
   - All 9 endpoints have async equivalents
@@ -23,15 +44,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Release guide**: `RELEASE.md` with tag conventions
 
 ### Changed
+
 - **Tag Convention**: Now using `v` prefix (e.g., `v0.1.6` instead of `0.1.6`)
 - **GitHub Actions**: Updated to trigger on `v[0-9]*` tags
 - **Code Deduplication**: Consolidated 12 duplicate `_to_datestr()` helpers into 2 utility modules
 - **README**: Added async usage section with examples
 
 ### Fixed
+
 - **Plotting Error Handling**: `options()` method now raises clear `ValueError` for invalid `kind` parameter instead of `NameError`
 
 ### Dependencies
+
 - Added `httpx>=0.24` as optional dependency for async support
 - Added `pytest-asyncio` as dev dependency
 
@@ -55,7 +79,8 @@ Previous releases...
 
 Previous releases...
 
-[Unreleased]: https://github.com/ahmetsbilgin/finbrain-python/compare/v0.1.6...HEAD
+[Unreleased]: https://github.com/ahmetsbilgin/finbrain-python/compare/v0.1.7...HEAD
+[0.1.7]: https://github.com/ahmetsbilgin/finbrain-python/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/ahmetsbilgin/finbrain-python/compare/0.1.5...v0.1.6
 [0.1.5]: https://github.com/ahmetsbilgin/finbrain-python/compare/0.1.4...0.1.5
 [0.1.4]: https://github.com/ahmetsbilgin/finbrain-python/compare/0.1.3...0.1.4

{finbrain_python-0.1.6 → finbrain_python-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finbrain-python
-Version: 0.1.6
+Version: 0.1.8
 Summary: Official Python client for the FinBrain API
 Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
 License-Expression: MIT
@@ -86,6 +86,12 @@ fb.house_trades.ticker("S&P 500", "AMZN",
                        date_to="2025-06-30",
                        as_dataframe=True)
 
+# ---------- senate trades ----------
+fb.senate_trades.ticker("NASDAQ", "META",
+                        date_from="2025-01-01",
+                        date_to="2025-06-30",
+                        as_dataframe=True)
+
 # ---------- insider transactions ----------
 fb.insider_transactions.ticker("S&P 500", "AMZN", as_dataframe=True)
 
@@ -184,8 +190,42 @@ fb.plot.predictions("AMZN")         # prediction_type="monthly" for monthly pred
 fb.plot.sentiments("S&P 500", "AMZN",
                    date_from="2025-01-01",
                    date_to="2025-06-30")
+
+# ---------- Insider Transactions, House & Senate Trades (requires user price data) ----------
+# These plots overlay transaction markers on a price chart.
+# Since FinBrain doesn't provide historical prices, you must provide your own:
+
+import pandas as pd
+
+# Example: Load your price data from any legal source
+# (broker API, licensed data provider, CSV file, etc.)
+price_df = pd.DataFrame({
+    "close": [150.25, 151.30, 149.80],  # Your price data
+    "date": pd.date_range("2025-01-01", periods=3)
+}).set_index("date")
+
+# Plot insider transactions on your price chart
+fb.plot.insider_transactions("S&P 500", "AAPL", price_data=price_df)
+
+# Plot House member trades on your price chart
+fb.plot.house_trades("S&P 500", "NVDA",
+                     price_data=price_df,
+                     date_from="2025-01-01",
+                     date_to="2025-06-30")
+
+# Plot Senate member trades on your price chart
+fb.plot.senate_trades("NASDAQ", "META",
+                      price_data=price_df,
+                      date_from="2025-01-01",
+                      date_to="2025-06-30")
 ```
 
+**Price Data Requirements:**
+
+- DataFrame with DatetimeIndex
+- Must contain a price column: `close`, `Close`, `price`, `Price`, `adj_close`, or `Adj Close`
+- Obtain from legal sources: broker API, Bloomberg, Alpha Vantage, FMP, etc.
+
 ## 🔑 Authentication
 
 To call the API you need an **API key**, obtained by purchasing a **FinBrain API subscription**.  
@@ -214,6 +254,7 @@ fb = FinBrainClient(api_key="YOUR_KEY")
 | App ratings          | `client.app_ratings.ticker()`            | `/appratings/{MARKET}/{TICKER}`                      |
 | Analyst ratings      | `client.analyst_ratings.ticker()`        | `/analystratings/{MARKET}/{TICKER}`                  |
 | House trades         | `client.house_trades.ticker()`           | `/housetrades/{MARKET}/{TICKER}`                     |
+| Senate trades        | `client.senate_trades.ticker()`          | `/senatetrades/{MARKET}/{TICKER}`                    |
 | Insider transactions | `client.insider_transactions.ticker()`   | `/insidertransactions/{MARKET}/{TICKER}`             |
 | LinkedIn             | `client.linkedin_data.ticker()`          | `/linkedindata/{MARKET}/{TICKER}`                    |
 | Options – Put/Call   | `client.options.put_call()`              | `/putcalldata/{MARKET}/{TICKER}`                     |

{finbrain_python-0.1.6 → finbrain_python-0.1.8}/README.md

@@ -60,6 +60,12 @@ fb.house_trades.ticker("S&P 500", "AMZN",
                        date_to="2025-06-30",
                        as_dataframe=True)
 
+# ---------- senate trades ----------
+fb.senate_trades.ticker("NASDAQ", "META",
+                        date_from="2025-01-01",
+                        date_to="2025-06-30",
+                        as_dataframe=True)
+
 # ---------- insider transactions ----------
 fb.insider_transactions.ticker("S&P 500", "AMZN", as_dataframe=True)
 
@@ -158,8 +164,42 @@ fb.plot.predictions("AMZN")         # prediction_type="monthly" for monthly pred
 fb.plot.sentiments("S&P 500", "AMZN",
                    date_from="2025-01-01",
                    date_to="2025-06-30")
+
+# ---------- Insider Transactions, House & Senate Trades (requires user price data) ----------
+# These plots overlay transaction markers on a price chart.
+# Since FinBrain doesn't provide historical prices, you must provide your own:
+
+import pandas as pd
+
+# Example: Load your price data from any legal source
+# (broker API, licensed data provider, CSV file, etc.)
+price_df = pd.DataFrame({
+    "close": [150.25, 151.30, 149.80],  # Your price data
+    "date": pd.date_range("2025-01-01", periods=3)
+}).set_index("date")
+
+# Plot insider transactions on your price chart
+fb.plot.insider_transactions("S&P 500", "AAPL", price_data=price_df)
+
+# Plot House member trades on your price chart
+fb.plot.house_trades("S&P 500", "NVDA",
+                     price_data=price_df,
+                     date_from="2025-01-01",
+                     date_to="2025-06-30")
+
+# Plot Senate member trades on your price chart
+fb.plot.senate_trades("NASDAQ", "META",
+                      price_data=price_df,
+                      date_from="2025-01-01",
+                      date_to="2025-06-30")
 ```
 
+**Price Data Requirements:**
+
+- DataFrame with DatetimeIndex
+- Must contain a price column: `close`, `Close`, `price`, `Price`, `adj_close`, or `Adj Close`
+- Obtain from legal sources: broker API, Bloomberg, Alpha Vantage, FMP, etc.
+
 ## 🔑 Authentication
 
 To call the API you need an **API key**, obtained by purchasing a **FinBrain API subscription**.  
@@ -188,6 +228,7 @@ fb = FinBrainClient(api_key="YOUR_KEY")
 | App ratings          | `client.app_ratings.ticker()`            | `/appratings/{MARKET}/{TICKER}`                      |
 | Analyst ratings      | `client.analyst_ratings.ticker()`        | `/analystratings/{MARKET}/{TICKER}`                  |
 | House trades         | `client.house_trades.ticker()`           | `/housetrades/{MARKET}/{TICKER}`                     |
+| Senate trades        | `client.senate_trades.ticker()`          | `/senatetrades/{MARKET}/{TICKER}`                    |
 | Insider transactions | `client.insider_transactions.ticker()`   | `/insidertransactions/{MARKET}/{TICKER}`             |
 | LinkedIn             | `client.linkedin_data.ticker()`          | `/linkedindata/{MARKET}/{TICKER}`                    |
 | Options – Put/Call   | `client.options.put_call()`              | `/putcalldata/{MARKET}/{TICKER}`                     |

{finbrain_python-0.1.6 → finbrain_python-0.1.8}/RELEASE.md

@@ -35,13 +35,14 @@ git push origin v0.1.6
 ### 3. GitHub Actions (Automated)
 
 GitHub Actions will automatically:
+
 - Build the wheel and source distribution
 - Upload to TestPyPI first
 - Upload to production PyPI
 
 ### 4. Create GitHub Release (Manual)
 
-1. Go to: https://github.com/ahmetsbilgin/finbrain-python/releases/new
+1. Go to: <https://github.com/ahmetsbilgin/finbrain-python/releases/new>
 2. Select tag: `v0.1.6`
 3. Title: `v0.1.6 - Brief Description`
 4. Copy the relevant section from `CHANGELOG.md` into the description
@@ -49,7 +50,7 @@ GitHub Actions will automatically:
 
 ### 5. Verify
 
-- Check PyPI: https://pypi.org/project/finbrain-python/
+- Check PyPI: <https://pypi.org/project/finbrain-python/>
 - Test installation: `pip install finbrain-python==0.1.6`
 
 ## How setuptools-scm Works

finbrain_python-0.1.8/examples/transactions_plotting_example.py

@@ -0,0 +1,143 @@
+"""
+Example: Plotting Insider Transactions and House Trades with User-Provided Price Data
+
+This example demonstrates how to visualize insider transactions and House member trades
+on a price chart. Since FinBrain doesn't provide historical price data, users must
+bring their own price data from legal sources (e.g., their broker, Bloomberg, etc.).
+"""
+
+import os
+import pandas as pd
+from finbrain import FinBrainClient
+
+# Initialize client
+api_key = os.environ.get("FINBRAIN_API_KEY")
+if not api_key:
+    raise ValueError("Please set FINBRAIN_API_KEY environment variable")
+
+fb = FinBrainClient(api_key=api_key)
+
+# ============================================================================
+# Example 1: Mock price data for demonstration
+# ============================================================================
+# In production, replace this with real price data from your legal source
+# (broker API, Bloomberg, Alpha Vantage, yfinance with proper licensing, etc.)
+
+mock_prices = pd.DataFrame({
+    "date": pd.date_range("2024-01-01", "2024-12-31", freq="D"),
+    "close": [150 + i * 0.5 for i in range(366)],  # Simulated price trend
+})
+mock_prices.set_index("date", inplace=True)
+
+print("=" * 70)
+print("Example 1: Insider Transactions with Mock Price Data")
+print("=" * 70)
+
+# Plot insider transactions for AAPL
+# This will fetch real transaction data from FinBrain and overlay on your price data
+fig_insider = fb.plot.insider_transactions(
+    market="S&P 500",
+    ticker="AAPL",
+    price_data=mock_prices,
+    show=False,  # Don't display immediately for this example
+)
+
+print(f"Created insider transactions plot with {len(fig_insider.data)} traces")
+print("Green triangles (▲) = Buys | Red triangles (▼) = Sells")
+
+# Uncomment to display the figure:
+# fig_insider.show()
+
+# ============================================================================
+# Example 2: House Trades with Date Filtering
+# ============================================================================
+print("\n" + "=" * 70)
+print("Example 2: House Trades with Date Filtering")
+print("=" * 70)
+
+# Plot House member trades for a specific date range
+fig_house = fb.plot.house_trades(
+    market="S&P 500",
+    ticker="NVDA",
+    price_data=mock_prices,
+    date_from="2024-06-01",
+    date_to="2024-12-31",
+    show=False,
+)
+
+print(f"Created House trades plot with {len(fig_house.data)} traces")
+
+# Uncomment to display the figure:
+# fig_house.show()
+
+# ============================================================================
+# Example 3: Using Real Price Data (conceptual - adjust to your source)
+# ============================================================================
+print("\n" + "=" * 70)
+print("Example 3: Integration with Real Price Data (Conceptual)")
+print("=" * 70)
+
+# Example pattern for integrating with real data sources:
+
+# Option A: If you have CSV files from your broker
+# real_prices = pd.read_csv("path/to/your/price_data.csv", parse_dates=["date"], index_col="date")
+
+# Option B: If you have access to a licensed API (e.g., Alpha Vantage)
+# import requests
+# api_key = "your_alpha_vantage_key"
+# response = requests.get(f"https://www.alphavantage.co/query?function=TIME_SERIES_DAILY&symbol=AAPL&apikey={api_key}")
+# # ... parse and create DataFrame ...
+
+# Option C: If you have a Bloomberg Terminal subscription
+# from blpapi import Session
+# # ... Bloomberg API code ...
+
+# Then use it with FinBrain plotting:
+# fb.plot.insider_transactions("S&P 500", "AAPL", price_data=real_prices)
+
+print("""
+To use real price data, replace mock_prices with data from your legal source:
+  - Broker API (Interactive Brokers, TD Ameritrade, etc.)
+  - Licensed data provider (Bloomberg, Refinitiv, Alpha Vantage, etc.)
+  - Your own database/warehouse
+
+Required DataFrame format:
+  - DatetimeIndex with dates
+  - Column named 'close', 'Close', 'price', or 'Price'
+
+Example:
+             close
+  date
+  2024-01-01  150.25
+  2024-01-02  151.30
+  2024-01-03  149.80
+""")
+
+# ============================================================================
+# Example 4: Exporting to JSON for web applications
+# ============================================================================
+print("\n" + "=" * 70)
+print("Example 4: Export to JSON for Web Applications")
+print("=" * 70)
+
+# Get the plot as JSON (useful for web apps, dashboards, etc.)
+json_plot = fb.plot.insider_transactions(
+    market="S&P 500",
+    ticker="TSLA",
+    price_data=mock_prices,
+    as_json=True,
+    show=False,
+)
+
+print(f"Generated JSON plot (length: {len(json_plot)} characters)")
+print("This can be sent to a web frontend using Plotly.js")
+
+# Example: Save to file for web app
+# with open("insider_plot.json", "w") as f:
+#     f.write(json_plot)
+
+print("\n" + "=" * 70)
+print("Examples completed!")
+print("=" * 70)
+print("\nNote: To actually display the plots, uncomment the fig.show() lines above.")
+print("Make sure you have real price data from a legal source for production use.")

{finbrain_python-0.1.6 → finbrain_python-0.1.8}/src/finbrain/aio/client.py

@@ -15,6 +15,7 @@ from .endpoints.sentiments import AsyncSentimentsAPI
 from .endpoints.app_ratings import AsyncAppRatingsAPI
 from .endpoints.analyst_ratings import AsyncAnalystRatingsAPI
 from .endpoints.house_trades import AsyncHouseTradesAPI
+from .endpoints.senate_trades import AsyncSenateTradesAPI
 from .endpoints.insider_transactions import AsyncInsiderTransactionsAPI
 from .endpoints.linkedin_data import AsyncLinkedInDataAPI
 from .endpoints.options import AsyncOptionsAPI
@@ -68,6 +69,7 @@ class AsyncFinBrainClient:
         self.app_ratings = AsyncAppRatingsAPI(self)
         self.analyst_ratings = AsyncAnalystRatingsAPI(self)
         self.house_trades = AsyncHouseTradesAPI(self)
+        self.senate_trades = AsyncSenateTradesAPI(self)
         self.insider_transactions = AsyncInsiderTransactionsAPI(self)
         self.linkedin_data = AsyncLinkedInDataAPI(self)
         self.options = AsyncOptionsAPI(self)

finbrain_python-0.1.8/src/finbrain/aio/endpoints/senate_trades.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+import pandas as pd
+from urllib.parse import quote
+import datetime as _dt
+from typing import TYPE_CHECKING, Dict, Any
+
+from ._utils import to_datestr
+
+if TYPE_CHECKING:
+    from ..client import AsyncFinBrainClient
+
+
+class AsyncSenateTradesAPI:
+    """Async wrapper for /senatetrades endpoints."""
+
+    def __init__(self, client: "AsyncFinBrainClient") -> None:
+        self._c = client
+
+    async def ticker(
+        self,
+        market: str,
+        symbol: str,
+        *,
+        date_from: _dt.date | str | None = None,
+        date_to: _dt.date | str | None = None,
+        as_dataframe: bool = False,
+    ) -> Dict[str, Any] | pd.DataFrame:
+        """Fetch Senate-member trades for symbol in market (async)."""
+        params: Dict[str, str] = {}
+        if date_from:
+            params["dateFrom"] = to_datestr(date_from)
+        if date_to:
+            params["dateTo"] = to_datestr(date_to)
+
+        market_slug = quote(market, safe="")
+        path = f"senatetrades/{market_slug}/{symbol.upper()}"
+
+        data: Dict[str, Any] = await self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows = data.get("senateTrades", [])
+            df = pd.DataFrame(rows)
+            if not df.empty and "date" in df.columns:
+                df["date"] = pd.to_datetime(df["date"])
+                df.set_index("date", inplace=True)
+            return df
+
+        return data

{finbrain_python-0.1.6 → finbrain_python-0.1.8}/src/finbrain/client.py

@@ -16,6 +16,7 @@ from .endpoints.sentiments import SentimentsAPI
 from .endpoints.app_ratings import AppRatingsAPI
 from .endpoints.analyst_ratings import AnalystRatingsAPI
 from .endpoints.house_trades import HouseTradesAPI
+from .endpoints.senate_trades import SenateTradesAPI
 from .endpoints.insider_transactions import InsiderTransactionsAPI
 from .endpoints.linkedin_data import LinkedInDataAPI
 from .endpoints.options import OptionsAPI
@@ -63,6 +64,7 @@ class FinBrainClient:
         self.app_ratings = AppRatingsAPI(self)
         self.analyst_ratings = AnalystRatingsAPI(self)
         self.house_trades = HouseTradesAPI(self)
+        self.senate_trades = SenateTradesAPI(self)
         self.insider_transactions = InsiderTransactionsAPI(self)
         self.linkedin_data = LinkedInDataAPI(self)
         self.options = OptionsAPI(self)

finbrain_python-0.1.8/src/finbrain/endpoints/senate_trades.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+import pandas as pd
+from urllib.parse import quote
+import datetime as _dt
+from typing import TYPE_CHECKING, Dict, Any
+
+from ._utils import to_datestr
+
+if TYPE_CHECKING:  # imported only by type-checkers
+    from ..client import FinBrainClient
+
+
+class SenateTradesAPI:
+    """
+    Endpoint
+    --------
+    ``/senatetrades/<MARKET>/<TICKER>`` - trading activity of U.S. Senators
+    for the selected ticker.
+    """
+
+    # ------------------------------------------------------------------ #
+    def __init__(self, client: "FinBrainClient") -> None:
+        self._c = client  # reference to the parent client
+
+    # ------------------------------------------------------------------ #
+    def ticker(
+        self,
+        market: str,
+        symbol: str,
+        *,
+        date_from: _dt.date | str | None = None,
+        date_to: _dt.date | str | None = None,
+        as_dataframe: bool = False,
+    ) -> Dict[str, Any] | pd.DataFrame:
+        """
+        Fetch Senate-member trades for *symbol* in *market*.
+
+        Parameters
+        ----------
+        market :
+            Market name **exactly as FinBrain lists it**
+            (e.g. ``"NASDAQ"``, ``"NYSE"``, ``"S&P 500"``).
+            Spaces and special characters are accepted; they are URL-encoded
+            automatically.
+        symbol :
+            Ticker symbol; auto-upper-cased.
+        date_from, date_to :
+            Optional ISO dates (``YYYY-MM-DD``) bounding the returned rows.
+        as_dataframe :
+            If *True*, return a **pandas.DataFrame** indexed by ``date``;
+            otherwise return the raw JSON dict.
+
+        Returns
+        -------
+        dict | pandas.DataFrame
+        """
+        params: Dict[str, str] = {}
+        if date_from:
+            params["dateFrom"] = to_datestr(date_from)
+        if date_to:
+            params["dateTo"] = to_datestr(date_to)
+
+        market_slug = quote(market, safe="")
+        path = f"senatetrades/{market_slug}/{symbol.upper()}"
+
+        data: Dict[str, Any] = self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows = data.get("senateTrades", [])
+            df = pd.DataFrame(rows)
+            if not df.empty and "date" in df.columns:
+                df["date"] = pd.to_datetime(df["date"])
+                df.set_index("date", inplace=True)
+            return df
+
+        return data