AugustusHsu's Blog

VS Code Note 02

AugustusHsu — Sun, 03 Nov 2024 12:00:19 GMT

用VSCode開發C++

在現代軟體開發中，跨平台開發的重要性日益增長，尤其在 C++ 領域，由於其高效能和靈活性，使其成為許多應用程式的首選語言。在這樣的背景下，Visual Studio Code憑藉其輕量、跨平台、功能強大的特點，成為越來越多開發者的首選開發環境。VSCode不僅支援多種語言，還能夠透過擴充套件實現如 IDE 般的開發體驗，並提供與 Git 整合、遠端開發等功能，使開發者能更高效地管理跨平台專案。

在實際開發中，根據專案需求，開發者可能需要編譯出對應不同作業系統的動態連結庫 (DLL)。對於Windows系統，可以透過MinGW (Minimalist GNU for Windows) 來編譯DLL，而對於Linux系統，則可以利用WSL結合GCC來生成適用於Linux的動態庫。這樣的架構使得開發者能夠在同一個環境中同時開發並測試針對不同平台的程式碼，從而提高了工作效率並減少了環境切換所帶來的麻煩。

安裝編譯器

安裝方式可以按照VSCode的文檔說明來安裝，文檔上在Windows上有分別介紹使用MinGW、WSL和Microsoft Visual C++ (MSVC) 這三種方式來安裝編譯器。

在安裝之前要記得在VSCode擴充套件中安裝C/C++擴充功能的套件:

MinGW

可以按照文檔上所推薦的方式，透過MSYS2來安裝MinGW，安裝好MSYS2後打開終端執行下面這段

pacman -S --needed base-devel mingw-w64-ucrt-x86_64-toolchain

按下Enter接受 toolchain 群組中的預設套件數量:

直接安裝就可以了:

也可以透過MinGW Installation Manager Setup Tool或是MinGW的網站來安裝MinGW，安裝後將C:\msys64\ucrt64\bin加入環境變數中:

加入環境變數後，可以在terminal上執行以下指令確定可以執行:

gcc --version
g++ --version
gdb --version

在VSCode中點選右上角執行C/C++檔案後選擇用g++來建置及偵錯:

WSL

在Windows的WSL安裝完Ubuntu後，開啟WSL的Bash Shell更新一下Ubuntu再安裝GNU編譯器工具和GDB偵錯程式:

sudo apt-get update && sudo apt-get dist-upgrade

sudo apt-get install build-essential gdb

可以尋找g++和gdb來驗證安裝是否成功。如果whereis命令未傳回檔案名稱，請嘗試再次執行更新命令:

whereis g++
whereis gdb

安裝WSL的延伸模組:

安裝完後可以從VSCode的左下角連線到WSL裡面:

在Ubuntu的terminal中執行以下指令，確定可以執行:

whereis g++
whereis gdb

在VSCode中點選右上角執行C/C++檔案後選擇一樣用g++來建置及偵錯:

MSVC

如果選擇不安裝完整Visual Studio IDE的情況下，可以在Visual Studio最下面下載Build Tools for Visual Studio 2022:

勾選使用 C++ 進行桌面開發的選項，並選取安裝:

打開Developer Command Prompt，執行cl確定可以執行，之後如果要使用cl來編譯執行，要記得使用這個terminal輸入code來啟動VSCode才能編譯執行:

在VSCode中點選右上角執行C/C++檔案後選擇一樣cl.exe來建置及偵錯:

如果不在Developer Command Prompt中來啟動VSCode的話，需要在tasks.json的task前新增以下的段落:

{
  "version": "2.0.0",
  "windows": {
    "options": {
      "shell": {
        "executable": "cmd.exe",
        "args": [
          "/C",
          // The path to VsDevCmd.bat depends on the version of Visual Studio you have installed.
          "\"C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/Common7/Tools/VsDevCmd.bat\"",
          "&&"
        ]
      }
    }
  },
  "tasks": [
    ...
  ]
}

VsDevCmd.bat的路徑可能會有所不同，可以透過dir "\VsDevCmd*" /s來找到VsDevCmd.bat的的位置。

tasks.json

tasks.json主要用來定義執行各種任務的配置，這些任務通常是指編譯、清理、打包、執行自動化測試等操作。VSCode透過這個檔案來告訴編譯器或其他工具該如何運行，例如使用哪個編譯器、輸入和輸出檔案的位置、編譯選項等。

在第一次執行程式時，C++擴充功能會建立一個tasks.json檔案，可以在專案的.vscode資料夾中找到它，tasks.json會儲存建置組態，新tasks.json檔案應該類似於以下的JSON:

{
    "tasks": [
        {
            "type": "cppbuild",
            "label": "C/C++: g++.exe 建置使用中檔案",
            "command": "C:\\msys64\\ucrt64\\bin\\g++.exe",
            "args": [
                "-fdiagnostics-color=always",
                "-g",
                "${file}",
                "-o",
                "${fileDirname}\\${fileBasenameNoExtension}.exe"
            ],
            "options": {
                "cwd": "${fileDirname}"
            },
            "problemMatcher": [
                "$gcc"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "detail": "偵錯工具產生的工作。"
        }
    ],
    "version": "2.0.0"
}

這是VSCode中tasks.json文件的一個設定範例，它主要負責配置編譯C/C++程式的任務。

"tasks": 這個鍵是任務列表，裡面可以定義多個任務 (tasks)，每個任務都表示一個具體的操作，例如編譯程式碼。
"version": "2.0.0": 這表示tasks.json文件的版本，VSCode使用這個版本來理解文件格式。

"tasks"中的每個key:

"type": "cppbuild": 定義了任務的類型，cppbuild是用來標示這是一個 C++編譯任務，VSCode會針對這種類型的任務提供相應的支援，例如 C++ 擴充套件會監控這種編譯過程。
"label": "C/C++: g++.exe 建置使用中檔案": 任務的標籤，用來描述這個任務的用途可以隨意命名，會在VSCode的任務列表中顯示出來，這個標籤表明這個任務是使用g++.exe編譯當前開啟的C++檔案。

"command": "C:\\msys64\\ucrt64\\bin\\g++.exe": 這是實際執行的命令，這裡指的是MSYS2的g++編譯器，它位於指定的路徑下(C:\\msys64\\ucrt64\\bin\\g++.exe)，這個命令會被用來編譯 C++ 檔案。
"args": 定義了執行編譯器時要傳遞的參數。每個參數會在執行命令時依次加在後面：
- "-fdiagnostics-color=always": 用來啟用編譯器輸出的彩色診斷信息，方便識別錯誤和警告。
- "-g": 用來告訴編譯器生成包含調試資訊的可執行檔案，這樣可以在調試階段更容易追蹤程式行為。
- "${file}": 代表當前打開的檔案，VSCode會自動將這個變數替換為實際文件的路徑，並將該文件作為編譯的輸入。
- "${fileDirname}\\${fileBasenameNoExtension}.exe": 這個參數指定了輸出的可執行文件的名稱。"${fileDirname}"是當前檔案所在的目錄，"${fileBasenameNoExtension}"是不帶副檔名的文件名稱，最後編譯生成的可執行檔案是.exe。
"options": 定義了執行編譯命令的選項，這裡的cwd (current working directory) 設置為${fileDirname}，即當前打開檔案的目錄。這確保編譯命令在該檔案所在的目錄中執行。
"problemMatcher": 定義了問題匹配器，用來識別編譯器輸出的錯誤和警告，"$gcc"是一個內建的問題匹配器，適用於GCC編譯器 (包括 g++)。它會解析編譯器的輸出並顯示在VSCode問題面板中，讓開發者能方便地查看錯誤位置。
"group": 這個鍵定義了任務分組的屬性：
- "kind": "build": 這表示這個任務屬於「編譯」類別，VSCode 會將其分類到編譯任務。
- "isDefault": true: 這表示這個任務是默認的編譯任務，當使用快捷鍵 (如 Ctrl+Shift+B) 啟動編譯時，VSCode會執行這個任務。
"detail": "偵錯工具產生的工作。": 這是任務的詳細描述，用來幫助開發者了解任務的用途。

如果建置的時候需要使用多個cpp檔案來建置，可以修改tasks.json檔案的args，將"${file}"改為"${workspaceFolder}/*.cpp"，將建置當前資料夾所有的cpp檔案；原本"${fileDirname}\\${fileBasenameNoExtension}.exe"是會根據當前開始的檔案生成一個與該檔案名稱相同的exe檔，改為"${workspaceFolder}\\myProgram.exe"代表將所有cpp檔都將編譯並鏈接成一個名為myProgram.exe的檔案，這適合專案中有多個源文件，但最終只生成一個可執行檔案的情況。

launch.json

launch.json用於設定VSCode調試C++程式的配置，在編輯C++程式後需要啟動調試器時，VSCode會根據這個文件中的配置來執行調試過程。過程包括指定要調試的可執行文件、設定調試器 (這裡使用GDB)、在調試過程中如何處理命令列參數、工作目錄、環境變數等、設定調試前是否需要執行編譯任務。

launch.json的範例:

{
    "configurations": [
        {
            "name": "C/C++: g++.exe 建置及偵錯使用中的檔案",
            "type": "cppdbg",
            "request": "launch",
            "program": "${fileDirname}\\${fileBasenameNoExtension}.exe",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${fileDirname}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "gdb",
            "miDebuggerPath": "C:\\msys64\\ucrt64\\bin\\gdb.exe",
            "setupCommands": [
                {
                    "description": "啟用 gdb 的美化顯示",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                },
                {
                    "description": "將反組譯碼變體設為 Intel",
                    "text": "-gdb-set disassembly-flavor intel",
                    "ignoreFailures": true
                }
            ],
            "preLaunchTask": "C/C++: g++.exe 建置使用中檔案"
        }
    ],
    "version": "2.0.0"
}

這是一個啟動調試過程配置文件，"configurations"內各個參數的定義如下:

"name": 這是調試配置的名稱，用來標識這個調試任務，可以隨意命名，會在VSCode調試面板中顯示出來，這個名稱表明該配置是用來編譯並調試當前打開的 C++ 檔案。
"type": "cppdbg": 定義了調試的類型，cppdbg是用來表示這是一個 C++ 調試任務，VSCode 會使用這個類型來啟動對應的 C++ 調試功能，通常與 GDB 或 LLDB 調試器結合使用。
"request": "launch": 定義調試請求的類型，launch表示會啟動一個新的可執行文件並進行調試，如果是attach，則表示會附加到已經運行的程序上進行調試。
"program": "${fileDirname}\${fileBasenameNoExtension}.exe": 指定要調試的可執行文件的路徑，${fileDirname} 代表當前檔案所在的目錄，${fileBasenameNoExtension} 是當前打開檔案不帶副檔名的文件名稱，這樣可以生成 .exe 檔案作為調試目標。
"args": []: 定義了在調試過程中傳遞給可執行文件的命令列參數，如果需要在啟動時傳遞特定參數，可以在此設定。
"stopAtEntry": false: 定義是否在程序進入入口點時 (通常是 main 函數) 自動停止調試。如果設為 true，程序會在入口點處暫停，方便開發者檢查初始狀態。設為 false 表示程序將會直接執行，直到遇到斷點或結束。
"cwd": "${fileDirname}": 指定調試過程中執行程序的當前工作目錄，${fileDirname} 代表當前打開檔案所在的目錄，確保程序在這個目錄中執行。
"environment": []: 定義了調試過程中要設置的環境變數，當前是空列表，表示不會設置任何額外的環境變數。如果需要為程序運行設置特定的環境變數，可以在此添加。
"MIMode": "gdb": 指定使用哪種調試協議。gdb表示使用GNU Debugger (GDB) 來進行調試。如果使用的是LLDB調試器，這裡可以設為lldb。
"miDebuggerPath": "C:\msys64\ucrt64\bin\gdb.exe": 定義了GDB調試器的路徑。這裡指定了MSYS2安裝的GDB調試器所在的路徑，讓VSCode知道在哪裡找到調試器進行調試。
"setupCommands": 定義了一些在調試過程中執行的初始命令，這些命令通常用來配置調試器的行為。
- { "description": "啟用 gdb 的美化顯示", "text": "-enable-pretty-printing", "ignoreFailures": true }:
  這個命令用來啟用GDB的美化顯示功能 (pretty printing)，這樣可以更好地格式化顯示STL容器等複雜的數據結構，使其更易於閱讀和調試。
- { "description": "將反組譯碼變體設為 Intel", "text": "-gdb-set disassembly-flavor intel", "ignoreFailures": true }:
  這個命令設置GDB使用Intel語法進行反組譯顯示，這對於習慣Intel指令集的開發者來說會更容易閱讀。
"preLaunchTask": "C/C++: g++.exe 建置使用中檔案": 指定在啟動調試之前需要執行的任務。在此情況下，"C/C++: g++.exe 建置使用中檔案" 是在tasks.json中定義的編譯任務，這確保在每次啟動調試之前會重新編譯最新版本的程式碼。

CMake

Windows可以去CMake的網站找到對應作業系統的版本下載安裝，Ubuntu可以透過sudo apt-get install cmake來安裝，如果是Windows系統可以在安裝過程中點選Add CMake to the PATH environment variable這樣可以在terminal上直接使用CMake:

安裝完成後，在terminal上輸入cmake --version確認是否安裝成功。

可以透過VSCode的命令面板 (Ctrl+Shift+P) 執行CMake: Quick Start:

輸入專案名稱:

選擇C++作為專案語言:

選擇建立可執行檔，如果是想建立程式庫則選擇上方那個:

CPack 是一個打包工具，用來生成軟體的安裝包 (installers) 或發行包 (distribution packages)；CTest 是一個測試工具，用來運行和管理專案中的單元測試、整合測試等，幫助驗證專案的正確性。根據需求選擇:

接下來是要選擇預設的編譯器:

選擇從編譯器建立:

這裡選擇要使用的編譯器即可:

直接按Enter會使用預設的名稱:

全都設定好後會自動產生CMakePresets.json檔案，CMakePresets.json是一個用來簡化CMake配置、構建和測試過程的文件，允許在專案中定義多個不同的預設配置，並能夠輕鬆切換這些配置，統一在不同平台上的配置過程，並提高配置和構建的效率:

{
    "version": 8,
    "configurePresets": [
        {
            "name": "Visual Studio Build Tools 2022 Release - amd64",
            "displayName": "Visual Studio Build Tools 2022 Release - amd64",
            "description": "使用 Visual Studio 17 2022 的編譯器(x64 架構)",
            "generator": "Visual Studio 17 2022",
            "toolset": "host=x64",
            "architecture": "x64",
            "binaryDir": "${sourceDir}/out/build/${presetName}",
            "cacheVariables": {
                "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
                "CMAKE_C_COMPILER": "cl.exe",
                "CMAKE_CXX_COMPILER": "cl.exe"
            }
        }
    ],
    "buildPresets": [
        {
            "name": "Visual Studio Build Tools 2022 Release - amd64-debug",
            "displayName": "Visual Studio Build Tools 2022 Release - amd64 - Debug",
            "configurePreset": "Visual Studio Build Tools 2022 Release - amd64",
            "configuration": "Debug"
        }
    ]
}

接下來使用CMake: Configure來配置專案，生成構建系統文件，這是編譯之前的準備步驟:

接著用CMake: Build編譯專案，將源代碼編譯成可執行文件或庫，是最終生成目標的步驟:

結語

在這篇文章中，介紹了如何使用VSCode來進行C++開發，並詳細講解了在編譯C++專案時可能會用到的各種設定，如tasks.json和launch.json。同時也初步探討了CMake的作用，展示了如何利用它來簡化跨平台的編譯與配置過程，透過這些工具和設定，VSCode成為一個靈活、高效的C++開發環境，幫助開發者更輕鬆地管理和構建複雜的專案。

Python Note 05

AugustusHsu — Sun, 27 Oct 2024 12:00:45 GMT

Python 日誌利器- Loguru

在開發程式時，記錄日誌是至關重要的工作，尤其在錯誤排查、效能優化、以及應用程式監控等方面。然而標準的Python logging有時會顯得過於繁瑣，需要寫許多配置才能滿足需求。

為了簡化這些工作，Loguru 提供了豐富的功能，如格式化日誌、自動輪替檔案、日誌等級控制等，這些功能對於日常開發和運維都十分實用。

開箱即用Loguru

可以直接透過pip安裝Loguru :

pip install loguru

安裝完後就可以直接使用Loguru，無需額外的設定即可開始記錄日誌，一行代碼即可記錄日誌，Loguru預設會將日誌輸出到Terminal:

from loguru import logger

logger.info('This is info information')

並自帶格式化顯示:

2024-09-27 20:49:19.961 | INFO     | __main__::3 - This is info information

直觀且簡潔的API

前面有講過Loguru默認會將日誌輸出到Terminal，如果要取消預設設定則需要透過logger.remove來移除，handler_id=None代表刪除所有的logger:

logger.remove(handler_id=None)

如果要重新設定回來，要將logger.add()的sink變數設定為sys.stderr就能在Terminal上顯示，回傳的stderrLogger類型為int，在刪除的時可以將handler_id指定為stderrLogger來刪除，將stderrLogger物件移除之後，在這之後的內容不會再輸出到日誌檔案:

impory sys
stderrLogger = logger.add(sink=sys.stderr, level="TRACE")
logger.remove(handler_id=stderrLogger)

可以調整日誌的等級來控制輸出:

from loguru import logger

logger.trace('This is debug information')
logger.debug('This is debug information')
logger.info('This is info information')
logger.success('This is info information')
logger.warning('This is warn information')
logger.error('This is error information')
logger.critical('This is error information')

如果是在IDE或Terminal上運行會發現，Loguru在輸出不同等級的資訊時，會帶上不同的顏色:

如果要切換記錄不同level的log時，可以透過logger.add在建立時設定:

stderrLogger = logger.add(sys.stderr, level="TRACE")

以下是不同log level的對應關係:

Level Name	Sererity Value	Logger Method
`TRACE`	5	`logger.trace()`
`DEBUG`	10	`logger.debug()`
`INFO`	20	`logger.info()`
`SUCCESS`	25	`logger.success()`
`WARNING`	30	`logger.warning()`
`ERROR`	40	`logger.error()`
`CRITICAL`	50	`logger.critical()`

自定義日誌格式

在使用Loguru記錄日誌時，自訂日誌的儲存檔案名稱與日誌的格式化是常見需求，Loguru提供了非常靈活且直觀的方式來實現這兩個需求，讓開發者能夠依據應用場景，確保日誌文件的命名清晰、內容豐富且具可讀性。

自定義名稱

將日誌寫入文件時，自訂文件名稱可以幫助你組織和管理日誌文件，Loguru 允許在文件名稱中使用變量，特別是利用時間戳來動態產生文件名，這對於需要根據日期或時間進行日誌輪替的應用非常有用。

使用{time}來命名檔案，會自動替換{time}為日誌記錄的當前時間，最終產生的檔案名稱可能會類似於logs/log_2024-09-27_12-34-56.log:

# 使用日期時間作為檔案名稱的一部分
logger.add("logs/log_{time}.log")

也可以自定義時間格式，透過使用time.strftime的時間格式化規則來完成，每天的日誌都會儲存在不同的檔案中，僅根據日期進行輪換。 :

# 自定義時間格式
logger.add("logs/log_{time:YYYY-MM-DD}.log

除了時間，也可以在檔案名稱中使用更多自訂內容，例如進程ID、日誌等級等來產生有意義的檔案名稱，這對於需要記錄多進程應用程式的日誌時特別有用：

# 其他檔案名稱格式變量
logger.add("logs/log_{time}_{level}_{process}.log")

自定義格式

format參數允許自定義每條日誌的輸出格式，對於提升日誌的可讀性以及讓日誌內容更加有用是非常有用的，Loguru提供了一系列的內置變量，可以在中format使用來控制每條日誌的輸出樣式。

可以透過format來控制日誌輸出的格式，包括時間、日誌等級、訊息內容等:

logger.add("logs/log.log", format="{time} {level} {message}")
logger.info('This is info information')

這個範例的日誌輸出格式會顯示時間、日誌等級和訊息內容，最終的日誌可能看起來像這樣:

2024-09-28T13:44:58.839276+0000 INFO This is info information

Loguru 支援多種格式化變量，可以自由組合建立適合自己的日誌輸出格式：

變量	變量說明
`{time}`	該Log記錄的時間，默認格式為 YYYY-MM-DD HH:mm:ss
`{level}`	Log等級（如 DEBUG、INFO、WARNING、ERROR）
`{message}`	Log訊息內容
`{name}`	該Log產生的記錄器名稱
`{file}`	當前程式碼檔案名稱
`{line}`	該Log所在的程式碼行號
`{function}`	記錄該Log的函數名稱
`{thread}`	記錄該Log的thread ID
`{process}`	記錄該Log的process ID

如果希望在日誌中顯示檔案名稱、行號以及函數名稱，這些資訊可以在大型專案中更快地定位Bug或Debug問題:

logger.add("logs/log.log", format="{time} {level} {file}:{line} - {function} - {message}")
logger.info('This is info information')

這樣的日誌輸出會包含詳細的Debug訊息:

2024-09-28T13:46:25.002661+0000 INFO main.py:4 -  - This is info information

如果正在開發多線程或多進程應用，記錄thread和process資訊能夠更好地理解日誌的上下文，可以使用{thread}和{process}來顯示thread ID和process ID :

logger.add("logs/log.log", format="{time} {level} {process} {thread} {message}")
logger.info('This is info information')

這樣的日誌輸出會包含thread和process的資訊；

2024-09-28T13:48:08.821860+0000 INFO 2827 139391729250304 This is info information

自動檔案輪換

在日誌管理中，控制日誌檔案的大小、時間間隔或總檔案數量是非常重要的功能，特別是在長時間運行的應用中，過大的日誌檔案不僅難以管理，還會影響系統效能，Loguru提供了內置的rotation (檔案輪換)與retention (保留)功能，支援自動將日誌檔案輪換存檔，並且可以根據檔案大小、時間間隔或檔案數量進行控制。

Rotation

當達到一定的條件(如檔案大小、時間間隔時)，自動將目前日誌檔案關閉並建立新的檔案:

# 當文件大小超過 10 MB 時會自動創建一個新的日誌文件
logger.add("file_{time}.log", rotation="10 MB")

# 每天半夜自動創建一個新的日誌文件
logger.add("file_{time}.log", rotation="00:00")

# 也可以指定其他時間間隔來進行輪替 例如每小時、每分鐘等
# 每小時自動創建一個新的日誌文件
logger.add("file_{time}.log", rotation="1 hour")

Retention

根據特定條件決定要保留的日誌檔案數量或時間範圍，超出範圍的舊日誌檔案會自動刪除，防止檔案數量過多佔用過多儲存空間:

# 保留最近 10 個日誌文件 超過部分自動刪除
logger.add("file_{time}.log", retention=10)

# 保留最近 7 天的日誌文件
logger.add("file_{time}.log", retention="7 days")

Compression

Loguru還提供了壓縮功能，當日誌輪替後，舊日誌將會自動壓縮為.zip格式，以節省空間，使用compression參數來啟用此功能:

# 同時使用rotation和retention 以實現更加靈活的日誌管理
# 每天半夜輪替 保留 7 天的文件 並將舊文件壓縮為 .zip 格式
logger.add("file_{time}.log", rotation="00:00", retention="7 days", compression="zip")

logger.catch

Loguru提供了一個非常方便且強大的功能，就是透過函數裝飾器來自動處理錯誤和記錄日誌，這特別適用於想要自動記錄函數進出、錯誤堆疊追蹤、以及避免未捕捉異常導致程序崩潰的場景，logger.catch()是這項功能的核心，可以簡化錯誤處理，並自動記錄程式中的異常。

自動捕捉異常

直接使用 @logger.catch 作為函數的裝飾器，這樣當程式碼中出現未處理的異常時，Loguru會自動捕捉並記錄異常，而程式不會崩潰:

from loguru import logger

@logger.catch
def divide(a, b):
    return a / b

divide(10, 0)
print("-----Keep Running-----")

在上面例子中，divide()函數引發了ZeroDivisionError，由於使用了logger.catch()，這個異常會被捕捉，並完整記錄在日誌中，輸出的日誌將包含詳細的錯誤和堆疊追蹤的訊息:

2024-09-28 13:50:36.823 | ERROR    | __main__::7 - An error has been caught in function '', process 'MainProcess' (3438), thread 'MainThread' (140529672212480):
Traceback (most recent call last):

> File "/content/main.py", line 7, in 
    divide(10, 0)
    └ 

  File "/content/main.py", line 5, in divide
    return a / b
           │   └ 0
           └ 10

ZeroDivisionError: division by zero
-----Keep Running-----

這種方式不僅能記錄異常，還能包含詳細的堆疊追蹤信息，能快速定位問題。

保護程式碼區塊

除了用作函數裝飾器，logger.catch()還可以用來保護整個應用程式或一大段程式碼，而不僅僅是函數，這樣可以確保在某段程式碼運行過程中，任何未處理的異常都會被捕捉並記錄下來，從而防止任何異常影響整體程式:

from loguru import logger

logger.add("error.log")  # 將日誌寫入檔案

def main():
    with logger.catch():
        10 / 0  # 故意引發除零錯誤

main()

在上面的範例中，當程式引發除零錯誤時，logger.catch()會自動捕捉並將錯誤記錄到error.log中，而不是讓程式崩潰。這樣的使用方式非常適合那些無法通過函數裝飾器直接捕捉的代碼塊，例如某個函數內的多個邏輯分支或多個異步操作:

2024-09-28 14:00:49.070 | ERROR    | __main__:main:6 - An error has been caught in function 'main', process 'MainProcess' (5877), thread 'MainThread' (137382592274432):
Traceback (most recent call last):

  File "/content/main.py", line 9, in 
    main()
    └ 

> File "/content/main.py", line 7, in main
    10 / 0  # 故意引發除零錯誤

ZeroDivisionError: division by zero

強大的參數控制

logger.catch() 提供了一些進階參數來進一步控制異常處理的行為。

reraise 重新引發異常

如果在記錄完錯誤之後，希望將異常重新引發 (讓上層的代碼也能處理該異常)，可以使用 reraise=True 參數:

from loguru import logger

@logger.catch(reraise=True)
def divide(a, b):
    return a / b

try:
    divide(10, 0)
except ZeroDivisionError:
    print("捕捉到除零異常")

reraise=True會在捕捉到異常後，重新引發ZeroDivisionError，使得外部的try-except區塊也可以處理這個異常:

2024-09-28 14:09:04.104 | ERROR    | __main__::8 - An error has been caught in function '', process 'MainProcess' (7869), thread 'MainThread' (134771338235904):
Traceback (most recent call last):

> File "/content/main.py", line 8, in 
    divide(10, 0)
    └ 

  File "/content/main.py", line 5, in divide
    return a / b
           │   └ 0
           └ 10

ZeroDivisionError: division by zero
捕捉到除零異常

onerror 自定義錯誤處理

還可以使用 onerror 參數來設置一個回調函數，在捕捉到異常時執行自定義的邏輯，例如發送通知或記錄額外信息:

from loguru import logger

def notify_admin(e):
    print(f"系統出錯：{e}")
    print("啟動緊急應變流程、收集故障排除數據、發送郵件...")

@logger.catch(onerror=notify_admin)
def main():
    10 / 0  # 故意引發錯誤

main()

當這段程式執行時，notify_admin()會被調用，並將捕捉到的異常資訊傳遞給它。

2024-09-28 14:21:33.986 | ERROR    | __main__::11 - An error has been caught in function '', process 'MainProcess' (10861), thread 'MainThread' (137755256123392):
Traceback (most recent call last):

> File "/content/main.py", line 11, in 
    main()
    └ 

  File "/content/main.py", line 9, in main
    10 / 0  # 故意引發錯誤

ZeroDivisionError: division by zero
系統出錯：division by zero
啟動緊急應變流程、收集故障排除數據、發送郵件...

捕捉特定異常

logger.catch() 默認會捕捉所有類型的異常，但也可以根據需求選擇性地捕捉特定類型的異常，例如指定只捕捉Exception類型的異常，這涵蓋了大多數標準的異常類型:

from loguru import logger

@logger.catch(Exception)
def divide(a, b):
    return a / b

divide(10, 0)

也可以捕捉某些特定的異常類型，例如ZeroDivisionError:

@logger.catch(ZeroDivisionError)
def divide(a, b):
    return a / b

結論

Loguru是一個簡潔且功能豐富的日誌工具，能有效提升開發過程中的錯誤排查和性能優化。與標準的Python logging相比，Loguru 更加直觀易用，無需繁瑣的配置，即可輕鬆上手。此外，它提供了靈活的自訂格式、自動檔案輪替、壓縮和日誌保留等功能，這些特性對於需要長期運行且對日誌管理要求高的應用尤其有用。

Loguru的logger.catch()進一步簡化了錯誤處理流程免於手動編寫大量 try-except，允許開發者方便地捕捉異常並記錄詳細的堆疊信息，從而提升日誌的可讀性和應用的可維護性，大幅提升了錯誤排查的效率。。

unRAID Server Note 03

AugustusHsu — Sun, 20 Oct 2024 12:00:45 GMT

unRAID - Flexible & Powerful Home Server Plugins篇 (下)

在上一篇文章中，我們介紹了幾款必備的unRAID插件，提升了系統的性能和管理效率。接下來，讓我們繼續探索更多實用的工具，如Compose Manager、Disk Location、FolderView等，這些插件能進一步強化您的unRAID系統，讓日常管理變得更加輕鬆和高效。

Docker Compose Manager

Docker Compose Manager能讓使用者能夠方便地管理和運行基於Docker Compose的應用程式，可以配置docker-compose.yml和對應的.env檔。這個Plugin提供了圖形化的管理界面，可以輕鬆查看、運行和停止Docker Compose定義的應用程式，除此之外，也支持自動重啟和更新應用程式，確保您的多容器應用始終處於最佳狀態，還可以通過該Plugin直接查看每個Docker容器的運行日誌，方便快速診斷問題

安裝完後可以在「SETTINGS」>「Compose」中設定:

在「SETTINGS」>「Compose Manager」可以開始配置docker-compose.yml，如果有開Show Compose in Header Menu可以直接點選上方的「COMPOSE」進到配置畫面:

點選「ADD NEW STACK」可以開始創建Docker Compose:

創建完後可以點左邊的齒輪再點「EDIT STACK」開始配置所需的COMPOSE FILE和ENV FILE:

配置完點選「COMPOSE UP」會在「DOCKER」上看到啟動的container，後續可以靠FolderView來將這些container整合起來:

FolderView

FolderView供了一些針對Docker Container視覺化管理的實用功能，可以將多個 Docker 容器摺疊成一個圖示，讓unRAID的Docker管理界面更加簡潔避免界面變得過於雜亂，特別適合有大量容器運行的場景。

在「DOCKER」>「ADD FOLDER」往下滑就可以開始設定要整合起來的container:

還提供了自訂Docker容器Logo的功能，輸入Icon的網址，即可為摺疊資料夾設定個性化的圖示，有助於快速識別各個容器，讓界面變得更加美觀和專業:

折疊後可以讓頁面更簡潔:

摺疊後的圖示可以展開，顯示所有運行中的容器和其詳細狀態，使用者只需點擊即可檢視:

Disk Location

Disk Location目的是幫助用戶更好地管理物理硬碟的位置信息，對於使用多顆硬碟的伺服器，用戶可能會遇到困難，尤其在需要識別、替換或維護硬碟時，難以迅速判斷哪一顆硬碟位於哪個實體槽位。Disk Location提供了一個直觀的圖形化界面，能輕鬆記錄和追蹤硬碟的物理位置，從而提高系統管理效率。

從「PLUGINS」>「Disk Location」可以進到管理的頁面，其中點選「System」可以開始掃描硬碟，如果是第一次按鈕應該只會有「FORCE SCAN ALL」:

掃描後可以進到「Configuration」調整設定:

在「Configuration」最下方點選「+」的圖示可以新增「Disk Tray Layout」的格式，這個格式取決於存放硬碟的形式，我所使用的是8格硬碟櫃設定如下:

創建完Group可以進到「Tray Allocations」設定要加入前面Layout的硬碟:

如果硬碟所在的硬碟櫃有燈號的顯示，可以點選「LOCATE」找到選取的硬碟具體在硬碟櫃所處的位置，Group可以選取前面所創建的Layout，TrayID則是設定所選硬碟所在的位置，設定完成點選「SAVE」即可:

前面的設定完成後即可在「DASHBOARD」上看到多了「Disk Location」的欄位，當硬碟出問題可以快速的定位到硬碟所在的位置進行替換:

以上是粗略的使用Disk Location的方法，如果了解設定裡的選項還可以做更細緻的調整。

Dynamix System Temperature

Dynamix System Temperature用於監控伺服器的硬體溫度，特別是 CPU 和主機板的溫度，安裝完後可以從「SETTINGS」>「System Temp」進入到設定畫面，選擇要監控的溫度即可:

設定完後可以在「DASHBORAD」的MOTHERBOARD和PROCESSOR中看到監控的溫度:

Recycle Bin

unRAID的Recycle Bin插件為您的網絡共享提供了一個回收站功能。當您在共享文件夾中刪除文件時，這些文件不會立即從系統中永久刪除，而是被移動到回收站中。這樣就可以在需要時輕鬆恢復誤刪的文件，增強數據的安全性和可靠性。

通過unRAID的網頁管理界面，可以設定哪些共享文件夾啟用回收站功能，並設置自動清理規則，如在回收站中保留文件的天數，也可以查看、恢復或永久刪除回收站中的文件。

可以在「SETTINGS」>「Recycle Bin」中查看:

當在指定的共享文件夾中刪除文件時，文件將被移動到回收站，如下:

要注意的是回收站中的文件仍佔用磁盤空間，請定期清理或設定自動清理策略，刪除的敏感文件可能仍存在於回收站中，對重要的共享文件夾建議設置訪問權限。除此之外在大量文件操作的環境下，回收站功能可能對系統性能有輕微影響，可根據需求調整設置。

Intel GPU TOP

Intel GPU TOP專為支持 Intel 集成顯示卡的系統設計，可以解鎖Intel GPU的硬件加速能力，讓unRAID用戶能夠充分利用Intel GPU來加速各種多媒體任務，例如視頻轉碼、轉碼解碼、圖像處理等。

安裝完後可以在Docker中新增Device變數，讓Container可以使用Intel GPU的硬件加速能力:

Unassigned Devices

Unassigned Devices可以讓用戶在unRAID伺服器中掛載和管理未被unRAID陣列或快取池使用的硬碟或存儲設備，可以靈活地處理外部硬碟、USB驅動器或網絡存儲裝置，並且不需要將這些設備納入unRAID的陣列中，這款插件對於需要臨時或外部存儲的使用情境特別實用。

安裝完後如果有未加入陣列中的硬碟，會在「MAIN」中看到Unassigned Devices的欄位:

如果Docker或是VM會需要使用到這些硬碟，可以將這些硬碟直通到使用場景中。

unbalanced

Unbalance專為重新分佈和整理存儲數據而設計。它的主要功能是幫助用戶將數據從一顆或多顆硬碟上移動到其他硬碟上，以平衡存儲空間的使用。

可以在「SETTINGS」>「unbalanced」中啟用該功能:

點開「Open Web UI」可以看到提供兩種主要操作模式SCATTER、GATHER:

SCATTER 的作用是將指定磁碟上的文件分散到其他未滿的磁碟上。這個模式非常有用，當某個磁碟接近存滿時，你可以使用 SCATTER 把文件移到其他空間較多的磁碟，從而為該磁碟釋放出空間。
GATHER 的作用則相反，它是將分佈在多個磁碟上的文件集中到指定的一個磁碟上。當用戶希望整理數據，或者把某個資料夾下的文件都放到同一個磁碟時，GATHER 模式非常有用。

這些操作不會改變文件的目錄結構，只是改變它們的存儲位置，幫助用戶更好地管理他們的存儲資源。

unRAID Server Note 02

AugustusHsu — Sun, 13 Oct 2024 12:00:09 GMT

unRAID - Flexible & Powerful Home Server Plugins篇 (上)

unRAID擁有豐富的插件生態，以下是我認為必備的插件，它們大大提升了系統的功能和使用體驗。

Community Applications

在 6.10.x 及以上版本中要安裝 CA，可以前往 unRAID介面中已存在的「APPS」標籤，系統會提示您自動安裝。

對於較舊版本的 unRAID，請將以下 URL 貼入「PLUGINS」 > 「Install Plugin」中:

https://raw.githubusercontent.com/Squidly271/community.applications/master/plugins/community.applications.plg

關於Community Applications的說明可以在官方的論壇中看到。

Language

語言的部分需要在「APPS」中安裝相關的語言包 (APP功能的啟用在下方有介紹)，安裝後可以在上方的「Actions」中選擇切換該語言:

也可以在右上方的這個圖示中選擇切換 (目前測試時發現需要先透過上方的方式切換一次語言後才能透過這個圖示切換) :

Nerd Tools

在日常使用unRAID的過程中，您可能會需要一些命令列工具來完成特定的任務。然而，unRAID系統本身並不預裝這些工具，這給用戶帶來了一定的不便。

缺乏套件管理器: unRAID基於 Slackware Linux，但它不提供像 apt（Debian/Ubuntu）或 yum（CentOS/Fedora）這樣的套件管理工具。這使得安裝軟體變得相對麻煩。
軟體兼容性問題: 大多數軟體不會提供針對 Slackware 的編譯版本，導致直接安裝預編譯套件變得困難。
自行編譯的複雜性: 如果選擇自行編譯軟體，您需要建立完整的編譯環境，這不僅複雜，而且容易出現錯誤。
耗時費力: 每次需要安裝新的軟體，都需要手動編譯，這非常耗時且效率低下。

為了解決這些問題，Nerd Tools Plugin為 unRAID用戶提供了一個便利的解決方案:

集合常用工具: Nerd Tools 包含了許多常用的命令列工具，您可以根據需要選擇性地安裝。
簡化安裝流程: 通過圖形化介面，您可以輕鬆地在 unRAID上安裝所需的工具，而無需手動編譯。
提高效率: 減少了建立編譯環境和手動編譯的時間，使您能更專注於實際任務。

從「SETTINGS」>「NerdTools」可以進到管理套件的介面，搜尋要安裝的套件點選左邊的按鈕再點下APPLY就可以安裝了:

這邊推薦幾個可以安裝的套件:

vim: 功能強大的文字編輯器，適合編輯配置文件和編寫腳本。
iotop: 實時顯示磁盤 I/O 使用情況，可以找出佔用大量磁盤讀寫的進程。
ncdu: 磁盤使用分析工具，幫助您查看哪些文件或目錄佔用了最多空間。
iftop: 網絡流量監控工具，實時顯示當前網絡連接和流量使用情況。

解除安裝也很簡單，點選要解除安裝的工具將其變成OFF再點選APPLY就可以了，有看到其他習慣或常用的工具可以自行下載。

Appdata Backup

💡

Appdata Backup 只支援≥6.12的系統版本，如果你的系統版本<6.12，那麼插件將會是另一個版本，名稱叫做Appdata Backup v2.5。

備份

這個網站上有詳細的介紹，以下是我的設定，設定刪除超過120天的輩分，至少存3份設定檔、超過就刪除最早的那份，設定要備份的位置 (appdata的位置)、備份到哪個資料夾、是否壓縮 (使用zstdmt壓縮方法)，同時備份flash跟VM的資料:

這裡的設定為是否跳過關閉的containers、是否驗證備份、忽略備份時發生的錯誤:

這邊設定的是通知和備份的時機點，設定為只通知錯誤訊息、每個月第二天半夜3點30分開始備份，主要是為了錯開檢查奇偶校驗的時間點:

是否在備份完後更新container:

接下來的設定為是否需要跳過個別的container、是否需要儲存appdata資料夾以外的資料夾、是否在不停止Docker 的情況下進行備份，一般保持預設值即可:

剩餘的設定我這邊為空:

還原

還原方式很簡單，選擇Restore標籤頁、再選擇備份的來源，點選NEXT，就可以選擇備份的版本:

後續先這邊參考這邊的處理，有機會再補上。

Fix Common Problems

Fix Common Problems是unRAID系統上一款必備的診斷和故障排除插件，主要功能是幫助用戶自動檢測和解決系統中可能存在的各種常見問題，包括配置錯誤、插件衝突、硬體故障等。通過定期運行，可以確保unRAID系統始終處於最佳狀態，避免潛在的故障和數據損失。

他可以定期或按需掃描系統，檢查系統設置、插件、Docker 容器和 VM 的潛在問題，同時提供問題的詳細描述和可能的影響，為每個問題提供具體的解決建議和指導。它擁有直觀的用戶界面，方便新手和高級用戶使用，一鍵就可以運行掃描，快速獲取結果。一旦發現問題可以通過unRAID的通知系統提醒用戶需要關注的問題

安裝完成後可以在「Plugins」找到"Fix Common Problems"，點擊「Run Scan」按鈕，就可以開始系統掃描。掃描完成後，插件會列出所有發現的問題，每個問題都包含詳細的描述和建議的解決方案，根據插件的建議，採取相應的措施來修復問題。

常見檢測項目有以下幾種：

配置錯誤：檢查不合理的系統設置，如不正確的網絡配置、共享設置等。
插件問題：檢測過時、衝突或已知有問題的插件。
Docker 容器：識別有潛在問題的 Docker 映像或配置錯誤。
硬體故障：檢查磁盤錯誤、溫度過高等硬體相關問題。
安全風險：提示潛在的安全漏洞，如弱密碼、未受保護的共享等

Fix Common Problems 插件是維護unRAID系統穩定性和可靠性的強大工具。通過自動檢測和提示潛在問題，您可以主動解決可能影響系統性能和安全性的隱患。無論您是新手還是有經驗的用戶，安裝和使用 FCP 都能讓您的unRAID系統運行得更加順暢和安全。

CA Auto Turbo Write Mode

CA Auto Turbo Write Mode 是unRAID中一款能夠自動管理寫入模式的插件，旨在根據系統負載自動切換unRAID的寫入模式，實現性能與能源效率之間的平衡。

在unRAID中，有兩種主要的寫入模式：

默認模式（Read/Modify/Write）： 寫入數據時僅需要啟動相關的數據盤和校驗盤，這種模式功耗較低，但寫入速度相對較慢。
Turbo Write 模式（Reconstruct Write）： 寫入數據時會啟動所有數據盤和校驗盤，通過重建數據來提高寫入速度，但功耗和硬盤磨損較大。

CA Auto Turbo Write Mode 的主要功能：

自動切換寫入模式：根據磁盤活動量，動態在默認模式和 Turbo Write 模式間切換，當系統有大量寫入操作時自動啟用 Turbo Write，以提升性能，當寫入操作較少時回到默認模式以節省能源。
提升寫入速度：適合大數據傳輸的場景，顯著提升寫入效率，並在不需要高效能時自動降低資源消耗。

CA Auto Update Applications

CA Auto Update Applications是unRAID的一款插件，用於自動更新系統中的 Docker 容器、插件和應用程式。這款工具大大簡化了unRAID系統的維護工作，確保您的應用始終處於最新狀態，從而提高系統的穩定性和安全性。

CA Auto Update Applications 的主要功能：

自動更新：自動檢查並更新系統中的 Docker 容器、插件和應用程式，無需手動操作，節省時間和精力。
自定義更新頻率：用戶可以設置更新檢查的頻率（如每天、每週），並根據需要自動執行更新過程。
靈活的應用管理：用戶可以選擇哪些應用程式或插件需要自動更新，哪些則不需要，這樣可以靈活控制系統更新。
通知功能：當更新完成時，系統會通過通知（電子郵件或其他推送方式）告知用戶，確保對系統變更保持追蹤。
更新日誌：該插件還會記錄更新日誌，方便用戶隨時查看更新過程和結果。

CA Auto Update Applications是一個非常方便的工具，讓unRAID使用者輕鬆管理和更新系統中的Docker容器和插件，保持系統始終處於最佳狀態。對於希望簡化維護流程並確保系統安全和穩定的用戶來說，這是不可或缺的插件。

結論

在這篇文章中，介紹了幾個必備的unRAID插件，這些工具無疑大大增強了系統的功能和便利性，無論是針對日常使用的命令列工具、系統的自動化維護，還是提升性能的優化，都能讓您的unRAID系統更加高效和穩定。無論是剛入門的新手，還是已經在unRAID上有豐富經驗的用戶，這些插件都將讓使用體驗大為提升。

當然unRAID的插件生態系統遠不止於此，後續還會深入探討更多實用的插件、更好地利用unRAID的強大功能，敬請期待下一篇的詳細介紹。

unRAID Server Note 01

AugustusHsu — Sun, 06 Oct 2024 12:00:14 GMT

unRAID - Flexible & Powerful Home Server 設定篇

unRAID是一款專為家庭和小型辦公室設計的NAS作業系統，它基於Linux核心，提供了一個靈活且易於擴充的儲存解決方案。與傳統的RAID系統不同，unRAID允許你使用不同容量和品牌的硬碟，組成一個彈性的儲存池，並通過奇偶校驗（Parity）機制提供數據保護，這對於家中有多顆不同硬碟的使用者特別友善。

除了強大的儲存功能，unRAID還支援虛擬化和Docker容器，這意味著你可以在同一台機器上運行多個虛擬機或應用程式，滿足各種需求。無論是搭建媒體伺服器、開發環境，還是其他服務，都能輕鬆實現。

本文主要在記錄unRAID上安裝了什麼實用的工具和加上了哪些設定，這些都是我在使用過程中覺得非常有幫助的，在初次安裝unRAID後，有一些重要的設定，可以提升系統的功能、穩定性和安全性。

網路與安全設定

為了方便管理和連接，可以為unRAID伺服器設定了一個固定的IP地址，避免每次重新啟動路由器或伺服器時，IP地址改變帶來的不便。可以在unRAID的「SETTINGS」>「Network Settings」中，將IP地址從自動取得改為手動設定。

建立使用者帳戶與權限

unRAID允許建立多個使用者帳戶，並為不同的共享資料夾設定讀寫權限。可以為家人和朋友建立各自的帳戶，確保私人資料的安全性，同時方便共享公共資源，可以在「USERS」>「ADD USER」中新增使用者。

配置通知設定

可以在「SETTINGS」>「Notification Settings」中設定電子郵件或手機APP通知，當系統發生錯誤、硬碟故障或需要注意的事件時，會即時收到提醒，其中可以設定SMTP發送郵件的通知訊息:

也可以綁定Discord、Slack、Telegram等等的APP來通知:

設定Parity硬碟

為了保護資料安全，可以添加了Parity硬碟，每增加一顆Parity硬碟，可以預防一顆資料硬碟故障資料也不會遺失。要注意的是Parity硬碟容量要大於等於其他的資料硬碟，以覆蓋陣列中所有硬碟的容量。

配置Cache快取盤

使用了一顆SSD作為Cache快取盤，可以加速資料的讀寫速度，這對於頻繁存取和小檔案的操作特別有效，可以在「MAIN」的「Devices」部分添加Cache盤:

並在「SHARES」的設定中「Primary storage」啟用Cache功能，啟動會優先將檔案存在Cache的硬碟中:

Primary storage (主儲存空間): 顧名思義，是建立新檔案和新資料夾時所使用的儲存池。主儲存空間只有兩種類型的選擇— Array和Cache：

Secondary storage (輔助儲存): 只有在主儲存空間選擇了快取池之後，輔助儲存才可能進行配置，並且只有兩個固定選項－None/ Array。

如果你在主儲存空間選擇了Array，那麼也就等於不去使用Cache (此時Secondary storage不可設定，Array為灰色無法選擇) :

Mover可以指定要從Array > Cache 或是Cache > Array :

在「SETTINGS」>「Scheduler」可以設定將資料從Cache轉移到資料硬碟的定期執行時間:

設定時區

在「SETTINGS」>「Date and Time」設定自己的時區:

Parity Check

在「SETTINGS」>「Scheduler」中設定定期奇偶校驗的時間，我是習慣在每個月的第一天半夜3點30分開始奇偶校驗:

開啟Log

在管理和維護unRAID伺服器的過程中，Syslog是非常重要的工具。它可以幫助您監控系統運行情況、診斷問題以及追蹤異常事件。通過啟用Syslog Server，您可以將系統日誌集中保存，方便日後查看和分析。

在「SETTINGS」>「Syslog Server」中可以開啟Syslog的設定，其他設定方面可以參照下圖，要注意的是Remote syslog server要設定為本機的ip:

結論

通過這些設定，unRAID不僅可以作為強大的 NAS 伺服器，還能成為一個靈活的家庭伺服器平台，滿足多樣化的需求。從網路設定、使用者權限管理到重要的 Parity 硬碟與 Cache 快取盤配置，這些步驟不僅提升了系統的性能和效率，也增強了資料的保護性和管理便利性。此外，通過啟用 Syslog 伺服器和設置通知功能，您可以隨時掌握系統運行狀況並迅速處理潛在問題。這些設定將使unRAID成為一個穩定、高效且可靠的家庭伺服器平台，不僅讓您更安心，也能讓家人和朋友輕鬆共享資源與服務。

無論是初次安裝unRAID，還是進行後續優化，這些實用的工具和設定都將顯著提升系統的整體使用體驗。如果你想要一個簡單易用、功能強大的家用伺服器平台，unRAID 絕對是不錯的選擇！

Python Note 04

AugustusHsu — Sun, 29 Sep 2024 12:00:55 GMT

Python的Debug神器

在日常除錯過程中，我們經常會使用 print()函數查看變數內容，以確認程式執行的結果是否如預期。然而，這樣做往往需要花費大量時間去逐一檢查輸出的正確性。在 Python 中，有一個內建函數叫做 breakpoint()，專門用於啟動偵錯器。當執行到 breakpoint() 時，程序會暫停，並進入一個互動式的調試環境。透過這個功能，你可以查看變數的值、逐步執行程式碼，以及有效地進行問題調試。

`breakpoint()`的主要功能：

暫停程序執行：當程式執行到breakpoint()時，程式會暫停，進入偵錯器。
進入互動式調試環境：你可以查看目前的變數、執行下一步操作、檢查堆疊幀等。
調試程式碼：你可以使用偵錯器的命令（例如n進入下一步、c繼續運行、q退出調試器等）來逐步執行程式碼，幫助你發現問題。

breakpoint()在Python 3.7 版本中被引入，它會調用sys.breakpointhook()，通常會啟動預設的Python 偵錯器pdb。

常見調試器命令：

n (next)：執行下一行程式碼。
s (step)：執行下一行程式碼，如果該行為函數呼叫則進入函數，停在函數第一行。
w (where)：列出從當前執行點到最外層調用的一系列函數調用和行號。
c (continue)：繼續執行直到遇到下一個斷點或程式結束。
q (quit)：退出偵錯器並結束程式。
p (print)：列印變數的值，例如p some_variable。
l (list)：印出目前所在 function/frame上下 10 行的程式碼。
ll (long list)：印出目前所在 function/frame 的所有程式碼。
r (return)：繼續執行到當前函數返回為止。

使用`breakpoint()`的範例：

運行範例：

def calculate_area(length, width):
    area = length * width
    breakpoint()
    return area

length = 5
width = 10
area = calculate_area(length, width)
print(f"The area is {area}")

當程式碼執行到breakpoint()時，會進入偵錯模式，你可以使用偵錯器指令來查看變數的值或逐步執行程式碼。

輸出(在進入調試模式後)：

> (5)calculate_area()
-> return area
(Pdb) p length
5
(Pdb) p width
10
(Pdb) p area
50
(Pdb) n
(Pdb) w
/media/lukaslu/2E7C3ACF7C3A9217/user_data/Jim/code/MongoDB_MinIO_FastAPI/test.py(8)()
-> area = calculate_area(length, width)
> /media/lukaslu/2E7C3ACF7C3A9217/user_data/Jim/code/MongoDB_MinIO_FastAPI/test.py(4)calculate_area()
-> return area

在這個範例中，程式會在breakpoint()處暫停，你可以使用p指令查看變數length、width和area的值；使用n逐步執行程式碼；使用w可以查看從程式入口到當前中斷點的完整調用棧，箭頭 -> 指向當前正在執行的行。

小技巧

使用 breakpoint() 的一些小技巧可以讓你的 Python 調試過程更加高效和便利。以下是一些實用的建議：

條件斷點

你可以在 breakpoint() 函數中添加條件，只有當條件為真時，才會觸發斷點。這在處理循環或條件語句中特別有用。

for i in range(100):
    if i == 50:
        breakpoint()  # 只在 i 等於 50 時暫停

動態設置和移除斷點

通過編程方式設置和移除斷點，可以根據運行時數據或條件動態地改變調試策略。

if some_condition:
    breakpoint()  # 動態設置斷點

整合日誌

使用 breakpoint() 時，考慮在進入調試器前後添加日誌語句，這樣可以在不進入調試器的情況下追蹤程式的運行狀態。

logging.debug('About to hit breakpoint')
breakpoint()
logging.debug('Resuming from breakpoint')

自定義 `sys.breakpointhook`

你可以自定義 breakpoint() 的行為，通過設置 sys.breakpointhook。這允許你在觸發斷點時執行自定義代碼或調用其他調試器，如 ipdb，提供了 pdb 的所有功能，同時增加了語法高亮、Tab 補全和更詳細的調用棧資訊，使得調試過程更直觀和用戶友好。提

import sys

def my_debugger():
    import ipdb
    print("Custom debugging session starts.")
    ipdb.set_trace()

sys.breakpointhook = my_debugger

# Somewhere in your code
breakpoint()  # This will trigger `my_debugger` instead of the default pdb.

進行性能分析

在性能關鍵部分的代碼中使用breakpoint()，檢查特定操作前後的系統狀態或變數，使用如 memory_profiler 或 time 模塊來檢測記憶體使用或時間消耗，有助於識別效能瓶頸。

from memory_profiler import memory_usage
import time
import pdb

def perform_heavy_operations():
    # 假設這是一個記憶體和處理時間密集型操作
    sum = 0
    for i in range(10000000):
        sum += i
    return sum

# 檢測記憶體和時間使用
initial_memory = memory_usage()
start_time = time.time()

# 執行密集型操作
result = perform_heavy_operations()

# 斷點設置
breakpoint()  # 在此處觸發斷點以檢視當前狀態

final_memory = memory_usage()
end_time = time.time()

# 計算使用的記憶體和時間
memory_used = final_memory[0] - initial_memory[0]  # 單位為 MiB
time_taken = end_time - start_time  # 單位為秒

print(f"Result of operations: {result}")
print(f"Memory used: {memory_used} MiB")
print(f"Time taken: {time_taken} seconds")

總結

`breakpoint()` 的基本功能：

暫停程序執行：在指定的代碼點暫停執行，進入偵錯模式。
互動式調試環境：允許查看變數、逐步執行程式碼、檢查調用棧等。
簡化調試過程：提供一個直觀的方式來逐步通過程式碼，找出錯誤的來源。

`breakpoint()` 使用技巧：

條件斷點：在符合特定條件時才觸發斷點，適用於循環或條件語句中。
動態斷點：根據運行時數據或條件動態設置斷點，以靈活調整調試策略。
整合日誌：在進入和離開調試器時記錄日誌，方便追蹤程式運行狀態。
自定義 sys.breakpointhook：自定義斷點行為，可整合其他工具或執行特定調試代碼。

使用 `breakpoint()` 進行性能分析：

檢測記憶體和時間使用：使用 memory_profiler 和 time 模塊在斷點前後測量記憶體和執行時間，以識別效能瓶頸。
分析操作效果：透過斷點檢視特定操作對系統資源的影響，並評估優化策略。

這些總結點幫助你更有效地利用 breakpoint() 來進行錯誤排查和性能分析，提升開發效率和程式的運行效能。

VS Code Note 01

AugustusHsu — Wed, 27 Mar 2024 12:00:00 GMT

VS Code套件安裝記錄

VS Code對於開發者來說是一件非常好用的IDE，可以根據不同的開發環境安裝各種擴充套件，自己本身是寫深度學習的專案，不過這裡介紹的套件應該也可以套用到多數開發環境，具體的可能需要自行測試才會知道合不合適，目前安裝的套件有以下這幾種:

Git相關的VS Code套件
輔助開發的VS Code套件
Python相關的VS Code套件
- Python
- Pylance
- Python Indent
- Python Environment Manager

Git相關的VS Code套件

軟體開發的流程總是離不開版本控制，VS Code的套件已經將版本控制的一些功能非常好的整合到IDE上面，一些常用功能也有視覺化的套件可以使用。

GitLab Workflow

VS Code剛安裝完本身就可以Clone Github上面的Repository，如果是要用Clone GitLab上的project就需要這個套件來幫忙連線到GitLab上，使用方法也很簡單，安裝VSCode上的GitLab Workflow套件後，如果是自架的GitLab伺服器，需要創建access token接著點選Add Account將token輸入:

新增完token後點選複製存放庫，可以看到多了一個GitLab選項，點選後就能Clone該帳號下的專案了:

GitLens

在開發專案時總是會遇到一些想要飆罵髒話狀況，譬如:

啊?程式怎麼掛在這個地方?XXX!這行XX誰寫的!

這時候就可以使用git blame來找出導致發生這種事的兇手，而GitLens就是可以在每一行程式碼後面加上git blame的訊息:

除此之外還可以針對這個檔案或是行去查過往的commit紀錄:

在右上角的按鈕還可以比對前一次commit的差異:

點選後就像下面這張圖片，基本上就是git diff畫面，比起命令列友善許多:

在下面還可以看到最近一次commit的時間和commit的內容，可以快速掌握上次commit做了什麼:

Git Graph

Git Graph算是我在git相關套件中最喜歡的套件之一了，當多人協作時，每個人都會開一個branch，透過Git Graph可以查看各個branch、和各個commit、merge的狀況，除此之外還可以做一些基本操作，比如分支合併、rebase、tag、stash 等等:

git-commit-lint-vscode

用來規定git commit標題在指定的類型清單中選擇，可以對該類型的說明添加自訂的敘述，還可以對不同的類型設定指定的Emoji:

"gitCommitLintVscode.customType": [
    {
        "emoji": "🎉",
        "type": "init",
        "name": "初始化",
        "description": "初次提交/初始化專案"
    },
    {
        "emoji": "✨",
        "type": "feat",
        "name": "功能",
        "description": "新增/修改功能 (feature)"
    },
    {
        "emoji": "🐛",
        "type": "fix",
        "name": "修復bug",
        "description": "修復bug (bug fix)"
    },
    {
        "emoji": "📝",
        "type": "docs",
        "name": "文檔",
        "description": "添加/更新文檔，完善專案說明 (documentation)"
    },
    {
        "emoji": "💄",
        "type": "style",
        "name": "代碼風格、格式",
        "description": "程式碼風格變更，例如格式調整，不影響程式碼運行"
    },
    {
        "emoji": "♻️",
        "type": "refactor",
        "name": "程式碼重構",
        "description": "不影響既有的功能前提下，改進程式碼的結構、可讀性和維護性"
    },
    {
        "emoji": "👌",
        "type": "perf",
        "name": "優化",
        "description": "增進效能、修復效能問題、新增效能優化 (增加快取)"
    },
    {
        "emoji": "✅",
        "type": "test",
        "name": "測試",
        "description": "涉及測試方面的更改，如新增/修改測試案例"
    },
    {
        "emoji": "🛠️",
        "type": "chore",
        "name": "維護性的工作",
        "description": "建置流程或輔助工具/套件的變動 (保持程式碼的健康和可讀性，不直接影響代碼的功能)"
    },
    {
        "emoji": "↩️",
        "type": "revert",
        "name": "撤銷",
        "description": "撤銷回復先前的commit (標記撤銷操作，讓團隊成員更容易了解變更的背景和原因)"
    },
    {
        "emoji": "➖",
        "type": "",
        "name": "",
        "description": "─────────────────────────以上為常用的type─────────────────────────"
    },
    {
        "emoji": "🥚",
        "type": "format",
        "name": "格式化代码",
        "description": "格式化"
    },
    {
        "emoji": "🚑",
        "type": "patch",
        "name": "添加重要补丁",
        "description": "补丁"
    },
    {
        "emoji": "📦",
        "type": "file",
        "name": "添加新文件",
        "description": "新文件"
    },
    {
        "emoji": "🚀",
        "type": "publish",
        "name": "发布新版本",
        "description": "新版本"
    },
    {
        "emoji": "📌",
        "type": "tag",
        "name": "发布版本/添加标签",
        "description": "书签"
    },
    {
        "emoji": "🔧",
        "type": "config",
        "name": "修改配置文件",
        "description": "配置"
    },
    {
        "emoji": "🙈",
        "type": "git",
        "name": "添加或修改.gitignore文件",
        "description": "不可见"
    }
]

輔助開發的VS Code套件

VS Code套件除了有強而有力的git相關套件以外，還有一些套件可以幫助自己管理開發的專案。

Settings Sync

每個人安裝的套件、VSCode的設定還有setting.json的內容都是根據個人的使用狀況而製作的，當換了一台電腦，總不能一一把舊電腦上的套件裝到新電腦上，所以這時候就要有同步的工具來儲存紀錄舊電腦安裝過的套件、使用的設定，還原到新電腦上。

套件本身已不再更新，現在使用內建的Settings Sync功能即可，使用方法也很簡單，點選左下角的齒輪後選擇開啟設定同步，再跟Github做連結即可。

詳細的操作可以直接查看VS Code的官方說明文檔。

Project Manager

當同時要開發好幾個專案時，使用VS Code會需要開好幾個視窗，切換視窗時總是會分不清哪個視窗是哪個專案的，可以透過這個套件直接在一個視窗中切換不同專案，使用方法也很簡單，開啟要開發的專案然後點選Save Project，接著命名專案名稱就可以顯示在左邊的清單中了:

要新增其他的專案也是一樣，開啟其他專案後點選清單旁邊被紅框圈選起來的圖示新增到左邊，需要切換的話點一下就可以切換不同的專案:

Metarial Icon Theme

這個套件功能很簡單，基本上就是替換在VS Code中出現的Icon，具體替換的圖示可以參考套件上的說明:

如果不喜歡這個套件更換的圖示，可以試試看file-icons，這個套件的圖示整體亮度會比上一個稍低，也是一個不錯的選擇:

TODO Tree

在寫程式時總有些時候會突然有新的想法，感覺可以在某段程式碼中加上一些功能、或是優化這段程式碼，通常會寫一些註解在想修改的程式附近，但是當正在開發的部分告一段落後，突然發現想不起來想要加上的功能或是優化的方法在哪；也有些時候有段程式碼出現了bug，為了要debug而新增某段程式，當修復好bug後忘記修改的地方在哪，導致產生了新的bug。

而這個套件對於開發來說很方便，可以管理在專案中一些臨時新增的測試程式碼或是想在要新增的功能說明，如下可以在某段程式碼上增加註解，並統一管理:

Todo Tree設定排除的資料夾可以在設定裡面搜尋Todo-tree › Filtering: Exclude Globs，將要排除的資料夾填入:

可以設定自己Todo Tree的註解樣式，icon的部分可以去這個網站上查，下面是我的設定檔:

"todo-tree.general.tags": [
    "TODO",
    "TEST",
    "BUG",
    "FIXME",
    "FIX",
    "HACK",
    "NOTE",
    "TAG",
    "DONE"
],
"todo-tree.highlights.customHighlight": {
    "TODO": {
        "icon": "checklist",
        "foreground": "#000000",
        "background": "#ffffff",
        "iconColour": "#ffffff",
        "rulerColour": "#ffffff",
        "gutterIcon": true
    },
    "BUG": {
        "icon": "bug",
        "background": "#d10000",
        "foreground": "#ffffff",
        "iconColour": "#d10000",
        "rulerColour": "#d10000",
        "gutterIcon": true
    },
    "FIXME": {
        "icon": "flame",
        "background": "#a32cc4",
        "foreground": "#ffffff",
        "iconColour": "#a32cc4",
        "rulerColour": "#a32cc4",
        "gutterIcon": true
    },
    "TEST": {
        "icon": "beaker",
        "background": "#FF4500",
        "foreground": "#ffffff",
        "iconColour": "#FF4500",
        "rulerColour": "#FF4500",
        "gutterIcon": true
    },
    "TAG": {
        "icon": "tag",
        "background": "#0000ff",
        "foreground": "#ffffff",
        "iconColour": "#0000ff",
        "rulerColour": "#0000ff",
        "gutterIcon": true
    },
    "NOTE": {
        "icon": "bookmark",
        "background": "#00ff00",
        "foreground": "#ffffff",
        "iconColour": "#00ff00",
        "rulerColour": "#00ff00",
        "gutterIcon": true
    },
    "DONE": {
        "icon": "verified",
        "background": "#000000",
        "foreground": "#ffffff",
        "iconColour": "#000000",
        "rulerColour": "#000000",
        "gutterIcon": true
    },
    "HACK": {
        "icon": "rocket",
        "background": "#08deea",
        "foreground": "#ffffff",
        "iconColour": "#08deea",
        "rulerColour": "#08deea",
        "gutterIcon": true
    }
},
"todo-tree.general.tagGroups": {
    "FIXME": [
        "FIXME",
        "FIX"
    ]
},
"todo-tree.highlights.defaultHighlight": {
    "type": "tag",
    "rulerLane": "full"
},

自訂Highlight設定說明

icon: 圖示，可以從上面說的官方網站中查詢，但不是全部可以用
background: 背景顏色
foreground: 前景演色 (字體顏色)
iconColour: 圖示顏色
rulerColour: 右邊滾動條上顯示的顏色
rulerLane: 滾動條的顯示類型 (left, center, right, full, none)
gutterIcon: 在行數左邊是否顯示圖示
opacity: 背景的不透明度

autoDocstring

在程式中註解有多重要相信不需要過多的強調，這個套件可以自動的把所有函式的輸入輸出參數以指定的風格生成註解，自己習慣使用的google風格:

使用方式也很簡單，直接在函式下面輸入"""就行，以下圖片來自該套件的資料中:

Rainbow Fart

這個套件趣味性十足，它可以加速開發的速度，也可以讓你在寫程式的時候充滿信心，在你身心俱疲的時候還會為你提供幫助，具體的等你安裝過後就知道(嘿嘿嘿)。

Python相關的VS Code套件

Python、Pylance基本上是必裝的套件，這裡不多做介紹。

Python Indent

Python Indent的功能很簡單，就是對縮排進行優化，以下是官方的說明動畫:

Python Environment Manager

如果有使用coda或是venv來建構python環境的話這個套件還蠻實用的，可以查看目前有的環境，和環境內安裝的套件，不過我自己本身還是習慣透過命令列管理環境，畢竟環境這東西使用的頻率不會太高，而且目前也蠻多專案是使用docker來建構環境的，所以目前是沒有使用這個套件。

MongoDB Note 01

AugustusHsu — Sun, 05 Nov 2023 12:00:07 GMT

基礎概念簡介

前言

傳統的資料庫使用的是關聯式資料庫管理系統(Relational Database Management System/RDBMS)，需要在關聯式資料庫中事先定義好Schema(綱要)；也就是每張Table(資料表)中包含哪一些Column(欄位)，並且要確保後續新增儲存的Row(資料)都要遵循schema的定義。

這邊舉個例子，如果想要在RDBMS中記錄會員的資訊，如果最初定義Product 資料表的schema中有姓名、職業、身高、體重四個欄位，則該資料表中的每一筆資料都必須要有這四個欄位，結果資料表快建完了才發現忘記加上血型這個欄位，又或者希望幫其中一個會員紀錄上興趣，這種狀況在關聯式資料庫中，因為要遵守schema的定義，所以需要更動schema，在欄位上新增血型、興趣欄位，再來寫一個script幫現有所有的會員都加上興趣(若無可填上空值)。

比起上述的情況，對於MongoDB來說，因為它被設計為一種以document為主的database，所以可以直接將興趣欄位直接加入屬於這個會員的資料內即可。除了可以很容易的增加欄位外，MongoDB還能透過Sharding功能，輕易地水平擴展整體的資料庫大小。

💡

因為MongoDB不需要定義Schema (Schemaless)，可以直接新增，如此可以大幅縮短開發時間，適合用於資料格式常變動的應用中。

MongoDB的層級架構

MongoDB的層級從大到小分別是Database、Collection和Document，下面這張圖對應了MongoDB和傳統關聯式資料庫SQLDatabase的對應關係:

SQL	MongoDB	說明
Database	Database	資料庫
Table	Collection	資料表/集合
Row	Document	一筆數據紀錄/文檔
Column	Field	數據欄位/域
Index	Index	索引
Table Joins		合併資料表/MongoDB沒有Join
Primary Key	Primary Key	主鍵

Database

一個MongoDB伺服器中可以有多個獨立的Database，每一個都有自己的collection和權限，在實際上的應用中，不同服務或是應用的資料會放在不同的database中。

例如有一家公司同時有A和B服務，兩者的資料是不相通的，那就可以直接在MongoDB中建立兩個database，分別存放兩服務所需要儲存的資料。

資料庫的名字在MongoDB中有著一些限制:

不能是空字串
不可以含有' '(空格)、.(點)、$(錢字符)、/(斜線)、\(反斜線)和\0(空字符)
應全為小寫
最多64個字元

此外，有一些database的名稱是建立時就預設存在的，可以直接連結進行查看:

admin
MongoDB會將所有使用者的資訊儲存在這個database(名稱、密碼和使用者的驗證資料庫)，如果要建立個別database的使用者，在個別的database中建立即可，但如果要跨database使用，則需要在這個資料庫中建立，會自動繼承到其他database，關於管理使用者的方法會在額外發一篇介紹。
local
這個database永遠不會被複製，用來儲存這台機器的檔案和資訊，不會因為建立💡replica set(建立副本，預防MongoDB掛掉而導致服務掛掉)複製這個database的資料。
config
主要存放Sharding相關的資料，在3.6版本以後，會儲存standalone或是replication資料，也有跟transaction相關的資料，但是禁止去針對這個database進行修改或刪除，僅可以查看。
當MongoDB使用Sharding時，config database會在內部使用，用於保存sharding的相關資訊。

💡

Replica Set為近年多數資料庫所使用的架構，以Primary和Secondary來取代舊有的Master和Slave架構，具有自動故障恢復、讀寫控制等等優勢。

建立database的方法很簡單，直接使用use即可切換到指定的database，如果在MongoDB中沒有該database則會直接建立一個新的:

> show dbs
admin   0.000GB
config  0.000GB
local   0.000GB
> use testDataset
switched to db testDataset

Collection

Collection相當於關聯式資料庫的 Table的概念，主要差別在它存放的是document而非固定大小、格式的record，通常一個 databse 中會有數個 collection。

以database上的例子來說如果服務 A為一個銷售資料庫，可能會想要分別記錄「購買人資訊」、「製造商資訊」、「販售地點」...等等，因此可以在「產品 A 的 database」中分別開設對應的 collection。

同時因為MongoDB沒有固定的結構，所以還可以針對特定的資料設計不同的結構，但同時都是屬於同一個collection。

例如以「購買人資訊」為例，可以只針對特定的user增加興趣的欄位，而其他的user則完全不受影響:

{
    "name": 'Stank',
    "job": 'software engineer',
    "bloodType": 'A'
}
{
    "name": 'Augustus',
    "job": 'software engineer',
    "bloodType": 'O',
    "hobbies": ['sleeping', 'computer game', 'guitar'],
}

Document

Document就是一筆資料，概念好比關聯式資料庫的Row。通常一個collection中會有數筆document。也因此我們稱MongoDB是document database。

例如在「購買人資訊」的collection中，真正的一筆「購買人資訊」就是一個document。

以下是Document的例子，可以看到長的跟JSON一樣，由多組的key-value組成，不過在MongoDB中是使用field這個名稱:

{
    "name": "Augustus",               <----field:value
    "age": 26,                        <----field:value
    "status": "S",                    <----field:value
    "groups": ["MongoDB", "GitLab"]   <----field:value
}

MongoDB儲存格式 (BSON)

MongoDB每筆document都是像JSON格式的key-value組合，但實際上MongoDB在儲存資料的格式是BSON(Binary JSON，JSON二進位表示形式)，使用BSON的優點在於在空間上儲存較有效率，BSON支援的格式可以參考官網，這裡介紹一些比較特別的格式:

binData
儲存二進制的資料(binary data)。
timestamp & date
timestamp和date一樣是儲存時間的資料，但是date在跨時區的時候會有需要轉換時區的問題產生。
object
可以在這個欄位中插入document，可以想像成文件中的子文件，如下範例的livein欄位:

{
    "name": 'Augustus',
    "job": 'software engineer',
    "bloodType": 'O',
    "hobbies": ['sleeping', 'computer game', 'guitar'],
    "livein":
    {
        "contry": 'Taiwan',
        "city": 'Taipei'
    }
}

regex
用來儲存正則表達式。
javascript
用來儲存javascript語法。
objectId
會在文章下面提到。

objectId

MongoDB的核心，可以透過這個id直接處理document，以下是objectId的幾個特性:

預設每一個文件都有的欄位(連object型態的資料都會有)
如果沒有設定，會自動產生這個欄位
每一個文件的唯一位置
系統預設的single index key
collection層級的唯一值
資料行別為ObjectId

以下是一個objectId的例子:

db.costumer.insertOne({ ... })

db.costumer.find()

{
    "_id" : ObjectId("62d511895ddbc92df38d37e3"),
    "name": 'Augustus',
    "job": 'software engineer',
    "bloodType": 'O',
    "hobbies": ['sleeping', 'computer game', 'guitar'],
    "livein":
    {
        "contry": 'Taiwan',
        "city": 'Taipei'
    }
}

系統如何生成objectId的相關文檔在這可以看到，另外objectId也可以自行定義，其他型別也可以拿來做為_id，但是需要確保_id在collection層級上的唯一性。

MongoDB優缺點比較

優點	缺點
靈活的數據模型	需要更多的儲存空間
大部分可工作的數據儲存在RAM	RAM的使用會爆高
可水平擴展 (Sharding支援20PB)	弱一致性 (最終一致)，沒有💡ACID保證
	沒有Triger
文檔=物件，不需要ORM(物件關係對映)	重複的數據
索引(index)	索引(index)
	不支援Join

💡

ACID，是指資料庫管理系統（DBMS）在寫入或更新資料的過程中，為保證事務（transaction）是正確可靠的，所必須具備的四個特性：原子性（atomicity，或稱不可分割性）、一致性（consistency）、隔離性（isolation，又稱獨立性）、持久性（durability）。

MongoDB實務層面上的問題

在使用MongoDB之前有查詢到MongoDB在實際使用上的一些問題:

Aggregation查詢在橫跨多個Database、多個Collection時會變慢很多
需要有設計良好的Database和Collection才能確保擁有快速的查詢速度
後期效能問題:
百G以上的資料，需要有良好的index設計來提速
ex.資料庫內有十萬條6000字文本後，查詢速度降低

結論

MongoDB強勢的地方在於儲存資料的格式彈性，由於屬於NoSQL不需要定義Schema，可以輕易的新增、修改資料，對於剛開始使用資料庫，資料的格式還沒定下來的應用十分友善，在效能方面也是相當快速，又因為可以快速的水平擴張，在大數據的應用上也是相當方便。

Ghost Blog Note 02

AugustusHsu — Sun, 29 Oct 2023 12:00:21 GMT

紀錄Casper Theme的更動 (一)

這個Blog使用的主題為Casper (5.7.0)，這篇主要是要記錄從Github下載後更動過可能會影響到視覺效果的所有內容。

Collection功能

Collection或是叫Categories也可以，主要目的是用文章的Tag來區分各個主題，不過這裡要注意我的方法是直接列出使用的Tag，接著把它存成collection.hbs放在主題的程式碼中即可:

{{!< default}}
{{!-- The tag above means - insert everything in this file into the {body} of the default.hbs template --}}



    

        {{#get 'tags' limit='all' include='count.posts' order='count.posts desc'}}
            {{#foreach tags}}
            
                
                    {{#if feature_image}}
                    
                        {{!-- This is a responsive image, it loads different sizes depending on device
                        https://medium.freecodecamp.org/a-guide-to-responsive-images-with-ready-to-use-templates-c400bd65c433 --}}
                        
                    
                    {{/if}}

                    
                        
                            
                                    
                                        {{name}} 
                                    
                                    
                                    {{#if description}}
                                        {{description}}
                                    {{else}}
                                        {{!-- A collection of {{count.posts}}  --}}
                                        A collection of {{plural count.posts empty='zero posts' singular='% post' plural='% posts'}}
                                    {{/if}}
                                    
                            
                        
                    
                

                {{#get "posts" filter="tag:{{slug}}" include="tags,authors" order="published_at desc"}}
                    {{#foreach posts}}
                        {{!-- The tag below includes the markup for each post - partials/post-card.hbs --}}
                        {{> "post-card"}}
                    {{/foreach}}
                {{/get}}

            {{/foreach}}
        {{/get}}

collection頁面

完整的collection.hbs可以參考這個檔案

collection.hbs

3 KB

建立好collection.hbs也要更改routes.yaml的設定，在Settings > Labs > Routes可以下載目前的設定，更改如下:

routes:
  /collection/: collection

collections:
  /:
    permalink: /{slug}/
    template: index

taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

在Settings > Navigation新增Collection頁面對應的網址:

Code Highlight

開啟Settings > Code injection，在Site Header下的方框輸入以下程式碼:

一樣在中的Site Footer下面方框輸入以下程式碼:

在閱讀長文章或是想要查閱文章特定內容的時候，如果有個目錄的話可以幫助你快速想要看到的內容。Tocbot是一個JavaScript的套件，會去掃描網頁的內容自動生成目錄、創建指向那些標題的鏈結、展示它們在頁面上的位置，並根據頁面的標題層次分層組成目錄，這增加了用戶對網頁內容的導航能力。

另外Tocbot允許開發者進行多種自定義設置，包括目錄樣式、深度、位置等，也能夠在不同的設備上提供良好的使用體驗，包括桌面和移動設備。目前的Ghost部落格Casper主題需要修改default.hbs和post.hbs兩個個個文件。

編輯default.hbs

在前面head標籤中{{ghost_head}}添加Tocbot的css樣式，這裡使用的是4.18.2版本，如果後續有需要升級再更改這裡的版本號：

如果直接使用Ghost官方教學的方式會發現生成目錄前面的標號是用英文的abc，所以針對.gh-content ol ol ol li和gh-content ol ol ol li增加了list-style-type: decimal，可以讓生成的標號轉換為數字：

接下來的程序在{{ghost_foot}}添加 Tocbot 的 JS 代碼之前，版本同樣使用 4.18.2：

{{!-- Tocbot script --}}

在最近一段時間script之後新增了下一個用於初始化 Tocbot 的方程式，其中.gh-toc和gh-content用於匹配 Casper 的 CSS 類別：

{{! Initialize Tocbot after you load the script }}

編輯post.hbs

在post.hbs中{{content}}前新增TOC的div標籤：


    {{! The TOC will be inserted here }}
    
    {{content}}

回到頂部按鈕、顯示閱讀進度

和前面的TOC相同，在default.hbs的{{ghost_head}}前加入以下這段，這個滾動到頂部的按鈕是參考這篇文章，其中有針對使用的主題做一些修改，像是把位置移到右上角、顏色方面改動:

一樣在default.hbs上，將下面程式碼新增在{{ghost_foot}}前:

Python Note 03

AugustusHsu — Sun, 22 Oct 2023 12:00:51 GMT

基於Pytest框架的自動化測試 (下)

前面介紹了直接使用測試函數、用class包裝測試、setup和teardown、參數化測試案例、驗證預期的錯誤和跳過錯誤，這些是pytest基本的測試方法，接下來會透過pytest的fixture、conftest來整合這些功能，還有透過pytest的一些插件來產生報表，讓pytest的功能變得更加強大和靈活。

進階功能

接下來介紹的是 pytest 的進階功能，分別有fixture、conftest和產生報表的方法。

fixture

fixtures是pytest中的一個關鍵概念，他有前面介紹的setup跟teardown一樣的功能，可以幫助建構測試所需的環境，並在測試函數中重複使用:

import pytest


@pytest.fixture
def setup_teardown_example():
    # 在測試之前執行的代碼
    test_data = "在資料庫中準備測試資料"
    yield test_data
    # 在測試之後執行的代碼
    print("清理測試資料")


def test_using_fixture(setup_teardown_example):
    test_data = setup_teardown_example
    # 使用 fixture
    assert something == expected_result

fixture可使用的參數有下列三種:

scope：表示作用域，預設為function。
name：用來設定fixture的別名，預設為函式名稱
autouse：預設為False，若為True，則會自動進行使用 (根據scope作用域而定)

其中fixture的scope作用域跟setup跟teardown有略微不同，總共有四種，分別為:

function : 預設的選項，在每個測試函數運行之前和之後執行，各測試函數都將獲得一個新的、獨立的fixture實例，不會共享數據。
class : Fixture將在每個測試類 (使用@pytest.mark.usefixtures裝飾器) 中的測試函數之前和之後執行，在多個測試函數之間共享相同的fixture數據非常有用。
module : 在整個測試模塊 (測試文件) 中的測試函數之間執行，對於在模塊級別共享數據非常有用。
session : 整個pytest會話 (所有測試模塊) 中的測試函數之前和之後執行，允許在多個模塊之間共享持久性數據。

比較特別的是fixture在class上的應用，以下是使用@pytest.mark.usefixtures的範例，fixture會在測試class的所有方法之前運行一次，會在整個class中共享數據，然後在所有測試方法執行完成後進行清理:

import pytest

@pytest.fixture(scope="class")
def class_fixture():
    # 在測試類別中的測試方法之前和之後執行一次的fixture
    print("Class fixture setup")
    yield
    print("Class fixture teardown")

@pytest.mark.usefixtures("class_fixture")
class TestClassWithFixture:

    def test_method1(self):
        print("Test method 1")

    def test_method2(self):
        print("Test method 2")

以下展示了fixture在各個層級使用的範例，在這個範例中展示了fixture在session創建了與資料庫的連結；在module層級上的指定了測試用的collection並插入數據用於測試；在class層級上新增了測試資料讓後續的class級別的測試方法可以進行測試:

import pytest
from pymongo import MongoClient


# 定義一個具有session級別MongoDB client的fixture
@pytest.fixture(scope="session")
def mongodb_connection():
    # 連接到MongoDB的Client
    client = MongoClient('localhost', 27017)
    # 使用測試用的資料庫
    db = client['mytestdb']
    yield db
    # 清理測試用資料庫
    client.drop_database('mytestdb')


# 定義一個具有module級別的資料庫連接fixture，用於插入Document
@pytest.fixture(scope="module")
def setup_mongodb_data(mongodb_connection):
    # 使用測試集合名稱寫入數據
    collection = mongodb_connection['mycollection']
    data = [
        {"_id": 1, "name": "user1"},
        {"_id": 2, "name": "user2"},
    ]
    collection.insert_many(data)
    yield
    collection.delete_many({})


# 定義一個class級別的fixture
@pytest.fixture(scope="class")
def class_fixture(mongodb_connection, setup_mongodb_data):
    # 在測試的class中所有測試方法之前和之後運行一次的fixture設置
    collection = mongodb_connection['mycollection']
    data = {"_id": 3, "name": "user3"}
    collection.insert_one(data)
    yield
    collection.delete_one({"_id": 3})


# 在測試的class中使用前面設定的fixture進行測試
@pytest.mark.usefixtures("class_fixture")
class TestMongoDBClass:

    def test_fetch_user_data(self, mongodb_connection):
        collection = mongodb_connection['mycollection']
        user = collection.find_one({"_id": 1})
        assert user["name"] == 'user1'
  
    def test_another_test(self, mongodb_connection):
        collection = mongodb_connection['mycollection']
        user = collection.find_one({"_id": 2})
        assert user["name"] == 'user2'
  
    def test_class_fixture(self, mongodb_connection):
        collection = mongodb_connection['mycollection']
        user = collection.find_one({"_id": 3})
        assert user["name"] == 'user3'

conftest

conftest.py是pytest中一個特殊的模塊，它允許在不同的測試文件之間共享 fixture、自定義 hook 函數和配置選項，簡而言之就是一個可以存放經常被使用到 fixture的地方。

pytest在一開始執行時，就會先去抓是否有conftest.py的存在，而存放在conftest.py當中的fixture不需要透過 import就可以直接進行使用，如果有某些fixture會被許多個test module使用的話，就可以試著將該fixture放到conftest.py當中。

conftest.py的名稱和位置是固定的，必須放置在測試項目的根目錄或子目錄下，pytest會自動識別並加載它，conftest.py所存在的當前目錄以及其所有子目路中的test case都可以使用，若於不同目錄則需要另外寫一個conftest.py。

使用conftest.py的的資料夾結構可以如下:

├─src
│  ├─pkg1
│  │  ├─__init__.py
│  │  └─module_a.py
│  └─pkg2
│     ├─__init__.py
│     ├─module_a.py
│     └─module_b.py
├─tests
│  ├─test_pkg1
│  │  ├─__init__.py
│  │  └─test_case.py
│  ├─test_pkg2
│  │  ├─__init__.py
│  │  ├─test_case.py
│  │  └─conftest.py
│  ├─__init__.py
│  ├─conftest.py
│  └─test_1.py
└─setup.py

產生報表

前面介紹了許多使用pytest的方法，當使用pytest執行測試時，產生報表也是非常重要的，這是因為測試報表具有以下幾個關鍵用途和優勢:

可視化測試結果: 測試報表可以將測試結果以易於理解的方式呈現，通常用顏色和標籤來區分通過的測試、失敗的測試和錯誤的測試，使開發人員能夠快速識別和定位問題，並更容易理解測試的運行情況。
歷史紀錄: 測試報表通常可以保存歷史測試運行的結果，開發團隊可以追蹤測試運行的變化，對於檢測測試覆蓋率的提高或測試性能的改進非常有用。
集成到CI/CD流程: 在CI/CD流程中，測試報表可以自動生成並保存，這樣團隊可以輕鬆地監視應用程序的測試狀態，並確保每次部屬都是穩定的。如果測試報告顯示問題，則可以停止部屬，以防止潛在的錯誤進入生產環境。
分析測試結果: 測試報表還可以提供測試運行時間、測試覆蓋率、測試失敗的統計訊息等等，這有助於開發人員進行性能分析和測試覆蓋率分析。

以下是pytest常用產生報表的插件:

pytest-json-report: 用於生成JSON格式的測試報告。
使用方法: pytest --json-report=path/to/report.json
pytest-cov: 用於測試覆蓋率報告，可生成HTML供檢視。
使用方法: pytest --cov= --cov-report=html
pytest-html: 生成漂亮的HTML測試報告 (4.0.2會有問題，目前使用3.2.0)。
使用方法: pytest --html=report.html --self-contained-html
allure-pytest: Allure是一個開源的測試報告框架，可用於紀錄、展示和分析測試結果，下面單獨介紹如何使用這個套件。

Allure

安裝Allure需要Java JDK支持，需要到這個網站安裝，接下來直接到Allure的Github網址下載最新版本Allure的zip檔，將allure-x.x.x/bin放到系統的PATH中，可以在命令列上輸入allure --version檢查是否安裝成功。

接著要安裝allure在pytest的套件:

poetry add allure-pytest

可以直接在專案內執行以下命令，可以得到測試結果的資料:

pytest --alluredir ./allure/data

可以透過以下命令產生出html檔案，可以將index.html放到瀏覽器中查看報告:

allure generate ./allure/data -o ./allure/report/ --clean

不過用這種方式可能會遇到網頁打開了，但讀取不到數據的問題，這是因為CORS policy error的問題，如果是使用Google Chrome，在啟動時需要加上以下的參數以避免CORS policy error:

--allow-file-access-from-files

或是可以透過以下命令直接建構一個本地Web服務器:

allure serve ./allure/data

Allure還有許多其他的功能，具體可以參考官方文檔，後續有機會也可以專門為Allure寫一篇介紹文。

結論

測試框架在軟件開發過程中扮演著重要的角色，它不僅幫助測試人員高效地執行測試，還有助於開發團隊確保產品質量和穩定性，測試框架是保證軟件品質的不可或缺的工具之一。除錯和測試是軟體開發過程中的正常部分，不要害怕花時間來進行這些工作，每次修復一個錯誤，程式將變得更加穩定和可靠，持續學習和改進測試和除錯技巧也是提高軟體開發效率的關鍵。

Python Note 02

AugustusHsu — Sun, 15 Oct 2023 12:00:28 GMT

基於Pytest框架的自動化測試 (上)

在寫程式的時候，有時會不太確定自己的程式是不是按照自己想的一樣在執行，往往要針對個別案例進行手動的測試，而且還可能無法確定每一次測試的東西都是相同的；除此之外當遇到修改某功能的時候，有時會莫名地影響到了另一個功能，導致產出的結果不符合預期或是直接發生錯誤，這個時候就需要一個測試框架將測試的流程規範化，將每個測試寫成一個個的用例來驗證各個功能是否正確。

測試框架有很多種，主要的用處是幫助管理測試的用例、執行測試、收集測試結果和生成測試報告等等，將開發的注意力集中在測試的用例上，而不會浪費在原本可以避免的問題上。

核心功能

Pytest是一個用於Python程式語言的測試框架。它允許開發者撰寫簡潔而有效的測試，以確保他們的代碼正確運行。以下是一些pytest的主要特點和功能：

簡單易用、容易上手使用標準的斷言語句來檢查代碼的行為是否符合預期。
文件豐富，文件中有很多例項可以參考。
能夠支援簡單的單元測試和複雜的功能測試。
能夠自動發現和執行你的測試用例，只需按照特定的命名規則來命名測試文件和函數，pytest就能夠自動識別並運行它們。
允許參數化測試用例，這意味著您可以定義一個測試，為不同的輸入參數運行該測試。這有助於測試不同情景下的代碼行為。
支援各種插件，這些插件可以擴展pytest的功能，並添加額外的報告、測試選項和功能。
提供多種報告格式，包括文本報告、HTML報告和JUnit XML 報告等，方便您查看測試結果。
支持並行執行測試，這意味著測試套件中的多個測試用例可以同時運行，從而節省時間。
易於集成到持續集成和持續部署 (CI/CD) 流水線中。開發團隊可以使用Pytest來確保每次代碼更改都經過全面的測試。

Pytest安裝方式跟一般的套件安裝方式一樣，使用pip或是poetry都是可以的:

pip install pytest
poetry add pytest

進入到安裝了pytest的環境，可以用以下指令查看有甚麼參數可以設定:

pytest --help

使用案例

這裡簡單的介紹如何使用pytest的資料夾結構、基礎使用方法、產生報表，只針對簡單的數學計算寫測試案例，後續如果有時間會再開一篇針對後端、資料庫寫測試範例的紀錄。

資料夾結構

首先創建一個test資料夾，用作存放測試的用例方便管理。pytest預設會自動把目錄裡所有名稱為test_*.py的檔案全都測試一遍，所以用作測試的檔案要以test_開頭命名。

專案中常見的資料夾結構大致上分為兩種，一種是放在應用程式程式碼之外的測試，這種方案的好處很明顯，這些測試案例獨立於套件，簡化了測試的組織架構，可以將所有測試都集中在test資料夾內單獨測試，不需要考慮專案內的層次結構:

├─src
│  └─pkg
│     ├─__init__.py
│     ├─module_a.py
│     └─module_b.py
├─tests
│  ├─__init__.py
│  ├─test_module_a.py
│  └─test_module_b.py
└─setup.py

如果測試和你的專案密切相關，可以使將測試案例作為專案程式碼的一部分，這樣可以更好地組織程式碼，並且因為在同一個資料夾內便於維護:

├─src
│  ├─pkg
│  │  ├─__init__.py
│  │  ├─module_a.py
│  │  └─module_b.py
│  └─tests
│     ├─test_module_a.py
│     └─test_module_b.py
└─setup.py

只要團隊內有共識，無論選擇哪一種pytest都可以進行識別和測試，最重要的是確保測試的組織結構清晰且易於維護即可。

可以看到test內有__init__.py，這是為了將test視為一個python的package，使得pytest能夠在其中識別和執行測試文件，有助於更好地組織您的測試代碼，使其更易於管理和維護。

簡單範例

創建一個Python文件 calculator.py，其中包含要測試的函數：

# calculator.py

def add(a, b):
    return a + b

然後創建一個測試文件 test_calculator.py，其中包含測試用例：

# test_calculator.py

import calculator

def test_add_positive_numbers():
    assert calculator.add(2, 3) == 5

def test_add_negative_numbers():
    assert calculator.add(-2, -3) == -5

def test_add_mixed_numbers():
    assert calculator.add(5, -3) == 2

def test_add_zero():
    assert calculator.add(0, 0) == 0

在這個例子中，創建了四個測試用例，分別測試了 add 函數的不同情景：兩個正數相加、兩個負數相加、一個正數和一個負數相加，以及兩個零相加。切換到包含測試資料夾的路徑運行pytest，pytest會自動發現並運行 test_calculator.py 的測試用例，並且報告結果，如果一切正確應該會看到類似以下的輸出：

======================= test session starts =======================
platform win32 -- Python 3.10.10, pytest-7.4.2, pluggy-1.3.0        
rootdir: /path/to/your/tests
collected 4 items                                                   

tests\test_calculator.py ....                                [100%] 

======================== 4 passed in 0.02s ========================

這說明所有四個測試用例都成功通過，如果其中任何一個測試失敗，Pytest會報告相關的詳細信息，幫助您快速定位問題。這種測試方式有助於確保 add 函數的正確性。

Class範例

除了前面介紹的方式來使用pytest以外，還可以使用class的形式來組織測試，這稱為 "類級別的測試"，這對於在多個測試之間共享設置或資源特別有用。以下是一個示例，展示了如何使用類進行測試以及相應的被測試代碼。

創建一個 test_cls_calculator.py 測試文件，使用類的形式進行測試：

# test_cls_calculator.py

import pytest
import calculator

class TestCalculator:
    def test_add_positive_numbers(self):
        result = calculator.add(2, 3)
        assert result == 5

    def test_add_negative_numbers(self):
        result = calculator.add(-2, -3)
        assert result == -5

    def test_add_mixed_numbers(self):
        result = calculator.add(5, -3)
        assert result == 2

    def test_add_zero(self):
        result = calculator.add(0, 0)
        assert result == 0

這種方法特別適用於複雜的測試場景，為不同測試方法之間共享設置和資源。

setup & teardown

setup和teardown是常見用於測試用例的預設定和清理設定的概念，在執行測試用例之前進行一些環境設定、初始化等等，以及在測試執行後進行清理的工作。在pytest中提供了許多方法來實現這些設定和清理的操作，包括setup、teardown和後續要介紹的Fixture。

setup和teardown不能直接使用，要在後面加上測試進行時的作用域，分別是以下這四種:

function: 函數級別，在每次函數開始和結束時運行。
method: 方法級別，class中使用，在類別內method被調用的開始和結束時運行。
class: 類別級別，一樣在class中使用，在類別開始和結束時運行。
module: 模組級別，在整個.py模組開始和結束時運行。

使用方式大致如下:

# test_calculator.py

from src.package import calculator


def setup_module():
    print()
    print("setup_module")


def teardown_module():
    print()
    print("teardown_module")


def setup_function():
    print()
    print("setup_function")


def teardown_function():
    print()
    print("teardown_function")


def test_add_positive_numbers():
    assert calculator.add(2, 3) == 5


def test_add_negative_numbers():
    assert calculator.add(-2, -3) == -5


def test_add_mixed_numbers():
    assert calculator.add(5, -3) == 2


def test_add_zero():
    assert calculator.add(0, 0) == 0

如果是class的話則是:

# test_cls_calculator.py
import pytest

from src.package import calculator


def setup_module():
    print()
    print("setup_module")


def teardown_module():
    print()
    print("teardown_module")


class TestCalculator:
    def setup_class(self):
        print()
        print("setup_class")

    def teardown_class(self):
        print()
        print("teardown_class")

    def setup_method(self):
        print()
        print("setup_method")

    def teardown_method(self):
        print()
        print("teardown_method")

    def test_add_positive_numbers(self):
        result = calculator.add(2, 3)
        assert result == 5

    def test_add_negative_numbers(self):
        result = calculator.add(-2, -3)
        assert result == -5

    def test_add_mixed_numbers(self):
        result = calculator.add(5, -3)
        assert result == 2

    def test_add_zero(self):
        result = calculator.add(0, 0)
        assert result == 0


if __name__ == "__main__":
    pytest.main()

結果如下，每一個點代表的是一個通過的測試:

======================= test session starts =======================
platform win32 -- Python 3.10.10, pytest-7.4.2, pluggy-1.3.0        
rootdir: /path/to/your/tests
collected 8 items

tests\test_calculator.py
setup_module

setup_function
.
teardown_function

setup_function
.
teardown_function

setup_function
.
teardown_function

setup_function
.
teardown_function

teardown_module

tests\test_cls_calculator.py
setup_module

setup_class

setup_method
.
teardown_method

setup_method
.
teardown_method

setup_method
.
teardown_method

setup_method
.
teardown_method

teardown_class

teardown_module


======================== 8 passed in 0.06s ========================

如果要在命令列看到定義的setup和teardown中所print的內容，在測試的時候記得在pytest後面加上-s才能看到setup和teardown print出來的資訊。

參數化

當需要對同一組函數測試多組測試案例時，可以透過pytest的@pytest.mark.parametrize這個裝飾器來設定，可以設定多組的輸入參數和預期輸出，pytest會自動運行測試用例的多個運行實例，每個實例使用不同的輸入參數。

在下面的程式碼可以看到透過讀取json檔案獲取輸入參數和預期輸出，設定argnames跟argvalues來指定變數名稱跟輸入變數，然後可以指定每組的測試名稱ids來區分不同的測試實例，最後定義出測試函數:

# test_calculator.py

import json

import pytest

from src.package import calculator

with open("tests/test_calculator/test_calculator_args.json", "r", encoding="utf8") as file:
    calculator_test_case = json.loads(file.read())["calculator_test_case"]


ids = [f"case: {idx}" for idx in range(1, len(calculator_test_case) + 1)]


@pytest.mark.parametrize(
    argnames="input_a, input_b, expected_output", argvalues=calculator_test_case, ids=ids
)
def test_add_positive_numbers(input_a: int, input_b: int, expected_output: int):
    assert calculator.add(input_a, input_b) == expected_output

下方是測試資料test_calculator_args.json的內容:

{
    "calculator_test_case": [
        [2, 3, 5],
        [-2, -3, -5],
        [5, -3, 2],
        [0, 0, 0]
    ]
}

最後pytest的輸出結果，可以看到每筆測試資料都對應一個測試實例，名稱ids也顯示在結果上:

===================================== test session starts =====================================
platform win32 -- Python 3.10.10, pytest-7.4.2, pluggy-1.3.0        
rootdir: /path/to/your/tests
collected 4 items                                                                               

tests/test_calculator/test_param_calculator.py::test_add_positive_numbers[case: 1] PASSED [ 25%]
tests/test_calculator/test_param_calculator.py::test_add_positive_numbers[case: 2] PASSED [ 50%]
tests/test_calculator/test_param_calculator.py::test_add_positive_numbers[case: 3] PASSED [ 75%]
tests/test_calculator/test_param_calculator.py::test_add_positive_numbers[case: 4] PASSED [100%]
====================================== 4 passed in 0.03s ======================================

驗證錯誤

在專案中有時會需要設計一些預期內的錯誤，像是無效的輸入、邊界條件或是不合理的操作等等，這些就是合理、預期內的錯誤，pytest有驗證錯誤的功能來確保應用程式在遇到錯誤時不會崩潰或產生不符預期的結果。

建立一個測試用例，用pytest.raises捕獲ValueError確保引發了預期的錯誤:

# test_error.py

import pytest


def test_value_error():
    with pytest.raises(ValueError):
        raise ValueError("This is a test error")

除了驗證錯誤以外，pytest還可以檢查錯誤訊息是否符合預期:

def test_value_error_msg():
    with pytest.raises(ValueError) as exc_info:
        raise ValueError("This is a test error")

    assert str(exc_info.value) == "This is a test error"

    assert exc_info.typename == ValueError.__name__

跳過測試

在軟體開發中，有時候可能需要跳過測試，如尚未實現的功能、臨時性的問題、特定平台或是環境、待解決的問題等等，碰到這些情況pytest提供了跳過的功能skip和skipif，如下:

# test_skip.py

import sys

import pytest


@pytest.mark.skip(reason="This test is not implemented yet")
def test_unimplemented_feature():
    # 尚未實作該測試，先跳過
    pass


@pytest.mark.skipif(condition=sys.platform == "win32", reason="Conditionally skipped test")
def test_conditionally_skipped_feature():
    # 當系統為win32時跳過
    pass

要注意雖然跳過測試在某些情況下是合理的，但不應該成為標準作法，應該致力於解決跳過測試的原因，並確保測試套件是完整的，可以正確的驗證應用程序的功能，否則長期跳過測試可能會導致問題累積並降低程式碼的可靠性。

常用指令

這裡介紹幾個在測試時常用到的指令:

pytest -v: 顯示詳細的輸出，包含每個測試的名稱和結果。
pytest -s: 在運行測試時顯示標準輸出 (stdout)，通常僅在調試或檢查測試輸出時使用，不然可能會降低測試報告的可讀性。
pytest -r: 用於指定測試報告的顯示級別，-r f顯示失敗的測試 (簡單報告)；-r a顯示所有測試 (常規報告)；-r A顯示每個測試 (詳細報告)。
pytest -k: 選擇性地運行包含特定關鍵字的函數或方法，-k test_func_name根據測試名稱；-k my_keyword根據關鍵字；-k keyword1 or keyword2關鍵字表達式；-k "not slow"排除包含slow關鍵字的測試。

結論

前面介紹pytest的使用方法基本上已經能完整的測試一整個專案了，下一篇會再介紹pytest其他強大的功能，諸如fixture、conftest、coverage、產生報表等等。

CI/CD Server Note 05

AugustusHsu — Sun, 08 Oct 2023 12:00:57 GMT

Install Drone - CI/CD Tools

Drone是一個以GO語言開發的開源CI/CD平台，它可以協助開發團隊在程式碼變更時自動進行測試、建置和部署，這種自動化流程有助於提高團隊的效率，確保程式碼的品質，並快速將變更推送到生產環境中。

Drone可以透過配置簡單的YAML設定檔來定義 CI/CD 流程，該設定檔可以指定哪些測試需要運行、何時進行建置、以及何時將應用程式部署到伺服器上，Drone 也支援多種版本控制系統，如GitHub、Gitea和GitLab等等。

建置與安裝Drone

要使用Drone來建置CI/CD的流程需要先建立版本控制系統，根據Drone的文檔網站可以看到所支援的版本控制系統，在先前的文章介紹了如何安裝Gitea，安裝好了Gitea之後需要在Gitea的設定授權OAuth2才可以開始安裝Drone。

在Gitea > 設定 > 應用程式 > 新增OAuth2應用程式寫入需要的資訊，其中下面那項URL根據你之後要建立的Drone網址填入即可，若還不清楚後續再做更改也可以:

建立應用程式後要記錄客戶端ID和客戶端密鑰，在後續安裝Drone的時候會用到，密鑰在按下儲存按鈕後會被隱藏，若後面忘記的話也沒關係，按下重新產生密鑰就可以:

後續因為要建置drone-runner，需要透過OpenSSL生成一組密鑰。透過下面指令在linux產生一組長度為128 個位元組(16 個字元)隨機(rand子指令)的十六進制字串，加上"-hex"選項，表示要輸出十六進制形式的隨機數:

openssl rand -hex 16

接下來就只剩下建立Drone Server和Drone Runner的Docker，將前面所記錄的客戶端ID、客戶端密鑰和透過OpenSSL產生的隨機數填入下面的docker-compose.yml上，用docker-compose建立:

version: "3"

services:
  drone-server:
    image: drone/drone:latest
    container_name: drone-server
    ports:
      - "5080:80"
    volumes:
      - ./drone:/data
      - /var/run/docker.sock:/var/run/docker.sock
    restart: always
    environment:
      - DRONE_GITEA_SERVER=your.gitea.website
      - DRONE_GITEA_CLIENT_SECRET=客戶端密鑰
      - DRONE_GITEA_CLIENT_ID=客戶端ID
      - DRONE_GIT_ALWAYS_AUTH=true
      - DRONE_SERVER_HOST=your.drone.website
      - DRONE_SERVER_PROTO=http
      - DRONE_RPC_SECRET=透過OpenSSL產生的隨機數
      - DRONE_AGENTS_ENABLED=true
      # 先自行建立admin
      - DRONE_USER_CREATE=username:your_user_name,admin:true
      - DRONE_UI_USERNAME=root
      - DRONE_UI_PASSWORD=root

  drone-agent:
    image: drone/drone-runner-docker:latest
    container_name: drone-runner
    ports:
      - "30001:3000"
    restart: always
    depends_on:
      - drone-server
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - DRONE_RPC_PROTO=http
      - DRONE_RPC_HOST=your.drone.website
      - DRONE_RPC_SECRET=透過OpenSSL產生的隨機數
      - DRONE_RUNNER_CAPACITY=10
      - DRONE_RUNNER_NAME=agent-01

使用Drone - 入門

建好後Server跟Runner後開啟一個專案，編輯.drone.yml輸入以下程式碼，送出commit後push到Gitea:

kind: pipeline
type: docker
name: hello_world

steps:
- name: hello_world
  image: ubuntu:20.04
  commands:
    - echo hello drone

進入Drone Server的網址，點選CONTINUE:

接下來會需要填入你的基本訊息:

授權Drone可以存取你的帳戶:

處理完後就可以看到Drone的管理頁面，在首頁會顯示可以存取到的所有專案，如果沒有顯示可以點擊SYNC到Drone，這個時候Drone還不會開始工作，需要啟用要使用Drone的專案:

進入剛剛建立的專案後，點選畫面中央的+ACTIVATE REPOSITORY 就可以為這個專案啟用、建立CI的流程:

啟用後Settings的頁面會長這樣，後續如果需要做一些調整或是添加一些參數可以在這個頁面中調整:

點選Builds可以看到剛剛push上去的commit已經通過測試了:

點進這次的紀錄之後，就可以看到關於這次 Build 的詳細過程:

在Gitea上可以在Commit Message後面看到一個✅，代表通過了你寫的測試:

結論

總結來說，Drone是一個用於自動化持續整合和持續交付流程的工具，它可以協助開發團隊更快速地將程式碼部署到生產環境中，同時確保程式碼的品質和穩定性。

CI/CD Server Note 04

AugustusHsu — Sun, 01 Oct 2023 12:00:17 GMT

pre-commit程式碼風格檢查

在多人協作開發軟體的情境下，程式碼品質是一個需要重視的議題，要確保程式碼的一致性、可讀性和可維護性，除了程式碼重構，還有一個極為實用的工具，那就是pre-commit。

這個工具可以在程式碼提交之前自動執行程式碼格式化、語法檢查等等，確保在程式碼進入版本控制系統之前符合一定的品質標準和規範，有助於防止不良程式碼進入版本控制系統，減少在後續的CI/CD pipeline過程發生錯誤而需要做code review的次數，從而提升整個團隊的效率和程式碼的品質和效率。

Hooks

pre-commit是透過Git的Git Hooks來實現的，當某些操作git的動作發生時，會觸發自定義的script，而pre-commit如同字面上的意思，是在commit的時候會先觸發定義的script對程式碼進行檢查或是其他操作，再進行commit的動作。

Hooks大致上可分成pre-跟post-兩種，除了這兩種以外常用的還有commit-msg跟update:

pre- : 代表在Git操作執行之前所要進行的動作，可以用來做執行代碼風格檢查、測試、驗證提交內容等操作。
post- : 則在Git操作執行之後要進行的動作，通常用來執行自動化部署、發送通知或日誌記錄等後處理操作。
commit-msg : 在提交訊息(commit message)被編輯後觸發，可用於檢查提交訊息的格式。
update : 在參考(reference)更新時觸發，可用於驗證參考的更新。

通常情況下，這些hook script通常需要搭配特定的檔案、工具和執行環境，以實現其功能，因此整包可能會變得相當龐大。當需要在其他專案中使用這個hook script時必須將這龐大的script複製到另個專案中，這個過程非常麻煩，而pre-commit套件就是為了解決這個問題。

pre-commit基本設定

pre-commit最初是為了Python設計的套件，不過也可以用於其他語言的項目，只要設計好要使用的語言相應的檢查、驗證腳本。目前專案中我都使用Poetry來管理python的套件，所以這裡使用poetry來安裝pre-commit，使用pip來安裝也可以，由於pre-commit希望只在開發環境使用，不會想要在測試或是產品上安裝他，所以要設定成--group main:

poetry add pre-commit --group main
pip install pre-commit

設定檔

接下來要在專案的根目錄創建.pre-commit-config.yaml檔案範例如下:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: check-added-large-files
      - id: check-ast
      - id: check-case-conflict
      - id: check-json
      - id: check-toml
      - id: check-yaml
      - id: end-of-file-fixer
      
  - repo: # 後略

其中yaml檔案的repo、rev、hooks、id以外還有其他可添加的元素，所代表的意義為何可以參考官方的文檔，下面介紹範例中使用到的元素:

repo : 可以用git clone的repository連結。
rev : rev為對應的版本號，可以在release的tag頁面看到。
hooks : 要使用哪些hook，這個頁面列出了可使用的變數。
id : 要使用存儲庫中的哪個hook。

上面這個範例使用的是由pre-commit提供的基本hooks:

trailing-whitespace : 檢查程式碼是否存在多餘的尾隨空格。
check-added-large-files : 檢查是否添加了過大的文件。
check-ast : 對程式碼進行抽象語法樹(AST)分析，以檢查淺在的問題。
check-case-conflict : 檢查檔案名的大小寫是否與版本控制系統中的文件衝突。
check-json : 驗證JSON文件的格式是否正確。
check-toml : 驗證TOML文件的格式是否正確。
check-yaml : 驗證YAML文件的格式是否正確。
end-of-file-fixer : 自動添加文件末尾的換行符號。

以上是列出pre-commit-hooks自帶的一些常用hook，如果有需要添加新的hook可以去官方文檔中尋找。

使用

在下指令以前要確定已經進入了安裝了pre-commit的python虛擬環境，不然可能會找不到指令，接著在專案根目錄以命令列執行pre-commit install，將.pre-commit-config.yaml轉譯為hook腳本存在專案下的.git/hooks目錄中:

> pre-commit install

pre-commit installed at .git\hooks\pre-commit

到這個步驟後，執行git commit就會執行.pre-commit-config.yaml設定的各個hook，如果是在VSCode執行，並有不符合規定的會直接跳出警告，可以查看哪個環節出錯了:

按照官方的文檔說明，如果添加了新的hook建議執行以下指令 (或是你想要手動執行)，讓所有的檔案都檢查過一次:

pre-commit run --all-files

除了使用所有的hook檢查所有的檔案，也可以指定hook-id或特定的檔案去執行:

# 指定hook檢查所有檔案
pre-commit run [hook-id] -a

# 指定hook檢查特定檔案
pre-commit run [hook-id] --files

💡

小提醒: pre-commit所檢查的檔案只有放到暫存區的檔案，也就是經過git add的檔案，但如果使用--all-files參數則真的為所有檔案。

跳過/停用

如果要跳過pre-commit直接commit的話，在git commit後面加上--no-verify又可以跳過檢查了:

git commit --no-verify -m "Commit Message"

如果要直接停用pre-commit直接輸入以下指令就可以停用了:

pre-commit uninstal

其他hook

前面有提到可以到官方提供的可支援hooks列表中安裝需要的script，下面會介紹幾個目前在用的hook，可以讓剛上手的人有一個基本的設定可以使用。

Flake8

Flake8是用來檢查python程式碼風格和找到程式碼潛在的品質問題以符合PEP8，有助於提高程式碼的質量、可讀性和可維護性，關於Flake8的介紹網路有很多了，這裡就直接上範例:

# 前略
  - repo: https://github.com/PyCQA/flake8
    rev: 6.1.0
    hooks:
      - id: flake8
        exclude: .venv/
        args:
          - --max-line-length=100
          - --ignore=E402

可以看到比起前面的寫法多了exclude跟args兩個參數:

exclude : 指定需要排除檢查的檔案或資料夾。
args : 要傳遞給hook的附加參數清單。

這裡排除了.venv/資料夾，且傳入了max-line-length=100和ignore=E402兩個參數給Flake8，其中max-line-length=100將限制長度從原本的79改為100；而ignore則是要Flake8忽略某些警告或是錯誤，這裡的E402代表的是import python套件的位置不在檔案的頂部的錯誤，Flake8的規則可以在這裡查到，可以根據團隊的規定或是不同的專案來配合需求。

isort

isort主要是將import進python的套件按照一定的規則排序、分組，並按照字母順序排列，同樣isort也符合PEP8的規定，以下是使用isort的範例:

# 前略
  - repo: https://github.com/PyCQA/isort
    rev: 5.12.0
    hooks:
      - id: isort
        exclude: .venv/
        args:
          - --line-length=100
          - --profile=black

同樣在這裡看到了line-length，為了讓彼此共通的判斷規則一致，設定為100。

yapf

yapf (Yet Another Python Formatter) 是一個python程式碼格式化工具，它可以幫助開發者自動調整python程式碼的風格和格式，以確保程式碼的一致性和可讀性，YAPF根據PEP 8規範自動格式化代碼，使代碼風格一致，並減少程式碼審查中的風格問題。

按照pre-commit支援的hook安裝的方式可以在.pre-commit-config.yaml上添加以下代碼:

# 前略
  - repo: https://github.com/pre-commit/mirrors-yapf
    rev: v0.32.0
    hooks:
      - id: yapf
        exclude: .venv/
        args:
          - column_limit = 100
        additional_dependencies: [toml]

或是使用google的yapf，它提供了許多可以客製化的參數設定，詳細的說明可以去github上查看:

# 前略
  - repo: https://github.com/google/yapf
    rev: v0.40.1
    hooks:
      - id: yapf
        name: yapf
        language: python
        entry: yapf
        args: 
          - -i
          - COLUMN_LIMIT = 100
        types: [python]

black

black跟yapf一樣是程式碼格式工具，不過black是以嚴格的規範出名，基本上沒有太多的客製化參數可以調整:

  - repo: https://github.com/psf/black
    rev: v23.9.1
    hooks:
    - id: black
      args:
        - --line-length=100
        - --skip-string-normalization

大致上會使用的參數就這兩種，其他的參數可以參考這個網址:

--line-length: 單行的長度限制，預設為88。
--skip-string-normalization: black會對所有字串使用雙引號並標準化字串。

Linter & Formatter

前面所介紹的Flake8跟yapf分別是一種python的Linter跟Formatter，用來統一程式碼風格的工具，使用步驟通常是:

先用Linter來檢查程式碼中的潛在問題、風格指南違規和錯誤，它會提供有關代碼中可能存在的問題的警告或錯誤消息，如未定義的變數、未使用的變數、代碼風格不符合慣例等。
再用Formatter自動調整程式碼的格式，以符合指定的風格指南和慣例，它會自動糾正縮進、空格、換行等風格問題，以確保代碼的一致性。

常見用於python的Linter有下面這幾種:

Pylint
Flake8
pycodestyle (以前的名稱是PEP8)

常見用於python的Formatter有下面這幾種:

總的來說，你應該首先運行 Linter 來檢查代碼中的問題，然後再運行 Formatter 來確保代碼符合風格指南。這樣可以確保你的代碼既沒有錯誤，又符合一致的風格，提高了代碼的品質和可維護性。

使用的範例

要注意如果有彼此共通的判斷規則，那參數要記得設定一樣:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: check-added-large-files
      - id: check-ast
      - id: check-case-conflict
      - id: check-json
      - id: check-toml
      - id: check-yaml
      - id: end-of-file-fixer

  - repo: https://github.com/PyCQA/flake8
    rev: 5.0.4
    hooks:
      - id: flake8
        exclude: migrations/
        args:
          - --max-line-length=100
          - --ignore=E131

  - repo: https://github.com/PyCQA/isort
    rev: 5.11.5
    hooks:
      - id: isort
        exclude: migrations/
        args:
          - --line-length=100
          - --profile=black

  # 選擇black或是yapf
  - repo: https://github.com/google/yapf
    rev: v0.40.1
    hooks:
      - id: yapf
        name: yapf
        language: python
        entry: yapf
        args: 
          - -i
          - COLUMN_LIMIT = 100
        types: [python]

  - repo: https://github.com/psf/black
    rev: 23.9.1
    hooks:
      - id: black
        args:
          - --line-length=100

Python Note 01

AugustusHsu — Sun, 24 Sep 2023 12:00:23 GMT

套件、虛擬環境管理工具-Poetry

使用Python來開發軟體時，管理在專案中使用的套件和Python版本是一件麻煩的事情，從一開始接觸的pip install、或是管理不同專案的虛擬環境conda來安裝不同版本的Python或是套件，都或多或少會有一些相依性的問題。

尤其是使用pip uninstall的時候，解除安裝套件時就只會解除安裝你指定的套件，其他相依的套件通常都不會被一併解除安裝，這就會遇到一些關於相依性的問題，餘下的套件可能會和之後新安裝的套件產生衝突，所以我們需要一個完整的套件相依性管理工具來處理這個問題，而Poetry就是負責管理套件相依性、依賴性和虛擬環境的工具。

poetry具體的指令或方法建議參考官方網站的指令，

安裝Poetry

安裝poetry在Windows需要使用Powershell來安裝，打開Powershell輸入以下指令(目前安裝的版本為1.6.1) :

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

如果是linux、macOS或是Windows的WSL則是用以下指令，如果需要安裝python2的poetry指令內的python3可以更改為python2:

curl -sSL https://install.python-poetry.org | python3 -

如果安裝時遇到:

Poetry installation failed.
See /home/username/poetry-installer-error-4khp4juv.log for error logs.

去看log會發現缺少distutils，這是用於協助建立和分發Python套件的工具:

ModuleNotFoundError: No module named 'distutils.cmd'

需要你安裝python3-distutils，用以下指令安裝:

sudo apt-get install python3-distutils

如果是Windows安裝完的位置會在%APPDATA%\Python\Scripts而Unix系統則是在$HOME/.local/bin上，如果要直接使用要設定環境變數PATH，Windows直接使用以下指令或是前往環境變數設定的地方新增即可，其中的使用者要記得改為自己的使用者名稱:

$Env:Path += ";C:\Users\YourUserName\AppData\Roaming\Python\Scripts"; setx PATH "$Env:Path"

Unix系統則是要在.zshrc、.bashrc或.bash_profile新增以下的指令:

export PATH=$PATH:$HOME/.local/bin

安裝完後會發現如果按下TAB是無法補全剩餘的字串的，如果是在Unix下使用bash，加上以下這段可以恢復補全功能:

poetry completions bash >> ~/.bash_completion

初始化Poetry專案

使用Poetry的話需要在你使用Poetry的資料夾使用以下指令，會跳出一連串的互動對話協助建立專案，其中會問你是否要以互動方式定義你的main/development依賴這兩個問題，這兩個我都選no，而最後會print出你的設定檔內容要你確認:

poetry init

結束後會新增一個pyproject.toml做為設定檔:

[tool.poetry]
name = "your_project_name"
version = "0.1.0"
description = ""
authors = ["AuthorName "]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.10.11"


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

💡

在這裡python版本號要把後面的.11也列出來，我在後續使用poetry add的時候發現套件安裝的速度非常地慢，加上後就正常了。

除了使用init外，還可以用new的方式建立專案，除了會建立pyproject.toml以外還會建構一些資料夾或檔案，後面可以接上你專案名稱將專案資料夾建立在你目前的位置上，或是加上路徑建立在你指定的資料夾內:

poetry new your_project
poetry new your_project_path

建立/進入Python虛擬環境

Poetry預設建立虛擬環境的位置在C:\Users\YourUserName\AppData\Local\pypoetry\Cache\virtualenvs，可以透過設定將建立虛擬環境的路徑改在專案下，首先使用以下指令列出poetry的設定:

poetry config --list

在Windows的設定內容如下，其中要修改virtualenvs.in-project = null，讓虛擬環境的路徑改為你專案目錄:

cache-dir = "C:\\Users\\YourUserName\\AppData\\Local\\pypoetry\\Cache"
experimental.system-git-client = false
installer.max-workers = null
installer.modern-installation = true
installer.no-binary = null
installer.parallel = true
virtualenvs.create = true
virtualenvs.in-project = null
virtualenvs.options.always-copy = false
virtualenvs.options.no-pip = false
virtualenvs.options.no-setuptools = false
virtualenvs.options.system-site-packages = false
virtualenvs.path = "{cache-dir}\\virtualenvs"  # C:\Users\YourUserName\AppData\Local\pypoetry\Cache\virtualenvs
virtualenvs.prefer-active-python = false
virtualenvs.prompt = "{project_name}-py{python_version}"

使用以下指令就可以更改設定:

poetry config virtualenvs.in-project true

用以下指令建立虛擬環境，其中python可以改為你要使用的python路徑，因為已經將虛擬環境建立的路徑改為專案內，所以在專案內會建立.venv的資料夾，也就是你的python虛擬環境:

poetry env use python

可以在Windows使用where指令或在Linux使用which找到你的python安裝路徑:

where python
which python3

建立虛擬環境後，可以使用poetry shell進入虛擬環境:

poetry shell

💡

當你的專案還沒有建立虛擬環境時，使用poetry shell也會順帶建立虛擬環境，不過是使用預設版本python來建立虛擬環境。

指令會偵測當前的目錄或上一層目錄是否存在pyporject.toml來確定要啟動的虛擬環境，如果沒有會出現以下錯誤:

> poetry shell

Poetry could not find a pyproject.toml file in /currnet/path or its parents

退出跟一般進入環境的方式一樣，使用exit即可。

Poetry常用指令

Poetry在使用的時候跟Anaconda很像，都是透過自己的指令來建立、管理你的python虛擬環境，比起Anaconda或是PyPI他使用的方式複雜了一些，需要花費一些時間來學習。

poetry add

poetry add跟pip install或conda install一樣是用來安裝套件的，這裡示範安裝pandas，可以清楚地看到安裝了哪一些套件:

poetry add pandas

Using version ^2.1.0 for pandas

Updating dependencies
Resolving dependencies...

Writing lock file

Package operations: 5 installs, 0 updates, 0 removals

  • Installing six (1.16.0)
  • Installing python-dateutil (2.8.2)
  • Installing pytz (2023.3.post1)
  • Installing tzdata (2023.3)
  • Installing pandas (2.1.0)

打開pyproject.toml會發現在tool.poetry.dependencies多了pandas和它對應的版本號:

[tool.poetry.dependencies]
python = "3.10.10"
pandas = "^2.1.0"

poetry lock

poetry add除了會更新pyproject.toml以外，還會根據目前專案中pyproject.toml內的設定產生poetry.lock檔案，詳細記載了所有安裝的套件與對應的版本、依賴的套件。

所以大體上Poetry管理套件的流程是:

更新pyproject.toml
依照pyproject.toml內的設定更新poetry.lock
根據poetry.lock創建對應的虛擬環境.venv

所以說Poetry中的指令只要有涉及到對套件進行更改的部分，都是會按照這個流程去進行，如果不使用指令操作直接對pyproject.toml進行更改，譬如調整特定套件的版本，這時候pyproject.toml和poetry.lock之間就失去了對應的關係，需要透過poetry lock這指令讓Poetry依照pyproject.toml內的設定，來更新poetry.lock。

譬如我更改了之前安裝的pandas套件版本，^的意思是任何大於或等於 2.1.0 且小於 3.0.0的版本，所以改為 (不加上^) 2.0.0 :

[tool.poetry.dependencies]
python = "3.10.10"
pandas = "2.0.0"           # 原為^2.1.0

使用poetry lock來更新poetry.lock檔案:

> poetry lock

Updating dependencies
Resolving dependencies...

Writing lock file

在poetry.lock上會看到更新後對應的版本:

# 前略
[[package]]
name = "pandas"
version = "2.0.0"
# 後略

接下來還有最後一步驟，就是把poetry.lock的更改寫入對應虛擬環境:

poetry install --sync

如果當前目錄中有poetry.lock文件，poetry install會使用那裡的確切版本。
如果沒有poetry.lock，會從當前專案中讀取pyproject.toml文件，解析依賴項並安裝它們。

poetry update

poetry update的作用就是更新套件，可以直接使用指令更新目前所有有用到的套件，也可以針對特定的套件進行更新:

poetry update
poetry update pandas

除此之外poetry update的實現流程和上一部分介紹的poetry lock流程是一樣的，poetry update同樣也會根據pyproject.toml來產生對應的poetry.lock，不過會把後續的poetry install也一併執行。

將pandas版本改回^2.1.0，並執行poetry update:

[tool.poetry.dependencies]
python = "3.10.10"
pandas = "^2.1.0"

會得到以下結果:

Updating dependencies
Resolving dependencies...

Package operations: 0 installs, 1 update, 0 removals

  • Updating pandas (2.0.0 -> 2.1.0)

Writing lock file

更新poetry.lock的同時也會套用到虛擬環境:

>>> import pandas as pd
>>> pd.__version__
'2.1.0'

poetry show

poetry show的作用跟pip list、conda list一樣，都是列出所安裝的套件，直接使用的結果如下:

numpy           1.25.2       Fundamental package for array computing in Python
pandas          2.1.0        Powerful data structures for data analysis, time series, and stat...  
python-dateutil 2.8.2        Extensions to the standard Python datetime module
pytz            2023.3.post1 World timezone definitions, modern and historical
six             1.16.0       Python 2 and 3 compatibility utilities
tzdata          2023.3       Provider of IANA time zone data

除此之外還有一個特別的功能，就是列出套件的樹狀結構，使用方法是直接在poetry show後面加上--tree參數，用這種方式可以顯示主要套件和依賴套件的關係與階級，結果如下:

pandas 2.1.0 Powerful data structures for data analysis, time series, and statistics
├── numpy >=1.22.4
├── numpy >=1.23.2
├── python-dateutil >=2.8.2
│   └── six >=1.5
├── pytz >=2020.1
└── tzdata >=2022.1

也可以列出指定的套件，如下:

poetry show pandas
poetry show pandas --tree

poetry remove

poetry remove的作用如同字面上一樣是用來移除不要的套件，在指令後面要加上要移除的套件名稱:

poetry remove pandas

從輸出結果可以看到除了把pandas移除以外，也將依賴的套件一併移除了:

Updating dependencies
Resolving dependencies...

Package operations: 0 installs, 0 updates, 6 removals

  • Removing numpy (1.25.2)
  • Removing pandas (2.0.0)
  • Removing python-dateutil (2.8.2)
  • Removing pytz (2023.3.post1)
  • Removing six (1.16.0)
  • Removing tzdata (2023.3)

Writing lock file

group

在python有一些套件可能只會在開發的時候用到，像是code formatter相關的套件black、yapf，或是負責測試的套件pytest，這些都只會在開發的時候使用到，你不會希望被包在部署環境裡面，無謂的增加大小使得部署環境過於臃腫。

所以在安裝套件的時候可以加上--group或是-G來區分開發環境或是測試環境所需安裝的套件，~~預設主環境的group名稱是main~~目前新的版本改成用group來區分，預設的主環境為tool.poetry.dependencies:

poetry add black --group dev
poetry add pytest --group test
poetry add pandas --group main

如果是第一次加上group來安裝套件，打開pyproject.toml會發現除了tool.poetry.dependencies以外多了一段，這是在group環境中所需要安裝套件，如下:

[tool.poetry.group.yourgroupname.dependencies]
package_name = "^version"

前面在介紹把poetry.lock的更改寫入對應虛擬環境會用poetry install這個指令，在還沒有建立虛擬環境的時候，要安裝不同的group的話，可以在後面添加--without、--with或--only；如果已經建立虛擬環境的時候，可以透過--sync選項同步環境並確保與poetry.lock匹配 :

# 排除test和docs group
poetry install --without test,docs
# 選擇test group
poetry install --with test
# 僅安裝test group
poetry install --only test

# sync 一樣可以套用with、without、only
poetry install --without test --sync
poetry install --with test --sync
poetry install --only test --sync

💡

透過--with和--only來安裝除了會安裝在所選的group中的套件外(也就是[tool.poetry.group.yourgroupname.dependencies]所列的套件外)，兩者的差別為是否會安裝tool.poetry.dependencies中所列的套件。

如果想將環境還原成沒有安裝套件的狀態，可以透過以下指令，環境就只會剩下python本身的基礎套件:

poetry install --only-root --sync

具體的指令可以參考官方文件的說明。

poetry export

雖然說已經使用Poetry來管理python套件，但還是有可能會需要轉到其他沒有Poetry的環境使用，那就需要將安裝的套件匯出成requirements.txt，再到其他環境用pip install來安裝，這時候就需要poetry export:

poetry export -f requirements.txt -o requirements.txt

💡

要注意的是用這指令產生出來的requirements.txt預設只會輸出pyproject.toml中的[tool.poetry.dependencies]區塊內的套件。

如果要指定輸出的group和前面的poetry install一樣，要使用--with、--without或是--only來指定要使用的group，規則和前面介紹的一樣:

poetry export -f requirements.txt -o requirements.txt --only test,docs

輸出的requirements.txt預設會有hash值，用pip install安裝會檢查這些hash:

pandas==2.1.0 ; python_full_version >= "3.10.11" and python_full_version < "4.0.0" \
    --hash=sha256:0164b85937707ec7f70b34a6c3a578dbf0f50787f910f21ca3b26a7fd3363437 \
# 下略

如果不要有hash，加上--without-hashes就行:

poetry export -f requirements.txt -o requirements.txt --without-hashes

如果要在Docker上使用Poetry來安裝專案內使用的套件，有一篇文章詳細的介紹如何用Docker透過Poetry安裝套件且產生最小化的Image。

總結常用指令

poetry init/poetry new <專案路徑> : 初始化專案
poetry env use : 建立環境用
poetry shell : 進入建立的虛擬環境
poetry add : 安裝套件
poetry lock : 根據pyproject.toml更新poetry .lock
poetry install : 根據poetry.lock更新虛擬環境
poetry update : 更新套件
poetry show : 列出安裝的套件
poetry remove <套件名稱> : 移除指定套件
poetry export:匯出安裝的套件

Ghost Blog Note 01

AugustusHsu — Sun, 17 Sep 2023 12:00:06 GMT

安裝紀錄

撰寫部落格是為了記錄一些日常或者記錄一些學習筆記，我一直認為是一些很酷的行為，不過因為懶惰等等原因總是更新的很慢、很佛性。

從2019年開始，我使用hexo利用github的頁面功能在github.io上建立了部落格，寫了一些學習、研究技術的文章，荒廢的很大一個原因是hexo的一些設置有點複雜，需要處理主題、插件、佈局等等設置，而且我本身也不熟悉 Node.js，為了維護或升級這些有點難度，另外編輯、發布的功能因為不是所見即所得的方式，通常可能需要花一個排版亂掉會一堆時間去找到問題，後來就找到了Ghost Blog這個可以選擇在平台上開賬號或者自架的部落格。

這個部落格是安裝在AWS提供的lightsail服務上，安裝的方法很簡單而且在網上也有教學，這裡就先跳過了，本文主要記錄針對主題去更改什麼了設置、或者添加了什麼為主。

更新幽靈

進入ghost資料夾，更新後更改權限：

cd /opt/bitnami/ghost
sudo su ghost -c "ghost update"

sudo chown ghost:bitnami -R /opt/bitnami/ghost
sudo chmod 640 /opt/bitnami/ghost/config.production.json

更新後config.production.json可能會改變可以去查看是否有被變更，主要可能被變更的選項如下：

改回來後需要重啟ghost：

sudo su ghost -c "ghost restart"

備份設置

之前在升級Ghost Blog的時候，遇到因為打錯指令導致整個部落格開不起來，後來直接想辦法取出前一段時間慢慢匯出的資料，再還原到新的服務器上，所以在對服務器進行操作的時候進行備份或定期備份是一件很重要的事情，在這台服務器上我所使用的方式是Amazon Lightsail的Sanpshots來進行備份，他可以手動進行備份、也可以定期執行備份的動作，整體來說有一個很方便的功能。

快照

進入 Amazon Lightsai 的頁面，看到大量實例中您要備份的機器，然後選擇快照，可以看到以下畫面：

可以直接Create snapshot:

或是開啟下面的Automatic snapshots，Change snapshot time來選擇備份時間:

mail設定

要讓其他對你的Ghost部落格有興趣的人可以進行評論、通知訂閱者發了新文章等等操作，或是作者需要對密碼進行重製等等都需要使用到郵件來通知。這裡使用了SMTP的方式進行設定，SMTP的服務則是選擇了Mailgun來發送郵件。

Mailgun設定

進入Mailgun的控制台在右上角點選Add New Domain新增一個網域:

按照說明填入你的網域和選擇使用的伺服器:

接下來要去管理你網域的DNS服務商那裏去設定DNS紀錄、MX紀錄:

因為我這邊使用的是Cloudflare平台，要注意最後一個CNAME要記得在Cloudflare上不要使用到proxy，要設定成DNS only (要讓橘黃色小雲變成灰色):

都設定好之後可以點選上方的Verify DNS settings:

如果沒有問題，在Status上會顯示Verified或是Active:

設定好之後要去左邊的Sending > Domain setting ，接著點選SMTP credentials，記住這裡的Login名稱和產生的密碼，密碼如果忘記了可以直接點選Reset password來重設:

接著在同個頁面，點選Sending API keys，再點右上方的Add sending key來新增，輸入該API Key的敘述:

得到Sending API key一樣記錄下來，如果忘了則需要重新產生，之後會需要用到:

寫入Mailgun設定

將之前在SMTP credentials中的帳號密碼填入:

然後要在後台的Settings > Email newsletter最下方Mailgun configuration點選Expand，選好Mailgun region和輸入在Mailgun註冊的domain，將剛剛取得的API key輸入到下方的Mailgun Private API key空格處:

Mailgun添加白名單

弄好上方的設定後，可能會發現一般的訂閱或是文章回覆是可以收到Mail，但是一旦發表新文章時卻收不到信，這時候需要將伺服器所在的IP加入Mailgun的IP白名單，首先點選右上角的個人資訊、選擇API Security:

點選上方的IP allow list:

點選Add to allow list後，將Ghost Blog所在的IP填入即可:

設定完後可以自行發表文章測試看看收不收的到信，目前Ghost Blog (5.59.2) 的 Casper (5.7.0) 主題預設的留言方式在留言的時候同時會寄信給作者，也可以在文章下留言來測試郵件是否能正常發送。

Google Analytics

如果你是第一次使用Google Analytics登入進去後有以下畫面，點選開始測量:

首先需要先創建一個帳戶，這裡的帳戶負責管理你要分析的資源，資源可能是網站或是APP (ISO或是Android) :

接下來就按照它上面所引導的步驟把必要的資訊一一填入:

我們需要分析的是部落格，所以這邊選擇網站:

把網站的資訊填入:

之後會挑出來Google Analytics所產生的JS程式碼:

複製前面的程式碼，貼到Ghost Blog管理介面裡Settings > Code injection的Header裡面:

接下來進入部落格重新整理一下，去看Google Analytics的報表上有沒有產生瀏覽紀錄，如果有代表已經完成了:

Google News Sitemap

參照Ghost的教學文章，新增sitemap.hbs:


  
    {{#get "posts" filter="published_at:>now-2d" limit="1000" include="tags"}}
      {{#foreach posts}}
        
          {{url absolute="true"}}
          
            
              {{@site.title}}
              {{@site.locale}}
            
            {{#has visibility="members"}}
            Registration
            {{/has}}
            {{#has visibility="paid"}}
            Subscription
            {{/has}}
            {{date published_at format="YYYY-MM-DDTHH:mm:ssZ"}}
            {{title}}
            {{tags limit="5" autolink="false"}}
          
        
      {{/foreach}}
    {{/get}}

更新route.yaml，在routes新增以下這段:

routes:
  /sitemap/:
    template: sitemap
    content_type: text/xml

進入Google Search Console確認Google是否有偵測到sitemap，因為目前只有這個網站需要使用sitemap的功能，所以選擇右邊的選項填入網站的名稱:

因為之前已經完成了Google Analytics的連結，所以可以直接驗證為擁有者:

點選左方的Sitemap選項:

填入剛剛創建的sitemap網址，最後看到成功就代表完成了:

結論

到這裡關於Ghost Blog的設定基本上就完成了，之後如果有新增功能會以較為短篇的文章記錄。