eetc-utils 1.0.2__tar.gz → 1.2.0__tar.gz

eetc_utils-1.2.0/PKG-INFO

@@ -0,0 +1,403 @@
+Metadata-Version: 2.4
+Name: eetc-utils
+Version: 1.2.0
+Summary: EETC Utils Library
+License: MIT
+License-File: LICENSE
+Author: East Empire Trading Company
+Author-email: eastempiretradingcompany2019@gmail.com
+Maintainer: East Empire Trading Company
+Maintainer-email: eastempiretradingcompany2019@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: arch (>=8.0.0,<9.0.0)
+Requires-Dist: numpy (>=2.3.4,<3.0.0)
+Requires-Dist: pandas (>=2.3.3,<3.0.0)
+Requires-Dist: pytest (>=9.0.1,<10.0.0)
+Requires-Dist: requests (>=2.28.0,<3.0.0)
+Requires-Dist: setuptools (>=80.9.0,<81.0.0)
+Requires-Dist: wheel (>=0.45.1,<0.46.0)
+Project-URL: Bug Tracker, https://github.com/east-empire-trading-company/eetc-utils/issues
+Project-URL: Homepage, https://github.com/east-empire-trading-company/eetc-utils
+Project-URL: Repository, https://github.com/east-empire-trading-company/eetc-utils
+Description-Content-Type: text/markdown
+
+# EETC Utils
+
+[![PyPI version](https://badge.fury.io/py/eetc-utils.svg)](https://badge.fury.io/py/eetc-utils)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Python library providing reusable utilities for financial analysis and algorithmic trading. Built by [East Empire Trading Company](https://github.com/east-empire-trading-company) for quantitative finance and trading strategy development.
+
+## Features
+
+### Finance Utilities
+- **Quantitative Finance Functions**: Kelly Criterion position sizing, DCF valuation, compound interest
+- **GARCH Models**: Advanced volatility forecasting using ARCH library integration
+- **OHLC Data Manipulation**: Convert daily data to weekly timeframes, performance calculations
+
+### Options Trading
+- **Black-Scholes Pricing**: Calculate option prices for calls and puts
+- **Greeks Calculations**: Gamma exposure (GEX) and other option Greeks
+- **Volatility Analysis**: Convert option IV to underlying IV, standard distribution functions
+- **Strike Range Tools**: Find strike prices within percentage ranges
+
+### API Clients
+- **EETC Data Hub Client**: Fetch price data, fundamentals, macroeconomic indicators, and order history
+- **EETC Notifications Client**: Send trade updates and notifications to Telegram channels
+
+### Strategy Framework
+- **Live Trading**: Abstract base classes for implementing live/paper trading strategies
+- **Execution Engine**: Production-ready engine for running trading strategies
+- **Backtesting Framework**: Complete backtesting suite with broker simulation, performance metrics, and result persistence
+
+## Installation
+
+```bash
+pip install eetc-utils
+```
+
+## Quick Start
+
+### Finance Utilities
+
+```python
+from eetc_utils.finance import (
+    calculate_optimal_leverage_kelly,
+    intrinsic_value_using_dcf,
+    garch_annualized_volatility,
+    convert_daily_ohlc_data_to_weekly
+)
+import pandas as pd
+
+# Calculate optimal leverage using Kelly Criterion
+price_df = pd.DataFrame({
+    'date': pd.date_range('2020-01-01', periods=200),
+    'close': [100 + i * 0.5 for i in range(200)]
+})
+
+leverage = calculate_optimal_leverage_kelly(
+    df=price_df,
+    position_type="LONG",
+    regime_start_date="2020-01-01",
+    fractional_kelly_multiplier=0.5,
+    use_garch=False
+)
+
+# DCF valuation
+intrinsic_value = intrinsic_value_using_dcf(
+    cash_flow=1000000000,
+    growth_years=10,
+    shares=100000000,
+    growth_rate=1.15,
+    beta=1.2
+)
+
+# Forecast volatility using GARCH
+volatility = garch_annualized_volatility(price_df)
+
+# Convert daily OHLC to weekly
+weekly_df = convert_daily_ohlc_data_to_weekly(price_df)
+```
+
+### Options Trading
+
+```python
+from eetc_utils.options import (
+    calculate_option_price_black_scholes,
+    find_strikes_in_range,
+    GEX,
+    calculate_underlying_iv_from_option_iv
+)
+
+# Calculate Black-Scholes option price
+call_price = calculate_option_price_black_scholes(
+    right="C",
+    und_price=100.0,
+    strike=105.0,
+    rate=0.05,
+    tte=0.5,
+    implied_vol=0.25,
+    pv_dividend=0.0
+)
+
+# Find strike prices within a range
+strikes = find_strikes_in_range(
+    range_length_perc=0.1,
+    price=100.0
+)
+
+# Calculate Gamma Exposure
+gex = GEX(oi=1000, gamma=0.05)
+
+# Convert option IV to underlying IV
+underlying_iv = calculate_underlying_iv_from_option_iv(
+    option_implied_vol=0.20,
+    t=30/365
+)
+```
+
+### EETC Data Hub Client
+
+```python
+from eetc_utils.clients.eetc_data import EETCDataClient
+import os
+
+# Initialize client (requires EETC_API_KEY environment variable)
+client = EETCDataClient(api_key=os.getenv("EETC_API_KEY"))
+
+# Fetch price data
+price_data = client.get_price_data(symbol="AAPL", start_date="2024-01-01")
+
+# Get fundamentals
+fundamentals = client.get_fundamentals(symbol="AAPL")
+
+# Fetch macroeconomic indicators
+macro_data = client.get_macro_indicators(indicator="GDP", country="US")
+```
+
+### EETC Notifications Manager Client
+
+```python
+from eetc_utils.clients.eetc_notifications import EETCNotificationsClient
+import os
+
+# Initialize client (requires EETC_API_KEY environment variable)
+client = EETCNotificationsClient(api_key=os.getenv("EETC_API_KEY"))
+
+# Send trade update via Telegram
+client.send_trade_update_to_telegram(msg="Shorted TSLA x100 at 1312.69.")
+```
+
+
+### Backtesting Framework
+
+```python
+from eetc_utils.strategy.backtesting.strategy import Strategy
+from eetc_utils.strategy.backtesting.engine import BacktestEngine
+import pandas as pd
+
+class MyStrategy(Strategy):
+    def on_start(self, context):
+        self.position = 0
+
+    def on_data(self, bar, context):
+        # Simple moving average crossover
+        if len(self.data) < 20:
+            return
+
+        sma_short = self.data['close'].tail(5).mean()
+        sma_long = self.data['close'].tail(20).mean()
+
+        if sma_short > sma_long and self.position == 0:
+            context['place_order']('buy', quantity=100)
+            self.position = 100
+        elif sma_short < sma_long and self.position > 0:
+            context['place_order']('sell', quantity=100)
+            self.position = 0
+
+    def on_stop(self, context):
+        pass
+
+# Load historical data
+data = pd.read_csv("AAPL_historical.csv")
+
+# Run backtest
+engine = BacktestEngine(
+    strategy=MyStrategy(),
+    data=data,
+    symbol="AAPL",
+    initial_capital=100000,
+    commission=0.001
+)
+
+results = engine.run()
+print(f"Total Return: {results['total_return']:.2%}")
+print(f"Sharpe Ratio: {results['sharpe_ratio']:.2f}")
+print(f"Max Drawdown: {results['max_drawdown']:.2%}")
+```
+
+## Documentation
+
+### Module Structure
+
+```
+src/eetc_utils/
+├── finance.py              # Quantitative finance utilities
+├── options.py              # Options pricing and Greeks
+├── clients/
+│   ├── eetc_data.py       # EETC Data Hub API client
+│   └── eetc_notifications.py  # Notifications client
+└── strategy/
+    ├── strategy.py         # Live trading strategy base class
+    ├── engine.py          # Live trading execution engine
+    └── backtesting/
+        ├── strategy.py    # Backtesting strategy base class
+        ├── engine.py      # Backtesting engine
+        ├── broker_sim.py  # Broker simulator
+        └── metrics.py     # Performance metrics
+```
+
+### Key Functions & Classes
+
+#### Finance Module (`finance.py`)
+- `calculate_optimal_leverage_kelly()`: Calculate optimal leverage using Kelly Criterion
+- `calculate_position_size_kelly()`: Calculate position size based on Kelly Criterion
+- `intrinsic_value_using_dcf()`: Discounted cash flow valuation
+- `garch_annualized_volatility()`: GARCH-based volatility forecasting
+- `convert_daily_ohlc_data_to_weekly()`: Convert daily OHLC data to weekly timeframes
+- `performance_over_time()`: Calculate percentage performance between dates
+- `compound_interest()`: Calculate compound interest
+- `beta_to_discount_rate()`: Map beta to discount rate for DCF
+
+#### Options Module (`options.py`)
+- `calculate_option_price_black_scholes()`: Black-Scholes option pricing for calls and puts
+- `find_strikes_in_range()`: Find strike prices within a percentage range
+- `GEX()`: Calculate Gamma Exposure for option contracts
+- `calculate_underlying_iv_from_option_iv()`: Convert option IV to underlying IV
+- `PDF()`: Standard normal probability density function
+- `CND()`: Cumulative normal distribution
+- `D1()`, `D2()`: Black-Scholes d1 and d2 calculations
+
+#### API Clients
+- **EETCDataClient**: HTTP client for fetching market data and fundamentals
+  - `get_price_data()`: Fetch historical price data
+  - `get_fundamentals()`: Get company fundamentals
+  - `get_macro_indicators()`: Fetch macroeconomic indicators
+  - `get_order_history()`: Retrieve order history
+- **EETCNotificationsClient**: Send trading notifications via Telegram
+  - `send_trade_update_to_telegram()`: Send trade notifications
+
+#### Strategy Framework
+- **Live Trading**: `Strategy` (ABC) for implementing live strategies
+- **Backtesting**: Simplified `Strategy` class with `on_start()`, `on_data()`, `on_stop()` lifecycle
+- **Engines**: Orchestrate strategy execution (live or backtest)
+- **BrokerSim**: Simulate order execution with configurable slippage and commission
+- **Metrics**: Calculate Sharpe ratio, max drawdown, and other performance statistics
+
+## Development
+
+### Prerequisites
+- Python 3.12+
+- Poetry (for dependency management)
+
+### Setup
+
+```bash
+# Install system dependencies
+sudo apt-get install build-essential
+
+# Install Python dependencies
+make update_and_install_python_requirements
+```
+
+### Code Formatting
+
+```bash
+make reformat_code  # Uses black for consistent code style
+```
+
+### Testing
+
+```bash
+# Run all tests
+python -m pytest tests/
+
+# Run specific test file
+python -m pytest tests/test_financials.py
+
+# Run with coverage
+python -m pytest tests/ --cov=src/eetc_utils
+```
+
+### Publishing to PyPI
+
+#### Prerequisites
+
+Create a `.pypirc` file in the project root with your PyPI API tokens:
+
+```ini
+[distutils]
+index-servers =
+  pypi
+  testpypi
+
+[testpypi]
+repository = https://test.pypi.org/legacy/
+username = __token__
+password = pypi-YOUR_TEST_PYPI_TOKEN_HERE
+
+[pypi]
+repository = https://upload.pypi.org/legacy/
+username = __token__
+password = pypi-YOUR_PRODUCTION_PYPI_TOKEN_HERE
+```
+
+**Note**: The `.pypirc` file is already in `.gitignore` and will not be committed to version control.
+
+To generate API tokens:
+- **TestPyPI**: https://test.pypi.org/manage/account/token/
+- **Production PyPI**: https://pypi.org/manage/account/token/
+
+#### Publishing Steps
+
+1. Update version in `pyproject.toml`:
+   - Increment `version` field in `[tool.poetry]` section
+   - Update dependencies in `[tool.poetry.dependencies]` if needed
+
+2. Build the package:
+   ```bash
+   python -m build
+   ```
+
+3. Test on PyPI Test:
+   ```bash
+   make publish_package_on_pypi_test
+   ```
+
+4. Publish to production PyPI:
+   ```bash
+   make publish_package_on_pypi
+   ```
+
+The Makefile commands automatically read credentials from `.pypirc` and configure Poetry before publishing.
+
+## Configuration
+
+### Environment Variables
+
+- `EETC_API_KEY`: API key for EETC Data Hub client (required for data access)
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+- Code follows the project's style guide (enforced by `black`)
+- All tests pass before submitting PR
+- New features include appropriate tests
+- Documentation is updated for API changes
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Authors
+
+- **East Empire Trading Company** - [eastempiretradingcompany2019@gmail.com](mailto:eastempiretradingcompany2019@gmail.com)
+- **Stefan Delic** - [einfach.jung1@gmail.com](mailto:einfach.jung1@gmail.com)
+- **Milos Dovedan** - [dovedanmilosh@gmail.com](mailto:dovedanmilosh@gmail.com)
+
+## Links
+
+- **Homepage**: [https://github.com/east-empire-trading-company/eetc-utils](https://github.com/east-empire-trading-company/eetc-utils)
+- **PyPI**: [https://pypi.org/project/eetc-utils/](https://pypi.org/project/eetc-utils/)
+- **Bug Tracker**: [https://github.com/east-empire-trading-company/eetc-utils/issues](https://github.com/east-empire-trading-company/eetc-utils/issues)
+
+## Support
+
+For questions, issues, or feature requests, please [open an issue](https://github.com/east-empire-trading-company/eetc-utils/issues) on GitHub.