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

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

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

{finbrain_python-0.1.4 → finbrain_python-0.1.6}/.github/workflows/release.yml

@@ -2,7 +2,7 @@ name: Build & Publish
 
 on:
   push:
-    tags: ['[0-9]*']          # e.g. v0.1.0, v1.2.3
+    tags: ['v[0-9]*']         # e.g. v0.1.0, v1.2.3
 
 jobs:
   build:

finbrain_python-0.1.6/CHANGELOG.md

@@ -0,0 +1,64 @@
+# 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).
+
+## [Unreleased]
+
+## [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...
+
+[Unreleased]: https://github.com/ahmetsbilgin/finbrain-python/compare/v0.1.6...HEAD
+[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.4/src/finbrain_python.egg-info → finbrain_python-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finbrain-python
-Version: 0.1.4
+Version: 0.1.6
 Summary: Official Python client for the FinBrain API
 Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
 License-Expression: MIT
@@ -12,9 +12,13 @@ Requires-Dist: typer[all]>=0.12
 Requires-Dist: pandas>=2.2
 Requires-Dist: plotly>=6.0
 Requires-Dist: numpy>=1.22.4
+Provides-Extra: async
+Requires-Dist: httpx>=0.24; extra == "async"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
 Requires-Dist: responses; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
@@ -34,6 +38,7 @@ 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.)
 - Transparent retries & custom error hierarchy (`FinBrainError`)
@@ -45,12 +50,16 @@ Fetch deep-learning price predictions, sentiment scores, insider trades, LinkedI
 ---
 
 ## 🚀 Quick start
+
 Install the SDK:
-```
+
+```bash
 pip install finbrain-python
 ```
+
 Create a client and fetch data:
-```
+
+```python
 from finbrain import FinBrainClient
 
 fb = FinBrainClient(api_key="YOUR_KEY")        # create once, reuse below
@@ -103,6 +112,45 @@ fb.sentiments.ticker("S&P 500", "AMZN",
                      as_dataframe=True)
 ```
 
+## ⚡ Async Usage
+
+For async/await support, install with the `async` extra:
+
+```bash
+pip install finbrain-python[async]
+```
+
+Then use `AsyncFinBrainClient` with `httpx`:
+
+```python
+import asyncio
+from finbrain.aio import AsyncFinBrainClient
+
+async def main():
+    async with AsyncFinBrainClient(api_key="YOUR_KEY") as fb:
+        # All methods are async and return the same data structures
+        markets = await fb.available.markets()
+
+        # Fetch predictions
+        predictions = await fb.predictions.ticker("AMZN", as_dataframe=True)
+
+        # Fetch sentiment data
+        sentiment = await fb.sentiments.ticker(
+            "S&P 500", "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)
+
+asyncio.run(main())
+```
+
+**Note**: The async client uses `httpx.AsyncClient` and must be used with `async with` context manager for proper resource cleanup.
+
 ## 📈 Plotting
 
 Plot helpers in a nutshell
@@ -111,7 +159,7 @@ Plot helpers in a nutshell
 
 - `as_json=True` – skips display and returns the figure as a Plotly-JSON string, ready to embed elsewhere.
 
-```
+```python
 # ---------- App Ratings Chart - Apple App Store or Google Play Store ----------
 fb.plot.app_ratings("S&P 500", "AMZN",
                     store="app",                # "play" for Google Play Store
@@ -120,15 +168,17 @@ fb.plot.app_ratings("S&P 500", "AMZN",
 
 # ---------- LinkedIn Metrics Chart ----------
 fb.plot.linkedin("S&P 500", "AMZN",
-                 date_from="2025-01-01", date_to="2025-06-30")
+                 date_from="2025-01-01",
+                 date_to="2025-06-30")
 
 # ---------- Put-Call Ratio Chart ----------
 fb.plot.options("S&P 500", "AMZN",
                 kind="put_call",
-                date_from="2025-01-01", date_to="2025-06-30")
+                date_from="2025-01-01",
+                date_to="2025-06-30")
 
 # ---------- Predictions Chart ----------
-fb.plot.predictions("AMZN")
+fb.plot.predictions("AMZN")         # prediction_type="monthly" for monthly predictions
 
 # ---------- Sentiments Chart ----------
 fb.plot.sentiments("S&P 500", "AMZN",
@@ -145,33 +195,12 @@ To call the API you need an **API key**, obtained by purchasing a **FinBrain API
 2. Copy the key from your dashboard.
 3. Pass it once when you create the client:
 
-```
+```python
 from finbrain import FinBrainClient
 fb = FinBrainClient(api_key="YOUR_KEY")
 ```
 
-### Async (currently under development)
-
-```
-import asyncio, os
-from finbrain.aio import FinBrainAsyncClient async
-def main():
-    async with FinBrainAsyncClient(api_key=os.getenv("FINBRAIN_API_KEY")) as fb:
-        data = await fb.sentiments.ticker("S&P 500", "AMZN")
-        print(list(data["sentimentAnalysis"].items())[:3])
-
-asyncio.run(main())
-```
-
-### CLI (currently under development)
-
-```
-export FINBRAIN_API_KEY=your_key
-finbrain markets
-finbrain predict AAPL --type daily
-``` 
-
-----------
+---
 
 ## 📚 Supported endpoints
 
@@ -189,11 +218,11 @@ finbrain predict AAPL --type daily
 | LinkedIn             | `client.linkedin_data.ticker()`          | `/linkedindata/{MARKET}/{TICKER}`                    |
 | Options – Put/Call   | `client.options.put_call()`              | `/putcalldata/{MARKET}/{TICKER}`                     |
 
-----------
+---
 
 ## 🛠️ Error-handling
 
-```
+```python
 from finbrain.exceptions import BadRequest
 try:
     fb.predictions.ticker("MSFT", prediction_type="weekly")
@@ -210,24 +239,24 @@ except BadRequest as exc:
 | 405         | `MethodNotAllowed`       | HTTP method not supported on endpoint |
 | 500         | `ServerError`            | FinBrain internal error               |
 
-----------
+---
 
 ## 🔄 Versioning & release
 
--   Semantic Versioning (`MAJOR.MINOR.PATCH`)
-    
--   Version auto-generated from Git tags (setuptools-scm)
+- Semantic Versioning (`MAJOR.MINOR.PATCH`)
 
-```
-git tag -a 0.2.0 -m "Add options.chain endpoint"
+- Version auto-generated from Git tags (setuptools-scm)
+
+```bash
+git tag -a v0.2.0 -m "Add options.chain endpoint"
 git push --tags # GitHub Actions builds & uploads to PyPI
 ```
 
-----------
+---
 
 ## 🧑‍💻 Development
 
-```
+```bash
 git clone https://github.com/finbrain-tech/finbrain-python
 cd finbrain-python
 python -m venv .venv && source .venv/bin/activate
@@ -241,35 +270,35 @@ pytest -q # unit tests (mocked)
 
 Set `FINBRAIN_LIVE_KEY`, then run:
 
-```
+```bash
 pytest -m integration
 ```
-----------
+
+---
 
 ## 🤝 Contributing
 
-1.  Fork → create a feature branch
-    
-2.  Add tests & run `ruff --fix`
-    
-3.  Ensure `pytest` & CI pass
-    
-4.  Open a PR — thanks!
-    
+1. Fork → create a feature branch
 
-----------
+2. Add tests & run `ruff --fix`
+
+3. Ensure `pytest` & CI pass
+
+4. Open a PR — thanks!
+
+---
 
 ## 🔒 Security
 
-Please report vulnerabilities to **info@finbrain.tech**.  
+Please report vulnerabilities to **<info@finbrain.tech>**.  
 We respond within 48 hours.
 
-----------
+---
 
 ## 📜 License
 
 MIT — see [LICENSE](LICENSE).
 
-----------
+---
 
 © 2025 FinBrain Technologies — Built with ❤️ for the quant community.

finbrain_python-0.1.4/PKG-INFO → finbrain_python-0.1.6/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: finbrain-python
-Version: 0.1.4
-Summary: Official Python client for the FinBrain API
-Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
-License-Expression: MIT
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests>=2.31
-Requires-Dist: typer[all]>=0.12
-Requires-Dist: pandas>=2.2
-Requires-Dist: plotly>=6.0
-Requires-Dist: numpy>=1.22.4
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: responses; extra == "dev"
-Requires-Dist: build; extra == "dev"
-Requires-Dist: twine; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Dynamic: license-file
-
 # FinBrain Python SDK&nbsp;<!-- omit in toc -->
 
 [![PyPI version](https://img.shields.io/pypi/v/finbrain-python.svg)](https://pypi.org/project/finbrain-python/)
@@ -34,6 +12,7 @@ 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.)
 - Transparent retries & custom error hierarchy (`FinBrainError`)
@@ -45,12 +24,16 @@ Fetch deep-learning price predictions, sentiment scores, insider trades, LinkedI
 ---
 
 ## 🚀 Quick start
+
 Install the SDK:
-```
+
+```bash
 pip install finbrain-python
 ```
+
 Create a client and fetch data:
-```
+
+```python
 from finbrain import FinBrainClient
 
 fb = FinBrainClient(api_key="YOUR_KEY")        # create once, reuse below
@@ -103,6 +86,45 @@ fb.sentiments.ticker("S&P 500", "AMZN",
                      as_dataframe=True)
 ```
 
+## ⚡ Async Usage
+
+For async/await support, install with the `async` extra:
+
+```bash
+pip install finbrain-python[async]
+```
+
+Then use `AsyncFinBrainClient` with `httpx`:
+
+```python
+import asyncio
+from finbrain.aio import AsyncFinBrainClient
+
+async def main():
+    async with AsyncFinBrainClient(api_key="YOUR_KEY") as fb:
+        # All methods are async and return the same data structures
+        markets = await fb.available.markets()
+
+        # Fetch predictions
+        predictions = await fb.predictions.ticker("AMZN", as_dataframe=True)
+
+        # Fetch sentiment data
+        sentiment = await fb.sentiments.ticker(
+            "S&P 500", "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)
+
+asyncio.run(main())
+```
+
+**Note**: The async client uses `httpx.AsyncClient` and must be used with `async with` context manager for proper resource cleanup.
+
 ## 📈 Plotting
 
 Plot helpers in a nutshell
@@ -111,7 +133,7 @@ Plot helpers in a nutshell
 
 - `as_json=True` – skips display and returns the figure as a Plotly-JSON string, ready to embed elsewhere.
 
-```
+```python
 # ---------- App Ratings Chart - Apple App Store or Google Play Store ----------
 fb.plot.app_ratings("S&P 500", "AMZN",
                     store="app",                # "play" for Google Play Store
@@ -120,15 +142,17 @@ fb.plot.app_ratings("S&P 500", "AMZN",
 
 # ---------- LinkedIn Metrics Chart ----------
 fb.plot.linkedin("S&P 500", "AMZN",
-                 date_from="2025-01-01", date_to="2025-06-30")
+                 date_from="2025-01-01",
+                 date_to="2025-06-30")
 
 # ---------- Put-Call Ratio Chart ----------
 fb.plot.options("S&P 500", "AMZN",
                 kind="put_call",
-                date_from="2025-01-01", date_to="2025-06-30")
+                date_from="2025-01-01",
+                date_to="2025-06-30")
 
 # ---------- Predictions Chart ----------
-fb.plot.predictions("AMZN")
+fb.plot.predictions("AMZN")         # prediction_type="monthly" for monthly predictions
 
 # ---------- Sentiments Chart ----------
 fb.plot.sentiments("S&P 500", "AMZN",
@@ -145,33 +169,12 @@ To call the API you need an **API key**, obtained by purchasing a **FinBrain API
 2. Copy the key from your dashboard.
 3. Pass it once when you create the client:
 
-```
+```python
 from finbrain import FinBrainClient
 fb = FinBrainClient(api_key="YOUR_KEY")
 ```
 
-### Async (currently under development)
-
-```
-import asyncio, os
-from finbrain.aio import FinBrainAsyncClient async
-def main():
-    async with FinBrainAsyncClient(api_key=os.getenv("FINBRAIN_API_KEY")) as fb:
-        data = await fb.sentiments.ticker("S&P 500", "AMZN")
-        print(list(data["sentimentAnalysis"].items())[:3])
-
-asyncio.run(main())
-```
-
-### CLI (currently under development)
-
-```
-export FINBRAIN_API_KEY=your_key
-finbrain markets
-finbrain predict AAPL --type daily
-``` 
-
-----------
+---
 
 ## 📚 Supported endpoints
 
@@ -189,11 +192,11 @@ finbrain predict AAPL --type daily
 | LinkedIn             | `client.linkedin_data.ticker()`          | `/linkedindata/{MARKET}/{TICKER}`                    |
 | Options – Put/Call   | `client.options.put_call()`              | `/putcalldata/{MARKET}/{TICKER}`                     |
 
-----------
+---
 
 ## 🛠️ Error-handling
 
-```
+```python
 from finbrain.exceptions import BadRequest
 try:
     fb.predictions.ticker("MSFT", prediction_type="weekly")
@@ -210,24 +213,24 @@ except BadRequest as exc:
 | 405         | `MethodNotAllowed`       | HTTP method not supported on endpoint |
 | 500         | `ServerError`            | FinBrain internal error               |
 
-----------
+---
 
 ## 🔄 Versioning & release
 
--   Semantic Versioning (`MAJOR.MINOR.PATCH`)
-    
--   Version auto-generated from Git tags (setuptools-scm)
+- Semantic Versioning (`MAJOR.MINOR.PATCH`)
 
-```
-git tag -a 0.2.0 -m "Add options.chain endpoint"
+- Version auto-generated from Git tags (setuptools-scm)
+
+```bash
+git tag -a v0.2.0 -m "Add options.chain endpoint"
 git push --tags # GitHub Actions builds & uploads to PyPI
 ```
 
-----------
+---
 
 ## 🧑‍💻 Development
 
-```
+```bash
 git clone https://github.com/finbrain-tech/finbrain-python
 cd finbrain-python
 python -m venv .venv && source .venv/bin/activate
@@ -241,35 +244,35 @@ pytest -q # unit tests (mocked)
 
 Set `FINBRAIN_LIVE_KEY`, then run:
 
-```
+```bash
 pytest -m integration
 ```
-----------
+
+---
 
 ## 🤝 Contributing
 
-1.  Fork → create a feature branch
-    
-2.  Add tests & run `ruff --fix`
-    
-3.  Ensure `pytest` & CI pass
-    
-4.  Open a PR — thanks!
-    
+1. Fork → create a feature branch
 
-----------
+2. Add tests & run `ruff --fix`
+
+3. Ensure `pytest` & CI pass
+
+4. Open a PR — thanks!
+
+---
 
 ## 🔒 Security
 
-Please report vulnerabilities to **info@finbrain.tech**.  
+Please report vulnerabilities to **<info@finbrain.tech>**.  
 We respond within 48 hours.
 
-----------
+---
 
 ## 📜 License
 
 MIT — see [LICENSE](LICENSE).
 
-----------
+---
 
 © 2025 FinBrain Technologies — Built with ❤️ for the quant community.

finbrain_python-0.1.6/RELEASE.md

@@ -0,0 +1,112 @@
+# Release Guide
+
+This guide explains how to create a new release for finbrain-python.
+
+## Tag Convention
+
+Starting from v0.1.6, we use **`v`-prefixed tags** (e.g., `v0.1.6`, `v0.2.0`, `v1.0.0`).
+
+## Release Process
+
+### 1. Update CHANGELOG.md
+
+Edit `CHANGELOG.md` and move items from `[Unreleased]` to a new version section:
+
+```markdown
+## [0.1.6] - 2025-01-15
+### Added
+- Your new features
+### Changed
+- Your changes
+### Fixed
+- Your bug fixes
+```
+
+### 2. Create and Push Tag
+
+```bash
+git add CHANGELOG.md
+git commit -m "Release v0.1.6"
+git tag -a v0.1.6 -m "Release v0.1.6: Brief description"
+git push origin main
+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
+2. Select tag: `v0.1.6`
+3. Title: `v0.1.6 - Brief Description`
+4. Copy the relevant section from `CHANGELOG.md` into the description
+5. Click "Publish release"
+
+### 5. Verify
+
+- Check PyPI: https://pypi.org/project/finbrain-python/
+- Test installation: `pip install finbrain-python==0.1.6`
+
+## How setuptools-scm Works
+
+- Tag `v0.1.6` → Package version `0.1.6`
+- The `v` prefix is automatically stripped
+
+### Previous Tag Convention
+
+Earlier releases used tags without the `v` prefix (e.g., `0.1.0`, `0.1.4`). Both formats work with setuptools-scm, but going forward we standardize on `v`-prefixed tags for consistency with common practices.
+
+### Workflow Trigger
+
+The GitHub Actions release workflow triggers on: `tags: ['v[0-9]*']`
+
+This matches:
+
+- ✅ `v0.1.0`
+- ✅ `v1.2.3`
+- ✅ `v10.20.30`
+- ❌ `0.1.0` (old format, won't trigger)
+- ❌ `version-0.1.0` (won't trigger)
+
+### Version Scheme
+
+We follow **Semantic Versioning** (semver):
+
+- `MAJOR.MINOR.PATCH`
+- **MAJOR**: Breaking changes
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes, backward compatible
+
+### Examples
+
+```bash
+# Patch release (bug fixes)
+git tag -a v0.1.5 -m "Fix retry logic in async client"
+
+# Minor release (new features)
+git tag -a v0.2.0 -m "Add async support"
+
+# Major release (breaking changes)
+git tag -a v1.0.0 -m "Stable API release"
+
+# Push the tag
+git push origin <tag-name>
+```
+
+### Checking Current Version
+
+```bash
+# See all tags
+git tag -l
+
+# See latest tag
+git describe --tags --abbrev=0
+
+# Check what version setuptools-scm will generate
+python -m setuptools_scm
+```