Historical 8P Extractor V2 - 股票歷史數據與 8P 估值分析工具

📊 功能介紹

Historical 8P Extractor V2 是一個功能強大的股票分析工具，設計用於從 Yahoo Finance 獲取股票歷史數據並執行詳細的 8P 估值分析。本工具是原始 get_yfinance_data.py 的模組化重構升級版本，保留了完全相同的功能，但程式碼結構更加清晰，易於維護和擴展。

主要功能：

基本股票資訊：獲取股票的基本資訊，如公司名稱、行業、市值等
歷史價格分析：提供年度和月度高低價分析，包括對應的日期和成交量
8P 估值分析：計算並顯示 8P 估值指標，包括：
- PE（市盈率）：公司市值 / 淨利潤，評估盈利穩定性
- PS（市銷率）：公司市值 / 銷售收入，聚焦收入成長潛力
- PB（市淨率）：公司市值 / 淨資產，適合資產密集型企業評估
- DY（股息收益率）：每股股息 / 股價，以百分比表示，適用於成熟派息企業
- PEG（市盈率/增長率）：評估公司增長性與估值水平
- PSG（市銷率/增長率）：評估公司收入增長性與估值水平
- PCF（市現率）：公司市值 / 經營現金流，評估公司現金流質量
- PFCF（市自由現率）：公司市值 / 自由現金流，評估公司自由現金流質量
歷史 8P 估值分析：顯示每個年度的 8P 估值指標的高低值，方便進行歷史比較和趨勢分析
財務報表分析：提供損益表、資產負債表、現金流量表的關鍵指標
進度條視覺化：直觀顯示各比率在歷史區間中的位置
自定義財務數據支援：允許從自定義 CSV 檔案匯入財務數據，優先用於 8P 估值分析，自動用 API 數據補足缺失部分
數據來源透明度：清晰顯示各年份財務數據來源，區分 API 數據與自定義數據

🚀 快速開始

安裝依賴

pip install yfinance pandas rich

基本使用方法

命令行方式

# 使用默認參數（股票代碼 2318.hk，過去 3 年）
python main.py

# 指定股票代碼
python main.py AAPL

# 指定日期範圍
python main.py 2318.hk --start 2022-01-01 --end 2023-01-01

# 指定時間段（支援：1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 3y, 5y, 10y, ytd, max）
python main.py 2318.hk --period 5y

# 使用調整後的價格（考慮股票分割和股息）
python main.py 2318.hk --adjust

# 使用自定義財務數據
python main.py 2318.hk --custom-data import_data/2318_data.csv

# 顯示財務指標的詳細數據來源
python main.py 2318.hk --view-source-details

注意：程式支援兩種導入方式，可以直接在程式根目錄執行 python main.py 或以模組方式執行 python -m historical_8p_extractor_v2。程式會自動處理相對和絕對導入，確保在任何執行模式下都能正常運作。

互動式方式

如果不提供命令行參數，程序將以互動式模式執行，引導您：

輸入股票代碼
選擇時間範圍模式
設定是否使用調整後價格
選擇是否使用自定義財務數據及其路徑
選擇是否顯示財務指標的詳細數據來源

📝 參數說明

參數	簡寫	說明	預設值
ticker	-	股票代碼	2318.hk
--start	-s	開始日期 (YYYY-MM-DD)	None
--end	-e	結束日期 (YYYY-MM-DD)	None
--period	-p	時間段	3y
--adjust	-	啟用價格自動調整	False
--custom-data	-	自定義財務數據 CSV 檔案路徑	None
--view-source-details	-	顯示財務指標的詳細數據來源	False

🧩 模組結構

程序被分拆為以下模組：

main.py：程序主入口，整合所有功能
main.py：命令行介面入口
utils.py：共用工具函數
stock_data_fetcher.py：從 yfinance 獲取數據
stock_data_processor.py：處理和轉換數據
price_analysis.py：價格分析功能
ratio_analysis.py：8P 估值分析功能
display_utils.py：數據展示和格式化功能
financial_utils.py：財務數據處理和比率計算輔助函數，包含：
- 股數獲取函數 get_shares_from_balance_sheet
- 市值計算函數 calculate_market_cap
- 財務數據獲取函數 get_financial_value
- 比率計算函數 calculate_ratio
custom_data_loader.py：自定義財務數據讀取與合併模組，包含：
- CSV 檔案讀取函數 read_custom_data
- 數據合併函數 merge_custom_and_api_data
- 數據來源標示函數 get_data_source_info

📊 分析結果示例

基本股票信息

顯示股票的基本信息，包括公司名稱、行業、市值、52週高低點等。

歷史股價數據

提供年度和月度高低價匯總表，展示每年/每月的最高價和最低價，以及對應的日期和成交量。

8P 估值分析

計算並展示當前的 8P 估值比率，以及這些比率在歷史範圍中的位置。使用視覺化進度條直觀顯示當前值在歷史最高值和最低值之間的位置。

TTM 方法說明

當前比率計算使用 TTM（Trailing Twelve Months，過去十二個月）方法，這是一種臨時性計算方式，可能導致一定誤差。程序會明確標示此方法的使用，並提供相關說明。未來版本將加入更嚴謹的業務前瞻分析基礎數據。

歷史 8P 估值分析

提供每個年度的 8P 估值指標的高低值，分為基本估值指標（PE、PS、PB、DY）和進階估值指標（PEG、PSG、PCF、PFCF）兩個部分。該功能可以讓投資者快速掌握股票在不同時期的估值水平，更好地進行歷史比較和趨勢分析。所有表格統一使用綠色標示最高值，紅色標示最低值，提升視覺一致性。

財務數據分析

顯示各年度的關鍵財務指標，包括總營收、淨利潤、營收增長率、淨資產、經營現金流、自由現金流等。

股數數據說明

顯示股票的流通股數信息，包括各年份的股數數據及其來源。程序會自動選擇最適合的股數數據來源（優先使用 Ordinary Shares Number），並清晰標示資料來源：

當前年份數據標示為「估計值（基於最近可用數據）」
自定義 CSV 數據清晰標示為「自定義 CSV」
API 數據則顯示具體的數據欄位來源

數據來源透明度

程序可通過 --view-source-details 參數顯示財務指標的詳細數據來源，清晰區分來自 API 或自定義 CSV 的數據，確保分析過程透明可追溯。

🔎 8P 估值法基礎數據表指標說明

8P 估值法基礎數據表中的各項指標經過精心設計，保證數據獲取的準確性和可靠性。以下是各指標的詳細說明：

1. 損益表數據

指標	說明	數據來源與邏輯
總營收 (Total Revenue)	公司在特定年度的總銷售額或收入	從損益表中嘗試獲取 "Total Revenue", "Revenue", "Sales", "Total Sales" 等欄位
淨利潤 (Net Income)	公司扣除所有成本和費用後的最終獲利	從損益表中按優先順序嘗試獲取 "Net Income", "Net Income Common Stockholders" 欄位
營收增長率 (YoY%)	同比上一年度的營收增長百分比	使用當年與上一年度的總營收計算: (當年營收-上年營收)/上年營收×100%

2. 資產負債表數據

指標	說明	數據來源與邏輯
淨資產（Total Stockholders' Equity）	公司資產總值減去負債後歸屬於股東的部分	從資產負債表中嘗試獲取 "Stockholders Equity", "Total Equity", "Book Value" 等欄位

3. 現金流量表數據

指標	說明	數據來源與邏輯
經營現金流 (Operating CF)	公司從日常業務運營中產生的現金流入淨額	從現金流量表中嘗試獲取 "Operating Cash Flow", "Total Cash From Operating Activities" 等欄位
資本支出 (Capital Expenditure)	公司投資於長期資產的資金，在 yfinance API 中呈現為負值	從現金流量表中嘗試獲取 "Capital Expenditure", "Capital Expenditures" 等欄位
自由現金流 (Free Cash Flow)	公司在支付所有營運和資本支出後剩餘的現金	首選直接獲取 "Free Cash Flow" 欄位；其次計算：經營現金流 + 資本支出（因資本支出在 API 中為負值，等同於財務公式：經營現金流 - 資本支出的絕對值）

4. 其他重要數據

指標	說明	數據來源與邏輯
年度最高/最低股價	年度內的最高和最低交易價格	從歷史價格數據中計算並記錄對應日期與成交量
年度股息（Annual Dividend）	公司在一年內向股東支付的總股息金額	從股票對象的 dividends 屬性中獲取並計算年度總和
年末總股數（Shares Outstanding at Year End）	公司在年末的已發行股票總數	智能選擇最佳股數數據來源："Ordinary Shares Number", "Share Issued", "Common Stock Shares Outstanding"，並提供數據來源透明度
最高/最低市值估算	根據年度最高/最低股價與年末總股數計算的市值	計算公式：股價 × 總股數，為 8P 估值比率計算提供基礎

數據獲取優化策略

多欄位嘗試：為每個指標嘗試多個可能的欄位名稱，增強數據獲取可靠性
智能回退機制：實現從「最佳欄位」到其他欄位的回退機制，確保盡可能獲得有效數據
數據透明度：記錄並顯示數據來源，增加分析的透明度和可靠性
合理的格式化：將數值適當轉換為十億或百萬單位，提高數據可讀性

📄 自定義財務數據 CSV 格式

如需使用自定義財務數據，請遵循以下 CSV 文件格式：

年份,總營收,淨利潤,淨資產,經營現金流,資本支出,自由現金流,年度股息,年末總股數
2024,1141346000000,126607000000,931184000000,382474000000,-9136000000,373338000000,2.45,18210234607
2023,1031863000000,85665000000,899011000000,360403000000,-7810000000,352593000000,2.43,18210234607
2022,1221351000000,83774000000,858675000000,485905000000,-8871000000,477034000000,2.42,18280241410
2021,1287675000000,101618000000,812405000000,90116000000,-12186000000,77930000000,2.38,18280241410

CSV 欄位說明：

年份：財務數據的年度，格式為 YYYY
總營收：全年總收入，單位為原始貨幣（如 HKD、USD、RMB 等）
淨利潤：年度淨利潤，單位為原始貨幣
淨資產：資產負債表中的淨資產總額，單位為原始貨幣
經營現金流：年度經營現金流量，單位為原始貨幣
資本支出：年度資本支出，單位為原始貨幣，支出以負值表示（與 yfinance API 一致）
自由現金流：經營現金流加上資本支出（因資本支出為負值，實際相當於經營現金流減去資本支出的絕對值）
年度股息：全年每股股息，單位為原始貨幣
年末總股數：年末已發行股票總數

使用說明：

數據必須按年份降序排列（最新年份在最前）
所有金額必須為完整數值，不使用千分位分隔符
缺失數據請留空，程式會自動使用 yfinance API 數據補充
程式會根據自定義數據的有無，在分析結果中清晰標示數據來源

🔄 更新歷史

2025-04-29：
- 新增自定義財務數據功能，允許從 CSV 檔案匯入數據用於 8P 估值分析
- 增加數據來源標記，清晰顯示各年度數據是來自 CSV 還是 API
- 優化股數數據來源顯示，明確標示自動回填的數據和估計值
- 新增「財務指標數據來源詳情」功能，顯示每個指標的具體來源和欄位對應關係
- 完善錯誤處理和日誌記錄功能
- 優化淨利潤數據獲取邏輯，調整欄位來源，僅使用 "Net Income" 和 "Net Income Common Stockholders" 欄位
- 添加 8P 估值法基礎數據表指標的詳細說明，包括數據來源和處理邏輯
- 改進缺失數據檢測與回填機制，對自動從 API 補足的數據提供明確標示
- 優化文檔結構，提高用戶理解程序功能和實現方式的便利性
- 澄清自由現金流計算邏輯，反映 yfinance API 中資本支出為負值的特性
2025-04-28：
- 重構程式碼，消除重複邏輯，提升可維護性
- 新增 financial_utils.py 模組，封裝共用財務數據處理函數
- 改進模組導入邏輯，同時支援相對導入和絕對導入，提升執行兼容性
- 更新 README.md 命令行運行指令，使其與實際執行方式一致
- 優化程式穩定性和擴展性
2025-04-24：
- 優化 TTM 方法重要說明顯示，明確標示當前比率計算使用 TTM 方法
- 統一所有表格顏色方案，最高值使用綠色，最低值使用紅色
- 隱藏不必要的調試訊息，使輸出更加簡潔專業
- 優化股數來源與市值計算的說明，避免重複顯示
- 改進資訊顯示的一致性和專業性
2025-04-22：
- 新增歷史 8P 估值分析功能，提供每個年度的 8P 估值指標高低值
- 將 8P 估值指標分為基本指標和進階指標兩個表格顯示
- 優化日期處理和數據格式，提高分析準確性
- 增強錯誤處理和日誌記錄，改善程式穩定性
- 模組化重構，將原有的 get_yfinance_data.py 分拆為多個功能模組，提高代碼的可維護性和擴展性
2025-04-21：改進 DY 比率顯示為數值形式（非百分比）；新增視覺化進度條功能，直觀展示各比率當前值在歷史範圍中的位置；統一 8P 比率顯示順序
2025-04-20：修正 8P 估值法分析的標題序號；修改計算邏輯，確保每年使用對應年份的股數數據
之前更新：股數數據獲取流程優化；移除 API 股數警告；改善數據來源透明度

🔍 注意事項

此工具使用 Yahoo Finance API 獲取數據，股票代碼需遵循 Yahoo Finance 的標準（如香港股票需加 .HK 後綴，美國股票可直接使用代碼）
部分財務數據可能因數據源限制而不完整
程序會自動識別純數字代碼為香港股票，並添加 .hk 後綴
如需多國股票支援，可直接輸入完整代碼（如 0700.HK, AAPL, 7203.T 等）
使用 conda 環境 adamlab4_env 運行此程序可獲得最佳兼容性
程序文件不超過 600 行，便於維護和擴展

💻 開發說明

代碼結構優化

本版本在原有基礎上進行了以下優化：

消除重複邏輯：
- 提取共用財務數據處理函數至 financial_utils.py 模組
- 統一比率計算方法，提高代碼一致性
- 改進錯誤處理和邊界情況處理
模組導入改進：
- 支援相對導入和絕對導入
- 同時兼容作為腳本直接運行或作為模組調用
- 使用 try/except 結構處理不同執行環境
代碼可維護性：
- 函數精確命名，提高代碼可讀性
- 添加詳細注釋，說明邏輯流程
- 模塊化結構，便於擴展新功能

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
__pycache__		__pycache__
import_data		import_data
.gitignore		.gitignore
.windsurfrules		.windsurfrules
README.md		README.md
__init__.py		__init__.py
__main__.py		__main__.py
custom_data_loader.py		custom_data_loader.py
display_utils.py		display_utils.py
financial_utils.py		financial_utils.py
historical_8p_extractor_debug.log		historical_8p_extractor_debug.log
main.py		main.py
price_analysis.py		price_analysis.py
ratio_analysis.py		ratio_analysis.py
ratio_analysis.py.bak		ratio_analysis.py.bak
simple_test.py		simple_test.py
stock_data_fetcher.py		stock_data_fetcher.py
stock_data_processor.py		stock_data_processor.py
test_capex.py		test_capex.py
test_yfinance_fields.py		test_yfinance_fields.py
utils.py		utils.py

Adamchanadam/historical_8p_extractor_v2

Folders and files

Latest commit

History

Repository files navigation