PythonCodingGuidelines
1.0.0
Python 編碼指南是一組經過驗證的關於 Python 編碼的指南、規則和最佳實踐。
該指南的目的是幫助開發人員有效地使用Python並提供更具可讀性的現代Python風格。易於維護和擴展的程式碼。此外，還建立了在 Python 中開發應用程式或程式庫時應遵循的開發標準。
希望這篇文件也能幫助您開始使用Python。如果您來自其他腳本語言（例如 JavaScript），您會發現 Python 非常相似，而本文檔是過渡到 Python 的一種方法。
該指南重點關注 PEP8 標準中通常定義的 Python 語言提供的所有資源。 PEP8 這裡的 PEP8 僅用作此編碼指南提案的基礎。我想推廣一種更具可讀性和現代性的Python風格。
您可能會發現本指南的某些規則與您的期望相反，甚至與您的經驗相反。
如果我沒有建議你以任何方式改變你的程式設計風格，我就失敗了！
請嘗試驗證或反駁本指南的規則。特別是，我真的希望一些提議的規則能夠得到更好的範例的測量支持。
是軟體開發的一般規則，旨在製作可讀、可維護和可擴展的應用程式。這並不總是事實，但我們致力於實現這一目標。
程式碼標準是有助於利用上述三元組原則建立應用程式的工具。以下是建立一致的開發標準所帶來的一些好處：
️ 警告：這是一份正在不斷改進的動態文檔。歡迎提出改進意見和建議。隨著我們理解的提高和可用庫集的語言的發展，我計劃修改和擴展本文檔。
| 姓名 | 習俗 | 程式碼範例 |
|---|---|---|
| 單一變數名 | 蛇箱 | age: int = 100 |
| 複合變數名 | 蛇箱 | first_name: str = "Akira" |
| 常數名稱 | 常量 | CPU: number = 8 |
| 複合常數名 | 常量 | MAX_NUMBER: number = 100 |
| 枚舉名稱 | 帕斯卡案例 | class Color(Enum): RED = 1 GREEN = 2 |
| 函數名 | 蛇箱 | def main() |
| 帶參數的函數 | 蛇箱 | def calculate(n1: int, n2: int) |
| 有返回類型的函數 | 蛇箱 | def calculate(n1: int, n2: int) -> int: |
| 複合函數名 | 蛇箱 | def add_two_numbers(n1: int, n2: int) -> int: |
| 類別名 | 帕斯卡案例 | class Base |
| 複合類別名 | 帕斯卡案例 | class MyClass |
| 介面 | 帕斯卡案例 | class IUser(ABC) |
| 鑄件 | 預設 | age: int = int(100) |
| 清單 | 駝色箱 | myList: list[int] = [1,2,3] |
| 元組 | 駝色箱 | myTuple: tuple[int] = (1,2,3) |
| 放 | 蛇箱 | my_set: set[int] = {1,2,3} |
| 字典 | 蛇箱 | my_dictionary: dict = {"name": "John", "age": 100} |
| 多種類型提示 | 蛇箱 | var_a: Union[int, str] |
我們建議對 Python 文件使用 Google Doc Style，因為它最容易閱讀和理解。 Google 風格指南在 Python 社群中也非常流行且廣泛使用。
def add_binary ( a : int , b : int ) -> int :
"""
Returns the sum of two decimal numbers in binary format.
Parameters:
a (int): First number to add
b (int): Second number to add
Returns:
binary (int): Binary int of the sum of a and b
"""
binary_sum = bin ( a + b )[ 2 :]
return int ( binary_sum )類型提示是靜態指示值類型的正式解決方案。
例子：
def addBinary(a: int, b: int)-> int:
...
在上面的函數中，明確該函數等待變數a和b中的int值，並傳回int值。
檢查此連結：Python 打字官方文檔
但Python不是一種無型別語言嗎？是的，不是。如果您傳遞任何不同於int值，它就會起作用。
如何檢查Python中的型別命中？
您應該使用mypy庫。
Mypy 是 Python 的可選靜態類型檢查器，旨在結合動態（或「鴨子」）類型和靜態類型的優點。 （來源：官方文件）
pip install mypy
mypy mycode.py
對 python 使用 linter 的想法是強制執行本文檔中提出的編碼指南。我將使用預提交。
pip install pre-commit
基本配置：
.pre-commit-config.yml來儲存預提交配置在下面的範例中，腳本將執行以下步驟：
例子：
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.3.0
hooks:
- id: check-yaml
- id: end-of-file-fixer
- id: trailing-whitespace
- id: check-json
- id: detect-private-key
- repo: https://github.com/PyCQA/isort
rev: 5.12.0
hooks:
- id: isort
- repo: https://github.com/psf/black
rev: 22.12.0
hooks:
- id: black
language_version: python3.10
- repo: https://github.com/charliermarsh/ruff-pre-commit
rev: 'v0.0.260'
hooks:
- id: ruff
pyproject.toml來保存預提交運行器配置例子：
[tool.black]
line-length = 80
target-version = ['py310']
include = '.pyi?$'
[tool.isort]
line_length = 79
multi_line_output = 3
include_trailing_comma = true
force_grid_wrap = 0
use_parentheses = true
ensure_newline_before_comments = true
進行此配置後，每次提交時都會執行預提交
預先提交官方文檔
建議用於測試的框架是 pytest。它也是一個非常流行的Python測試框架。
tests資料夾： pytest
pytest --cov . 
有關更多 pytest 命令，請參閱此處的官方文檔 pytest
以下是測試函數定義的範例：
建立函數後，如下例所示： 
您可以按照以下步驟建立單元測試：
test_ 。
要啟動一個新項目，您可以使用以下命令克隆該項目：
git clone https://github.com/rsaz/python-project-template這是建議的項目預設結構。
專案結構基於以下內容：
| 資料夾/文件 | 描述 |
|---|---|
| 實用程式 | PowerShell 腳本可讓您建立、啟用、停用和刪除環境，以及更新和建立依賴項 |
| .vscode | 編輯器特定配置 |
| 原始碼 | 專案主來源資料夾 |
| 測試 | 包含所有應用程式單元測試的資料夾 |
| 維尼夫 | Python虛擬環境 |
| .pylintrc | Python pylint 靜態程式碼分析器的設定檔 |
| pytest.ini | pytest的設定檔 |
| 許可證.txt | 專案授權條款 |
| 自述文件.md | 項目詳情 |
| 要求.txt | 專案依賴 |
| setup.cfg 和 setup.py | 專案初始配置 |
