finbrain-python 0.1.7__tar.gz → 0.2.0__tar.gz

{finbrain_python-0.1.7 → finbrain_python-0.2.0}/.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.2.0/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-03-09
+
+### BREAKING CHANGES
+
+- **v2 API Migration**: SDK now targets FinBrain API v2 (`/v2/` base URL)
+- **Authentication**: Switched from `?token=` query parameter to `Authorization: Bearer` header
+- **`market` parameter removed**: All per-symbol endpoint methods no longer accept `market` as an argument (v2 API identifies tickers by symbol alone)
+  - Affected: `sentiments.ticker()`, `analyst_ratings.ticker()`, `app_ratings.ticker()`, `options.put_call()`, `insider_transactions.ticker()`, `house_trades.ticker()`, `senate_trades.ticker()`, `linkedin_data.ticker()`, and all plotting methods
+- **`predictions.market()` removed**: Use `screener.predictions_daily()` or `screener.predictions_monthly()` instead
+- **`sentiments.ticker()` `days` parameter removed**: Use `date_from`/`date_to` instead
+- **Response envelope**: All v2 responses are wrapped in `{"success": true, "data": ..., "meta": {...}}`. The SDK auto-unwraps this — endpoint methods return just the `data` portion
+- **Prediction DataFrame columns**: `main` column renamed to `mid` (matching v2 API)
+- **App Ratings DataFrame columns**: Flat columns like `playStoreScore` replaced with nested-then-flattened `ios_score`, `android_score`, `ios_ratingsCount`, `android_ratingsCount`, `android_installCount`
+- **Options DataFrame columns**: `callCount`/`putCount` renamed to `callVolume`/`putVolume`
+- **LinkedIn DataFrame columns**: `followersCount` renamed to `followerCount`
+- **v2 API paths changed**: All endpoint URLs updated (e.g., `/sentiments/{MARKET}/{TICKER}` → `/sentiment/{SYMBOL}`, `/housetrades/` → `/congress/house/`, etc.)
+- **Date query parameters**: Internal mapping changed from `dateFrom`/`dateTo` to `startDate`/`endDate` (Python parameter names `date_from`/`date_to` unchanged)
+- **Markets response format**: `available.markets()` now returns `[{"name": "S&P 500", "region": "US"}, ...]` instead of `["S&P 500", ...]`
+
+### Added
+
+- **News Endpoint**: `fb.news.ticker("AAPL")` — fetch news articles with sentiment scores (`/news/{SYMBOL}`)
+- **Screener Endpoints**: `fb.screener.*` — cross-ticker screening with 11 methods:
+  - `sentiment()`, `analyst_ratings()`, `insider_trading()`, `congress_house()`, `congress_senate()`, `news()`, `put_call_ratio()`, `linkedin()`, `app_ratings()`, `predictions_daily()`, `predictions_monthly()`
+- **Recent Data Endpoints**: `fb.recent.news()`, `fb.recent.analyst_ratings()` — latest data across all tracked stocks
+- **Regions Endpoint**: `fb.available.regions()` — markets grouped by region
+- **`limit` parameter**: Added to all per-symbol endpoints and screener/recent endpoints
+- **`RateLimitError` exception**: New exception for HTTP 429 responses
+- **`error_code` and `error_details` attributes**: Added to `FinBrainError` for v2 structured error responses
+- **`client.last_meta`**: Stores the `meta` object from the last API response (contains `timestamp`)
+- **Async parity**: All new endpoints have full async counterparts
+- **Envelope tests**: `tests/test_envelope.py` dedicated tests for v2 response handling
+- **79 unit tests**: Comprehensive test coverage for all v2 endpoints
+
+### Changed
+
+- **Base URL**: `https://api.finbrain.tech/v1/` → `https://api.finbrain.tech/v2/`
+- **Error message extraction**: Updated to handle v2 error format `{"error": {"code": "...", "message": "..."}}`
+- **Insider transactions date parsing**: Simplified from custom `"%b %d '%y"` format to standard ISO dates
+- **All plotting methods**: Updated for v2 column names and removed `market` parameter
+
+## [0.1.8] - 2025-12-27
+
+### Added
+
+- **Senate Trades Endpoint**: `fb.senate_trades.ticker()` - Fetch U.S. Senator trading activity (`/senatetrades/{MARKET}/{TICKER}`)
+- **Senate Trades Plotting**: `fb.plot.senate_trades()` - Visualize Senator trades on price charts
+- **Async Senate Trades**: Full async support via `AsyncSenateTradesAPI`
+- **Python 3.14 Support**: Added to CI test matrix (now testing 3.9-3.14)
+- **Senate Trades Tests**: `tests/test_senate_trades.py`
+
+## [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
+  - Install with: `pip install finbrain-python[async]`
+  - Example: `examples/async_example.py`
+- **Python 3.13 Support**: Added to CI test matrix (now testing 3.9, 3.10, 3.11, 3.12, 3.13)
+- **Async utilities module**: `src/finbrain/aio/endpoints/_utils.py`
+- **Sync utilities module**: `src/finbrain/endpoints/_utils.py`
+- **Plotting tests**: `tests/test_plotting.py`
+- **Async client tests**: `tests/test_async_client.py`
+- **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
+
+## [0.1.5] - 2024-09-18
+
+Previous releases...
+
+## [0.1.4] - 2024-06-25
+
+Previous releases...
+
+## [0.1.3] - 2024-06-13
+
+Previous releases...
+
+## [0.1.2] - 2024-06-13
+
+Previous releases...
+
+## [0.1.1] - 2024-06-13
+
+Previous releases...
+
+[0.2.0]: https://github.com/ahmetsbilgin/finbrain-python/compare/v0.1.8...v0.2.0
+[0.1.8]: https://github.com/ahmetsbilgin/finbrain-python/compare/v0.1.7...v0.1.8
+[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
+[0.1.3]: https://github.com/ahmetsbilgin/finbrain-python/compare/0.1.2...0.1.3
+[0.1.2]: https://github.com/ahmetsbilgin/finbrain-python/compare/0.1.1...0.1.2
+[0.1.1]: https://github.com/ahmetsbilgin/finbrain-python/releases/tag/0.1.1

{finbrain_python-0.1.7 → finbrain_python-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finbrain-python
-Version: 0.1.7
+Version: 0.2.0
 Summary: Official Python client for the FinBrain API
 Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
 License-Expression: MIT
@@ -30,8 +30,8 @@ Dynamic: license-file
 [![CI](https://github.com/ahmetsbilgin/finbrain-python/actions/workflows/ci.yml/badge.svg)](https://github.com/ahmetsbilgin/finbrain-python/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
 
-**Official Python client** for the [FinBrain API](https://docs.finbrain.tech).  
-Fetch deep-learning price predictions, sentiment scores, insider trades, LinkedIn metrics, options data and more — with a single import.
+**Official Python client** for the [FinBrain API v2](https://docs.finbrain.tech).
+Fetch deep-learning price predictions, sentiment scores, insider trades, LinkedIn metrics, options data, news and more — with a single import.
 
 *Python ≥ 3.9  •  requests, pandas, numpy & plotly  •  asyncio optional.*
 
@@ -39,11 +39,11 @@ Fetch deep-learning price predictions, sentiment scores, insider trades, LinkedI
 
 ## ✨ Features
 
-- One-line auth (`FinBrainClient(api_key="…")`)
-- Complete endpoint coverage (predictions, sentiments, options, insider, etc.)
+- One-line auth (`FinBrainClient(api_key="…")`) with Bearer token
+- Complete v2 endpoint coverage (predictions, sentiments, options, insider, news, screener, etc.)
 - Transparent retries & custom error hierarchy (`FinBrainError`)
+- Response envelope auto-unwrapping (v2 `{success, data, meta}` format)
 - Async parity with `finbrain.aio` (`httpx`)
-- CLI (`finbrain markets`, `finbrain predict AAPL`)
 - Auto-version from Git tags (setuptools-scm)
 - MIT-licensed, fully unit-tested
 
@@ -64,52 +64,70 @@ from finbrain import FinBrainClient
 
 fb = FinBrainClient(api_key="YOUR_KEY")        # create once, reuse below
 
-# ---------- availability ----------
-fb.available.markets()                         # list markets
+# ---------- discovery ----------
+fb.available.markets()                         # list markets with regions
 fb.available.tickers("daily", as_dataframe=True)
+fb.available.regions()                         # markets grouped by region
 
 # ---------- app ratings ----------
-fb.app_ratings.ticker("S&P 500", "AMZN",
+fb.app_ratings.ticker("AMZN",
                       date_from="2025-01-01",
                       date_to="2025-06-30",
                       as_dataframe=True)
 
 # ---------- analyst ratings ----------
-fb.analyst_ratings.ticker("S&P 500", "AMZN",
+fb.analyst_ratings.ticker("AMZN",
                           date_from="2025-01-01",
                           date_to="2025-06-30",
                           as_dataframe=True)
 
 # ---------- house trades ----------
-fb.house_trades.ticker("S&P 500", "AMZN",
+fb.house_trades.ticker("AMZN",
                        date_from="2025-01-01",
                        date_to="2025-06-30",
                        as_dataframe=True)
 
+# ---------- senate trades ----------
+fb.senate_trades.ticker("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)
+fb.insider_transactions.ticker("AMZN", as_dataframe=True)
 
 # ---------- LinkedIn metrics ----------
-fb.linkedin_data.ticker("S&P 500", "AMZN",
+fb.linkedin_data.ticker("AMZN",
                         date_from="2025-01-01",
                         date_to="2025-06-30",
                         as_dataframe=True)
 
 # ---------- options put/call ----------
-fb.options.put_call("S&P 500", "AMZN",
+fb.options.put_call("AMZN",
                     date_from="2025-01-01",
                     date_to="2025-06-30",
                     as_dataframe=True)
 
 # ---------- price predictions ----------
-fb.predictions.market("S&P 500", as_dataframe=True)   # all tickers in market
-fb.predictions.ticker("AMZN", as_dataframe=True)      # single ticker
+fb.predictions.ticker("AMZN", as_dataframe=True)
 
 # ---------- news sentiment ----------
-fb.sentiments.ticker("S&P 500", "AMZN",
+fb.sentiments.ticker("AMZN",
                      date_from="2025-01-01",
                      date_to="2025-06-30",
                      as_dataframe=True)
+
+# ---------- news articles ----------
+fb.news.ticker("AMZN", limit=20, as_dataframe=True)
+
+# ---------- screener (cross-ticker) ----------
+fb.screener.sentiment(market="S&P 500", as_dataframe=True)
+fb.screener.predictions_daily(limit=100, as_dataframe=True)
+fb.screener.insider_trading(limit=50)
+
+# ---------- recent data ----------
+fb.recent.news(limit=100, as_dataframe=True)
+fb.recent.analyst_ratings(limit=50)
 ```
 
 ## ⚡ Async Usage
@@ -136,15 +154,17 @@ async def main():
 
         # Fetch sentiment data
         sentiment = await fb.sentiments.ticker(
-            "S&P 500", "AMZN",
+            "AMZN",
             date_from="2025-01-01",
             date_to="2025-06-30",
             as_dataframe=True
         )
 
         # All other endpoints work the same way
-        app_ratings = await fb.app_ratings.ticker("S&P 500", "AMZN", as_dataframe=True)
-        analyst_ratings = await fb.analyst_ratings.ticker("S&P 500", "AMZN", as_dataframe=True)
+        app_ratings = await fb.app_ratings.ticker("AMZN", as_dataframe=True)
+        analyst_ratings = await fb.analyst_ratings.ticker("AMZN", as_dataframe=True)
+        news = await fb.news.ticker("AMZN", limit=10)
+        screener = await fb.screener.sentiment(market="S&P 500")
 
 asyncio.run(main())
 ```
@@ -161,18 +181,18 @@ Plot helpers in a nutshell
 
 ```python
 # ---------- App Ratings Chart - Apple App Store or Google Play Store ----------
-fb.plot.app_ratings("S&P 500", "AMZN",
+fb.plot.app_ratings("AMZN",
                     store="app",                # "play" for Google Play Store
                     date_from="2025-01-01",
                     date_to="2025-06-30")
 
 # ---------- LinkedIn Metrics Chart ----------
-fb.plot.linkedin("S&P 500", "AMZN",
+fb.plot.linkedin("AMZN",
                  date_from="2025-01-01",
                  date_to="2025-06-30")
 
 # ---------- Put-Call Ratio Chart ----------
-fb.plot.options("S&P 500", "AMZN",
+fb.plot.options("AMZN",
                 kind="put_call",
                 date_from="2025-01-01",
                 date_to="2025-06-30")
@@ -181,11 +201,11 @@ fb.plot.options("S&P 500", "AMZN",
 fb.plot.predictions("AMZN")         # prediction_type="monthly" for monthly predictions
 
 # ---------- Sentiments Chart ----------
-fb.plot.sentiments("S&P 500", "AMZN",
+fb.plot.sentiments("AMZN",
                    date_from="2025-01-01",
                    date_to="2025-06-30")
 
-# ---------- Insider Transactions & House Trades (requires user price data) ----------
+# ---------- 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:
 
@@ -199,13 +219,19 @@ price_df = pd.DataFrame({
 }).set_index("date")
 
 # Plot insider transactions on your price chart
-fb.plot.insider_transactions("S&P 500", "AAPL", price_data=price_df)
+fb.plot.insider_transactions("AAPL", price_data=price_df)
 
 # Plot House member trades on your price chart
-fb.plot.house_trades("S&P 500", "NVDA",
+fb.plot.house_trades("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("META",
+                      price_data=price_df,
+                      date_from="2025-01-01",
+                      date_to="2025-06-30")
 ```
 
 **Price Data Requirements:**
@@ -216,7 +242,7 @@ fb.plot.house_trades("S&P 500", "NVDA",
 
 ## 🔑 Authentication
 
-To call the API you need an **API key**, obtained by purchasing a **FinBrain API subscription**.  
+To call the API you need an **API key**, obtained by purchasing a **FinBrain API subscription**.
 *(The Terminal-only subscription does **not** include an API key.)*
 
 1. Subscribe at <https://www.finbrain.tech> → FinBrain API.
@@ -228,23 +254,37 @@ from finbrain import FinBrainClient
 fb = FinBrainClient(api_key="YOUR_KEY")
 ```
 
+Or set the `FINBRAIN_API_KEY` environment variable and omit the argument:
+
+```python
+fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var
+```
+
 ---
 
 ## 📚 Supported endpoints
 
-| Category             | Method                                   | Path                                                 |
-|----------------------|------------------------------------------|------------------------------------------------------|
-| Availability         | `client.available.markets()`             | `/available/markets`                                 |
-|                      | `client.available.tickers()`             | `/available/tickers/{TYPE}`                          |
-| Predictions          | `client.predictions.ticker()`            | `/ticker/{TICKER}/predictions/{daily\|monthly}`      |
-|                      | `client.predictions.market()`            | `/market/{MARKET}/predictions/{daily\|monthly}`      |
-| Sentiments           | `client.sentiments.ticker()`             | `/sentiments/{MARKET}/{TICKER}`                      |
-| 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}`                     |
-| 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}`                     |
+| Category             | Method                                   | v2 Path                                     |
+|----------------------|------------------------------------------|---------------------------------------------|
+| Discovery            | `client.available.markets()`             | `/markets`                                  |
+|                      | `client.available.tickers()`             | `/tickers`                                  |
+|                      | `client.available.regions()`             | `/regions`                                  |
+| Predictions          | `client.predictions.ticker()`            | `/predictions/{daily\|monthly}/{SYMBOL}`    |
+| Sentiments           | `client.sentiments.ticker()`             | `/sentiment/{SYMBOL}`                       |
+| News                 | `client.news.ticker()`                   | `/news/{SYMBOL}`                            |
+| App ratings          | `client.app_ratings.ticker()`            | `/app-ratings/{SYMBOL}`                     |
+| Analyst ratings      | `client.analyst_ratings.ticker()`        | `/analyst-ratings/{SYMBOL}`                 |
+| House trades         | `client.house_trades.ticker()`           | `/congress/house/{SYMBOL}`                  |
+| Senate trades        | `client.senate_trades.ticker()`          | `/congress/senate/{SYMBOL}`                 |
+| Insider transactions | `client.insider_transactions.ticker()`   | `/insider-trading/{SYMBOL}`                 |
+| LinkedIn             | `client.linkedin_data.ticker()`          | `/linkedin/{SYMBOL}`                        |
+| Options – Put/Call   | `client.options.put_call()`              | `/put-call-ratio/{SYMBOL}`                  |
+| Screener             | `client.screener.sentiment()`            | `/screener/sentiment`                       |
+|                      | `client.screener.predictions_daily()`    | `/screener/predictions/daily`               |
+|                      | `client.screener.insider_trading()`      | `/screener/insider-trading`                 |
+|                      | ... and 8 more screener methods          |                                             |
+| Recent               | `client.recent.news()`                   | `/recent/news`                              |
+|                      | `client.recent.analyst_ratings()`        | `/recent/analyst-ratings`                   |
 
 ---
 
@@ -256,6 +296,8 @@ try:
     fb.predictions.ticker("MSFT", prediction_type="weekly")
 except BadRequest as exc:
     print("Invalid parameters:", exc)
+    print("Error code:", exc.error_code)        # e.g. "VALIDATION_ERROR"
+    print("Details:", exc.error_details)         # structured details dict
 ```
 
 | HTTP status | Exception class          | Meaning                               |
@@ -265,6 +307,7 @@ except BadRequest as exc:
 | 403         | `PermissionDenied`       | Authenticated, but not authorised     |
 | 404         | `NotFound`               | Resource or endpoint not found        |
 | 405         | `MethodNotAllowed`       | HTTP method not supported on endpoint |
+| 429         | `RateLimitError`         | Too many requests                     |
 | 500         | `ServerError`            | FinBrain internal error               |
 
 ---
@@ -276,7 +319,7 @@ except BadRequest as exc:
 - Version auto-generated from Git tags (setuptools-scm)
 
 ```bash
-git tag -a v0.2.0 -m "Add options.chain endpoint"
+git tag -a v0.2.0 -m "v2 API migration"
 git push --tags # GitHub Actions builds & uploads to PyPI
 ```
 
@@ -291,15 +334,7 @@ python -m venv .venv && source .venv/bin/activate
 pip install -e .[dev]
 
 ruff check . # lint / format
-pytest -q # unit tests (mocked) 
-```
-
-### Live integration test(currently under development)
-
-Set `FINBRAIN_LIVE_KEY`, then run:
-
-```bash
-pytest -m integration
+pytest -q # unit tests (mocked)
 ```
 
 ---
@@ -308,7 +343,7 @@ pytest -m integration
 
 1. Fork → create a feature branch
 
-2. Add tests & run `ruff --fix`
+2. Add tests & run `ruff check --fix`
 
 3. Ensure `pytest` & CI pass
 
@@ -318,7 +353,7 @@ pytest -m integration
 
 ## 🔒 Security
 
-Please report vulnerabilities to **<info@finbrain.tech>**.  
+Please report vulnerabilities to **<info@finbrain.tech>**.
 We respond within 48 hours.
 
 ---
@@ -329,4 +364,4 @@ MIT — see [LICENSE](LICENSE).
 
 ---
 
-© 2025 FinBrain Technologies — Built with ❤️ for the quant community.
+© 2026 FinBrain Technologies — Built with ❤️ for the quant community.