小狐狸事務所: Python 學習筆記 : 將 K 線圖模組 kbar.py 打包上傳 PyPI (二)

2025年8月20日星期三

Python 學習筆記 : 將 K 線圖模組 kbar.py 打包上傳 PyPI (二)

由於篇幅太長了, 所以我將整篇記錄拆成三篇, 此為中篇. 本系列前一篇文章參考 :

# Python 學習筆記 : 將 K 線圖模組 kbar.py 打包上傳 PyPI (一)

Python 量化投資筆記索引參考 :

# Python 量化投資筆記索引

本篇繼續來進行套件打包作業.

4. 編輯單元測試 unittest 程式檔 :

抄錄前篇所配置的檔案目錄結構 :

D:\pypi>tree kbar /f

列出磁碟區新增磁碟區的資料夾 PATH

磁碟區序號為 1258-16B8

D:\PYPI\KBAR

│ LICENSE

│ pyproject.toml

│ README.md

├─src

│ └─kbar

│ │ kbar.py

│ └─ __init__.py

└─tests

│ test_kbar.py

└─__init__.py

在 tests 資料夾底下的 test_kbar.py 是用來測試套件功能的單元測試程式, 可以在檔案中利用 unittest 套件撰寫測試邏輯, 但也可以是一個空檔案或將整個 test 子目錄移除, 這並不會影響套件的打包與上傳, PyPI 可以接受發佈的套件中沒有 test 資料夾或測試程式為空檔案.

雖然我還不會用 unittest, 但為了套件的完整性, 還是請 ChatGPT 幫忙生成了一個 test_kbar.py 測試檔, 提示詞如下 :

"請為上面的 kbar.py 寫一個在套件子目錄 tests 下的 test_kbar.py 檔案"

經過了幾次除錯之後得到如下的單元測試程式 :

# test_kbar.py

import unittest

import pandas as pd

import numpy as np

from kbar import KBar, detect_font

class TestKBar(unittest.TestCase):

def setUp(self):

# 建立測試用的 DataFrame

data = {

'Open': [100, 102, 101, 105],

'High': [103, 106, 104, 108],

'Low': [99, 100, 98, 102],

'Close': [102, 104, 103, 107],

'Volume': [1000, 1500, 1200, 1300],

}

self.df = pd.DataFrame(data, index=pd.date_range(start="2023-01-01", periods=4))

self.kbar = KBar(self.df)

def test_initialization(self):

# 測試初始化是否正確

self.assertEqual(len(self.kbar.addplots), 0)

pd.testing.assert_frame_equal(self.kbar.df, self.df)

def test_font_detection(self):

# 測試是否能偵測到字型（不保證一定有中文，但至少不應該 None）

font = detect_font()

self.assertIsNotNone(font)

def test_addplot(self):

# 測試 addplot 方法

data = self.df['Close']

self.kbar.addplot(data, color='red', linestyle='--', width=2)

self.assertEqual(len(self.kbar.addplots), 1)

def test_addplot_content(self):

# 驗證 addplot 內容正確性

data = self.df['Close']

self.kbar.addplot(data, color='blue')

plot_obj = self.kbar.addplots[0]

# 驗證資料長度一致

self.assertEqual(len(plot_obj.get_data()[1]), len(self.df))

def test_plot_without_returnfig(self):

# 測試 plot 方法不傳回圖表

try:

self.kbar.plot(volume=True, title='Test Plot', ylabel='Price')

except Exception as e:

self.fail(f"plot() raised an exception: {e}")

def test_plot_with_returnfig(self):

# 測試 plot 方法傳回圖表

fig, axes = self.kbar.plot(returnfig=True, volume=True, title='Test Plot')

self.assertTrue(hasattr(fig, "axes"))

self.assertGreaterEqual(len(fig.axes), 2) # 檢查有主圖與成交量副圖

def test_plot_with_returnfig_axes_labels(self):

# 測試標題是否被正確設定

fig, axes = self.kbar.plot(returnfig=True, volume=True, title='My Test Title')

self.assertIn('My Test Title', fig._suptitle.get_text())

def test_invalid_addplot_data(self):

# 測試傳入錯誤型別資料

with self.assertRaises(TypeError):

self.kbar.addplot("invalid_data")

def test_plot_with_custom_params(self):

# 測試自訂參數的情況

try:

self.kbar.plot(

volume=True,

figscale=1.2,

figratio=(10, 6),

tight_layout=True,

xrotation=30,

)

except Exception as e:

self.fail(f"plot() raised an exception with custom params: {e}")

if __name__ == "__main__":

unittest.main()

開啟命令提示字元視窗, 切換至專案目錄 (此處是 D:\pypi\kbar) 下 :

D:\cd pypi\kbar

然後執行下列編輯模式安裝指令 (editable install) :

pip install -e .

這會把 src/kbar 安裝到 Python 的 site-packages, 但 Python 不是把 kbar 套件複製到 site-packages 去安裝, 而是建立一個指向 kbar 專案原始碼的連結, 這樣在專案目錄改檔案時, Python 就會直接看到改動, 對開發與做單元測試都非常方便, 這樣 unittest 測試程式中就能直接使用 from kbar import KBar 匯入指令了 :

D:\PyPi\kbar>pip install -e .

Obtaining file:///D:/PyPi/kbar

Installing build dependencies ... done

Checking if build backend supports build_editable ... done

Getting requirements to build editable ... done

Preparing editable metadata (pyproject.toml) ... done

Requirement already satisfied: mplfinance>=0.12.10b0 in c:\users\tony1\appdata\roaming\python\python310\site-packages (from kbar==0.1.0) (0.12.10b0)

Requirement already satisfied: matplotlib in c:\users\tony1\appdata\roaming\python\python310\site-packages (from mplfinance>=0.12.10b0->kbar==0.1.0) (3.7.2)

Requirement already satisfied: pandas in c:\users\tony1\appdata\roaming\python\python310\site-packages (from mplfinance>=0.12.10b0->kbar==0.1.0) (2.0.3)

Requirement already satisfied: contourpy>=1.0.1 in c:\users\tony1\appdata\local\programs\thonny\lib\site-packages (from matplotlib->mplfinance>=0.12.10b0->kbar==0.1.0) (1.3.2)

Requirement already satisfied: cycler>=0.10 in c:\users\tony1\appdata\roaming\python\python310\site-packages (from matplotlib->mplfinance>=0.12.10b0->kbar==0.1.0) (0.11.0)

Requirement already satisfied: fonttools>=4.22.0 in c:\users\tony1\appdata\roaming\python\python310\site-packages (from matplotlib->mplfinance>=0.12.10b0->kbar==0.1.0) (4.42.1)

Requirement already satisfied: kiwisolver>=1.0.1 in c:\users\tony1\appdata\roaming\python\python310\site-packages (from matplotlib->mplfinance>=0.12.10b0->kbar==0.1.0) (1.4.5)

Requirement already satisfied: numpy>=1.20 in c:\users\tony1\appdata\roaming\python\python310\site-packages (from matplotlib->mplfinance>=0.12.10b0->kbar==0.1.0) (1.24.3)

Requirement already satisfied: packaging>=20.0 in c:\users\tony1\appdata\local\programs\thonny\lib\site-packages (from matplotlib->mplfinance>=0.12.10b0->kbar==0.1.0) (24.2)

Requirement already satisfied: pillow>=6.2.0 in c:\users\tony1\appdata\roaming\python\python310\site-packages (from matplotlib->mplfinance>=0.12.10b0->kbar==0.1.0) (9.5.0)

Requirement already satisfied: pyparsing<3.1,>=2.3.1 in c:\users\tony1\appdata\roaming\python\python310\site-packages (from matplotlib->mplfinance>=0.12.10b0->kbar==0.1.0) (3.0.9)

Requirement already satisfied: python-dateutil>=2.7 in c:\users\tony1\appdata\roaming\python\python310\site-packages (from matplotlib->mplfinance>=0.12.10b0->kbar==0.1.0) (2.8.2)

Requirement already satisfied: six>=1.5 in c:\users\tony1\appdata\local\programs\thonny\lib\site-packages (from python-dateutil>=2.7->matplotlib->mplfinance>=0.12.10b0->kbar==0.1.0) (1.16.0)

Requirement already satisfied: pytz>=2020.1 in c:\users\tony1\appdata\roaming\python\python310\site-packages (from pandas->mplfinance>=0.12.10b0->kbar==0.1.0) (2023.3)

Requirement already satisfied: tzdata>=2022.1 in c:\users\tony1\appdata\roaming\python\python310\site-packages (from pandas->mplfinance>=0.12.10b0->kbar==0.1.0) (2023.3)

Building wheels for collected packages: kbar

Building editable for kbar (pyproject.toml) ... done

Created wheel for kbar: filename=kbar-0.1.0-0.editable-py3-none-any.whl size=4690 sha256=527ec2e5c2c4049a82bfe4d916e3772146cbe77bbd588b98ad8f1600c9cf803d

Stored in directory: C:\Users\tony1\AppData\Local\Temp\pip-ephem-wheel-cache-9ztfpvmy\wheels\c7\71\74\270f8495f568015ac5455877b0405b5fcc7d494f35cddcfb43

Successfully built kbar

Installing collected packages: kbar

Successfully installed kbar-0.1.0

有了編輯模式安裝, 即可順利執行 unittest 程式 (就不會出現找不到模組之錯誤) :

python -m unittest discover -s tests

D:\PyPi\kbar>python -m unittest discover -s tests

設定字型為: Microsoft JhengHei

.設定字型為: Microsoft JhengHei

使用指定字型: Microsoft JhengHei

字型候選清單: ['Microsoft JhengHei', 'DejaVu Sans', 'Arial']

.設定字型為: Microsoft JhengHei

使用指定字型: Microsoft JhengHei

字型候選清單: ['Microsoft JhengHei', 'DejaVu Sans', 'Arial']

.設定字型為: Microsoft JhengHei

使用指定字型: Microsoft JhengHei

字型候選清單: ['Microsoft JhengHei', 'DejaVu Sans', 'Arial']

.設定字型為: Microsoft JhengHei

使用指定字型: Microsoft JhengHei

字型候選清單: ['Microsoft JhengHei', 'DejaVu Sans', 'Arial']

----------------------------------------------------------------------

Ran 9 tests in 99.423s

結果會跳出 4 張測試結果的圖, 這表示測試 OK, 將其一一關掉即可 :

做完單元測試後, 在正式發佈前要先解除 -e 模式 :

D:\PyPi\kbar>pip uninstall kbar -y

Found existing installation: kbar 0.1.0

Uninstalling kbar-0.1.0:

Successfully uninstalled kbar-0.1.0

並重新安裝套件 :

D:\PyPi\kbar>pip install .

Processing d:\pypi\kbar

Installing build dependencies ... done

Getting requirements to build wheel ... done

Preparing metadata (pyproject.toml) ... done