范化：`sort_class.py` 方法排序工具實(shí)戰(zhàn)指南)
開發(fā)工具【免費(fèi)下載鏈接】PyGithubTyped interactions with the GitHub API v3項(xiàng)目地址https://gitcode.com/gh_mirrors/py/PyGithub點(diǎn)擊查看免費(fèi)下載本文面向 PyGithub 的維護(hù)者與二次開發(fā)者系統(tǒng)講解如何利用scripts/sort_class.py讓所有繼承GithubObject的類嚴(yán)格遵循 ARCHITECTURE.md 中定義的 “Internal Class Order” 約定并在--dry-run只讀模式下安全預(yù)覽改動、確認(rèn)后再落盤。讀完本文你將掌握該腳本的命令行用法、參數(shù)語義、底層排序邏輯基于 libcst 的 AST 重排以及它與openapi.py索引機(jī)制之間的協(xié)作關(guān)系可直接接入現(xiàn)有開發(fā)與貢獻(xiàn)流程。一、背景為什么 PyGithub 需要對類成員排序PyGithub 是 GitHub REST API v3 的 Python 類型化客戶端其github/目錄下存在大量繼承GithubObject的類如Autolink、HookDelivery、Repository等每個類都要維護(hù)私有屬性聲明、特殊方法、property訪問器、公開方法和_useAttributes回填邏輯。隨著openapi.py腳本從 GitHub REST API 的 OpenAPI 規(guī)范自動生成、更新代碼成員順序很容易被打亂。sort_class.py的目的正是“讓 PyGithub 類符合既定的方法與方法順序約定”Sort methods in PyGithub classes從而保證全倉庫代碼風(fēng)格統(tǒng)一降低人工 review 負(fù)擔(dān)讓openapi.py腳本基于穩(wěn)定結(jié)構(gòu)做增量更新見 doc/scripts.rst 中 Thescripts/openapi.pyscript works best when attributes and methods are sorted. 的說明使 diff 更小、更可讀便于維護(hù)者逐類審查自動生成的改動。注意該腳本只適用于繼承GithubObject含CompletableGithubObject、NonCompletableGithubObject等派生基類的類普通輔助類不在排序范圍內(nèi)詳見下文源碼解析中的基類判定邏輯。二、先決條件openapi.index索引文件腳本的第一個位置參數(shù)是索引文件路徑通常名為openapi.index它由scripts/openapi.py的index命令生成python3 scripts/openapi.py index github/ api.github.com.2022-11-28.json openapi.index該索引是一個 JSON 文件記錄了 OpenAPI spec 與 PyGithub 代碼庫的映射關(guān)系。SKILL 文檔明確提示如果索引文件尚不存在必須先用openapi.py創(chuàng)建它具體工作流參見 .claude/skills/openapi/SKILL.md。該 SKILL 還強(qiáng)調(diào)索引文件與生成它所使用的 OpenAPI spec 文件如api.github.com.2022-11-28.json是緊密綁定的更換 spec 就需要重新生成索引。SKILL 文檔的 frontmatter 開頭有一行from scripts import openapi/from scripts.sort_class import sort_class這指示本技能依賴scripts/目錄下的兩個模塊即openapi.py負(fù)責(zé)生成索引與sort_class.py負(fù)責(zé)排序兩者必須配套使用。三、命令行用法與參數(shù)詳解3.1 基本調(diào)用形式SKILL 文檔給出的標(biāo)準(zhǔn)命令為python scripts/sort_class.py --dry-run openapi.index class1 class2 ...從 doc/scripts.rst 與腳本自帶的 argparse 幫助可以還原出完整的 usageusage: sort_class.py [-h] [--dry-run] index_filename class_name [class_name ...] Sorts methods of GithubObject classes, also sorts attributes in _initAttributes and _useAttributes positional arguments: index_filename Path of index file class_name GithubObject class to sort, e.g. HookDelivery or github.HookDelivery.HookDeliverySummary options: -h, --help show this help message and exit --dry-run show prospect changes and do not modify the file參數(shù)語義與 scripts/sort_class.py 中parse_args()的實(shí)現(xiàn)一一對應(yīng)參數(shù)類型說明index_filename位置參數(shù)openapi.index索引文件路徑用于將類名解析為源文件路徑class_name位置參數(shù)nargs可傳多個要排序的GithubObject類名可傳簡單類名如HookDelivery或全限定名如github.HookDelivery.HookDeliverySummary--dry-run布爾開關(guān)默認(rèn)False只展示將產(chǎn)生的改動unified diff不修改任何文件class_name的兩種寫法說明簡單類名腳本會到索引的classes表中查package、module、name拼出全限定名scripts/sort_class.py全限定名含.直接按package.module.Class三段拆分適用于需要精確指定嵌套類如github.HookDelivery.HookDeliverySummary對應(yīng) github/HookDelivery.py 中的嵌套類的場景。腳本根據(jù)解析結(jié)果把文件定位到{package}/{module}.py例如github/Autolink.py。若傳了多個類會打印Sorting N Python files的提示并使用multiprocessing.Pool對多個文件并行排序main()中每個文件分配獨(dú)立的manager.Lock防并發(fā)寫沖突見 scripts/sort_class.py。3.2 干跑dry-run與正式應(yīng)用SKILL 文檔強(qiáng)調(diào)了一條安全工作流始終先用--dry-run只讀預(yù)覽——它不會改動任何文件只輸出類名和對應(yīng)的 unified diff將改動展示給用戶評審征得同意后再執(zhí)行正式命令若用戶明確同意應(yīng)用且無需再次評審去掉--dry-run重新執(zhí)行即可落盤。對應(yīng)實(shí)現(xiàn)dry_runTrue時腳本用difflib.unified_diff打印舊代碼與新代碼的差異通過stdout鎖串行輸出避免多進(jìn)程交錯只有dry_runFalse且tree_updated.deep_equals(tree)為假時才真正寫回文件scripts/sort_class.py。# 1. 只讀預(yù)覽推薦 python scripts/sort_class.py --dry-run openapi.index Autolink HookDelivery # 2. 評審?fù)ㄟ^后正式應(yīng)用 python scripts/sort_class.py openapi.index Autolink HookDelivery3.3 一次性排序所有類雖然 SKILL 文檔的調(diào)用形式是按類名逐個排序但倉庫中的 scripts/openapi-update-classes.sh 展示了批量場景該腳本用jq從索引讀取GithubObject的所有子孫類class_to_descendants過濾掉繼承自ABC的抽象類后把全部具體類一次性傳給sort_class.py見 scripts/openapi-update-classes.sh 與update()中的調(diào)用。這印證了腳本nargs設(shè)計就是為了支持“給定一個類或多個類或全部類”的批量需求。四、排序規(guī)則Internal Class Order排序邏輯并非隨意為之而是嚴(yán)格遵循 ARCHITECTURE.md 中 Internal Class Order 一節(jié)的約定。該約定要求的類內(nèi)成員順序?yàn)開initAttributes() dunder methods (alphabetical: __eq__, __hash__, __repr__, __str__, …) property (one per attribute, alphabetical by name) public methods _useAttributes()補(bǔ)充約束_useAttributes永遠(yuǎn)是類中最后一個方法Dunder 方法__name__形式的特殊方法緊跟在_initAttributes()之后按字母序排列。PyGithub 類中最常見的有__eq__(self, other)自定義相等性如NamedUser按login與id比較__hash__(self)凡定義__eq__必須同時定義__repr__(self)每個類都有通常使用self.get__repr__({key: self._key.value})__str__(self)需要人類可讀的單行字符串時使用如CodeScanAlertInstanceLocation公開方法擁有大量方法的類會把相關(guān)操作聚成一塊放在主方法之后例如所有 reaction 方法get_reactions→create_reaction→delete_reaction作為一組sub-issue 方法同理。五、源碼級實(shí)現(xiàn)原理libcst AST 重排排序能力由 scripts/sort_class.py 中的SortMethodsTransformer繼承cst.CSTTransformer實(shí)現(xiàn)它用libcst把 Python 源碼解析成具體語法樹CST在保留注釋、空白、引號風(fēng)格的前提下安全地重排節(jié)點(diǎn)。核心流程如下5.1 類級排序leave_ClassDef范圍過濾若指定了class_name僅處理當(dāng)前類否則處理所有類scripts/sort_class.py基類判定檢查類的所有基類名是否以GithubObject結(jié)尾含cst.Name與屬性訪問兩種形態(tài)不滿足則跳過——這正是“只作用于 GithubObject 類”的機(jī)制scripts/sort_class.py健壯性校驗(yàn)若類中沒有任何函數(shù)、或函數(shù)不構(gòu)成連續(xù)塊中間夾雜非函數(shù)語句直接拋出ValueError防止破壞代碼結(jié)構(gòu)scripts/sort_class.py分桶重排把函數(shù)塊拆成prolog函數(shù)前的類級語句如 docstring、__init__、_initAttributes、dunder 方法集合、property方法集合、其余公開方法、_useAttributes、epilog函數(shù)后的尾隨語句然后按約定順序重組prolog __init__ _initAttributes dunders(字母序) properties(字母序) public methods _useAttributes epilogscripts/sort_class.py其中 dunder 與 property 集合會按方法名做字母排序sort_func_defs而公開方法僅在sort_funcsTrue時排序默認(rèn)保持原有相對順序以尊重人工對方法分組/cluster 的編排ARCHITECTURE 中提到的方法聚類慣例。5.2 屬性級排序leave_FunctionDefSortMethodsTransformer還深入兩個特殊方法的函數(shù)體內(nèi)部_initAttributes找出函數(shù)體中連續(xù)的AnnAssign帶類型注解的賦值語句塊按屬性名self._xxx的xxx字母序排序scripts/sort_class.py。這對應(yīng) ARCHITECTURE 的要求“所有私有屬性字段按字母序每個都帶類型并初始化為NotSet”_useAttributes找出函數(shù)體中連續(xù)的if xxx in attributes分支塊按分支測試的屬性名排序scripts/sort_class.py。5.3 一個已排序的范例以 github/Autolink.py 為例其成員順序完全符合約定class Autolink(NonCompletableGithubObject): ... def _initAttributes(self) - None: # 1. 屬性聲明字母序 self._id: Attribute[int] NotSet self._is_alphanumeric: Attribute[bool] NotSet self._key_prefix: Attribute[str] NotSet self._updated_at: Attribute[datetime] NotSet self._url_template: Attribute[str] NotSet def __repr__(self) - str: # 2. dunder return self.get__repr__({id: self._id.value}) property # 3. property 訪問器字母序 def id(self) - int: return self._id.value property def is_alphanumeric(self) - bool: return self._is_alphanumeric.value # ... key_prefix / updated_at / url_template 依次排列 def _useAttributes(self, attributes: dict[str, Any]) - None: # 4. 最后一個方法 if id in attributes: # pragma no branch self._id self._makeIntAttribute(attributes[id]) if is_alphanumeric in attributes: # pragma no branch self._is_alphanumeric self._makeBoolAttribute(attributes[is_alphanumeric]) # ...可以看到_useAttributes中的if分支同樣按屬性名字母序排列。這正是運(yùn)行sort_class.py之后類應(yīng)呈現(xiàn)的標(biāo)準(zhǔn)形態(tài)。六、實(shí)際工作流在 OpenAPI 更新流程中的位置sort_class.py并非孤立工具它是 PyGithub 自動化更新管線的一環(huán)。在 scripts/openapi-update-classes.sh 的update()函數(shù)中每個類的處理順序?yàn)閛penapi.py suggest schemas --add # 為類補(bǔ)充 OpenAPI schema openapi.py index # 重建索引 sort_class.py index classes # 先排序類成員本次主題 openapi.py apply properties # 應(yīng)用屬性到源碼 openapi.py apply properties --tests # 同步測試文件 prepare-for-update-assertions.py update-assertions.sh # 更新斷言 pytest testAttributes # 運(yùn)行屬性測試每一步之后都會以 “Sort attributes and methods in $class” 之類的信息提交。從該腳本還可以看到sort_class.py被獨(dú)立運(yùn)行$python $sort_class $index ${classes[]}即排序是先于schema 應(yīng)用執(zhí)行的、獨(dú)立的代碼整理步驟——先保證結(jié)構(gòu)穩(wěn)定再做增量修改。因此如果參與 PyGithub 的貢獻(xiàn)流程推薦的手動操作序列為# 0) 確保索引存在若缺失 python3 scripts/openapi.py index github/ api.github.com.2022-11-28.json openapi.index # 1) 預(yù)覽指定類的排序改動 python scripts/sort_class.py --dry-run openapi.index HookDelivery # 2) 評審后正式應(yīng)用 python scripts/sort_class.py openapi.index HookDelivery # 3) 運(yùn)行 lint 與類型檢查openapi 技能要求 pre-commit run --all-files mypy github tests七、常見問題與注意事項(xiàng)索引缺失直接運(yùn)行sort_class.py會因找不到openapi.index而報錯。先按 .claude/skills/openapi/SKILL.md 的initfetch index流程生成索引文件索引過期任何對 PyGithub 源碼的改動新增類、改名、移動文件都要求重新執(zhí)行openapi.py index更新索引否則類名解析可能失敗或指向錯誤文件類名不存在簡單類名在索引的classes中查不到時main()會拋出ValueError(fClass {class_name} does not exist in index)scripts/sort_class.py--dry-run是安全邊界建議把它當(dāng)作默認(rèn)習(xí)慣正式應(yīng)用前務(wù)必確認(rèn) diff 內(nèi)容符合 Internal Class Order 預(yù)期非 GithubObject 類會被自動跳過不需要手工規(guī)避腳本按基類名自動判斷多類并行同時傳入多個類時腳本并行排序但通過文件級鎖保證同一文件不會被并發(fā)寫壞可以放心批量使用。八、小結(jié)sort_class.py以一行命令將 PyGithub 類成員順序收斂到 ARCHITECTURE.md 規(guī)定的統(tǒng)一形態(tài)是 OpenAPI 自動更新體系中的“穩(wěn)定器”先排序、再應(yīng)用 schema、最后同步測試與斷言。其核心實(shí)現(xiàn)libcst AST 變換 多進(jìn)程并行 文件鎖既保證了重排的安全性也保證了批量處理的效率。維護(hù)者與貢獻(xiàn)者只要遵循“先--dry-run評審、再正式應(yīng)用”的流程即可讓倉庫中每一個GithubObject類都保持清晰、一致、可機(jī)器處理的結(jié)構(gòu)。參考資源技能文檔.claude/skills/sorted-classes/SKILL.md腳本源碼scripts/sort_class.py排序約定ARCHITECTURE.mdInternal Class Order 一節(jié)索引生成前置.claude/skills/openapi/SKILL.md 與 scripts/openapi.py文檔說明doc/scripts.rstScript sort_class.py 一節(jié)集成腳本scripts/openapi-update-classes.sh已排序范例github/Autolink.py贊分享開發(fā)工具【免費(fèi)下載鏈接】PyGithubTyped interactions with the GitHub API v3項(xiàng)目地址https://gitcode.com/gh_mirrors/py/PyGithub點(diǎn)擊查看免費(fèi)下載相關(guān)推薦Terminal.Gui 代碼布局規(guī)范Backing Field 與成員排序的工程實(shí)踐指南Terminal.Gui 代碼布局規(guī)范Backing Field 與成員排序的工程實(shí)踐指南 本篇技術(shù)指南聚焦于 Terminal.Gui.NET 跨平臺終端UI組件跨平臺桌面應(yīng)用VisiData 排序完全指南列類型、多級排序與排序順序查看VisiData 排序完全指南列類型、多級排序與排序順序查看 VisiData 是一款終端電子表格工具其內(nèi)置排序體系圍繞類型化值 排序優(yōu)先級 內(nèi)部數(shù)據(jù)分析CLI數(shù)據(jù)可視化eslint-plugin-unicorn 類成員順序規(guī)則實(shí)戰(zhàn)consistent-class-member-order 與快照測試深度剖析eslint plugin unicorn 類成員順序規(guī)則實(shí)戰(zhàn)consistent class member order 與快照測試深度剖析 本篇文章以 esLint代碼質(zhì)量上一篇5個實(shí)戰(zhàn)技巧深度優(yōu)化macOS鼠標(biāo)體驗(yàn)的開源利器下一篇VoiceFixer終極指南免費(fèi)AI音頻修復(fù)工具拯救受損聲音的完整教程創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 PyGithub 類成員順序規(guī)范化：`sort_class.py` 方法排序工具實(shí)戰(zhàn)指南
開發(fā)工具【免費(fèi)下載鏈接】PyGithubTyped interactions with the GitHub API v3項(xiàng)目地址https://gitcode.com/gh_mirrors/py/PyGithub點(diǎn)擊查看免費(fèi)下載本文面向 PyGithub 的維護(hù)者與二次開發(fā)者系統(tǒng)講解如何利用scripts/sort_class.py讓所有繼承GithubObject的類嚴(yán)格遵循 ARCHITECTURE.md 中定義的 “Internal Class Order” 約定并在--dry-run只讀模式下安全預(yù)覽改動、確認(rèn)后再落盤。讀完本文你將掌握該腳本的命令行用法、參數(shù)語義、底層排序邏輯基于 libcst 的 AST 重排以及它與openapi.py索引機(jī)制之間的協(xié)作關(guān)系可直接接入現(xiàn)有開發(fā)與貢獻(xiàn)流程。一、背景為什么 PyGithub 需要對類成員排序PyGithub 是 GitHub REST API v3 的 Python 類型化客戶端其github/目錄下存在大量繼承GithubObject的類如Autolink、HookDelivery、Repository等每個類都要維護(hù)私有屬性聲明、特殊方法、property訪問器、公開方法和_useAttributes回填邏輯。隨著openapi.py腳本從 GitHub REST API 的 OpenAPI 規(guī)范自動生成、更新代碼成員順序很容易被打亂。sort_class.py的目的正是“讓 PyGithub 類符合既定的方法與方法順序約定”Sort methods in PyGithub classes從而保證全倉庫代碼風(fēng)格統(tǒng)一降低人工 review 負(fù)擔(dān)讓openapi.py腳本基于穩(wěn)定結(jié)構(gòu)做增量更新見 doc/scripts.rst 中 Thescripts/openapi.pyscript works best when attributes and methods are sorted. 的說明使 diff 更小、更可讀便于維護(hù)者逐類審查自動生成的改動。注意該腳本只適用于繼承GithubObject含CompletableGithubObject、NonCompletableGithubObject等派生基類的類普通輔助類不在排序范圍內(nèi)詳見下文源碼解析中的基類判定邏輯。二、先決條件openapi.index索引文件腳本的第一個位置參數(shù)是索引文件路徑通常名為openapi.index它由scripts/openapi.py的index命令生成python3 scripts/openapi.py index github/ api.github.com.2022-11-28.json openapi.index該索引是一個 JSON 文件記錄了 OpenAPI spec 與 PyGithub 代碼庫的映射關(guān)系。SKILL 文檔明確提示如果索引文件尚不存在必須先用openapi.py創(chuàng)建它具體工作流參見 .claude/skills/openapi/SKILL.md。該 SKILL 還強(qiáng)調(diào)索引文件與生成它所使用的 OpenAPI spec 文件如api.github.com.2022-11-28.json是緊密綁定的更換 spec 就需要重新生成索引。SKILL 文檔的 frontmatter 開頭有一行from scripts import openapi/from scripts.sort_class import sort_class這指示本技能依賴scripts/目錄下的兩個模塊即openapi.py負(fù)責(zé)生成索引與sort_class.py負(fù)責(zé)排序兩者必須配套使用。三、命令行用法與參數(shù)詳解3.1 基本調(diào)用形式SKILL 文檔給出的標(biāo)準(zhǔn)命令為python scripts/sort_class.py --dry-run openapi.index class1 class2 ...從 doc/scripts.rst 與腳本自帶的 argparse 幫助可以還原出完整的 usageusage: sort_class.py [-h] [--dry-run] index_filename class_name [class_name ...] Sorts methods of GithubObject classes, also sorts attributes in _initAttributes and _useAttributes positional arguments: index_filename Path of index file class_name GithubObject class to sort, e.g. HookDelivery or github.HookDelivery.HookDeliverySummary options: -h, --help show this help message and exit --dry-run show prospect changes and do not modify the file參數(shù)語義與 scripts/sort_class.py 中parse_args()的實(shí)現(xiàn)一一對應(yīng)參數(shù)類型說明index_filename位置參數(shù)openapi.index索引文件路徑用于將類名解析為源文件路徑class_name位置參數(shù)nargs可傳多個要排序的GithubObject類名可傳簡單類名如HookDelivery或全限定名如github.HookDelivery.HookDeliverySummary--dry-run布爾開關(guān)默認(rèn)False只展示將產(chǎn)生的改動unified diff不修改任何文件class_name的兩種寫法說明簡單類名腳本會到索引的classes表中查package、module、name拼出全限定名scripts/sort_class.py全限定名含.直接按package.module.Class三段拆分適用于需要精確指定嵌套類如github.HookDelivery.HookDeliverySummary對應(yīng) github/HookDelivery.py 中的嵌套類的場景。腳本根據(jù)解析結(jié)果把文件定位到{package}/{module}.py例如github/Autolink.py。若傳了多個類會打印Sorting N Python files的提示并使用multiprocessing.Pool對多個文件并行排序main()中每個文件分配獨(dú)立的manager.Lock防并發(fā)寫沖突見 scripts/sort_class.py。3.2 干跑dry-run與正式應(yīng)用SKILL 文檔強(qiáng)調(diào)了一條安全工作流始終先用--dry-run只讀預(yù)覽——它不會改動任何文件只輸出類名和對應(yīng)的 unified diff將改動展示給用戶評審征得同意后再執(zhí)行正式命令若用戶明確同意應(yīng)用且無需再次評審去掉--dry-run重新執(zhí)行即可落盤。對應(yīng)實(shí)現(xiàn)dry_runTrue時腳本用difflib.unified_diff打印舊代碼與新代碼的差異通過stdout鎖串行輸出避免多進(jìn)程交錯只有dry_runFalse且tree_updated.deep_equals(tree)為假時才真正寫回文件scripts/sort_class.py。# 1. 只讀預(yù)覽推薦 python scripts/sort_class.py --dry-run openapi.index Autolink HookDelivery # 2. 評審?fù)ㄟ^后正式應(yīng)用 python scripts/sort_class.py openapi.index Autolink HookDelivery3.3 一次性排序所有類雖然 SKILL 文檔的調(diào)用形式是按類名逐個排序但倉庫中的 scripts/openapi-update-classes.sh 展示了批量場景該腳本用jq從索引讀取GithubObject的所有子孫類class_to_descendants過濾掉繼承自ABC的抽象類后把全部具體類一次性傳給sort_class.py見 scripts/openapi-update-classes.sh 與update()中的調(diào)用。這印證了腳本nargs設(shè)計就是為了支持“給定一個類或多個類或全部類”的批量需求。四、排序規(guī)則Internal Class Order排序邏輯并非隨意為之而是嚴(yán)格遵循 ARCHITECTURE.md 中 Internal Class Order 一節(jié)的約定。該約定要求的類內(nèi)成員順序?yàn)開initAttributes() dunder methods (alphabetical: __eq__, __hash__, __repr__, __str__, …) property (one per attribute, alphabetical by name) public methods _useAttributes()補(bǔ)充約束_useAttributes永遠(yuǎn)是類中最后一個方法Dunder 方法__name__形式的特殊方法緊跟在_initAttributes()之后按字母序排列。PyGithub 類中最常見的有__eq__(self, other)自定義相等性如NamedUser按login與id比較__hash__(self)凡定義__eq__必須同時定義__repr__(self)每個類都有通常使用self.get__repr__({key: self._key.value})__str__(self)需要人類可讀的單行字符串時使用如CodeScanAlertInstanceLocation公開方法擁有大量方法的類會把相關(guān)操作聚成一塊放在主方法之后例如所有 reaction 方法get_reactions→create_reaction→delete_reaction作為一組sub-issue 方法同理。五、源碼級實(shí)現(xiàn)原理libcst AST 重排排序能力由 scripts/sort_class.py 中的SortMethodsTransformer繼承cst.CSTTransformer實(shí)現(xiàn)它用libcst把 Python 源碼解析成具體語法樹CST在保留注釋、空白、引號風(fēng)格的前提下安全地重排節(jié)點(diǎn)。核心流程如下5.1 類級排序leave_ClassDef范圍過濾若指定了class_name僅處理當(dāng)前類否則處理所有類scripts/sort_class.py基類判定檢查類的所有基類名是否以GithubObject結(jié)尾含cst.Name與屬性訪問兩種形態(tài)不滿足則跳過——這正是“只作用于 GithubObject 類”的機(jī)制scripts/sort_class.py健壯性校驗(yàn)若類中沒有任何函數(shù)、或函數(shù)不構(gòu)成連續(xù)塊中間夾雜非函數(shù)語句直接拋出ValueError防止破壞代碼結(jié)構(gòu)scripts/sort_class.py分桶重排把函數(shù)塊拆成prolog函數(shù)前的類級語句如 docstring、__init__、_initAttributes、dunder 方法集合、property方法集合、其余公開方法、_useAttributes、epilog函數(shù)后的尾隨語句然后按約定順序重組prolog __init__ _initAttributes dunders(字母序) properties(字母序) public methods _useAttributes epilogscripts/sort_class.py其中 dunder 與 property 集合會按方法名做字母排序sort_func_defs而公開方法僅在sort_funcsTrue時排序默認(rèn)保持原有相對順序以尊重人工對方法分組/cluster 的編排ARCHITECTURE 中提到的方法聚類慣例。5.2 屬性級排序leave_FunctionDefSortMethodsTransformer還深入兩個特殊方法的函數(shù)體內(nèi)部_initAttributes找出函數(shù)體中連續(xù)的AnnAssign帶類型注解的賦值語句塊按屬性名self._xxx的xxx字母序排序scripts/sort_class.py。這對應(yīng) ARCHITECTURE 的要求“所有私有屬性字段按字母序每個都帶類型并初始化為NotSet”_useAttributes找出函數(shù)體中連續(xù)的if xxx in attributes分支塊按分支測試的屬性名排序scripts/sort_class.py。5.3 一個已排序的范例以 github/Autolink.py 為例其成員順序完全符合約定class Autolink(NonCompletableGithubObject): ... def _initAttributes(self) - None: # 1. 屬性聲明字母序 self._id: Attribute[int] NotSet self._is_alphanumeric: Attribute[bool] NotSet self._key_prefix: Attribute[str] NotSet self._updated_at: Attribute[datetime] NotSet self._url_template: Attribute[str] NotSet def __repr__(self) - str: # 2. dunder return self.get__repr__({id: self._id.value}) property # 3. property 訪問器字母序 def id(self) - int: return self._id.value property def is_alphanumeric(self) - bool: return self._is_alphanumeric.value # ... key_prefix / updated_at / url_template 依次排列 def _useAttributes(self, attributes: dict[str, Any]) - None: # 4. 最后一個方法 if id in attributes: # pragma no branch self._id self._makeIntAttribute(attributes[id]) if is_alphanumeric in attributes: # pragma no branch self._is_alphanumeric self._makeBoolAttribute(attributes[is_alphanumeric]) # ...可以看到_useAttributes中的if分支同樣按屬性名字母序排列。這正是運(yùn)行sort_class.py之后類應(yīng)呈現(xiàn)的標(biāo)準(zhǔn)形態(tài)。六、實(shí)際工作流在 OpenAPI 更新流程中的位置sort_class.py并非孤立工具它是 PyGithub 自動化更新管線的一環(huán)。在 scripts/openapi-update-classes.sh 的update()函數(shù)中每個類的處理順序?yàn)閛penapi.py suggest schemas --add # 為類補(bǔ)充 OpenAPI schema openapi.py index # 重建索引 sort_class.py index classes # 先排序類成員本次主題 openapi.py apply properties # 應(yīng)用屬性到源碼 openapi.py apply properties --tests # 同步測試文件 prepare-for-update-assertions.py update-assertions.sh # 更新斷言 pytest testAttributes # 運(yùn)行屬性測試每一步之后都會以 “Sort attributes and methods in $class” 之類的信息提交。從該腳本還可以看到sort_class.py被獨(dú)立運(yùn)行$python $sort_class $index ${classes[]}即排序是先于schema 應(yīng)用執(zhí)行的、獨(dú)立的代碼整理步驟——先保證結(jié)構(gòu)穩(wěn)定再做增量修改。因此如果參與 PyGithub 的貢獻(xiàn)流程推薦的手動操作序列為# 0) 確保索引存在若缺失 python3 scripts/openapi.py index github/ api.github.com.2022-11-28.json openapi.index # 1) 預(yù)覽指定類的排序改動 python scripts/sort_class.py --dry-run openapi.index HookDelivery # 2) 評審后正式應(yīng)用 python scripts/sort_class.py openapi.index HookDelivery # 3) 運(yùn)行 lint 與類型檢查openapi 技能要求 pre-commit run --all-files mypy github tests七、常見問題與注意事項(xiàng)索引缺失直接運(yùn)行sort_class.py會因找不到openapi.index而報錯。先按 .claude/skills/openapi/SKILL.md 的initfetch index流程生成索引文件索引過期任何對 PyGithub 源碼的改動新增類、改名、移動文件都要求重新執(zhí)行openapi.py index更新索引否則類名解析可能失敗或指向錯誤文件類名不存在簡單類名在索引的classes中查不到時main()會拋出ValueError(fClass {class_name} does not exist in index)scripts/sort_class.py--dry-run是安全邊界建議把它當(dāng)作默認(rèn)習(xí)慣正式應(yīng)用前務(wù)必確認(rèn) diff 內(nèi)容符合 Internal Class Order 預(yù)期非 GithubObject 類會被自動跳過不需要手工規(guī)避腳本按基類名自動判斷多類并行同時傳入多個類時腳本并行排序但通過文件級鎖保證同一文件不會被并發(fā)寫壞可以放心批量使用。八、小結(jié)sort_class.py以一行命令將 PyGithub 類成員順序收斂到 ARCHITECTURE.md 規(guī)定的統(tǒng)一形態(tài)是 OpenAPI 自動更新體系中的“穩(wěn)定器”先排序、再應(yīng)用 schema、最后同步測試與斷言。其核心實(shí)現(xiàn)libcst AST 變換 多進(jìn)程并行 文件鎖既保證了重排的安全性也保證了批量處理的效率。維護(hù)者與貢獻(xiàn)者只要遵循“先--dry-run評審、再正式應(yīng)用”的流程即可讓倉庫中每一個GithubObject類都保持清晰、一致、可機(jī)器處理的結(jié)構(gòu)。參考資源技能文檔.claude/skills/sorted-classes/SKILL.md腳本源碼scripts/sort_class.py排序約定ARCHITECTURE.mdInternal Class Order 一節(jié)索引生成前置.claude/skills/openapi/SKILL.md 與 scripts/openapi.py文檔說明doc/scripts.rstScript sort_class.py 一節(jié)集成腳本scripts/openapi-update-classes.sh已排序范例github/Autolink.py贊分享開發(fā)工具【免費(fèi)下載鏈接】PyGithubTyped interactions with the GitHub API v3項(xiàng)目地址https://gitcode.com/gh_mirrors/py/PyGithub點(diǎn)擊查看免費(fèi)下載相關(guān)推薦Terminal.Gui 代碼布局規(guī)范Backing Field 與成員排序的工程實(shí)踐指南Terminal.Gui 代碼布局規(guī)范Backing Field 與成員排序的工程實(shí)踐指南 本篇技術(shù)指南聚焦于 Terminal.Gui.NET 跨平臺終端UI組件跨平臺桌面應(yīng)用VisiData 排序完全指南列類型、多級排序與排序順序查看VisiData 排序完全指南列類型、多級排序與排序順序查看 VisiData 是一款終端電子表格工具其內(nèi)置排序體系圍繞類型化值 排序優(yōu)先級 內(nèi)部數(shù)據(jù)分析CLI數(shù)據(jù)可視化eslint-plugin-unicorn 類成員順序規(guī)則實(shí)戰(zhàn)consistent-class-member-order 與快照測試深度剖析eslint plugin unicorn 類成員順序規(guī)則實(shí)戰(zhàn)consistent class member order 與快照測試深度剖析 本篇文章以 esLint代碼質(zhì)量上一篇5個實(shí)戰(zhàn)技巧深度優(yōu)化macOS鼠標(biāo)體驗(yàn)的開源利器下一篇VoiceFixer終極指南免費(fèi)AI音頻修復(fù)工具拯救受損聲音的完整教程創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考