finlab

FinLab 核心模組，提供登入認證和 Token 管理功能。

使用情境

• 首次使用 FinLab 時進行登入認證
• 在腳本中自動設定 API Token
• 在不同環境（本地、Colab、伺服器）進行認證
• 查詢當前登入狀態

快速範例

方式 1：瀏覽器登入（推薦）

import finlab

# 啟動瀏覽器登入（會自動開啟瀏覽器）
finlab.login()

# 登入成功後，憑證會儲存在 ~/.finlab/credentials.json
# 之後使用不需要再次登入

方式 2：API Token 登入（舊版，仍可用）

import finlab

# 使用 API Token 登入
finlab.login('YOUR_API_TOKEN')

# 取得 API Token：https://ai.finlab.tw/account

方式 3：環境變數登入

import os

# 設定環境變數（適合腳本自動化）
os.environ['FINLAB_API_TOKEN'] = 'YOUR_API_TOKEN'

# 之後使用 finlab 會自動讀取環境變數
from finlab import data
close = data.get('price:收盤價')

---

認證方式比較

方式	優點	缺點	適用場景
瀏覽器登入	安全、方便、自動更新 Token	需要瀏覽器環境	本地開發、Jupyter Notebook
API Token	簡單、適合自動化	Token 過期需手動更新	腳本自動化、CI/CD
環境變數	安全、不寫入程式碼	需要額外設定	生產環境、Docker

---

認證優先順序

FinLab 會按照以下順序尋找認證資訊：

1. ~/.finlab/credentials.json - 瀏覽器登入產生的憑證（新版）
2. FINLAB_API_TOKEN 環境變數 - 手動設定的 API Token（舊版）
3. 互動式登入 - 如果以上都沒有，會提示登入

---

詳細教學

瀏覽器登入流程

import finlab

# 1. 呼叫 login() 不帶參數
finlab.login()

# 2. 瀏覽器會自動開啟 FinLab 登入頁面
# 3. 登入成功後，憑證會自動儲存
# 4. 之後使用不需要再次登入

憑證儲存位置：~/.finlab/credentials.json

有效期限：60 天（自動更新）

取得 API Token

如果使用 API Token 方式登入：

1. 前往 FinLab 會員中心
2. 複製您的 API Token
3. 在程式中使用 finlab.login('YOUR_API_TOKEN')

在不同環境使用

Google Colab

# 方式 1：使用瀏覽器登入（推薦）
import finlab
finlab.login()

# 方式 2：使用 Colab Secrets（避免 Token 外洩）
from google.colab import userdata
import finlab
finlab.login(userdata.get('FINLAB_API_TOKEN'))

Docker / 生產環境

# 使用環境變數（在 docker-compose.yml 或 .env 設定）
export FINLAB_API_TOKEN='YOUR_API_TOKEN'

# Python 腳本會自動讀取環境變數
from finlab import data
close = data.get('price:收盤價')

Jupyter Notebook / 本地開發

# 首次登入
import finlab
finlab.login()  # 瀏覽器登入

# 之後使用不需要再次登入（憑證已儲存）
from finlab import data
close = data.get('price:收盤價')

---

API Reference

finlab.login()

finlab.login

login(api_token=None)

登錄量化平台。

可以至 api_token查詢頁面 獲取api_token，傳入函數後執行登錄動作。 之後使用Finlab模組的會員功能時，系統就不會自動跳出請求輸入api_token的GUI頁面。 若傳入的api_toke格式有誤，系統會要求再次輸入。

若不傳入 api_token，會啟動瀏覽器登入流程（新版）。

PARAMETER	DESCRIPTION
api_token	FinLab api_token TYPE: str DEFAULT: None

推薦使用方式

• 本地開發：使用 finlab.login() 瀏覽器登入（方便且安全）
• 自動化腳本：使用環境變數 FINLAB_API_TOKEN（避免 Token 寫入程式碼）
• 測試環境：使用 finlab.login('token') 快速驗證

API Token 注意事項

• 不要將 API Token 上傳到 GitHub 等公開平台
• 使用環境變數或 .env 文件管理 Token
• Token 過期時需要重新取得

finlab.get_token()

finlab.get_token

get_token()

取得登錄會員的認證 token。

認證優先順序： 1. ~/.finlab/credentials.json (新版 Firebase auth) → 返回 id_token 2. FINLAB_API_TOKEN 環境變數 (舊版) → 返回 api_token 3. 互動式登入

RETURNS	DESCRIPTION
tuple	(token_string, token_type) where token_type is 'id_token' or 'api_token'

---

常見問題

Q: 如何檢查是否已登入？

import finlab

try:
    token, token_type = finlab.get_token()
    print(f"✅ 已登入（{token_type}）")
    print(f"Token: {token[:10]}...")
except Exception as e:
    print("❌ 未登入")

Q: 瀏覽器登入失敗怎麼辦？

可能原因與解決方法：

1. 缺少 cryptography 套件

   pip install cryptography
   

2. 無瀏覽器環境（如伺服器）

3. 改用 API Token 方式：finlab.login('YOUR_API_TOKEN')

4. 防火牆阻擋

5. 檢查網路設定
6. 改用 API Token 方式

Q: API Token 過期怎麼辦？

# 重新取得 Token 並登入
import finlab
finlab.login('NEW_API_TOKEN')

# 或使用瀏覽器登入（會自動更新）
finlab.login()

Q: 如何在多個專案使用不同的 Token？

使用環境變數方式：

import os
import finlab

# 專案 A
os.environ['FINLAB_API_TOKEN'] = 'TOKEN_A'
# 使用 finlab...

# 專案 B
os.environ['FINLAB_API_TOKEN'] = 'TOKEN_B'
# 使用 finlab...

Q: 如何登出？

import os

# 清除環境變數
os.environ.pop('FINLAB_API_TOKEN', None)
os.environ.pop('finlab_id_token', None)

# 刪除憑證檔案（瀏覽器登入產生的）
import os
credentials_path = os.path.expanduser('~/.finlab/credentials.json')
if os.path.exists(credentials_path):
    os.remove(credentials_path)
    print("已登出")

---

參考資源

• FinLab 會員中心 - 取得 API Token
• 快速上手指南 - 完整安裝與登入教學
• 常見問題 FAQ - 更多登入相關問題