ftgo 1.0.0__py3-none-any.whl

ftgo/__init__.py

@@ -0,0 +1,29 @@
+"""
+FTMarkets - A Python library for fetching financial data from FT Markets
+
+This library provides easy access to historical stock prices and search 
+functionality for financial instruments from Financial Times Markets.
+"""
+
+from .search import search_securities, get_xid
+from .historical import get_historical_prices, get_multiple_historical_prices
+from .holdings import get_holdings, get_fund_breakdown
+from .infos import get_fund_profile, get_fund_stats, get_available_fields, search_profile_field
+
+__version__ = "1.0.0"
+__author__ = "gohibiki"
+__email__ = "gohibiki@protonmail.com"
+__description__ = "A Python library for fetching financial data from FT Markets"
+
+__all__ = [
+    "search_securities",
+    "get_xid",
+    "get_historical_prices", 
+    "get_multiple_historical_prices",
+    "get_holdings",
+    "get_fund_breakdown",
+    "get_fund_profile",
+    "get_fund_stats",
+    "get_available_fields",
+    "search_profile_field"
+]

ftgo/historical.py

@@ -0,0 +1,237 @@
+"""
+Historical data fetching functionality for FTMarkets.
+
+This module provides functions to fetch and process historical stock price data
+from FT Markets with support for OHLCV data and concurrent processing.
+"""
+
+import cloudscraper
+import pandas as pd
+from datetime import datetime
+from bs4 import BeautifulSoup
+from typing import Dict, Any, List
+import logging
+import concurrent.futures
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+
+def fetch_historical_prices(xid: str, date_from: str, date_to: str) -> Dict[str, Any]:
+    """
+    Fetch historical price data from FT Markets API.
+    
+    Args:
+        xid: The FT Markets XID
+        date_from: Start date in DDMMYYYY format (e.g., "01012024")
+        date_to: End date in DDMMYYYY format (e.g., "31122024")
+        
+    Returns:
+        JSON response from the API
+        
+    Raises:
+        requests.exceptions.HTTPError: If the API request fails
+    """
+    scraper = cloudscraper.create_scraper(
+        browser={
+            'browser': 'chrome',
+            'platform': 'windows',
+            'desktop': True
+        }
+    )
+    
+    try:
+        # Convert DDMMYYYY to FT format (YYYY%2FMM%2FDD)
+        start_date = datetime.strptime(date_from, "%d%m%Y")
+        end_date = datetime.strptime(date_to, "%d%m%Y")
+        
+        start_formatted = start_date.strftime("%Y%%2F%m%%2F%d")
+        end_formatted = end_date.strftime("%Y%%2F%m%%2F%d")
+        
+        url = f"https://markets.ft.com/data/equities/ajax/get-historical-prices?startDate={start_formatted}&endDate={end_formatted}&symbol={xid}"
+        
+        response = scraper.get(url)
+        response.raise_for_status()
+        return response.json()
+    except Exception as e:
+        logger.error(f"Failed to fetch historical data for XID {xid}: {e}")
+        raise
+
+
+def html_to_dataframe(html_content: str) -> pd.DataFrame:
+    """
+    Convert HTML response to a pandas DataFrame.
+    
+    Args:
+        html_content: HTML content from the FT Markets API
+        
+    Returns:
+        pandas.DataFrame with processed historical data
+        
+    Note:
+        Returns empty DataFrame if no data is found
+    """
+    if not html_content:
+        logger.warning("No HTML content provided")
+        return pd.DataFrame()
+    
+    try:
+        soup = BeautifulSoup(html_content, 'html.parser')
+        rows = soup.find_all('tr')
+        
+        historical_data = []
+        
+        for row in rows:
+            cells = row.find_all('td')
+            if len(cells) >= 6:  # Ensure we have all columns including volume
+                try:
+                    # Extract date
+                    date_cell = cells[0]
+                    date_spans = date_cell.find_all('span')
+                    if date_spans:
+                        date_text = date_spans[0].get_text().strip()
+                    else:
+                        date_text = date_cell.get_text().strip()
+                    
+                    # Parse date
+                    try:
+                        date_obj = datetime.strptime(date_text, '%A, %B %d, %Y')
+                    except ValueError:
+                        try:
+                            date_obj = datetime.strptime(date_text, '%B %d, %Y')
+                        except ValueError:
+                            continue
+                    
+                    formatted_date = date_obj.strftime('%Y-%m-%d')
+                    
+                    # Extract OHLC prices
+                    open_price = float(cells[1].get_text().strip().replace(',', ''))
+                    high_price = float(cells[2].get_text().strip().replace(',', ''))
+                    low_price = float(cells[3].get_text().strip().replace(',', ''))
+                    close_price = float(cells[4].get_text().strip().replace(',', ''))
+                    
+                    # Extract volume from 6th column
+                    volume_cell = cells[5]
+                    volume_spans = volume_cell.find_all('span')
+                    if volume_spans:
+                        # Use the first span with full number
+                        volume_text = volume_spans[0].get_text().strip().replace(',', '')
+                    else:
+                        volume_text = volume_cell.get_text().strip().replace(',', '')
+                    
+                    # Convert volume to integer
+                    try:
+                        volume = int(float(volume_text))
+                    except ValueError:
+                        volume = 0
+                    
+                    historical_data.append({
+                        'date': formatted_date,
+                        'open': open_price,
+                        'high': high_price,
+                        'low': low_price,
+                        'close': close_price,
+                        'volume': volume
+                    })
+                    
+                except (ValueError, IndexError) as e:
+                    continue
+        
+        if historical_data:
+            df = pd.DataFrame(historical_data)
+            df['date'] = pd.to_datetime(df['date'])
+            df = df.sort_values('date').reset_index(drop=True)
+            return df
+        
+    except Exception as e:
+        logger.error(f"Error processing HTML data: {e}")
+    
+    return pd.DataFrame()
+
+
+def get_historical_prices(xid: str, date_from: str, date_to: str) -> pd.DataFrame:
+    """
+    Get historical price data for a security with full OHLCV data.
+    
+    Args:
+        xid: The FT Markets XID (use get_xid to find this)
+        date_from: Start date in DDMMYYYY format (e.g., "01012024")
+        date_to: End date in DDMMYYYY format (e.g., "31122024")
+        
+    Examples:
+        >>> xid = get_xid('AAPL')
+        >>> df = get_historical_prices(xid, "01012024", "31012024")
+    """
+    if not xid:
+        raise ValueError("XID cannot be empty")
+    
+    logger.info(f"Fetching historical data for XID {xid} from {date_from} to {date_to}")
+    
+    json_data = fetch_historical_prices(xid, date_from, date_to)
+    
+    if not json_data.get('html'):
+        logger.warning("No HTML data in API response")
+        return pd.DataFrame()
+    
+    html_content = json_data['html']
+    if len(html_content) == 0:
+        logger.warning("Empty HTML content in API response")
+        return pd.DataFrame()
+    
+    df = html_to_dataframe(html_content)
+    
+    logger.info(f"Successfully retrieved {len(df)} data points for XID {xid}")
+    return df
+
+
+def get_multiple_historical_prices(
+    xids: List[str], 
+    date_from: str, 
+    date_to: str
+) -> pd.DataFrame:
+    """
+    Get historical data for multiple securities concurrently.
+    
+    Args:
+        xids: List of FT Markets XIDs
+        date_from: Start date in DDMMYYYY format (e.g., "01012024")
+        date_to: End date in DDMMYYYY format (e.g., "31122024")
+        
+    Returns:
+        pandas.DataFrame with data for all securities concatenated
+        
+    Raises:
+        ValueError: If parameters are invalid
+        
+    Examples:
+        >>> from ftmarkets import get_xid, get_multiple_historical_prices
+        >>> xids = [get_xid('AAPL'), get_xid('MSFT')]
+        >>> df = get_multiple_historical_prices(xids, "01012024", "31012024")
+    """
+    if not xids:
+        raise ValueError("XIDs list cannot be empty")
+    
+    logger.info(f"Fetching data for {len(xids)} securities")
+    
+    with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
+        futures = [
+            executor.submit(get_historical_prices, xid, date_from, date_to) 
+            for xid in xids
+        ]
+        results = []
+        
+        for future in concurrent.futures.as_completed(futures):
+            try:
+                result = future.result()
+                if not result.empty:
+                    results.append(result)
+            except Exception as e:
+                logger.error(f"Error fetching data for security: {e}")
+    
+    if results:
+        combined_df = pd.concat(results, axis=0, ignore_index=True)
+        logger.info(f"Successfully retrieved data for {len(results)} securities")
+        return combined_df
+    else:
+        logger.warning("No data retrieved for any securities")
+        return pd.DataFrame()

ftgo/holdings.py

@@ -0,0 +1,292 @@
+"""
+Holdings and allocation data functionality for FTMarkets.
+
+This module provides functions to fetch ETF/fund holdings, asset allocation,
+sector breakdown, and geographic allocation data from FT Markets.
+"""
+
+import cloudscraper
+import pandas as pd
+from bs4 import BeautifulSoup
+from typing import Dict, Any, Tuple, Optional
+from io import StringIO
+import logging
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+# Constants for holdings types
+ASSET_ALLOCATION = "asset_allocation"
+SECTOR_WEIGHTS = "sector_weights"  
+GEOGRAPHIC_ALLOCATION = "geographic_allocation"
+TOP_HOLDINGS = "top_holdings"
+ALL_TYPES = "all"
+
+# Valid holdings types for validation
+VALID_HOLDINGS_TYPES = {ASSET_ALLOCATION, SECTOR_WEIGHTS, GEOGRAPHIC_ALLOCATION, TOP_HOLDINGS, ALL_TYPES}
+
+
+def fetch_holdings_page(xid: str) -> str:
+    """
+    Fetch the holdings page HTML for a given XID from FT Markets.
+    
+    Args:
+        xid: The FT Markets XID
+        
+    Returns:
+        HTML content of the holdings page
+        
+    Raises:
+        requests.exceptions.HTTPError: If the API request fails
+    """
+    scraper = cloudscraper.create_scraper(
+        browser={
+            'browser': 'chrome',
+            'platform': 'windows',
+            'desktop': True
+        }
+    )
+    
+    try:
+        # Construct holdings URL using XID
+        url = f"https://markets.ft.com/data/etfs/tearsheet/holdings?s={xid}"
+        
+        response = scraper.get(url)
+        response.raise_for_status()
+        return response.text
+    except Exception as e:
+        logger.error(f"Failed to fetch holdings page for XID {xid}: {e}")
+        raise
+
+
+def extract_fund_name(soup: BeautifulSoup) -> str:
+    """Extract fund name from the page"""
+    try:
+        name_element = soup.find('h1', {
+            'class': 'mod-tearsheet-overview__header__name mod-tearsheet-overview__header__name--large'
+        })
+        if name_element:
+            return name_element.get_text().strip()
+    except Exception:
+        pass
+    return "Unknown Fund"
+
+
+def extract_asset_allocation(soup: BeautifulSoup, fund_name: str) -> pd.DataFrame:
+    """Extract asset allocation data"""
+    try:
+        allocation_div = soup.find('div', {'class': 'mod-asset-allocation__table'})
+        if allocation_div:
+            html_string = str(allocation_div)
+            df_list = pd.read_html(StringIO(html_string))
+            if df_list:
+                df = df_list[0]
+                # Rename the percentage column to fund name
+                if len(df.columns) >= 2:
+                    df = df.iloc[:, :2]  # Keep only first two columns
+                    df.columns = ['Asset Class', fund_name]
+                    return df
+    except Exception as e:
+        logger.warning(f"Could not extract asset allocation: {e}")
+    
+    return pd.DataFrame(columns=['Asset Class', fund_name])
+
+
+def extract_sector_weights(soup: BeautifulSoup, fund_name: str) -> pd.DataFrame:
+    """Extract sector weights data"""
+    try:
+        sectors_div = soup.find('div', {'class': 'mod-weightings__sectors__table'})
+        if sectors_div:
+            html_string = str(sectors_div)
+            df_list = pd.read_html(StringIO(html_string))
+            if df_list:
+                df = df_list[0]
+                # Rename the percentage column to fund name
+                if len(df.columns) >= 2:
+                    df = df.iloc[:, :2]  # Keep only first two columns
+                    df.columns = ['Sector', fund_name]
+                    return df
+    except Exception as e:
+        logger.warning(f"Could not extract sector weights: {e}")
+    
+    return pd.DataFrame(columns=['Sector', fund_name])
+
+
+def extract_geographic_allocation(soup: BeautifulSoup, fund_name: str) -> pd.DataFrame:
+    """Extract geographic allocation data"""
+    try:
+        geo_div = soup.find('div', {'class': 'mod-weightings__regions__table'})
+        if geo_div:
+            html_string = str(geo_div)
+            df_list = pd.read_html(StringIO(html_string))
+            if df_list:
+                df = df_list[0]
+                # Rename the percentage column to fund name
+                if len(df.columns) >= 2:
+                    df = df.iloc[:, :2]  # Keep only first two columns
+                    df.columns = ['Region', fund_name]
+                    return df
+    except Exception as e:
+        logger.warning(f"Could not extract geographic allocation: {e}")
+    
+    return pd.DataFrame(columns=['Region', fund_name])
+
+
+def extract_top_holdings(soup: BeautifulSoup) -> pd.DataFrame:
+    """Extract top holdings data"""
+    try:
+        # Find all module content divs
+        module_divs = soup.find_all('div', {'class': 'mod-module__content'})
+        
+        # Usually holdings are in the 3rd module (index 2)
+        if len(module_divs) >= 3:
+            holdings_html = str(module_divs[2]).replace('100%', '')  # Remove 100% text that breaks parsing
+            df_list = pd.read_html(StringIO(holdings_html))
+            
+            # Usually the second table contains the holdings
+            if len(df_list) >= 2:
+                df = df_list[1]
+                # Keep only first 3 columns and top 10 holdings
+                if len(df.columns) >= 3:
+                    df = df.iloc[:10, :3]
+                    # Standardize column names
+                    df.columns = ['Holding', 'Weight', 'Shares'] if len(df.columns) >= 3 else df.columns
+                    return df
+    except Exception as e:
+        logger.warning(f"Could not extract top holdings: {e}")
+    
+    return pd.DataFrame(columns=['Holding', 'Weight', 'Shares'])
+
+
+def parse_holdings_data(html_content: str) -> Dict[str, pd.DataFrame]:
+    """
+    Parse holdings data from HTML content into structured DataFrames.
+    
+    Args:
+        html_content: Raw HTML content from FT Markets holdings page
+        
+    Returns:
+        Dictionary containing DataFrames for different holdings types:
+        - asset_allocation: Asset class breakdown
+        - sector_weights: Sector allocation
+        - geographic_allocation: Geographic allocation
+        - top_holdings: Top holdings by weight
+    """
+    soup = BeautifulSoup(html_content, 'html.parser')
+    
+    # Extract fund name
+    fund_name = extract_fund_name(soup)
+    
+    # Extract all data types
+    asset_allocation = extract_asset_allocation(soup, fund_name)
+    sector_weights = extract_sector_weights(soup, fund_name)
+    geographic_allocation = extract_geographic_allocation(soup, fund_name)
+    top_holdings = extract_top_holdings(soup)
+    
+    return {
+        ASSET_ALLOCATION: asset_allocation,
+        SECTOR_WEIGHTS: sector_weights,
+        GEOGRAPHIC_ALLOCATION: geographic_allocation,
+        TOP_HOLDINGS: top_holdings
+    }
+
+
+def get_holdings(
+    xid: str,
+    holdings_type: str = "all"
+) -> pd.DataFrame | Tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+    """
+    Get holdings and allocation data for ETFs and funds from FT Markets.
+    
+    Args:
+        xid: The FT Markets XID (use get_xid to find this)
+        holdings_type: Type of holdings data to retrieve:
+            - "asset_allocation": Breakdown by asset class (stocks, bonds, cash)
+            - "sector_weights": Sector allocation
+            - "geographic_allocation": Geographic allocation
+            - "top_holdings": Top holdings by weight percentage
+            - "all": All holdings data types as a tuple
+            
+    Returns:
+        - pandas.DataFrame for specific holdings type
+        - Tuple of DataFrames for "all": (asset_allocation, sector_weights, geographic_allocation, top_holdings)
+        
+    Raises:
+        ValueError: If xid is missing or holdings_type is invalid
+        
+    Examples:
+        >>> from ftmarkets import get_xid, get_holdings
+        >>> xid = get_xid('SPY')
+        >>> asset_allocation = get_holdings(xid, "asset_allocation")
+        >>> print(asset_allocation)
+        
+        >>> # Get all data
+        >>> all_data = get_holdings(xid, "all")
+        >>> asset_alloc, sectors, regions, holdings = all_data
+    """
+    if not xid:
+        raise ValueError("Missing required parameter: xid")
+    
+    if holdings_type not in VALID_HOLDINGS_TYPES:
+        raise ValueError(
+            f"Invalid holdings_type '{holdings_type}'. "
+            f"Choose from: {', '.join(sorted(VALID_HOLDINGS_TYPES))}"
+        )
+
+    logger.info(f"Fetching holdings data for XID {xid}, type: {holdings_type}")
+    
+    try:
+        html_content = fetch_holdings_page(xid)
+        holdings_data = parse_holdings_data(html_content)
+
+        if holdings_type == ALL_TYPES:
+            return (
+                holdings_data[ASSET_ALLOCATION],
+                holdings_data[SECTOR_WEIGHTS], 
+                holdings_data[GEOGRAPHIC_ALLOCATION],
+                holdings_data[TOP_HOLDINGS]
+            )
+        else:
+            return holdings_data[holdings_type]
+            
+    except Exception as e:
+        logger.error(f"Error retrieving holdings data: {e}")
+        raise
+
+
+def get_fund_breakdown(xid: str) -> Dict[str, pd.DataFrame]:
+    """
+    Get complete fund breakdown with all allocation data.
+    
+    Args:
+        xid: The FT Markets XID
+        
+    Returns:
+        Dictionary with all DataFrames:
+        - 'asset_allocation': Asset class breakdown
+        - 'sector_weights': Sector weights
+        - 'geographic_allocation': Geographic distribution
+        - 'top_holdings': Top 10 holdings
+        
+    Examples:
+        >>> xid = get_xid('QQQ')
+        >>> breakdown = get_fund_breakdown(xid)
+        >>> print(breakdown['asset_allocation'])
+        >>> print(breakdown['top_holdings'])
+    """
+    logger.info(f"Fetching complete fund breakdown for XID {xid}")
+    
+    html_content = fetch_holdings_page(xid)
+    return parse_holdings_data(html_content)
+
+
+# Update __all__ for exports
+__all__ = [
+    "get_holdings",
+    "get_fund_breakdown",
+    "ASSET_ALLOCATION",
+    "SECTOR_WEIGHTS", 
+    "GEOGRAPHIC_ALLOCATION",
+    "TOP_HOLDINGS",
+    "ALL_TYPES"
+]

ftgo/infos.py

@@ -0,0 +1,239 @@
+"""
+Profile and information data functionality for FTMarkets.
+
+This module provides functions to fetch ETF/fund profile information,
+key statistics, and investment details from FT Markets.
+"""
+
+import cloudscraper
+import pandas as pd
+from bs4 import BeautifulSoup
+from typing import Dict, Any, Optional
+import logging
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+
+def fetch_profile_page(xid: str) -> str:
+    """
+    Fetch the profile/summary page HTML for a given XID from FT Markets.
+    
+    Args:
+        xid: The FT Markets XID
+        
+    Returns:
+        HTML content of the profile page
+        
+    Raises:
+        requests.exceptions.HTTPError: If the API request fails
+    """
+    scraper = cloudscraper.create_scraper(
+        browser={
+            'browser': 'chrome',
+            'platform': 'windows',
+            'desktop': True
+        }
+    )
+    
+    try:
+        # Construct profile URL using XID
+        url = f"https://markets.ft.com/data/etfs/tearsheet/summary?s={xid}"
+        
+        response = scraper.get(url)
+        response.raise_for_status()
+        return response.text
+    except Exception as e:
+        logger.error(f"Failed to fetch profile page for XID {xid}: {e}")
+        raise
+
+
+def extract_profile_data(html_content: str) -> pd.DataFrame:
+    """
+    Extract profile and investment data from FT Markets ETF page HTML.
+    
+    Args:
+        html_content: Raw HTML content from FT Markets profile page
+        
+    Returns:
+        pandas.DataFrame with Field and Value columns containing profile information
+        
+    Note:
+        Returns empty DataFrame if no profile data is found
+    """
+    if not html_content:
+        logger.warning("No HTML content provided")
+        return pd.DataFrame(columns=['Field', 'Value'])
+    
+    try:
+        soup = BeautifulSoup(html_content, 'html.parser')
+        
+        # Find the Profile and Investment section
+        profile_section = soup.find('div', {'data-f2-app-id': 'mod-profile-and-investment-app'})
+        
+        if not profile_section:
+            logger.warning("Profile and Investment section not found")
+            return pd.DataFrame(columns=['Field', 'Value'])
+        
+        # Extract all table data
+        data = []
+        tables = profile_section.find_all('table')
+        
+        for table in tables:
+            rows = table.find_all('tr')
+            for row in rows:
+                th = row.find('th')
+                td = row.find('td')
+                
+                if th and td:
+                    field = th.get_text(strip=True)
+                    value = td.get_text(separator=' ', strip=True)
+                    value = ' '.join(value.split())  # Clean whitespace
+                    data.append({'Field': field, 'Value': value})
+        
+        logger.info(f"Extracted {len(data)} profile data points")
+        return pd.DataFrame(data)
+        
+    except Exception as e:
+        logger.error(f"Error extracting profile data: {e}")
+        return pd.DataFrame(columns=['Field', 'Value'])
+
+
+def get_fund_profile(xid: str) -> pd.DataFrame:
+    """
+    Get profile and investment information for ETFs and funds from FT Markets.
+    
+    Args:
+        xid: The FT Markets XID (use get_xid to find this)
+        
+    Returns:
+        pandas.DataFrame with Field and Value columns containing all available
+        fund information including details, investment data, and statistics
+        
+    Raises:
+        ValueError: If xid is missing
+        requests.exceptions.HTTPError: If API request fails
+        
+    Examples:
+        >>> from ftmarkets import get_xid, get_fund_profile
+        >>> xid = get_xid('SPY')
+        >>> profile = get_fund_profile(xid)
+        >>> print(profile)
+        
+        >>> # Filter for specific information
+        >>> fees = profile[profile['Field'].str.contains('fee', case=False)]
+        >>> print(fees)
+    """
+    if not xid:
+        raise ValueError("Missing required parameter: xid")
+    
+    logger.info(f"Fetching profile data for XID {xid}")
+    
+    try:
+        html_content = fetch_profile_page(xid)
+        profile_data = extract_profile_data(html_content)
+        
+        logger.info(f"Successfully retrieved profile data for XID {xid}")
+        return profile_data
+        
+    except Exception as e:
+        logger.error(f"Error retrieving profile data: {e}")
+        raise
+
+
+def get_fund_stats(xid: str) -> Dict[str, str]:
+    """
+    Get all fund profile data as a dictionary for easy access.
+    
+    Args:
+        xid: The FT Markets XID
+        
+    Returns:
+        Dictionary with all available fund fields and values
+        
+    Examples:
+        >>> xid = get_xid('QQQ')
+        >>> stats = get_fund_stats(xid)
+        >>> 
+        >>> # Access any available field safely
+        >>> for field, value in stats.items():
+        >>>     print(f"{field}: {value}")
+        >>>
+        >>> # Check if specific fields exist before using
+        >>> inception = stats.get('Inception date', 'Not available')
+        >>> fees = stats.get('Ongoing charge', 'Not available')
+    """
+    profile_df = get_fund_profile(xid)
+    
+    if profile_df.empty:
+        return {}
+    
+    # Convert DataFrame to dictionary for easy access
+    stats_dict = dict(zip(profile_df['Field'], profile_df['Value']))
+    
+    logger.info(f"Converted profile data to dictionary with {len(stats_dict)} fields")
+    return stats_dict
+
+
+def get_available_fields(xid: str) -> list:
+    """
+    Get list of all available profile fields for a fund.
+    
+    Args:
+        xid: The FT Markets XID
+        
+    Returns:
+        List of all field names available for this fund
+        
+    Examples:
+        >>> xid = get_xid('SPY')
+        >>> fields = get_available_fields(xid)
+        >>> print("Available fields:")
+        >>> for field in fields:
+        >>>     print(f"  - {field}")
+    """
+    profile_df = get_fund_profile(xid)
+    
+    if profile_df.empty:
+        return []
+    
+    field_list = profile_df['Field'].tolist()
+    logger.info(f"Found {len(field_list)} available fields")
+    return field_list
+
+
+def search_profile_field(xid: str, search_term: str) -> pd.DataFrame:
+    """
+    Search for specific fields in the fund profile data.
+    
+    Args:
+        xid: The FT Markets XID
+        search_term: Term to search for in field names (case-insensitive)
+        
+    Returns:
+        pandas.DataFrame with matching fields and values
+        
+    Examples:
+        >>> xid = get_xid('SPY')
+        >>> fees = search_profile_field(xid, 'fee')
+        >>> inception = search_profile_field(xid, 'inception')
+    """
+    profile_df = get_fund_profile(xid)
+    
+    if profile_df.empty:
+        return pd.DataFrame(columns=['Field', 'Value'])
+    
+    # Filter for fields containing the search term
+    matches = profile_df[profile_df['Field'].str.contains(search_term, case=False, na=False)]
+    
+    logger.info(f"Found {len(matches)} fields matching '{search_term}'")
+    return matches
+
+
+# Export functions
+__all__ = [
+    "get_fund_profile",
+    "get_fund_stats", 
+    "get_available_fields",
+    "search_profile_field"
+]

ftgo/search.py

@@ -0,0 +1,160 @@
+"""
+Search functionality for FTMarkets library.
+
+This module provides functions to search for financial instruments
+and retrieve their XIDs from FT Markets.
+"""
+
+import cloudscraper
+import pandas as pd
+from urllib.parse import quote
+from typing import Dict, Any, Union
+import logging
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+
+def fetch_search_data(search_string: str) -> Dict[str, Any]:
+    """
+    Fetch search data for a given search string from FT Markets API.
+    
+    Args:
+        search_string: The ticker symbol or name to search for
+        
+    Returns:
+        JSON response from the API
+        
+    Raises:
+        requests.exceptions.HTTPError: If the API request fails
+    """
+    scraper = cloudscraper.create_scraper(
+        browser={
+            'browser': 'chrome',
+            'platform': 'windows',
+            'desktop': True
+        }
+    )
+    
+    try:
+        url = f"https://markets.ft.com/data/searchapi/searchsecurities?query={quote(search_string)}"
+        response = scraper.get(url)
+        response.raise_for_status()
+        return response.json()
+    except Exception as e:
+        logger.error(f"Failed to fetch search data for {search_string}: {e}")
+        raise
+
+
+def search_to_dataframe(json_data: Dict[str, Any]) -> pd.DataFrame:
+    """
+    Convert search JSON response to a pandas DataFrame.
+    
+    Args:
+        json_data: JSON response from the FT Markets search API
+        
+    Returns:
+        pandas.DataFrame with columns: xid, name, symbol, asset_class, url
+        
+    Note:
+        Returns empty DataFrame if no data is found
+    """
+    if 'data' not in json_data or 'security' not in json_data['data']:
+        logger.warning("No search data found in JSON response")
+        return pd.DataFrame()
+    
+    try:
+        securities = json_data['data']['security']
+        
+        # Process each security
+        processed_securities = []
+        for security in securities:
+            processed_securities.append({
+                'xid': security.get('xid'),
+                'name': security.get('name'),
+                'symbol': security.get('symbol'),
+                'asset_class': security.get('assetClass'),
+                'url': security.get('url')
+            })
+        
+        return pd.DataFrame(processed_securities)
+        
+    except (KeyError, IndexError) as e:
+        logger.error(f"Error processing search JSON data: {e}")
+        return pd.DataFrame()
+
+
+def search_securities(query: str) -> pd.DataFrame:
+    """
+    Search for securities on FT Markets.
+    
+    Args:
+        query: Search term for securities (ticker symbol or company name)
+        
+    Returns:
+        pandas.DataFrame with search results containing:
+        - xid: FT Markets identifier
+        - name: Company/security name
+        - symbol: Trading symbol
+        - asset_class: Type of security (Equities, ETFs, etc.)
+        - url: FT Markets URL path
+        
+    Raises:
+        ValueError: If query is empty
+        requests.exceptions.HTTPError: If API request fails
+        
+    Examples:
+        >>> results = search_securities('Apple')
+        >>> print(results.head())
+    """
+    if not query:
+        raise ValueError("Query parameter cannot be empty")
+    
+    logger.info(f"Searching for securities with query: {query}")
+    
+    json_data = fetch_search_data(query)
+    df = search_to_dataframe(json_data)
+    
+    logger.info(f"Found {len(df)} securities for query: {query}")
+    return df
+
+
+def get_xid(
+    ticker: str, 
+    display_mode: str = "first"
+) -> Union[str, pd.DataFrame]:
+    """
+    Get FT Markets XID for given ticker symbol.
+    
+    Args:
+        ticker: Single ticker symbol
+        display_mode: "first" to return first match XID, "all" to return all matches
+        
+    Returns:
+        - If display_mode="first": String XID of first match
+        - If display_mode="all": pandas.DataFrame with all search results
+        
+    Raises:
+        ValueError: If parameters are invalid or no data is found
+        
+    Examples:
+        >>> xid = get_xid('AAPL')
+        >>> print(xid)  # '36276'
+        
+        >>> all_results = get_xid('AAPL', display_mode='all')
+        >>> print(all_results)
+    """
+    if not ticker:
+        raise ValueError("Ticker parameter cannot be empty")
+    
+    df = search_securities(ticker)
+    
+    if df.empty:
+        raise ValueError(f"No data found for ticker: {ticker}")
+    
+    if display_mode == "all":
+        return df
+    elif display_mode == "first":
+        return df.iloc[0]['xid']
+    else:
+        raise ValueError("Invalid display_mode. Choose 'first' or 'all'.")

ftgo-1.0.0.dist-info/METADATA

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: ftgo
+Version: 1.0.0
+Summary: A Python library for fetching financial data from FT Markets
+Home-page: https://github.com/gohibiki/ftgo
+Author: gohibiki
+Author-email: gohibiki <gohibiki@protonmail.com>
+Maintainer-email: gohibiki <gohibiki@protonmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gohibiki/ftgo
+Project-URL: Repository, https://github.com/gohibiki/ftgo
+Project-URL: Documentation, https://github.com/gohibiki/ftgo#readme
+Project-URL: Bug Reports, https://github.com/gohibiki/ftgo/issues
+Project-URL: Changelog, https://github.com/gohibiki/ftgo/blob/main/CHANGELOG.md
+Keywords: finance,stocks,etf,historical-data,financial-analysis,market-data,ft-markets,financial-times
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cloudscraper>=1.2.68
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: beautifulsoup4>=4.11.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: matplotlib>=3.6.0; extra == "examples"
+Requires-Dist: jupyter>=1.0.0; extra == "examples"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# FTMarkets
+
+[![PyPI version](https://badge.fury.io/py/ftgo.svg)](https://badge.fury.io/py/ftgo)
+[![Python 3.7+](https://img.shields.io/badge/python-3.7+-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 for fetching financial data from Financial Times Markets, including historical stock prices, ETF holdings, fund profiles, and allocation breakdowns.
+
+## Features
+
+- **Historical Data**: Fetch historical OHLCV data for stocks and ETFs
+- **Holdings Data**: Get ETF/fund holdings, asset allocation, and sector breakdowns
+- **Fund Profiles**: Access fund information, statistics, and investment details
+- **Symbol Search**: Find FT Markets XIDs by ticker symbols
+- **Concurrent Processing**: Fast data retrieval using multithreading
+- **Pandas Integration**: Returns data as pandas DataFrames for easy analysis
+
+## Installation
+
+```bash
+pip install ftgo
+```
+
+## Quick Start
+
+```python
+from ftgo import search_securities, get_xid, get_historical_prices, get_holdings
+
+# Search for a security
+results = search_securities('AAPL')
+print(results)
+
+# Get XID for a ticker
+xid = get_xid('AAPL')
+
+# Fetch historical data
+df = get_historical_prices(xid, "01012024", "31012024")
+print(df.head())
+
+# Get ETF holdings
+spy_xid = get_xid('SPY')
+holdings = get_holdings(spy_xid, "top_holdings")
+print(holdings)
+```
+
+## API Reference
+
+### Search Functions
+
+#### `search_securities(query)`
+
+Search for securities on FT Markets.
+
+**Parameters:**
+- `query` (str): Search term for securities (ticker symbol or company name)
+
+**Returns:** pandas.DataFrame with search results containing xid, name, symbol, asset_class, url
+
+```python
+# Search for Apple
+results = search_securities('Apple')
+print(results)
+
+# Search by ticker
+results = search_securities('AAPL')
+```
+
+#### `get_xid(ticker, display_mode="first")`
+
+Get FT Markets XID for given ticker symbol.
+
+**Parameters:**
+- `ticker` (str): Ticker symbol
+- `display_mode` (str): "first" to return first match XID, "all" to return all matches
+
+**Returns:** String XID (if display_mode="first") or DataFrame (if display_mode="all")
+
+```python
+# Get XID for Apple
+xid = get_xid('AAPL')
+print(xid)  # Returns XID string
+
+# Get all matches
+all_results = get_xid('AAPL', display_mode='all')
+print(all_results)
+```
+
+### Historical Data
+
+#### `get_historical_prices(xid, date_from, date_to)`
+
+Get historical price data for a security with full OHLCV data.
+
+**Parameters:**
+- `xid` (str): The FT Markets XID
+- `date_from` (str): Start date in DDMMYYYY format (e.g., "01012024")
+- `date_to` (str): End date in DDMMYYYY format (e.g., "31122024")
+
+**Returns:** pandas.DataFrame with columns: date, open, high, low, close, volume
+
+```python
+xid = get_xid('AAPL')
+df = get_historical_prices(xid, "01012024", "31012024")
+print(df.head())
+```
+
+#### `get_multiple_historical_prices(xids, date_from, date_to)`
+
+Get historical data for multiple securities concurrently.
+
+**Parameters:**
+- `xids` (list): List of FT Markets XIDs
+- `date_from` (str): Start date in DDMMYYYY format
+- `date_to` (str): End date in DDMMYYYY format
+
+**Returns:** pandas.DataFrame with concatenated data for all securities
+
+```python
+xids = [get_xid('AAPL'), get_xid('MSFT')]
+df = get_multiple_historical_prices(xids, "01012024", "31012024")
+```
+
+### Holdings Data
+
+#### `get_holdings(xid, holdings_type="all")`
+
+Get holdings and allocation data for ETFs and funds.
+
+**Parameters:**
+- `xid` (str): The FT Markets XID
+- `holdings_type` (str): Type of holdings data:
+  - `"asset_allocation"`: Asset class breakdown (stocks, bonds, cash)
+  - `"sector_weights"`: Sector allocation
+  - `"geographic_allocation"`: Geographic allocation
+  - `"top_holdings"`: Top holdings by weight
+  - `"all"`: All holdings data types as a tuple
+
+**Returns:** pandas.DataFrame or tuple of DataFrames
+
+```python
+# Get top holdings for SPY ETF
+spy_xid = get_xid('SPY')
+top_holdings = get_holdings(spy_xid, "top_holdings")
+
+# Get asset allocation
+allocation = get_holdings(spy_xid, "asset_allocation")
+
+# Get all holdings data
+all_data = get_holdings(spy_xid, "all")
+asset_alloc, sectors, regions, holdings = all_data
+```
+
+#### `get_fund_breakdown(xid)`
+
+Get complete fund breakdown with all allocation data.
+
+**Parameters:**
+- `xid` (str): The FT Markets XID
+
+**Returns:** Dictionary with all DataFrames
+
+```python
+qqq_xid = get_xid('QQQ')
+breakdown = get_fund_breakdown(qqq_xid)
+print(breakdown['asset_allocation'])
+print(breakdown['top_holdings'])
+```
+
+### Fund Profile Data
+
+#### `get_fund_profile(xid)`
+
+Get profile and investment information for ETFs and funds.
+
+**Parameters:**
+- `xid` (str): The FT Markets XID
+
+**Returns:** pandas.DataFrame with Field and Value columns
+
+```python
+xid = get_xid('SPY')
+profile = get_fund_profile(xid)
+print(profile)
+
+# Filter for specific information
+fees = profile[profile['Field'].str.contains('fee', case=False)]
+```
+
+#### `get_fund_stats(xid)`
+
+Get fund profile data as a dictionary for easy access.
+
+**Parameters:**
+- `xid` (str): The FT Markets XID
+
+**Returns:** Dictionary with all available fund fields and values
+
+```python
+xid = get_xid('QQQ')
+stats = get_fund_stats(xid)
+
+# Access any available field safely
+inception = stats.get('Inception date', 'Not available')
+fees = stats.get('Ongoing charge', 'Not available')
+```
+
+#### `get_available_fields(xid)`
+
+Get list of all available profile fields for a fund.
+
+**Parameters:**
+- `xid` (str): The FT Markets XID
+
+**Returns:** List of all field names available
+
+```python
+xid = get_xid('SPY')
+fields = get_available_fields(xid)
+print("Available fields:")
+for field in fields:
+    print(f"  - {field}")
+```
+
+#### `search_profile_field(xid, search_term)`
+
+Search for specific fields in the fund profile data.
+
+**Parameters:**
+- `xid` (str): The FT Markets XID
+- `search_term` (str): Term to search for in field names (case-insensitive)
+
+**Returns:** pandas.DataFrame with matching fields and values
+
+```python
+xid = get_xid('SPY')
+fees = search_profile_field(xid, 'fee')
+inception = search_profile_field(xid, 'inception')
+```
+
+## Complete Example
+
+```python
+from ftgo import get_xid, get_historical_prices, get_holdings, get_fund_profile
+import matplotlib.pyplot as plt
+
+# Search for QQQ ETF
+qqq_xid = get_xid('QQQ')
+
+# Get 1 year of historical data
+historical_data = get_historical_prices(qqq_xid, "01012023", "31122023")
+
+# Get fund information
+profile = get_fund_profile(qqq_xid)
+top_holdings = get_holdings(qqq_xid, "top_holdings")
+asset_allocation = get_holdings(qqq_xid, "asset_allocation")
+
+# Plot price chart
+historical_data.set_index('date')['close'].plot(title='QQQ Price History')
+plt.show()
+
+# Display fund information
+print("Fund Profile:")
+print(profile.head(10))
+
+print("\nTop 10 Holdings:")
+print(top_holdings.head(10))
+
+print("\nAsset Allocation:")
+print(asset_allocation)
+```
+
+## Error Handling
+
+The library includes logging and error handling, but you should wrap calls in try-except blocks for production use:
+
+```python
+try:
+    xid = get_xid('INVALID_TICKER')
+    data = get_historical_prices(xid, "01012024", "31012024")
+except ValueError as e:
+    print(f"Error: {e}")
+except Exception as e:
+    print(f"Unexpected error: {e}")
+```
+
+## Requirements
+
+- Python 3.7+
+- cloudscraper >= 1.2.68
+- pandas >= 1.3.0
+- beautifulsoup4 >= 4.11.0
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Disclaimer
+
+This library is for educational and research purposes.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

ftgo-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ftgo/__init__.py,sha256=5sx2Wl-FnWfEtCF-m02vTaye3A_utwfsejmy9wTf_fM,937
+ftgo/historical.py,sha256=nbTEnG4IMVwoRHx1HlrsePtMGlv_nLAsdAZ4fz0oChE,8209
+ftgo/holdings.py,sha256=f-7BxyETvTfh-K0btptT8lIoePXXLQFTRL19SpwF-Lc,9990
+ftgo/infos.py,sha256=MEvCOOe7ur0sz_Kr447bHINmSbSRgUhkAF9OHhBlrbk,7110
+ftgo/search.py,sha256=io21frgPPQ1OX2Ye_aVT3tBE-UpHI6lXdpWGRapAnyg,4620
+ftgo-1.0.0.dist-info/licenses/LICENSE,sha256=WArc03ET22jEfE5yYGtaFIZ2Jk1mV2P94R4bO8ryrVI,1065
+ftgo-1.0.0.dist-info/METADATA,sha256=Wxar2b9idLGL82FuCBQLCNL9SPAi6fuKd1BsxINcMtw,9768
+ftgo-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ftgo-1.0.0.dist-info/entry_points.txt,sha256=eDQL8opHZgWyzkqYnG88hz6izwFkbHfWQ4cmu0iCmH4,61
+ftgo-1.0.0.dist-info/top_level.txt,sha256=mNuQHBAj10xcs7AUQk0pAsXGMHGV3cwjxuGvTIurrP0,5
+ftgo-1.0.0.dist-info/RECORD,,

ftgo-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ftgo-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ftgo-demo = ftgo.examples.basic_usage:main

ftgo-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 gohibiki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ftgo-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ftgo