人工智能計(jì)算機(jī)視覺(jué)深度學(xué)習(xí)【免費(fèi)下載鏈接】mmcvOpenMMLab Computer Vision Foundation項(xiàng)目地址https://gitcode.com/gh_mirrors/mm/mmcv點(diǎn)擊查看免費(fèi)下載本文是 OpenMMLab 計(jì)算機(jī)視覺(jué)基礎(chǔ)庫(kù) MMCV 的代碼風(fēng)格官方指南對(duì)應(yīng)倉(cāng)庫(kù)文檔 docs/zh_cn/community/code_style.md的深度展開(kāi)版。它面向兩類(lèi)讀者一是準(zhǔn)備向 MMCV 提交 Pull Request 的貢獻(xiàn)者需要讓代碼通過(guò) pre-commit、CI 與 reviewer 的審查二是希望在項(xiàng)目?jī)?nèi)建立統(tǒng)一代碼規(guī)范的團(tuán)隊(duì)。讀完本文你將掌握 MMCV 所遵循的 PEP 8 與 Google 風(fēng)格取舍、命名與 docstring 的具體寫(xiě)法、類(lèi)型注解與 mypy 的使用方法以及 pre-commit 工具鏈的完整配置從而寫(xiě)出與倉(cāng)庫(kù)風(fēng)格一致、可維護(hù)、易審查的 Python 代碼。一、代碼規(guī)范的兩個(gè)標(biāo)準(zhǔn)與 MMCV 的取舍1.1 PEP 8 —— Python 官方代碼規(guī)范PEP 8 是 Python 官方的代碼風(fēng)格指南是 OpenMMLab 算法庫(kù)首選的代碼規(guī)范見(jiàn) docs/zh_cn/community/contributing.md 中代碼風(fēng)格一節(jié)。它主要覆蓋以下幾方面內(nèi)容代碼布局規(guī)定 Python 中空行、斷行以及導(dǎo)入相關(guān)的風(fēng)格。一個(gè)常見(jiàn)疑問(wèn)是當(dāng)代碼較長(zhǎng)無(wú)法在一行內(nèi)寫(xiě)完時(shí)何處可以斷行PEP 8 給出了明確的換行規(guī)則。表達(dá)式規(guī)定表達(dá)式中空格的使用方式。尾隨逗號(hào)當(dāng)列表較長(zhǎng)、無(wú)法一行寫(xiě)下而寫(xiě)成逐行列表時(shí)推薦在末項(xiàng)之后也加上逗號(hào)便于后續(xù)追加選項(xiàng)和版本控制對(duì)比。尾隨逗號(hào)的正反例# Correct: FILES [setup.cfg, tox.ini] # Correct: FILES [ setup.cfg, tox.ini, ] # Wrong: FILES [setup.cfg, tox.ini,] # Wrong: FILES [ setup.cfg, tox.ini ]命名、注釋、類(lèi)型注解這些內(nèi)容的詳細(xì)規(guī)范是本文后續(xù)章節(jié)的主體。1.2 項(xiàng)目?jī)?nèi)一致性?xún)?yōu)先于 PEP 8A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is the most important.PEP 8 的規(guī)范并不是絕對(duì)的項(xiàng)目?jī)?nèi)的一致性要優(yōu)先于 PEP 8 的規(guī)范。OpenMMLab 各個(gè)項(xiàng)目都在setup.cfg中設(shè)定了代碼規(guī)范設(shè)置貢獻(xiàn)者應(yīng)遵照這些設(shè)置。例如 PEP 8 中有如下例子# Correct: hypot2 x*x y*y # Wrong: hypot2 x * x y * y這一規(guī)范本意是指示運(yùn)算優(yōu)先級(jí)但 OpenMMLab 的設(shè)置中通常沒(méi)有啟用 yapf 的ARITHMETIC_PRECEDENCE_INDICATION選項(xiàng)因而格式規(guī)范工具不會(huì)按照該推薦樣式強(qiáng)制格式化一切以項(xiàng)目實(shí)際配置為準(zhǔn)。打開(kāi)倉(cāng)庫(kù)根目錄的 setup.cfg 可以看到[yapf] based_on_style pep8 blank_line_before_nested_class_or_def true split_before_expression_after_opening_paren true [isort] line_length 79 multi_line_output 0 extra_standard_library pkg_resources,setuptools,logging,os,warnings,abc known_first_party mmcv known_third_party addict,cv2,matplotlib,numpy,onnx,packaging,pytest,pytorch_sphinx_theme,scipy,sphinx,torch,torchvision,yaml,yapf no_lines_before STDLIB,LOCALFOLDER default_section THIRDPARTY這些配置說(shuō)明yapf 基于 pep8 風(fēng)格isort 的每行長(zhǎng)度限制為 79 字符mmcv被標(biāo)記為 first party而 torch、numpy 等被標(biāo)記為 third party導(dǎo)入順序會(huì)自動(dòng)按標(biāo)準(zhǔn)庫(kù) → 第三方 → 本地模塊排列。1.3 Google 開(kāi)源項(xiàng)目風(fēng)格指南Google 開(kāi)源項(xiàng)目風(fēng)格指南Google Python Style Guide比 PEP 8 提供了更詳盡的指導(dǎo)包含語(yǔ)言規(guī)范和風(fēng)格規(guī)范兩個(gè)部分語(yǔ)言規(guī)范對(duì) Python 中許多語(yǔ)言特性異常、Lambda 表達(dá)式、列表推導(dǎo)式、metaclass 等進(jìn)行優(yōu)缺點(diǎn)分析并給出使用意見(jiàn)。風(fēng)格規(guī)范大部分約定建立在 PEP 8 基礎(chǔ)上同時(shí)有更細(xì)的約定如函數(shù)長(zhǎng)度、TODO 注釋、文件與 socket 對(duì)象的訪問(wèn)等。MMCV 推薦將 Google 指南作為開(kāi)發(fā)參考但不必嚴(yán)格遵照原因有二該指南存在 Python 2 兼容需求例如要求所有無(wú)基類(lèi)的類(lèi)顯式繼承object而在僅使用 Python 3 的環(huán)境中這一要求不必要按本項(xiàng)目慣例即可OpenMMLab 項(xiàng)目作為框架級(jí)開(kāi)源軟件不必對(duì)高級(jí)技巧過(guò)于避諱尤其是 MMCV但使用這些技巧前應(yīng)認(rèn)真考慮是否真的有必要并尋求其他開(kāi)發(fā)者的廣泛評(píng)估。需要特別留意的一處差異是包的導(dǎo)入Google 指南要求導(dǎo)入本地包時(shí)使用路徑全稱(chēng)且每個(gè)模塊單獨(dú)成行。這在 MMCV 中通常不必要也不符合項(xiàng)目開(kāi)發(fā)慣例本項(xiàng)目約定如下# Correct from mmcv.cnn.bricks import (Conv2d, build_norm_layer, DropPath, MaxPool2d, Linear) from ..utils import ext_loader # Wrong from mmcv.cnn.bricks import Conv2d, build_norm_layer, DropPath, MaxPool2d, \ Linear # 使用括號(hào)進(jìn)行連接而不是反斜杠 from ...utils import is_str # 最多向上回溯一層過(guò)多的回溯容易導(dǎo)致結(jié)構(gòu)混亂要點(diǎn)跨行導(dǎo)入用括號(hào)連接而非反斜杠相對(duì)導(dǎo)入最多向上回溯一層避免結(jié)構(gòu)混亂。1.4 OpenMMLab 的落地pre-commit 自動(dòng)格式化OpenMMLab 項(xiàng)目使用 pre-commit 工具自動(dòng)格式化代碼具體安裝與使用見(jiàn) docs/zh_cn/community/contributing.md 的配置 pre-commit與代碼風(fēng)格章節(jié)。核心命令如下須在 MMCV 目錄下執(zhí)行pip install -U pre-commit pre-commit install pre-commit run --all-files中國(guó)用戶(hù)若因網(wǎng)絡(luò)問(wèn)題安裝失敗可使用國(guó)內(nèi)鏡像配置pre-commit install -c .pre-commit-config-zh-cn.yaml pre-commit run --all-files -c .pre-commit-config-zh-cn.yaml倉(cāng)庫(kù)根目錄的 .pre-commit-config.yaml 是本項(xiàng)目實(shí)際的鉤子配置包含以下工具鏈鉤子作用flake8Python 官方推薦的代碼規(guī)范檢查工具是多個(gè)檢查工具的封裝isort自動(dòng)調(diào)整模塊導(dǎo)入順序yapfGoogle 發(fā)布的代碼格式化工具trailing-whitespace / mixed-line-ending / end-of-file-fixer去除行尾空白、統(tǒng)一行尾符LF、修復(fù)文件末尾換行check-yaml / check-merge-conflict校驗(yàn) YAML 語(yǔ)法、檢查未解決的合并沖突requirements-txt-fixer調(diào)整requirements.txt中包的順序double-quote-string-fixer / fix-encoding-pragma / pyupgrade統(tǒng)一引號(hào)、移除編碼聲明、升級(jí)為 Python 3 語(yǔ)法codespell檢查單詞拼寫(xiě)mdformat檢查并格式化 Markdown 文件配合 mdformat-openmmlabdocformatter格式化 docstring--in-place --wrap-descriptions 79check-copyright檢查文件版權(quán)頭針對(duì) mmcv、tests排除 mmcv/opsmypy靜態(tài)類(lèi)型檢查排除 tests 與 docs 目錄其中 C 和 CUDA 代碼遵循 Google C Style Guideclang-format 鉤子在配置中以注釋形式預(yù)留。如果提交的代碼不符合代碼風(fēng)格規(guī)范pre-commit 會(huì)發(fā)出警告并自動(dòng)修復(fù)部分錯(cuò)誤若想臨時(shí)繞開(kāi)檢查可在git commit時(shí)加上--no-verify僅用于臨時(shí)提交最終推送的代碼必須通過(guò) pre-commit 檢查。二、命名規(guī)范2.1 命名規(guī)范的重要性?xún)?yōu)秀的命名是良好代碼可讀性的基礎(chǔ)。基礎(chǔ)命名規(guī)范對(duì)各類(lèi)變量做約束使讀者能根據(jù)名字判斷它是一個(gè)類(lèi)、局部變量還是全局變量而優(yōu)秀的命名則要求作者對(duì)變量功能有清晰認(rèn)識(shí)與良好表達(dá)能力讓讀者僅憑名稱(chēng)即可理解其含義。2.2 基礎(chǔ)命名規(guī)范類(lèi)型公有私有模塊lower_with_under_lower_with_under包lower_with_under類(lèi)CapWords_CapWords異常CapWordsError函數(shù)方法lower_with_under_lower_with_under函數(shù) / 方法參數(shù)lower_with_under全局 / 類(lèi)內(nèi)常量CAPS_WITH_UNDER_CAPS_WITH_UNDER全局 / 類(lèi)內(nèi)變量lower_with_under_lower_with_under變量lower_with_under_lower_with_under局部變量lower_with_under注意盡量避免變量名與保留字沖突若不可避免可使用一個(gè)后置下劃線如class_盡量不要使用過(guò)于簡(jiǎn)單的命名約定俗成的循環(huán)變量i、文件變量f、錯(cuò)誤變量e除外不會(huì)被用到的變量可命名為_(kāi)邏輯檢查器會(huì)將其忽略。2.3 命名技巧良好的變量命名需保證三點(diǎn)含義準(zhǔn)確、沒(méi)有歧義長(zhǎng)短適中前后統(tǒng)一。# Wrong class Masks(metaclassABCMeta): # 命名無(wú)法表現(xiàn)基類(lèi)Instance or Semantic pass # Correct class BaseInstanceMasks(metaclassABCMeta): pass # Wrong不同地方含義相同的變量盡量用統(tǒng)一的命名 def __init__(self, inplanes, planes): pass def __init__(self, in_channels, out_channels): pass常見(jiàn)的函數(shù)命名方法動(dòng)賓命名法crop_img,init_weights動(dòng)賓倒置命名法imread,bbox_flip注意函數(shù)命名與參數(shù)的順序保證主語(yǔ)在前、符合語(yǔ)言習(xí)慣check_keys_exist(key, container)check_keys_contain(container, key)還要避免非常規(guī)或未統(tǒng)一約定的縮寫(xiě)如nb→num_blocksin_nc→in_channels。三、docstring 規(guī)范3.1 為什么要寫(xiě) docstringdocstring 是對(duì)一個(gè)類(lèi)、一個(gè)函數(shù)功能與 API 接口的詳細(xì)描述有兩個(gè)功能幫助其他開(kāi)發(fā)者了解代碼功能方便 debug 和復(fù)用代碼在 Readthedocs 文檔中自動(dòng)生成相關(guān) API reference 文檔幫助不了解源代碼的社區(qū)用戶(hù)使用功能。3.2 如何寫(xiě) docstring與普通注釋不同規(guī)范的 docstring 有嚴(yán)格的格式要求以便 Python 解釋器與 sphinx 進(jìn)行文檔解析docstring 的基本約定見(jiàn) PEP 257。MMCV 參考格式為 Google 風(fēng)格同時(shí)結(jié)合了 OpenMMLab 自身慣例。以下按模塊、類(lèi)、方法三種場(chǎng)景給出標(biāo)準(zhǔn)格式。1. 模塊文檔代碼風(fēng)格規(guī)范推薦為每個(gè)模塊Python 文件編寫(xiě) docstring但目前 OpenMMLab 項(xiàng)目大部分沒(méi)有此類(lèi) docstring因此不做硬性要求。參考格式A one line summary of the module or program, terminated by a period. Leave one blank line. The rest of this docstring should contain an overall description of the module or program. Optionally, it may also contain a brief description of exported classes and functions and/or usage examples. Typical usage example: foo ClassFoo() bar foo.FunctionBar() 2. 類(lèi)文檔類(lèi)文檔是貢獻(xiàn)者最常編寫(xiě)的類(lèi)型。按照 OpenMMLab 慣例這里使用了與 Google 風(fēng)格不同的寫(xiě)法不使用 Attributes 描述類(lèi)屬性而是使用 Args 描述__init__函數(shù)的參數(shù)。Args 中遵照parameter (type): Description.格式描述每個(gè)參數(shù)的類(lèi)型與功能多種類(lèi)型可用(float or str)寫(xiě)法可以為 None 的參數(shù)寫(xiě)為(int, optional)。class BaseRunner(metaclassABCMeta): The base class of Runner, a training helper for PyTorch. All subclasses should implement the following APIs: - run() - train() - val() - save_checkpoint() Args: model (:obj:torch.nn.Module): The model to be run. batch_processor (callable, optional): A callable method that process a data batch. The interface of this method should be batch_processor(model, data, train_mode) - dict. Defaults to None. optimizer (dict or :obj:torch.optim.Optimizer, optional): It can be either an optimizer (in most cases) or a dict of optimizers (in models that requires more than one optimizer, e.g., GAN). Defaults to None. work_dir (str, optional): The working directory to save checkpoints and logs. Defaults to None. logger (:obj:logging.Logger): Logger used during training. Defaults to None. (The default value is just for backward compatibility) meta (dict, optional): A dict records some import information such as environment info and seed, which will be logged in logger hook. Defaults to None. max_epochs (int, optional): Total training epochs. Defaults to None. max_iters (int, optional): Total training iterations. Defaults to None. def __init__(self, model, batch_processorNone, optimizerNone, work_dirNone, loggerNone, metaNone, max_itersNone, max_epochsNone): ...補(bǔ)充要求在算法實(shí)現(xiàn)的主體類(lèi)中建議加入原論文鏈接如果參考了其他開(kāi)源代碼實(shí)現(xiàn)應(yīng)加入modified from直接復(fù)制了其他代碼庫(kù)實(shí)現(xiàn)則應(yīng)加入copied from并注意源碼的 License如有必要可通過(guò).. math::加入數(shù)學(xué)公式。# 參考實(shí)現(xiàn) # This func is modified from detectron2 # ..._. # 復(fù)制代碼 # This code was copied from the ubelt # library..._. # 引用論文 添加公式 class LabelSmoothLoss(nn.Module): rInitializer for the label smoothed cross entropy loss. Refers to Rethinking the Inception Architecture for Computer Vision ..._. This decreases gap between output scores and encourages generalization. Labels provided to forward can be one-hot like vectors (NxC) or class indices (Nx1). And this accepts linear combination of one-hot like labels from mixup or cutmix except multi-label task. Args: label_smooth_val (float): The degree of label smoothing. num_classes (int, optional): Number of classes. Defaults to None. mode (str): Refers to notes, Options are original, classy_vision, multi_label. Defaults to classy_vision. reduction (str): The method used to reduce the loss. Options are none, mean and sum. Defaults to mean. loss_weight (float): Weight of the loss. Defaults to 1.0. Note: if the mode is original, this will use the same label smooth method as the original paper as: .. math:: (1-\epsilon)\delta_{k, y} \frac{\epsilon}{K} where :math:\epsilon is the label_smooth_val, :math:K is the num_classes and :math:\delta_{k,y} is Dirac delta, which equals 1 for ky and 0 otherwise. if the mode is classy_vision, this will use the same label smooth method as the facebookresearch/ClassyVision ..._ repo as: .. math:: \frac{\delta_{k, y} \epsilon/K}{1\epsilon} if the mode is multi_label, this will accept labels from multi-label task and smoothing them as: .. math:: (1-2\epsilon)\delta_{k, y} \epsilon 注意 reStructuredText 中三種引號(hào)功能不同here雙反引號(hào)表示一段代碼here單反引號(hào)表示斜體here雙引號(hào)無(wú)特殊含義一般表示字符串。其中單反引號(hào)的用法與 Markdown 不同需要多加留意。另外還有:obj:type 這種更規(guī)范的表示類(lèi)的寫(xiě)法鑒于長(zhǎng)度不做特別要求一般僅用于表示非常用類(lèi)型。3. 方法函數(shù)文檔函數(shù)文檔與類(lèi)文檔結(jié)構(gòu)基本一致但需要加入返回值文檔。對(duì)于較復(fù)雜的函數(shù)和類(lèi)可使用Examples字段加入示例如果需要給參數(shù)加入較長(zhǎng)備注可加入Note字段。示例最好能直接在 Python 交互式環(huán)境中運(yùn)行并給出對(duì)應(yīng)結(jié)果多個(gè)示例可用注釋分隔說(shuō)明。def import_modules_from_strings(imports, allow_failed_importsFalse): Import modules from the given list of strings. Args: imports (list | str | None): The given module names to be imported. allow_failed_imports (bool): If True, the failed imports will return None. Otherwise, an ImportError is raise. Defaults to False. Returns: List[module] | module | None: The imported modules. All these three lines in docstring will be compiled into the same line in readthedocs. Examples: osp, sys import_modules_from_strings( ... [os.path, sys]) import os.path as osp_ import sys as sys_ assert osp osp_ assert sys sys_ ...如果函數(shù)接口在某個(gè)版本發(fā)生了變化需要在 docstring 中加入說(shuō)明必要時(shí)添加Note或Warningclass CheckpointHook(Hook): Save checkpoints periodically. Args: out_dir (str, optional): The root directory to save checkpoints. If not specified, runner.work_dir will be used by default. If specified, the out_dir will be the concatenation of out_dir and the last level directory of runner.work_dir. Defaults to None. Changed in version 1.3.15. file_client_args (dict, optional): Arguments to instantiate a FileClient. See :class:mmcv.fileio.FileClient for details. Defaults to None. New in version 1.3.15. Warning: Before v1.3.15, the out_dir argument indicates the path where the checkpoint is stored. However, in v1.3.15 and later, out_dir indicates the root directory and the final path to save checkpoint is the concatenation of out_dir and the last level directory of runner.work_dir. Suppose the value of out_dir is /path/of/A and the value of runner.work_dir is /path/of/B, then the final path will be /path/of/A/B. 如果參數(shù)或返回值里帶有需要展開(kāi)描述字段的 dict應(yīng)采用如下格式def func(x): r Args: x (None): A dict with 2 keys, padded_targets, and targets. - targets (list[Tensor]): A list of tensors. Each tensor has the shape of :math:(T_i). Each element is the index of a character. - padded_targets (Tensor): A tensor of shape :math:(N). Each item is the length of a word. Returns: dict: A dict with 2 keys, padded_targets, and targets. - targets (list[Tensor]): A list of tensors. Each tensor has the shape of :math:(T_i). Each element is the index of a character. - padded_targets (Tensor): A tensor of shape :math:(N). Each item is the length of a word. return x3.3 docstring 與 readthedocs 渲染為了生成 readthedocs 文檔docstring 需要按照 reStructuredText 文檔格式編寫(xiě)否則會(huì)產(chǎn)生文檔渲染錯(cuò)誤。在提交 PR 前最好生成并預(yù)覽文檔效果方法見(jiàn) docs/zh_cn/community/contributing.md 的文檔渲染指引pip install -r requirements/docs.txt cd docs/zh_cn/ # or docs/en make html # check file in ./docs/zh_cn/_build/html/index.html語(yǔ)法規(guī)范參考 reStructuredText PrimerSphinx 官方文檔與 Example Google Style Python Docstringssphinxcontrib-napoleon 文檔。OpenMMLab 使用 pytorch_sphinx_theme 與 napoleon 擴(kuò)展見(jiàn) requirements/docs.txt 與 docs/zh_cn/conf.py將上述 Google 風(fēng)格的 docstring 自動(dòng)渲染為 API reference 頁(yè)面如 docs/zh_cn/api/ 下各模塊的 .rst 文件。四、注釋規(guī)范4.1 為什么要寫(xiě)注釋對(duì)于一個(gè)開(kāi)源項(xiàng)目團(tuán)隊(duì)合作以及社區(qū)之間的合作必不可少因此尤其要重視合理注釋。不寫(xiě)注釋的代碼可能過(guò)幾個(gè)月連作者自己也難以理解造成額外的閱讀和修改成本。4.2 如何寫(xiě)注釋最需要寫(xiě)注釋的是代碼中技巧性的部分。如果你在下次代碼審查的時(shí)候必須解釋一下那么你應(yīng)該現(xiàn)在就給它寫(xiě)注釋。對(duì)于復(fù)雜的操作應(yīng)該在其操作開(kāi)始前寫(xiě)上若干行注釋對(duì)于不是一目了然的代碼應(yīng)在其行尾添加注釋。Google 開(kāi)源項(xiàng)目風(fēng)格指南# We use a weighted dictionary search to find out where i is in # the array. We extrapolate position based on the largest num # in the array and the array size and then do binary search to # get the exact number. if i (i-1) 0: # True if i is 0 or a power of 2.兩條硬性規(guī)則為了提高可讀性注釋?xiě)?yīng)至少離開(kāi)代碼2 個(gè)空格絕不要描述代碼。假設(shè)閱讀代碼的人比你更懂 Python他只是不知道你的代碼要做什么。Google 開(kāi)源項(xiàng)目風(fēng)格指南# Wrong: # Now go through the b array and make sure whenever i occurs # the next element is i1 # Wrong: if i (i-1) 0: # True if i bitwise and i-1 is 0.在注釋中可以使用 Markdown 語(yǔ)法開(kāi)發(fā)人員通常熟悉 Markdown便于交流理解如用單反引號(hào)表示代碼和變量——注意不要與 docstring 中的 reStructuredText 語(yǔ)法混淆# _reversed_padding_repeated_twice is the padding to be passed to # F.pad if needed (e.g., for non-zero padding types that are # implemented as two ops: padding conv). F.pad accepts paddings in # reverse order than the dimension. self._reversed_padding_repeated_twice _reverse_repeat_tuple(self.padding, 2)4.3 注釋示例代碼風(fēng)格文檔給出了兩類(lèi)典型注釋場(chǎng)景復(fù)雜邏輯結(jié)構(gòu)對(duì)優(yōu)先級(jí)關(guān)系進(jìn)行說(shuō)明。例如 registry 構(gòu)建函數(shù)的選擇邏輯# self.build_func will be set with the following priority: # 1. build_func # 2. parent.build_func # 3. build_from_cfg if build_func is None: if parent is not None: self.build_func parent.build_func else: self.build_func build_from_cfg else: self.build_func build_funcbug 修復(fù)的特殊處理附帶相關(guān) issue 鏈接幫助其他人了解 bug 背景。例如 checkpoint 保存時(shí)針對(duì) PyTorch 1.6 文件格式變更的兼容處理def _save_ckpt(checkpoint, file): # The 1.6 release of PyTorch switched torch.save to use a new # zipfile-based file format. It will cause RuntimeError when a # checkpoint was saved in high version (PyTorch version1.6.0) but # loaded in low version (PyTorch version1.6.0). More details at # https://github.com/open-mmlab/mmpose/issues/904 if digit_version(TORCH_VERSION) digit_version(1.6.0): torch.save(checkpoint, file, _use_new_zipfile_serializationFalse) else: torch.save(checkpoint, file)五、類(lèi)型注解5.1 為什么要寫(xiě)類(lèi)型注解類(lèi)型注解是對(duì)函數(shù)中變量的類(lèi)型做限定或提示為代碼的安全性提供保障、增強(qiáng)可讀性、避免出現(xiàn)類(lèi)型相關(guān)的錯(cuò)誤。Python 對(duì)類(lèi)型沒(méi)有強(qiáng)制限制類(lèi)型注解只起提示作用IDE 會(huì)解析注解并在調(diào)用代碼時(shí)給出類(lèi)型提示類(lèi)型注解檢查工具如 mypy則會(huì)根據(jù)注解對(duì)代碼中可能出現(xiàn)的問(wèn)題進(jìn)行檢查減少 bug 的出現(xiàn)。通常不需要注釋模塊中的所有函數(shù)按以下原則權(quán)衡公共的 API 需要注釋在代碼的安全性、清晰性和靈活性之間權(quán)衡是否注釋對(duì)于容易出現(xiàn)類(lèi)型相關(guān)錯(cuò)誤的代碼進(jìn)行注釋難以理解的代碼請(qǐng)進(jìn)行注釋若代碼中的類(lèi)型已經(jīng)穩(wěn)定可以進(jìn)行注釋。對(duì)于一份成熟的代碼多數(shù)情況下即使注釋了所有函數(shù)也不會(huì)喪失太多靈活性。5.2 函數(shù) / 方法類(lèi)型注解通常不對(duì)self和cls注釋。根據(jù)行寬有多種寫(xiě)法from typing import Optional, List, Tuple # 全部位于一行 def my_method(self, first_var: int) - int: pass # 另起一行 def my_method( self, first_var: int, second_var: float) - Tuple[MyLongType1, MyLongType1, MyLongType1]: pass # 單獨(dú)成行具體的應(yīng)用場(chǎng)合與行寬有關(guān)建議結(jié)合 yapf 自動(dòng)化格式使用 def my_method( self, first_var: int, second_var: float ) - Tuple[MyLongType1, MyLongType1, MyLongType1]: pass # 引用尚未被定義的類(lèi)型 class MyClass: def __init__(self, stack: List[MyClass]) - None: pass類(lèi)型注解中的類(lèi)型可以是 Python 內(nèi)置類(lèi)型、自定義類(lèi)也可以使用typing提供的 wrapper 類(lèi)進(jìn)行裝飾。常用注解# 數(shù)值類(lèi)型 from numbers import Number # 可選類(lèi)型指參數(shù)可以為 None from typing import Optional def foo(var: Optional[int] None): pass # 聯(lián)合類(lèi)型指同時(shí)接受多種類(lèi)型 from typing import Union def foo(var: Union[float, str]): pass from typing import Sequence # 序列類(lèi)型 from typing import Iterable # 可迭代類(lèi)型 from typing import Any # 任意類(lèi)型 from typing import Callable # 可調(diào)用類(lèi)型 from typing import List, Dict # 列表和字典的泛型類(lèi)型 from typing import Tuple # 元組的特殊格式 # 雖然在 Python 3.9 中l(wèi)ist, tuple 和 dict 本身已支持泛型但為了支持之前的版本 # 我們?cè)谶M(jìn)行類(lèi)型注解時(shí)還是需要使用 List, Tuple, Dict 類(lèi)型 # 另外在對(duì)參數(shù)類(lèi)型進(jìn)行注解時(shí)盡量使用 Sequence Iterable Mapping # List, Tuple, Dict 主要用于返回值類(lèi)型注解5.3 變量類(lèi)型注解一般用于難以直接推斷類(lèi)型時(shí)# Recommend: 帶類(lèi)型注解的賦值 a: Foo SomeUndecoratedFunction() a: List[int]: [1, 2, 3] # List 只支持單一類(lèi)型泛型可使用 Union b: Tuple[int, int] (1, 2) # 長(zhǎng)度固定為 2 c: Tuple[int, ...] (1, 2, 3) # 變長(zhǎng) d: Dict[str, int] {a: 1, b: 2} # Not Recommend行尾類(lèi)型注釋 # 雖然這種方式被寫(xiě)在了 Google 開(kāi)源指南中但這是一種為了支持 Python 2.7 版本 # 而補(bǔ)充的注釋方式鑒于我們只支持 Python 3, 為了風(fēng)格統(tǒng)一不推薦使用這種方式。 a SomeUndecoratedFunction() # type: Foo a [1, 2, 3] # type: List[int] b (1, 2, 3) # type: Tuple[int, ...] c (1, 2, 3.5) # type: Tuple[int, Text, float]5.4 自定義泛型除了使用typing內(nèi)置的List、Dict泛型也可以利用TypeVar和Generic定義自己的泛型from typing import TypeVar, Generic KT TypeVar(KT) VT TypeVar(VT) class Mapping(Generic[KT, VT]): def __init__(self, data: Dict[KT, VT]): self._data data def __getitem__(self, key: KT) - VT: return self._data[key]使用上述方法定義了一個(gè)擁有泛型能力的映射類(lèi)mapping Mappingstr, float value: float example[a]另外可以利用TypeVar在函數(shù)簽名中指定聯(lián)動(dòng)的多個(gè)類(lèi)型from typing import TypeVar, List T TypeVar(T) # Can be anything A TypeVar(A, str, bytes) # Must be str or bytes def repeat(x: T, n: int) - List[T]: Return a list containing n references to x. return [x]*n def longest(x: A, y: A) - A: Return the longest of two strings. return x if len(x) len(y) else y5.5 mypy類(lèi)型注解檢查工具mypy 是一個(gè) Python 靜態(tài)類(lèi)型檢查工具。它會(huì)根據(jù)類(lèi)型注解檢查傳參、賦值等操作是否符合注解從而避免可能出現(xiàn)的 bug。考慮如下腳本test.pydef foo(var: int) - float: return float(var) a: str foo(2.0) b: int foo(3.0) # type: ignore運(yùn)行mypy test.py得到test.py:4: error: Incompatible types in assignment (expression has type float, variable has type int) test.py:4: error: Argument 1 to foo has incompatible type str; expected int Found 2 errors in 1 file (checked 1 source file)輸出分別指出了第 4 行在函數(shù)調(diào)用參數(shù)和返回值賦值兩處的類(lèi)型錯(cuò)誤第 5 行同樣存在兩處類(lèi)型錯(cuò)誤但因?yàn)槭褂昧藅ype: ignore而被忽略——只有部分特殊情況才需要此類(lèi)忽略。MMCV 在提交代碼時(shí)要求補(bǔ)充類(lèi)型注解并通過(guò) mypy 檢查mypy 鉤子已配置在 .pre-commit-config.yaml 中排除了 tests 與 docs 目錄。六、提交 PR 前的代碼規(guī)范自查清單結(jié)合 docs/zh_cn/community/contributing.md 與 docs/zh_cn/community/pr.md向 MMCV 提交代碼前應(yīng)完成以下檢查pre-commit 檢查在 MMCV 目錄下執(zhí)行pre-commit run --all-files確保 flake8、yapf、isort、mdformat、docformatter、codespell、mypy 等鉤子全部通過(guò)若鉤子安裝被網(wǎng)絡(luò)中斷可重復(fù)執(zhí)行pre-commit run ...繼續(xù)安裝單元測(cè)試pytest tests通過(guò)全量測(cè)試至少保證修改模塊的測(cè)試通過(guò)例如pytest tests/test_utils/test_env.py可用python -m coverage run -m pytest /path/to/test_file python -m coverage html檢查覆蓋率查看htmlcov/index.html文檔渲染若修改/新增了 docstring 或文檔安裝pip install -r requirements/docs.txt后在docs/zh_cn/或docs/en/下執(zhí)行make html確認(rèn) reStructuredText 語(yǔ)法渲染無(wú)誤檢查docs/zh_cn/_build/html/index.html代碼風(fēng)格Python 遵循 PEP 8 并遵循本文全部規(guī)范C 與 CUDA 遵循 Google C Style GuidePR 粒度與描述一個(gè) PR 只做一件事粒度要細(xì)標(biāo)題格式為[Prefix] Short description (Suffix)前綴包括[Feature]新功能、[Fix]修 bug、[Docs]文檔、[WIP]開(kāi)發(fā)中描述中說(shuō)明修改理由、修改內(nèi)容與影響并關(guān)聯(lián)相關(guān) Issue。遵守這套規(guī)范既能保證你的代碼與 MMCV 現(xiàn)有代碼庫(kù)高度一致也能讓代碼在 Readthedocs 上正確渲染為 API 文檔惠及所有社區(qū)用戶(hù)。贊分享人工智能計(jì)算機(jī)視覺(jué)深度學(xué)習(xí)【免費(fèi)下載鏈接】mmcvOpenMMLab Computer Vision Foundation項(xiàng)目地址https://gitcode.com/gh_mirrors/mm/mmcv點(diǎn)擊查看免費(fèi)下載相關(guān)推薦QUANTAXIS Python 代碼規(guī)范完全指南PEP 8、類(lèi)型注解、命名規(guī)范與質(zhì)量工具實(shí)戰(zhàn)QUANTAXIS Python 代碼規(guī)范完全指南PEP 8、類(lèi)型注解、命名規(guī)范與質(zhì)量工具實(shí)戰(zhàn) 本文依據(jù)倉(cāng)庫(kù)文檔 doc/development/code s金融科技后端數(shù)據(jù)分析DeepChem 開(kāi)發(fā)規(guī)范指南從 pre-commit 到類(lèi)型注解的完整代碼質(zhì)量保障體系DeepChem 開(kāi)發(fā)規(guī)范指南從 pre commit 到類(lèi)型注解的完整代碼質(zhì)量保障體系 本篇技術(shù)指南以 DeepChem 官方開(kāi)發(fā)文檔中的 Coding C人工智能深度學(xué)習(xí)機(jī)器學(xué)習(xí)生物信息學(xué)科學(xué)計(jì)算Python 3編碼規(guī)范與最佳實(shí)踐PEP 8完全解讀指南Python 3編碼規(guī)范與最佳實(shí)踐PEP 8完全解讀指南 想要寫(xiě)出專(zhuān)業(yè)、易讀且符合行業(yè)標(biāo)準(zhǔn)的Python代碼嗎掌握PEP 8編碼規(guī)范是每個(gè)Python開(kāi)發(fā)者文檔教程上一篇告別氣候數(shù)據(jù)處理困境用sqlx構(gòu)建高效驗(yàn)證案例數(shù)據(jù)庫(kù)下一篇gh_mirrors/ove/overleaf代碼審查流程PR規(guī)范與自動(dòng)化檢查創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考