Ruff ty 類型檢查器規(guī)則解析invalid-legacy-positional-parameter 與 Python 位置參數(shù)的兩代約定【免費下載鏈接】ruffAn extremely fast Python linter and code formatter, written in Rust.項目地址: https://gitcode.com/GitHub_Trending/ru/ruff本篇技術(shù)指南圍繞 Ruff 倉庫中 ty 類型檢查器位于crates/ty_python_semantic等 crate入口參見 crates/ty/README.md的invalid-legacy-positional-parameter規(guī)則展開說明它為何檢測以__雙下劃線開頭卻無法被類型檢查器識別為僅限位置positional-only參數(shù)的寫法并從 PEP 484 遺留約定、PEP 570 正式語法到該規(guī)則的源碼實現(xiàn)層層拆解。讀完本文你將理解這條 lint 的觸發(fā)條件與邊界掌握修正舊式位置參數(shù)寫法的兩種方案并能定位其檢查邏輯、AST 判定函數(shù)與簽名構(gòu)建流程的源碼位置在實際項目中準確復(fù)現(xiàn)與規(guī)避該診斷。規(guī)則定位它在檢查什么該規(guī)則的官方文檔位于 crates/ty_python_semantic/resources/lint_docs/invalid-legacy-positional-parameter.md語義描述為檢查那些試圖使用遺留約定legacy convention聲明某個參數(shù)為 positional-only但寫法并不正確the parameter appears right after a normal positional-or-keyword parameter的情況。圍繞這條規(guī)則有兩代僅限位置參數(shù)的規(guī)范需要厘清PEP 484 遺留約定legacy conventionPEP 484 規(guī)定對于名稱以__開頭且不以__結(jié)尾的參數(shù)類型檢查器應(yīng)當將其視為 positional-only。這套約定只對靜態(tài)類型檢查器生效Python 運行時并不會因此限制調(diào)用方式。PEP 570 正式語法Python 3.8在函數(shù)參數(shù)列表中使用/分隔符顯式聲明其左側(cè)的所有參數(shù)為 positional-only。該語法自 Python 3.8 起可用使 PEP 484 的__命名約定變得過時。正因如此仍有一些代碼庫為了兼容 Python 3.7 及更早版本而繼續(xù)沿用__命名約定——這正是invalid-legacy-positional-parameter規(guī)則存在的意義它不是要禁用遺留約定而是要攔截錯誤地使用遺留約定的情況。為什么這種寫法是錯的按 PEP 484 的約定類型檢查器只會把處于參數(shù)列表最前面一段連續(xù)位置即所有 positional-or-keyword 參數(shù)之前的__前綴參數(shù)視為 positional-only。一旦某個__前綴參數(shù)出現(xiàn)在一個普通的 positional-or-keyword 參數(shù)之后類型檢查器就不會再把它當作 positional-only而只會當它是一個以__開頭的普通參數(shù)。這往往與代碼作者的預(yù)期相?！髡咭詾橐呀?jīng)借命名約定了禁用關(guān)鍵字傳參實際并沒有。觸發(fā)示例與兩種修復(fù)方案規(guī)則文檔給出了最典型的錯誤樣例# __y 不會被類型檢查器視為 positional-only def f(x, __y): # error pass由于x是一個 positional-or-keyword 參數(shù)且排在__y之前類型檢查器無法把__y歸入前導(dǎo) positional-only 段于是觸發(fā)本規(guī)則。修正方法有兩條路徑取決于你愿意支持的最低 Python 版本方案一讓所有 positional-only 參數(shù)連續(xù)排在最前兼容 Python 3.7def f(__x, __y): # 需要兼容 Python 3.7 時使用 pass把x也改名為__x使__前綴參數(shù)形成從參數(shù)列表開頭連續(xù)的一段滿足 PEP 484 遺留約定對前導(dǎo)位置的要求。方案二升級到 Python 3.8 的顯式/語法def f(x, y, /): # Python 3.8 語法 pass/之前的x、y均被顯式聲明為 positional-only。這條路徑不依賴任何命名技巧語義最清晰也是現(xiàn)代代碼的首選。實踐中的邊界情況從源碼實現(xiàn)可以確認該規(guī)則還有幾個值得注意的邊界已使用 PEP 570 語法時不再做遺留約定檢查檢查函數(shù)會先判斷 AST 參數(shù)列表中是否已存在/聲明的 positional-only 參數(shù)posonlyargs若存在則整個跳過本次檢查見下文源碼解析避免新舊語法混用場景下產(chǎn)生噪聲。真正的 dunder 名稱不會被誤傷規(guī)則命中的條件是名稱以__開頭且不以__結(jié)尾因此__init__、__call__這類 dunder 方法參數(shù)不會被當作遺留約定的使用者。方法隱式收參self/cls會先占位在方法簽名構(gòu)建時隱式收參會先被排入 positional-only 段見下文簽名構(gòu)建邏輯其后緊跟的__前綴參數(shù)仍可被正確識別。源碼級解讀規(guī)則如何落地下面沿規(guī)則聲明 → 函數(shù)入口 → 判定邏輯 → AST 判定方法 → 簽名構(gòu)建這條鏈梳理實現(xiàn)所有路徑均以當前倉庫為準。規(guī)則聲明默認級別與穩(wěn)定版本規(guī)則通過declare_lint!宏聲明于 crates/ty_python_semantic/src/types/diagnostic.rssummarydetects incorrect usage of the legacy convention for specifying positional-only parametersdefault_levelWarn默認警告級不作為錯誤阻斷statusstable(0.0.15)即自 0.0.15 版本起穩(wěn)定可用同一規(guī)則也登記于 crates/ty/docs/rules.md 的規(guī)則總表中該 lint 在運行時通過registry.register_lint(INVALID_LEGACY_POSITIONAL_PARAMETER)注冊見 diagnostic.rs。檢查入口與觸發(fā)點函數(shù)定義的各類診斷在check_function_definition中統(tǒng)一調(diào)度其中就包含對遺留約定的專項檢查調(diào)用見 post_inference/function.rs。需要說明的是進入該函數(shù)之前帶有不進行類型檢查類裝飾器no_type_check的函數(shù)定義會被提前返回從而整體跳過包括本規(guī)則在內(nèi)的一批函數(shù)級診斷見 function.rs。核心判定函數(shù)判定主體為check_legacy_positional_only_convention位于 post_inference/function.rs。其邏輯要點如下前置過濾若ast_parameters.posonlyargs非空即函數(shù)已顯式使用 PEP 570/語法直接返回不做遺留約定檢查。配對遍歷將 AST 參數(shù)節(jié)點與解析后的簽名參數(shù)signature.parameters()按位置一一配對逐一跳過變長參數(shù)*args等。雙階段識別對某個__前綴參數(shù)而言合法的遺留約定用法會在簽名構(gòu)建階段被識別并標記為 positional-only從而在這里被continue跳過只有那些沒有被識別為 positional-only、卻仍然以__開頭即uses_pep_484_positional_only_convention()返回 true的參數(shù)才會走到報告邏輯——這正好印證了文檔所述排在 positional-or-keyword 參數(shù)之后的__參數(shù)是無效遺留約定。診斷信息命中時報告主注解消息Parameter name begins with__but will not be treated as positional-only附加說明infoA parameter can only be positional-only if it precedes all positional-or-keyword parameters若存在更早出現(xiàn)的普通參數(shù)則在其名稱上追加輔助注解Prior parameter here was positional-or-keyword幫助用戶一眼定位破壞前導(dǎo)連續(xù)性的那個參數(shù)。同時函數(shù)維護previous_non_positional_only游標遇到第一個非 positional-only 參數(shù)后就不再更新用于給后續(xù)所有無效__參數(shù)提供參照物注解。AST 層的判定方法是否是 PEP 484 遺留約定的寫法這一判斷被封裝在 AST 節(jié)點的工具方法中見 crates/ruff_python_ast/src/nodes.rs/// Return true if the parameter name uses the pre-PEP-570 convention /// (specified in PEP 484) to indicate to a type checker that it should be treated /// as positional-only. pub fn uses_pep_484_positional_only_convention(self) - bool { let name self.name(); name.starts_with(__) !name.ends_with(__) }即__foo、__bar命中__init__、__self__這類 dunder 因為以__結(jié)尾而被排除。簽名構(gòu)建為何前導(dǎo)連續(xù)才有效若要真正理解為什么__y跟在x后面就失效需要看簽名構(gòu)建階段的處理見 crates/ty_python_semantic/src/types/signatures.rs首先收集 PEP 570 顯式聲明的 positional-only 參數(shù)posonlyargs僅當顯式 positional-only 參數(shù)為空時才回退去識別 PEP 484 遺留約定若函數(shù)存在隱式位置收參如方法中的self/cls對應(yīng)has_implicitly_positional_first_parameter先把它作為 positional-only 放入隨后用peeking_take_while從頭連續(xù)地吞下所有uses_pep_484_positional_only_convention()為真的參數(shù)并把它們標記為ParameterKind::PositionalOnlytake_while意味著一旦遇到第一個不符合約定的參數(shù)后續(xù)即使再出現(xiàn)__前綴參數(shù)也不會再被吞入它們將落入普通的PositionalOrKeyword段——于是排在中途的__參數(shù)就必然成為invalid-legacy-positional-parameter的靶子。這條實現(xiàn)鏈條清晰印證了規(guī)則文檔的核心結(jié)論legacy 約定下一個參數(shù)要成為 positional-only必須位于所有 positional-or-keyword 參數(shù)之前。如何運行與驗證該類型檢查器在倉庫內(nèi)以獨立的tybin 形式提供可通過 Cargo 直接運行見 crates/ty/CONTRIBUTING.mdcargo run --bin ty -- check /path/to/project/ty check會檢查項目中的類型錯誤由于invalid-legacy-positional-parameter的默認級別是warn在不額外配置時它就會出現(xiàn)在輸出中可用于直觀驗證上文的觸發(fā)與修復(fù)示例。想要快速做一次驗證可以建一個臨時文件寫入def f(x, __y): pass再對其執(zhí)行ty check。與其他規(guī)則的關(guān)聯(lián)在同一個 lint 文檔目錄中還存在語義互補的兄弟規(guī)則 positional-only-parameter-as-kwarg它檢測的是調(diào)用側(cè)把 positional-only 參數(shù)按關(guān)鍵字傳入的誤用而invalid-legacy-positional-parameter關(guān)注的是定義側(cè)用遺留命名約定聲明 positional-only 卻聲明失敗的問題。二者分別從函數(shù)定義與函數(shù)調(diào)用兩個方向守護 positional-only 語義的一致性與正確性。小結(jié)invalid-legacy-positional-parameter是一條面向歷史兼容代碼的類型檢查 lint它允許你在仍支持 Python ≤ 3.7 的前提下沿用 PEP 484 的__命名約定但會堅決攔截試圖用遺留約定聲明、卻因位置靠后而實際無效的參數(shù)。修復(fù)時優(yōu)先推薦遷移到 Python 3.8 的/顯式語法若必須保持舊運行時兼容則將__前綴參數(shù)整理到參數(shù)列表最前的連續(xù)區(qū)間即可。要深入掌握這條規(guī)則建議依次閱讀 規(guī)則文檔、規(guī)則聲明、核心判定邏輯 與 簽名構(gòu)建邏輯四者合起來即是約定是什么、為什么錯、何時報告、底層如何判定的完整答案?！久赓M下載鏈接】ruffAn extremely fast Python linter and code formatter, written in Rust.項目地址: https://gitcode.com/GitHub_Trending/ru/ruff創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考