Upload 2 files

edgar_client.py

@@ -62,25 +62,25 @@ class EdgarDataClient:
                 return None
             
         except Exception as e:
-            print(f"搜索公司时出错: {e}")
+            print(f"Error searching company: {e}")
             return None
     
     def get_company_info(self, cik):
         """
-        获取公司基本信息
+        Get basic company information
         
         Args:
-            cik (str): 公司CIK码
+            cik (str): Company CIK code
             
         Returns:
-            dict: 包含公司信息的字典
+            dict: Dictionary containing company information
         """
         if not self.edgar:
-            print("sec_edgar_api库未安装")
+            print("sec_edgar_api library not installed")
             return None
             
         try:
-            # 获取公司提交信息
+            # Get company submissions
             submissions = self.edgar.get_submissions(cik=cik)
             
             return {
@@ -91,43 +91,43 @@ class EdgarDataClient:
                 "sic_description": submissions.get("sicDescription", "")
             }
         except Exception as e:
-            print(f"获取公司信息时出错: {e}")
+            print(f"Error getting company info: {e}")
             return None
     
     def get_company_filings(self, cik, form_types=None):
         """
-        获取公司所有财报文件列表
+        Get all company filing documents
         
         Args:
-            cik (str): 公司CIK码
-            form_types (list): 财报类型列表，如['10-K', '10-Q']，默认为None表示获取所有类型
+            cik (str): Company CIK code
+            form_types (list): List of form types, e.g., ['10-K', '10-Q'], None for all types
             
         Returns:
-            list: 财报文件列表
+            list: List of filing documents
         """
         if not self.edgar:
-            print("sec_edgar_api库未安装")
+            print("sec_edgar_api library not installed")
             return []
             
         try:
-            # 获取公司提交信息
+            # Get company submissions
             submissions = self.edgar.get_submissions(cik=cik)
             
-            # 提取财报信息
+            # Extract filing information
             filings = []
             recent = submissions.get("filings", {}).get("recent", {})
             
-            # 获取各个字段的数据
+            # Get data from each field
             form_types_list = recent.get("form", [])
             filing_dates = recent.get("filingDate", [])
             accession_numbers = recent.get("accessionNumber", [])
             primary_documents = recent.get("primaryDocument", [])
             
-            # 遍历所有财报
+            # Iterate through all filings
             for i in range(len(form_types_list)):
                 form_type = form_types_list[i]
                 
-                # 如果指定了财报类型，则只返回匹配的类型
+                # Filter by form type if specified
                 if form_types and form_type not in form_types:
                     continue
                 
@@ -146,58 +146,58 @@ class EdgarDataClient:
             
             return filings
         except Exception as e:
-            print(f"获取公司财报列表时出错: {e}")
+            print(f"Error getting company filings: {e}")
             return []
     
     def get_company_facts(self, cik):
         """
-        获取公司所有财务事实数据
+        Get all company financial facts data
         
         Args:
-            cik (str): 公司CIK码
+            cik (str): Company CIK code
             
         Returns:
-            dict: 公司财务事实数据
+            dict: Company financial facts data
         """
         if not self.edgar:
-            print("sec_edgar_api库未安装")
+            print("sec_edgar_api library not installed")
             return {}
             
         try:
             facts = self.edgar.get_company_facts(cik=cik)
             return facts
         except Exception as e:
-            print(f"获取公司财务事实时出错: {e}")
+            print(f"Error getting company facts: {e}")
             return {}
     
     def get_financial_data_for_period(self, cik, period):
         """
-        获取指定期间的财务数据（支持年度和季度）
+        Get financial data for a specific period (supports annual and quarterly)
         
         Args:
-            cik (str): 公司CIK码
-            period (str): 期间，格式为'YYYY'或'YYYYQX'（如'2025'或'2025Q3'）
+            cik (str): Company CIK code
+            period (str): Period in format 'YYYY' or 'YYYYQX' (e.g., '2025' or '2025Q3')
             
         Returns:
-            dict: 财务数据字典
+            dict: Financial data dictionary
         """
         if not self.edgar:
-            print("sec_edgar_api库未安装")
+            print("sec_edgar_api library not installed")
             return {}
             
         try:
-            # 获取公司财务事实
+            # Get company financial facts
             facts = self.get_company_facts(cik)
             
             if not facts:
                 return {}
             
-            # 提取us-gaap和ifrs-full部分的财务数据（20-F可能使用IFRS）
+            # Extract us-gaap and ifrs-full financial data (20-F may use IFRS)
             us_gaap = facts.get("facts", {}).get("us-gaap", {})
             ifrs_full = facts.get("facts", {}).get("ifrs-full", {})
             
-            # 定义要获取的财务指标及其XBRL标签
-            # 包含多个可能的标签以提高匹配率（包括US-GAAP和IFRS标签）
+            # Define financial metrics and their XBRL tags
+            # Include multiple possible tags to improve match rate (including US-GAAP and IFRS tags)
             financial_metrics = {
                 "total_revenue": ["Revenues", "RevenueFromContractWithCustomerExcludingAssessedTax", "RevenueFromContractWithCustomerIncludingAssessedTax", "SalesRevenueNet", "RevenueFromContractWithCustomer", "Revenue"],
                 "net_income": ["NetIncomeLoss", "ProfitLoss", "NetIncome", "ProfitLossAttributableToOwnersOfParent"],
@@ -206,28 +206,54 @@ class EdgarDataClient:
                 "operating_cash_flow": ["NetCashProvidedByUsedInOperatingActivities", "NetCashProvidedUsedInOperatingActivities", "NetCashFlowsFromUsedInOperatingActivities", "CashFlowsFromUsedInOperatingActivities"],
             }
             
-            # 存储结果
+            # Store result
             result = {"period": period}
             
-            # 确定要查找的表格类型
+            # Determine target form types to search
             if 'Q' in period:
-                # 季度数据，主要查找10-Q（20-F通常没有季度报告）
+                # Quarterly data, mainly search 10-Q (20-F usually doesn't have quarterly reports)
                 target_forms = ["10-Q"]
-                target_forms_annual = ["10-K", "20-F"]  # 用于回退查找
+                target_forms_annual = ["10-K", "20-F"]  # for fallback
                 year = int(period.split('Q')[0])
                 quarter = period.split('Q')[1]
             else:
-                # 年度数据，查找10-K和20-F年度表格
+                # Annual data, search 10-K and 20-F annual forms
                 target_forms = ["10-K", "20-F"]
                 target_forms_annual = target_forms
                 year = int(period)
                 quarter = None
             
-            # 遍历每个财务指标
+            # Get company filings to find accession number and primary document
+            filings = self.get_company_filings(cik, form_types=target_forms)
+            filings_map = {}  # Map: form -> {accession_number, primary_document, filing_date}
+            
+            # Build filing map for quick lookup
+            for filing in filings:
+                form_type = filing.get("form_type", "")
+                filing_date = filing.get("filing_date", "")
+                accession_number = filing.get("accession_number", "")
+                primary_document = filing.get("primary_document", "")
+                
+                if filing_date and accession_number:
+                    # Extract year from filing_date (format: YYYY-MM-DD)
+                    file_year = int(filing_date[:4]) if len(filing_date) >= 4 else 0
+                    
+                    # Store filing if it matches the period year
+                    if file_year == year:
+                        key = f"{form_type}_{file_year}"
+                        if key not in filings_map:
+                            filings_map[key] = {
+                                "accession_number": accession_number,
+                                "primary_document": primary_document,
+                                "form_type": form_type,
+                                "filing_date": filing_date
+                            }
+            
+            # Iterate through each financial metric
             for metric_key, metric_tags in financial_metrics.items():
-                # 支持多个可能的标签
+                # Support multiple possible tags
                 for metric_tag in metric_tags:
-                    # 同时查找US-GAAP和IFRS标签
+                    # Search both US-GAAP and IFRS tags
                     metric_data = None
                     data_source = None
                     
@@ -241,19 +267,19 @@ class EdgarDataClient:
                     if metric_data:
                         units = metric_data.get("units", {})
                         
-                        # 查找美元单位的数据（支持USD和USD/shares）
+                        # Find USD unit data (supports USD and USD/shares)
                         usd_data = None
                         if "USD" in units:
                             usd_data = units["USD"]
                         elif "USD/shares" in units and metric_key == "earnings_per_share":
-                            # EPS使用USD/shares单位
+                            # EPS uses USD/shares unit
                             usd_data = units["USD/shares"]
                         
                         if usd_data:
-                            # 首先尝试精确匹配，然后尝试宽松匹配
+                            # Try exact match first, then loose match
                             matched_entry = None
                             
-                            # 查找指定期间的数据
+                            # Search for data in the specified period
                             for entry in usd_data:
                                 form = entry.get("form", "")
                                 fy = entry.get("fy", 0)
@@ -265,36 +291,36 @@ class EdgarDataClient:
                                     
                                 entry_year = int(end_date[:4])
                                 
-                                # 检查表格类型是否匹配
+                                # Check if form type matches
                                 if form in target_forms:
                                     if quarter:
-                                        # 季度数据匹配
+                                        # Quarterly data match
                                         if entry_year == year and fp == f"Q{quarter}":
-                                            # 如果已有匹配，比较end date，选择最新的
+                                            # If already matched, compare end date, choose the latest
                                             if matched_entry:
                                                 if entry.get("end", "") > matched_entry.get("end", ""):
                                                     matched_entry = entry
                                             else:
                                                 matched_entry = entry
                                     else:
-                                        # 年度数据匹配 - 优先匹配FY字段
+                                        # Annual data match - prioritize FY field match
                                         if fy == year and (fp == "FY" or fp == "" or not fp):
-                                            # 如果已有匹配，比较end date，选择最新的（最近的财年结束日期）
+                                            # If already matched, compare end date, choose the latest (most recent fiscal year end date)
                                             if matched_entry:
                                                 if entry.get("end", "") > matched_entry.get("end", ""):
                                                     matched_entry = entry
                                             else:
                                                 matched_entry = entry
-                                        # 备选：匹配end日期的年份（仅当没有FY匹配时）
+                                        # Alternative: match end date year (only when no FY match)
                                         elif not matched_entry and entry_year == year and (fp == "FY" or fp == "" or not fp):
                                             matched_entry = entry
-                                        # 20-F特殊处理：有些20-F没有FY标记，通过frame字段匹配
+                                        # Special handling for 20-F: some 20-F don't have FY marker, match via frame field
                                         elif not matched_entry and form == "20-F" and "frame" in entry:
                                             frame = entry.get("frame", "")
                                             if f"CY{year}" in frame or str(year) in end_date:
                                                 matched_entry = entry
                             
-                            # 如果季度数据没找到，尝试从年度报告中查找（回退策略）
+                            # If quarterly data not found, try finding from annual report (fallback strategy)
                             if not matched_entry and quarter and target_forms_annual:
                                 for entry in usd_data:
                                     form = entry.get("form", "")
@@ -302,20 +328,41 @@ class EdgarDataClient:
                                     fp = entry.get("fp", "")
                                     
                                     if form in target_forms_annual and end_date:
-                                        # 检查结束日期是否在该季度范围内
+                                        # Check if end date is within this quarter range
                                         if str(year) in end_date and f"Q{quarter}" in fp:
                                             matched_entry = entry
                                             break
                             
-                            # 应用匹配的数据
+                            # Apply matched data
                             if matched_entry:
                                 result[metric_key] = matched_entry.get("val", 0)
-                                # 添加数据来源信息
-                                accn = matched_entry.get('accn', '').replace('-', '')
-                                result["source_url"] = f"https://www.sec.gov/Archives/edgar/data/{cik}/{accn}"
-                                result["source_form"] = matched_entry.get("form", "")
+                                
+                                # Get form and accession info
+                                form_type = matched_entry.get("form", "")
+                                accn_from_facts = matched_entry.get('accn', '').replace('-', '')
+                                
+                                # Try to get accession_number and primary_document from filings
+                                filing_key = f"{form_type}_{year}"
+                                filing_info = filings_map.get(filing_key)
+                                
+                                if filing_info:
+                                    # Use filing info from get_company_filings
+                                    accession_number = filing_info["accession_number"].replace('-', '')
+                                    primary_document = filing_info["primary_document"]
+                                    
+                                    # Generate complete source URL
+                                    if primary_document:
+                                        result["source_url"] = f"https://www.sec.gov/Archives/edgar/data/{cik}/{accession_number}/{primary_document}"
+                                    else:
+                                        result["source_url"] = f"https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK={cik}&type={form_type}&dateb=&owner=exclude&count=100"
+                                else:
+                                    # Fallback to company browse page if filing not found
+                                    result["source_url"] = f"https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK={cik}&type={form_type}&dateb=&owner=exclude&count=100"
+                                
+                                result["source_form"] = form_type
                                 result["data_source"] = data_source
-                                # 添加详细信息
+                                
+                                # Add detailed information
                                 result[f"{metric_key}_details"] = {
                                     "tag": metric_tag,
                                     "form": matched_entry.get("form", ""),
@@ -330,13 +377,13 @@ class EdgarDataClient:
                                     "data_source": data_source
                                 }
                         
-                        # 如果找到了数据，就跳出标签循环
+                        # If data is found, break out of tag loop
                         if metric_key in result:
                             break
             
             return result
         except Exception as e:
-            print(f"获取{period}期间财务数据时出错: {e}")
+            print(f"Error getting financial data for period {period}: {e}")
             return {}
 
 

financial_analyzer.py

@@ -8,92 +8,92 @@ import json
 class FinancialAnalyzer:
     def __init__(self, user_agent="Juntao Peng Financial Report Metrics App (jtyxabc@gmail.com)"):
         """
-        初始化财务分析器
+        Initialize financial analyzer
         
         Args:
-            user_agent (str): 用户代理字符串，用于识别请求来源
+            user_agent (str): User agent string for identifying request source
         """
         self.edgar_client = EdgarDataClient(user_agent)
         
     def search_company(self, company_input):
         """
-        搜索公司信息（通过名称或CIK）
+        Search company information (by name or CIK)
         
         Args:
-            company_input (str): 公司名称或CIK
+            company_input (str): Company name or CIK
             
         Returns:
-            dict: 公司信息
+            dict: Company information
         """
-        # 如果输入是数字，假设它是CIK
+        # If input is numeric, assume it's a CIK
         if company_input.isdigit() and len(company_input) >= 8:
-            # 获取公司信息
+            # Get company information
             company_info = self.edgar_client.get_company_info(company_input)
             if company_info:
                 return company_info
             else:
-                return {"error": "未找到指定CIK的公司"}
+                return {"error": "Company not found for specified CIK"}
         else:
-            # 通过名称搜索公司
+            # Search company by name
             company = self.edgar_client.search_company_by_name(company_input)
             if company:
-                # 获取详细信息
+                # Get detailed information
                 company_info = self.edgar_client.get_company_info(company['cik'])
                 if company_info:
                     return company_info
                 else:
-                    # 如果无法获取详细信息，返回基本信息
+                    # If detailed info unavailable, return basic info
                     return {
                         "cik": company['cik'],
                         "name": company['name'],
                         "tickers": [company['ticker']] if company['ticker'] else []
                     }
             else:
-                return {"error": "未找到匹配的公司"}
+                return {"error": "No matching company found"}
     
     def get_company_filings_list(self, cik, form_types=['10-K', '10-Q']):
         """
-        获取公司财报列表
+        Get company filings list
         
         Args:
-            cik (str): 公司CIK
-            form_types (list): 财报类型列表
+            cik (str): Company CIK
+            form_types (list): List of form types
             
         Returns:
-            list: 财报列表
+            list: Filings list
         """
         filings = self.edgar_client.get_company_filings(cik, form_types)
         return filings
     
     def extract_financial_metrics(self, cik, years=3):
         """
-        提取指定年数的财务指标
+        Extract financial metrics for specified number of years
         
         Args:
-            cik (str): 公司CIK
-            years (int): 要提取的年数，默认为3年
+            cik (str): Company CIK
+            years (int): Number of years to extract, default is 3 years
             
         Returns:
-            list: 财务数据列表
+            list: List of financial data
         """
-        # 直接从company facts中获取所有可用的财年数据
-        # 这样可以避免filing date和fiscal year不匹配的问题
+        # Get all available fiscal years directly from company facts
+        # This avoids mismatches between filing date and fiscal year
         financial_data = []
         
-        # 获取company facts以确定可用的财年
+        # Get company facts to determine available fiscal years
         facts = self.edgar_client.get_company_facts(cik)
         if not facts:
             return []
         
-        # 从facts中提取所有可用的财年
+        # Extract all available fiscal years from facts
         available_years = set()
         
-        # 检查US-GAAP和IFRS数据源
+        # Check US-GAAP and IFRS data sources
         for data_source in ["us-gaap", "ifrs-full"]:
             if data_source in facts.get("facts", {}):
                 source_data = facts["facts"][data_source]
                 
-                # 查找Revenue标签以确定可用年份
+                # Look for Revenue tags to determine available years
                 revenue_tags = ["Revenues", "RevenueFromContractWithCustomerExcludingAssessedTax", 
                                "Revenue", "RevenueFromContractWithCustomer"]
                 
@@ -102,14 +102,14 @@ class FinancialAnalyzer:
                         units = source_data[tag].get("units", {})
                         if "USD" in units:
                             for entry in units["USD"]:
-                                # 只考虑年度报告（10-K或20-F）
+                                # Only consider annual reports (10-K or 20-F)
                                 if entry.get("form") in ["10-K", "20-F"]:
-                                    # 优先使用fy字段（财政年度）
+                                    # Prioritize using fy field (fiscal year)
                                     fy = entry.get("fy", 0)
                                     if fy > 0:
                                         available_years.add(fy)
-                                    # 如果没有fy字段，从end date提取年份作为备选
-                                    # 注意：对于财年不等于日历年的公司，这可能不准确
+                                    # If no fy field, extract year from end date as fallback
+                                    # Note: This may be inaccurate for companies whose fiscal year differs from calendar year
                                     elif not fy:
                                         end_date = entry.get("end", "")
                                         if end_date and len(end_date) >= 4:
@@ -120,7 +120,7 @@ class FinancialAnalyzer:
                     break
         
         if not available_years:
-            # 如果无法从facts获取，回退到使用filing date
+            # If unable to get from facts, fall back to using filing date
             filings_10k = self.edgar_client.get_company_filings(cik, ['10-K'])
             filings_20f = self.edgar_client.get_company_filings(cik, ['20-F'])
             filings = filings_10k + filings_20f
@@ -128,7 +128,7 @@ class FinancialAnalyzer:
             if not filings:
                 return []
             
-            # 使用filing date作为参考
+            # Use filing date as reference
             latest_filing_year = None
             for filing in filings:
                 if 'filing_date' in filing and filing['filing_date']:
@@ -142,42 +142,42 @@ class FinancialAnalyzer:
             if latest_filing_year is None:
                 return []
             
-            # 生成年份列表
-            for i in range(years * 2):  # 扩大范围以捕获更多数据
+            # Generate year list
+            for i in range(years * 2):  # Expand range to capture more data
                 available_years.add(latest_filing_year - i)
         
-        # 按年份降序排列
+        # Sort years in descending order
         sorted_years = sorted(available_years, reverse=True)
         
-        # 生成期间列表（年度和季度）
+        # Generate period list (annual and quarterly)
         periods = []
         for year in sorted_years[:years]:
-            # 添加年度数据
+            # Add annual data
             periods.append(str(year))
-            # 添加季度数据，按Q4、Q3、Q2、Q1顺序
+            # Add quarterly data in order Q4, Q3, Q2, Q1
             for quarter in range(4, 0, -1):
                 periods.append(f"{year}Q{quarter}")
         
-        # 获取每个期间的财务数据
+        # Get financial data for each period
         for period in periods:
             data = self.edgar_client.get_financial_data_for_period(cik, period)
-            # 即使没有完整数据也添加，避免N/A情况
-            if data:  # 只要period字段存在就添加
+            # Add even if incomplete data, to avoid N/A situations
+            if data:  # Add as long as period field exists
                 financial_data.append(data)
         
         return financial_data
     
     def get_latest_financial_data(self, cik):
         """
-        获取最新财务数据
+        Get latest financial data
         
         Args:
-            cik (str): 公司CIK
+            cik (str): Company CIK
             
         Returns:
-            dict: 最新财务数据
+            dict: Latest financial data
         """
-        # 获取最近的财报年份（支持10-K和20-F）
+        # Get latest filing year (supports 10-K and 20-F)
         filings_10k = self.edgar_client.get_company_filings(cik, ['10-K'])
         filings_20f = self.edgar_client.get_company_filings(cik, ['20-F'])
         filings = filings_10k + filings_20f
@@ -185,7 +185,7 @@ class FinancialAnalyzer:
         if not filings:
             return {}
         
-        # 获取最新的财报年份
+        # Get latest filing year
         latest_filing_year = None
         for filing in filings:
             if 'filing_date' in filing and filing['filing_date']:
@@ -199,18 +199,18 @@ class FinancialAnalyzer:
         if latest_filing_year is None:
             return {}
         
-        # 获取最新年份的财务数据
+        # Get financial data for latest year
         return self.edgar_client.get_financial_data_for_period(cik, str(latest_filing_year))
     
     def format_financial_data(self, financial_data):
         """
-        格式化财务数据以便显示
+        Format financial data for display
         
         Args:
-            financial_data (dict or list): 财务数据
+            financial_data (dict or list): Financial data
             
         Returns:
-            dict or list: 格式化后的财务数据
+            dict or list: Formatted financial data
         """
         if isinstance(financial_data, list):
             formatted_data = []
@@ -222,24 +222,24 @@ class FinancialAnalyzer:
     
     def _format_single_financial_data(self, data):
         """
-        格式化单个财务数据条目
+        Format single financial data entry
         
         Args:
-            data (dict): 财务数据
+            data (dict): Financial data
             
         Returns:
-            dict: 格式化后的财务数据
+            dict: Formatted financial data
         """
         formatted = data.copy()
         
-        # 确保所有关键字段都存在，即使为None
+        # Ensure all key fields exist, even if None
         key_fields = ['total_revenue', 'net_income', 'earnings_per_share', 'operating_expenses', 'operating_cash_flow', 'source_url', 'source_form']
         for key in key_fields:
             if key not in formatted:
                 formatted[key] = None
         
-        # 不再进行单位转换，保持原始数值
-        # 格式化EPS，保留两位小数
+        # No longer perform unit conversion, keep original values
+        # Format EPS, keep two decimal places
         if 'earnings_per_share' in formatted and isinstance(formatted['earnings_per_share'], (int, float)):
             formatted['earnings_per_share'] = round(formatted['earnings_per_share'], 2)