Python 樣式指南

Fuchsia 專案遵循 Google Python 樣式指南,其中有幾項修正

Google Python 樣式指南提供更多變化 (可涵蓋大量現有來源)。本指南提供更嚴謹的選項。因此,Fuchsia Python 檔案也必須符合 Google 樣式指南的規定,但 Google Python 檔案可能不符合本指南的規定。詳情請參閱下方的修正項目

Python 版本

建構作業叫用的指令碼

由建構 (GN 或 Ninja) 叫用的指令碼是以 Python 3.8 執行。

建構系統可確保所有 Python 指令碼均由解譯器執行,且該解譯器會在 Fuchsia 來源結帳過程中進行安裝。

其他指令碼

直接叫用的指令碼應在前端使用 python,並與 2 和 3 相容:#!/usr/bin/env python

開發 Fuchsia 模組的開發人員可能會使用多種平台。部分平台包含 Python 2,而非 Python 3,反之亦然。在我們支援的知名開發環境之前,我們應支援 Python 2。

雖然支援 Python 2,但這兩種版本的測試指令碼。

任何政策異動都會反映在這份文件中。

多項繼承

我們不建議使用多個繼承。這和 Google C++ 樣式指南:「菱形」繼承的風險」模式相同,而容易造成混淆。如果發現避免多次繼承的案例不合理,則所有相關類別一開始都必須從基礎類別 object 繼承,而該類別控管了使用多個繼承配置。

對文字使用 Unicode

在支援 Python 2.x 的指令碼中 (請參閱 Python 版本),請分別使用 u""unicode()unichr()b""bytes()byte(),將文字字串明確宣告為萬國碼 (Unicode),以及二進位資料為位元組。Python 3.x 預設針對字串使用萬國碼 (Unicode),因此在支援 Python 2 時移除本指南。

Yes:

  a = u"Hello"  # Unicode constant.
  b = unicode(foo)  # Convert to Unicode.
  c = unichr(c)  # Convert to Unicode.
  d = io.open("bar.txt").read()  # Read text as Unicode.
No:

  a = "Hello"  # Ambiguous (depends on Python version).
  b = str(foo)  # Convert to ascii.
  c = chr(c)  # Convert to ascii.
  d = open("bar.txt").read()  # Read text as ascii.

分類標籤

我們對 Google Python 樣式指南所做的以下調整主要在切換不同版本時主要會選擇。舉例來說,如果樣式指南指出您可以執行 A、B 或 C,我們可能會選擇採用 B,並避免採用其他選項。

縮排

避免與開頭分隔符號對齊。建議您改用固定縮排 (4 個空格) 縮排。

(請參閱 Google Python 樣式指南中的縮排來進行比較。)

對帳單

避免建立單行陳述式,即使是使用 if 陳述式也沒問題。

Yes:

    if foo:
        bar(foo)
No:

    if foo: bar(foo)

(如需比較資訊,請參閱 Google Python 樣式指南中的陳述式)。

類型註解

在支援 Python 2 的指令碼中 (請參閱 Python 版本),系統就不會使用類型註解。

(如需比較,請參閱 Google Python 樣式指南中的 Type 註解)。

字串

字串應使用雙引號 (")。當宣告更容易透過單引號閱讀時,請使用單引號。例如,'The cat said "Meow"'"The cat said \\"Meow\\"" 更易讀取。

(如需比較資訊,請參閱 Google Python 樣式指南中的字串)。

保持一致

範圍一致。避免在 Fuchsia 中顯示少量一致性資料。只存在於單一檔案或目錄內並不一致。

third_party 中,意圖是遵循該專案或程式庫的現有樣式。視情況在該程式庫中尋找樣式指南。

(請參閱 Google Python 樣式指南中的部分字詞)。