openbb-akshare 0.3.1__py3-none-any.whl

openbb_akshare/utils/futures.csv

@@ -0,0 +1,189 @@
+Ticker,Description,Exchange,Category
+YI,"1,000 oz Mini Silver Futures",NYB,metals
+ALI,Aluminum Futures,CMX,metals
+BLK,Block Cheese Futures,CME,agriculture
+AW,Bloomberg Commodity Index Futures,CBT,index
+BZ,Brent Crude Oil Last Day Finance Futures,NYM,hydrocarbon
+BZT,Brent Crude Oil Last Day TAS Futures,NYM,hydrocarbon
+CB,Cash-Settled Butter Futures,CME,agriculture
+CSC,Cash-Settled Cheese Futures,CME,agriculture
+GEO,CBL Global Emissions Offset Futures,NYM,hydrocarbon
+ZW,Chicago SRW Wheat Futures,CBT,agriculture
+ZWT,Chicago SRW Wheat TAS Futures,CBT,agriculture
+DC,Class III Milk Futures,CME,agriculture
+GDK,Class IV Milk Futures,CME,agriculture
+HG0,Copper Spot TAS Futures,CMX,metals
+HGT,Copper TAS Futures,CMX,metals
+ZC,Corn Futures,CBT,agriculture
+ZCT,Corn TAS Futures,CBT,agriculture
+CLT,Crude Oil TAS Futures,NYM,hydrocarbon
+DY,Dry Whey Futures,CME,agriculture
+QC,E-mini Copper Futures,CMX,metals
+QM,E-mini Crude Oil Futures,NYM,hydrocarbon
+XAE,E-mini Energy Select Sector Futures,CME,index
+QO,E-mini Gold Futures,CMX,metals
+GC,CME Gold Futures,CMX,metals
+SGU,Shanghai Gold (USD) Futures,CMX,metals
+QG,E-mini Natural Gas Futures,NYM,hydrocarbon
+QH,E-mini NY Harbor ULSD Futures,NYM,hydrocarbon
+QU,E-mini RBOB Gasoline Futures,NYM,hydrocarbon
+QI,E-mini Silver Futures,CMX,metals
+GF,Feeder Cattle Futures,CME,agriculture
+GFT,Feeder Cattle TAS Futures,CME,agriculture
+GCT,Gold TAS Futures Futures,CMX,metals
+KE,KC HRW Wheat Futures,CBT,agriculture
+KET,KC HRW Wheat TAS Futures,CBT,agriculture
+HE,Lean Hogs Futures,CME,agriculture
+HET,Lean Hogs TAS Futures,CME,agriculture
+LE,Live Cattle Futures,CME,agriculture
+LET,Live Cattle TAS Futures,CME,agriculture
+HG,Copper Futures,CMX,metals
+MHG,E-mini Micro Copper Futures,CMX,metals
+MGC,E-mini Micro Gold Futures,CMX,metals
+SIL,E-mini Micro Silver Futures ,CMX,metals
+MCL,Micro WTI Crude Oil Futures,NYM,hydrocarbon
+YG,E-mini Gold Futures,NYB,metals
+XK,Mini Soybean Futures,CBT,agriculture
+XC,Mini Corn Futures,CBT,agriculture
+XW,Mini Chicago SRW Wheat Futures,CBT,agriculture
+GNF,Nonfat Dry Milk Futures,CME,agriculture
+ZO,Oats Futures,CBT,agriculture
+PRK,Pork Cutout Futures,CME,agriculture
+RBT,RBOB Gasoline TAS Futures,NYM,hydrocarbon
+ZR,Rough Rice Futures,CBT,agriculture
+GD,S&P GSCI Commodity Index Futures,CME,index
+SIT,Silver TAS Futures,CMX,metals
+ZS,Soybean Futures,CBT,agriculture
+ZM,Soybean Meal Futures,CBT,agriculture
+ZMT,Soybean Meal TAS Futures,CBT,agriculture
+ZL,Soybean Oil Futures,CBT,agriculture
+ZLT,Soybean Oil TAS Futures,CBT,agriculture
+SBT,Soybean TAS Futures,CBT,agriculture
+ZN,10-Year T-Note Futures,CBT,bonds
+N1U,10-Year USD MAC Swap Futures,CBT,bonds
+TWE,20-Year U.S. Treasury Bond Futures,CBT,bonds
+ZT,2-Year T-Note Futures,CBT,bonds
+F1U,5-Year USD MAC Swap Futures,CBT,bonds
+RX,Dow Jones Real Estate Index Futures,CBT,index
+GE,Eurodollar Futures,CME,currency
+GLB,One-Month Eurodollar Futures,CME,currency
+ZF,Five-Year US Treasury Note Futures,CBT,bonds
+10Y,Micro 10-Year Yield Futures,CBT,bonds
+2YY,Micro 2-Year Yield Futures,CBT,bonds
+30Y,Micro 30-Year Yield Futures,CBT,bonds
+5YY,Micro 5-Year Yield Futures,CBT,bonds
+SR1,One-Month SOFR Futures,CME,bonds
+ZFT,TAS on 5-Year Treasury Note Futures,CBT,bonds
+ZQ,Thirty-Day Fed Fund Futures,CBT,bonds
+Z3N,Three Year Treasury Note Futures,CBT,bonds
+SR3,Three-Month SOFR Futures,CME,bonds
+ZB,U.S. Treasury Bond Futures,CBT,bonds
+UB,Ultra U.S. Treasury Bond Futures,CBT,bonds
+BTM,Bakkt BTC (USD) Monthly Futures,NYB,currency
+BTC,Bitcoin Futures,CME,currency
+ETH,Ether Futures,CME,currency
+MBT,E-mini Micro Bitcoin Futures,CME,currency
+MET,E-mini Micro Ether Futures,CME,currency
+6A,Australian Dollar Futures,CME,currency
+6L,Brazilian Real Futures,CME,currency
+6B,British Pound Futures,CME,currency
+PJY,British Pound/Japanese Yen Futures,CME,currency
+PSF,British Pound/Swiss Franc Futures,CME,currency
+6C,Canadian Dollar Futures,CME,currency
+E7,E-mini Euro FX Futures,CME,currency
+J7,E-mini Japanese Yen Futures,CME,currency
+6E,Euro FX Futures,CME,currency
+EAD,Euro/Australian Dollar Futures,CME,currency
+RP,Euro/British Pound Futures,CME,currency
+ECD,Euro/Canadian Dollar Futures,CME,currency
+RY,Euro/Japanese Yen Futures,CME,currency
+ENK,Euro/Norwegian Krone Futures,CME,currency
+ESK,Euro/Swedish Krona Futures,CME,currency
+RF,Euro/Swiss Franc Futures,CME,currency
+SIR,Indian Rupee/USD Futures,CME,currency
+6J,Japanese Yen Futures,CME,currency
+KRW,Korean Won Futures,CME,currency
+6M,Mexican Peso Futures,CME,currency
+M6A,Micro AUD/USD Futures,CME,currency
+MCD,Micro CAD/USD Futures,CME,currency
+MSF,Micro CHF/USD Futures,CME,currency
+M6E,Micro EUR/USD Futures,CME,currency
+M6B,Micro GBP/USD Futures,CME,currency
+MIR,Micro INR/USD Futures,CME,currency
+M6C,Micro USD/CAD Futures,CME,currency
+M6J,Micro USD/JPY Futures,CME,currency
+6N,New Zealand Dollar Futures,CME,currency
+NKD,Nikkei Index (USD) Futures,CME,index
+NIY,Nikkei Index (YEN) Futures,CME,index
+NOK,Norwegian Krone Futures,CME,currency
+6R,Russian Ruble Futures,CME,currency
+6Z,South African Rand Futures,CME,currency
+SEK,Swedish Krona Futures,CME,currency
+6S,Swiss Franc Futures,CME,currency
+SJY,Swiss Franc/Japanese Yen Futures,CME,currency
+TPY,Yen Denominated TOPIX Futures,CME,index
+YMT,E-mini DJIA Index BTIC Futures,CBT,index
+NQT,E-mini Nasdaq 100 BTIC Futures,CME,index
+EST,E-mini S&P 500 BTIC Futures,CME,index
+XAF,E-mini S&P 500 Financial Select Sector Index Futures,CME,index
+RS1,E-mini Russell 1000 Index Futures,CME,index
+RSG,E-mini Russell 1000 Growth Index Futures,CME,index
+RSV,E-mini Russell 1000 Value Index Futures,CME,index
+RTY,E-mini Russell 2000 Index Futures,CME,index
+M2K,E-mini Micro Russell 2000 Index Futures,CME,index
+ESG,E-mini S&P 500 ESG Index Futures,CME,index
+EMT,E-mini S&P MidCap 400 Index BTIC Futures,CME,index
+EMD,E-mini S&P MidCap 400 Index Futures,CME,index
+MNQ,E-mini Micro Nasdaq 100 Index Futures,CME,index
+MES,E-mini Micro S&P 500 Index Futures,CME,index
+ES,E-Mini S&P 500 Index Futures,CME,index
+FNG,ICE Micro FANG+ Index Futures,NYB,index
+MMW,ICE MSCI ACWI NTR Index Futures,NYB,index
+CHH,ICE MSCI China NTR Futures,NYB,index
+MFS,ICE MSCI EAFE Index Futures,NYB,index
+ASN,ICE MSCI EM Asia NTR Index Futures,NYB,index
+LFM,ICE MSCI EM ESG Leaders NTR Index Futures,NYB,index
+MML,ICE MSCI EM Latin America NTR Index Futures,NYB,index
+MME,ICE MSCI Emerging Markets Index Futures,NYB,index
+MIN,ICE MSCI India NTR Index Futures,NYB,index
+USS,ICE MSCI USA GTR Index Futures,NYB,index
+MWL,ICE MSCI World Index Futures,NYB,index
+MWS,ICE MSCI World NTR Index Futures,NYB,index
+VLQ,Nasdaq 100 Volatility Index Futures,CME,index
+SDA,S&P 500 Annual Dividend Index Futures,CME,index
+SED,SED (SOFR-Eurodollar) Spread Futures,CME,bonds
+PL,Platinum Futures,NYM,metals
+PA,Palladium Futures,NYM,metals
+BUS,US Midwest Busheling Ferrous Futures,CMX,metals
+AUP,Aluminum MW U.S. Transaction,CMX,metals
+GLI,European Low Sulphur Gasoil Futures,NYM,hydrocarbon
+DX,ICE U.S. Dollar Index Futures,NYB,index
+FT5,E-mini FTSE China 50 Index Futures,CME,index
+MMM,ICE MSCI Emerging Markets EMEA NTR Index Futures,NYB,index
+MMN,ICE MSCI Emerging Markets NTR Index Futures,NYB,index
+MLE,ICE MSCI Latin America Index Futures,NYB,index
+YM,E-mini DJ $5 Index Futures,CBT,index
+XAI,E-mini S&P 500 Industrial Select Sector Futures,CME,index
+XAB,E-mini S&P 500 Materials Select Sector Futures,CME,index
+XAK,E-mini S&P 500 Technology Select Sector Futures,CME,index
+XAP,E-mini S&P 500 Consumer Staples Select Sector Futures,CME,index
+XAR,E-mini S&P 500 Real Estate Select Sector Futures,CME,index
+XAU,E-mini S&P 500 Utilities Select Sector Futures,CME,index
+XAV,E-mini S&P 500 Health Care Select Sector Futures,CME,index
+XAY,E-mini S&P 500 Consumer Discretionary Select Sector Futures,CME,index
+XAZ,E-mini S&P 500 Communication Services Select Sector Futures,CME,index
+BIO,E-mini Nasdaq Biotech Industry Futures,CME,index
+NQ,CME Nasdaq 100 Index Futures,CME,index
+NQQ,TACO on E-mini Nasdaq 100 Index Futures,CME,index
+UFV,Urea (Granular) FOB US Gulf Futures,CBT,agriculture
+CC,Cocoa Futures,NYB,agriculture
+KC,Coffee Futures,NYB,agriculture
+CT,Cotton Futures,NYB,agriculture
+SF,Sugar No. 16 Futures,NYB,agriculture
+SB,Sugar No. 11 Futures,NYB,agriculture
+OJ,Orange Juice Futures,NYB,agriculture
+NG,Natural Gas Futures,NYM,hydrocarbon
+HO,Heating Oil Futures,NYM,hydrocarbon
+RB,RBOB Gasoline Futures,NYM,hydrocarbon
+CL,WTI Crude Oil Futures,NYM,hydrocarbon
+TRM,ICE TRY/USD Futures,NYB,currency

openbb_akshare/utils/helpers.py

@@ -0,0 +1,206 @@
+"""AKShare helpers module."""
+
+# pylint: disable=unused-argument,too-many-arguments,too-many-branches,too-many-locals,too-many-statements
+import re
+from typing import Dict, Any, List, Optional, Union
+
+from openbb_core.provider.utils.errors import EmptyDataError
+from openbb_yfinance.utils.references import INTERVALS, MONTHS, PERIODS
+from pandas import DataFrame
+from datetime import datetime, timedelta
+from .tools import normalize_date, normalize_symbol
+
+import logging
+from openbb_akshare.utils.tools import setup_logger, normalize_symbol
+
+#setup_logger()
+logger = logging.getLogger(__name__)
+
+def ak_download(  # pylint: disable=too-many-positional-arguments
+    symbol: str,
+    start_date: Optional[Union[str, "date"]] = None,
+    end_date: Optional[Union[str, "date"]] = None,
+    interval: INTERVALS = "1d",
+    period: Optional[PERIODS] = None,
+    **kwargs: Any,
+) -> DataFrame:
+    import akshare as ak
+
+    start = start_date.strftime("%Y%m%d")
+    end = end_date.strftime("%Y%m%d")
+
+    symbol_b, symbol_f, market = normalize_symbol(symbol)
+    if market == "HK":
+        stock_zh_a_hist_df = ak.stock_hk_hist(symbol_b, period, start, end, adjust="")
+    else:
+        stock_zh_a_hist_df = ak.stock_zh_a_hist(symbol_b, period, start, end, adjust="")
+    
+    stock_zh_a_hist_df.rename(columns={"日期": "date", "股票代码": "symbol", "开盘": "open", "收盘": "close", "最高": "high", "最低": "low", "成交量": "volume", "成交额": "amount", "涨跌幅":"change_percent", "涨跌额": "change"}, inplace=True)
+    stock_zh_a_hist_df = stock_zh_a_hist_df.drop(columns=["振幅"])
+    stock_zh_a_hist_df = stock_zh_a_hist_df.drop(columns=["换手率"])
+    return stock_zh_a_hist_df
+
+
+import re
+
+def get_post_tax_dividend_per_share(dividend_str: str) -> float:
+    """
+    Parses Chinese dividend descriptions and returns post-tax dividend per share.
+    
+    Handles:
+        - Non-dividend cases (return 0)
+        - Per-share direct values (e.g., "每股0.38港元")
+        - Base-share values (e.g., "10派1元")
+        - Complex combinations (e.g., "每股派发现金股利0.088332港元,每10股派送股票股利3股")
+
+    Parameters:
+        dividend_str (str): Dividend description string
+
+    Returns:
+        float: Post-tax dividend amount per share, rounded to 4 decimal places
+    """
+    # Case 1: Non-dividend cases
+    if re.search(r'不分红|不分配不转增|转增.*不分配', dividend_str):
+        return 0.0
+    
+    # If A股 is present, extract only that part
+    a_share_match = re.search(r'(A股[^,]*)', dividend_str)
+    if a_share_match:
+        dividend_str = a_share_match.group(1)
+    # Remove 'A股' prefix if present
+    dividend_str = dividend_str.replace('A股', '')
+
+     # Extract base shares
+    base_match = re.match(r'(\d+(?:\.\d+)?)', dividend_str)
+    base = float(base_match.group(1)) if base_match else 0.0
+
+    # Extract bonus shares (送)
+    bonus_match = re.search(r'送(\d+(?:\.\d+)?)股', dividend_str)
+    bonus = float(bonus_match.group(1)) if bonus_match else 0.0
+
+    # Extract conversion shares (转)
+    conversion_match = re.search(r'转(\d+(?:\.\d+)?)股', dividend_str)
+    conversion = float(conversion_match.group(1)) if conversion_match else 0.0
+
+    # Extract cash dividend (派)
+    cash_match = re.search(r'派(\d+(?:\.\d+)?)元', dividend_str)
+    cash = float(cash_match.group(1)) if cash_match else 0.0
+
+    if base != 0 and cash != 0:
+        return round(cash / base, 4)
+       
+    # Case 2: Direct per-share values (e.g., "每股0.38港元", "每股人民币0.25元")
+    direct_match = re.search(r'每股[\u4e00-\u9fa5]*([\d\.]+)[^\d]*(?:港元|人民币|元)', dividend_str)
+    if direct_match:
+        return round(float(direct_match.group(1)), 4)
+    
+    # Case 3: Base-share values (e.g., "10派1元", "10转10股派1元")
+    # Match "10转10股派1元" or similar
+    match = re.match(r'(\d+)转(\d+)股派([\d\.]+)元', dividend_str)
+    if match:
+        base = int(match.group(1))
+        bonus = int(match.group(2))
+        cash = float(match.group(3))
+        total_shares = base
+        return round(cash / total_shares, 4)
+    # Handle "10派1元" or "10.00派2.00元"
+    match = re.match(r'(\d+(?:\.\d+)?)派([\d\.]+)元', dividend_str)
+    if match:
+        base = int(float(match.group(1)))
+        cash = float(match.group(2))
+        return round(cash / base, 4)
+
+    base_match = re.search(r'(\d+)(?:[转股]+[\d\.]+)*(?:派|现金股利)([\d\.]+)', dividend_str)
+    if base_match:
+        base_shares = int(float(base_match.group(1)))  # Handle '10.00' cases
+        dividend_amount = float(base_match.group(2))
+        return round(dividend_amount / base_shares, 4)
+    
+    # Case 4: Complex mixed formats (e.g., "每股派发现金股利0.088332港元,每10股派送股票股利3股")
+    complex_match = re.search(r'每股[\u4e00-\u9fa5]*([\d\.]+)[^\d]*(?:港元|人民币|元)', dividend_str)
+    if complex_match:
+        return round(float(complex_match.group(1)), 4)
+    
+    # Default: Return 0 for unrecognized formats
+    return 0.0
+def get_a_dividends(
+    symbol: str,
+    start_date: Optional[Union[str, "date"]] = None,
+    end_date: Optional[Union[str, "date"]] = None,
+) -> List[Dict]:
+    """
+    Fetches historical dividends for a Shanghai/Shenzhen/Beijing stock symbol.
+
+    Parameters:
+        symbol (str): Stock symbol to fetch dividends for.
+        start_date (Optional[Union[str, date]]): Start date for fetching dividends.
+        end_date (Optional[Union[str, date]]): End date for fetching dividends.
+
+    Returns:
+        DataFrame: DataFrame containing dividend information.
+    """
+    import akshare as ak
+
+    if not symbol:
+        raise EmptyDataError("Symbol cannot be empty.")
+
+    div_df = ak.stock_fhps_detail_ths(symbol)
+    div_df.dropna(inplace=True)
+    ticker = div_df[['实施公告日',
+                        '分红方案说明',
+                        'A股股权登记日',
+                        'A股除权除息日']]
+    ticker['amount'] = div_df['分红方案说明'].apply(
+        lambda x: get_post_tax_dividend_per_share(x) if isinstance(x, str) else None
+    )
+    ticker.rename(columns={'实施公告日': "report_date",
+                            '分红方案说明': "description", 
+                            'A股股权登记日': "record_date",
+                            'A股除权除息日': "ex_dividend_date"}, inplace=True)
+    dividends = ticker.to_dict("records")  # type: ignore
+    
+    if not dividends:
+        raise EmptyDataError(f"No dividend data found for {symbol}.")
+
+    return dividends
+
+def get_hk_dividends(
+    symbol: str,
+    start_date: Optional[Union[str, "date"]] = None,
+    end_date: Optional[Union[str, "date"]] = None,
+) -> List[Dict]:
+    """
+    Fetches historical dividends for a Hong Kong stock symbol.
+
+    Parameters:
+        symbol (str): Stock symbol to fetch dividends for.
+        start_date (Optional[Union[str, date]]): Start date for fetching dividends.
+        end_date (Optional[Union[str, date]]): End date for fetching dividends.
+
+    Returns:
+        DataFrame: DataFrame containing dividend information.
+    """
+    import akshare as ak
+
+    if not symbol:
+        raise EmptyDataError("Symbol cannot be empty.")
+
+    div_df = ak.stock_hk_fhpx_detail_ths(symbol[1:])
+    div_df.dropna(inplace=True)
+    ticker = div_df[['公告日期',
+                        '方案',
+                        '除净日',
+                        '派息日']]
+    ticker['amount'] = div_df['方案'].apply(
+        lambda x: get_post_tax_dividend_per_share(x) if isinstance(x, str) else None
+    )
+    ticker.rename(columns={'公告日期': "report_date",
+                            '方案': "description", 
+                            '除净日': "record_date",
+                            '派息日': "ex_dividend_date"}, inplace=True)
+    dividends = ticker.to_dict("records")  # type: ignore
+    
+    if not dividends:
+        raise EmptyDataError(f"No dividend data found for {symbol}.")
+
+    return dividends