人工智能計算機視覺深度學習【免費下載鏈接】mmcvOpenMMLab Computer Vision Foundation項目地址https://gitcode.com/gh_mirrors/mm/mmcv點擊查看免費下載本文是 OpenMMLab 計算機視覺基礎庫 MMCV 的代碼風格官方指南對應倉庫文檔 docs/zh_cn/community/code_style.md的深度展開版。它面向兩類讀者一是準備向 MMCV 提交 Pull Request 的貢獻者需要讓代碼通過 pre-commit、CI 與 reviewer 的審查二是希望在項目內(nèi)建立統(tǒng)一代碼規(guī)范的團隊。讀完本文你將掌握 MMCV 所遵循的 PEP 8 與 Google 風格取舍、命名與 docstring 的具體寫法、類型注解與 mypy 的使用方法以及 pre-commit 工具鏈的完整配置從而寫出與倉庫風格一致、可維護、易審查的 Python 代碼。一、代碼規(guī)范的兩個標準與 MMCV 的取舍1.1 PEP 8 —— Python 官方代碼規(guī)范PEP 8 是 Python 官方的代碼風格指南是 OpenMMLab 算法庫首選的代碼規(guī)范見 docs/zh_cn/community/contributing.md 中代碼風格一節(jié)。它主要覆蓋以下幾方面內(nèi)容代碼布局規(guī)定 Python 中空行、斷行以及導入相關的風格。一個常見疑問是當代碼較長無法在一行內(nèi)寫完時何處可以斷行PEP 8 給出了明確的換行規(guī)則。表達式規(guī)定表達式中空格的使用方式。尾隨逗號當列表較長、無法一行寫下而寫成逐行列表時推薦在末項之后也加上逗號便于后續(xù)追加選項和版本控制對比。尾隨逗號的正反例# Correct: FILES [setup.cfg, tox.ini] # Correct: FILES [ setup.cfg, tox.ini, ] # Wrong: FILES [setup.cfg, tox.ini,] # Wrong: FILES [ setup.cfg, tox.ini ]命名、注釋、類型注解這些內(nèi)容的詳細規(guī)范是本文后續(xù)章節(jié)的主體。1.2 項目內(nèi)一致性優(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ī)范并不是絕對的項目內(nèi)的一致性要優(yōu)先于 PEP 8 的規(guī)范。OpenMMLab 各個項目都在setup.cfg中設定了代碼規(guī)范設置貢獻者應遵照這些設置。例如 PEP 8 中有如下例子# Correct: hypot2 x*x y*y # Wrong: hypot2 x * x y * y這一規(guī)范本意是指示運算優(yōu)先級但 OpenMMLab 的設置中通常沒有啟用 yapf 的ARITHMETIC_PRECEDENCE_INDICATION選項因而格式規(guī)范工具不會按照該推薦樣式強制格式化一切以項目實際配置為準。打開倉庫根目錄的 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這些配置說明yapf 基于 pep8 風格isort 的每行長度限制為 79 字符mmcv被標記為 first party而 torch、numpy 等被標記為 third party導入順序會自動按標準庫 → 第三方 → 本地模塊排列。1.3 Google 開源項目風格指南Google 開源項目風格指南Google Python Style Guide比 PEP 8 提供了更詳盡的指導包含語言規(guī)范和風格規(guī)范兩個部分語言規(guī)范對 Python 中許多語言特性異常、Lambda 表達式、列表推導式、metaclass 等進行優(yōu)缺點分析并給出使用意見。風格規(guī)范大部分約定建立在 PEP 8 基礎上同時有更細的約定如函數(shù)長度、TODO 注釋、文件與 socket 對象的訪問等。MMCV 推薦將 Google 指南作為開發(fā)參考但不必嚴格遵照原因有二該指南存在 Python 2 兼容需求例如要求所有無基類的類顯式繼承object而在僅使用 Python 3 的環(huán)境中這一要求不必要按本項目慣例即可OpenMMLab 項目作為框架級開源軟件不必對高級技巧過于避諱尤其是 MMCV但使用這些技巧前應認真考慮是否真的有必要并尋求其他開發(fā)者的廣泛評估。需要特別留意的一處差異是包的導入Google 指南要求導入本地包時使用路徑全稱且每個模塊單獨成行。這在 MMCV 中通常不必要也不符合項目開發(fā)慣例本項目約定如下# 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 # 使用括號進行連接而不是反斜杠 from ...utils import is_str # 最多向上回溯一層過多的回溯容易導致結(jié)構混亂要點跨行導入用括號連接而非反斜杠相對導入最多向上回溯一層避免結(jié)構混亂。1.4 OpenMMLab 的落地pre-commit 自動格式化OpenMMLab 項目使用 pre-commit 工具自動格式化代碼具體安裝與使用見 docs/zh_cn/community/contributing.md 的配置 pre-commit與代碼風格章節(jié)。核心命令如下須在 MMCV 目錄下執(zhí)行pip install -U pre-commit pre-commit install pre-commit run --all-files中國用戶若因網(wǎng)絡問題安裝失敗可使用國內(nèi)鏡像配置pre-commit install -c .pre-commit-config-zh-cn.yaml pre-commit run --all-files -c .pre-commit-config-zh-cn.yaml倉庫根目錄的 .pre-commit-config.yaml 是本項目實際的鉤子配置包含以下工具鏈鉤子作用flake8Python 官方推薦的代碼規(guī)范檢查工具是多個檢查工具的封裝isort自動調(diào)整模塊導入順序yapfGoogle 發(fā)布的代碼格式化工具trailing-whitespace / mixed-line-ending / end-of-file-fixer去除行尾空白、統(tǒng)一行尾符LF、修復文件末尾換行check-yaml / check-merge-conflict校驗 YAML 語法、檢查未解決的合并沖突requirements-txt-fixer調(diào)整requirements.txt中包的順序double-quote-string-fixer / fix-encoding-pragma / pyupgrade統(tǒng)一引號、移除編碼聲明、升級為 Python 3 語法codespell檢查單詞拼寫mdformat檢查并格式化 Markdown 文件配合 mdformat-openmmlabdocformatter格式化 docstring--in-place --wrap-descriptions 79check-copyright檢查文件版權頭針對 mmcv、tests排除 mmcv/opsmypy靜態(tài)類型檢查排除 tests 與 docs 目錄其中 C 和 CUDA 代碼遵循 Google C Style Guideclang-format 鉤子在配置中以注釋形式預留。如果提交的代碼不符合代碼風格規(guī)范pre-commit 會發(fā)出警告并自動修復部分錯誤若想臨時繞開檢查可在git commit時加上--no-verify僅用于臨時提交最終推送的代碼必須通過 pre-commit 檢查。二、命名規(guī)范2.1 命名規(guī)范的重要性優(yōu)秀的命名是良好代碼可讀性的基礎?；A命名規(guī)范對各類變量做約束使讀者能根據(jù)名字判斷它是一個類、局部變量還是全局變量而優(yōu)秀的命名則要求作者對變量功能有清晰認識與良好表達能力讓讀者僅憑名稱即可理解其含義。2.2 基礎命名規(guī)范類型公有私有模塊lower_with_under_lower_with_under包lower_with_under類CapWords_CapWords異常CapWordsError函數(shù)方法lower_with_under_lower_with_under函數(shù) / 方法參數(shù)lower_with_under全局 / 類內(nèi)常量CAPS_WITH_UNDER_CAPS_WITH_UNDER全局 / 類內(nèi)變量lower_with_under_lower_with_under變量lower_with_under_lower_with_under局部變量lower_with_under注意盡量避免變量名與保留字沖突若不可避免可使用一個后置下劃線如class_盡量不要使用過于簡單的命名約定俗成的循環(huán)變量i、文件變量f、錯誤變量e除外不會被用到的變量可命名為_邏輯檢查器會將其忽略。2.3 命名技巧良好的變量命名需保證三點含義準確、沒有歧義長短適中前后統(tǒng)一。# Wrong class Masks(metaclassABCMeta): # 命名無法表現(xiàn)基類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常見的函數(shù)命名方法動賓命名法crop_img,init_weights動賓倒置命名法imread,bbox_flip注意函數(shù)命名與參數(shù)的順序保證主語在前、符合語言習慣check_keys_exist(key, container)check_keys_contain(container, key)還要避免非常規(guī)或未統(tǒng)一約定的縮寫如nb→num_blocksin_nc→in_channels。三、docstring 規(guī)范3.1 為什么要寫 docstringdocstring 是對一個類、一個函數(shù)功能與 API 接口的詳細描述有兩個功能幫助其他開發(fā)者了解代碼功能方便 debug 和復用代碼在 Readthedocs 文檔中自動生成相關 API reference 文檔幫助不了解源代碼的社區(qū)用戶使用功能。3.2 如何寫 docstring與普通注釋不同規(guī)范的 docstring 有嚴格的格式要求以便 Python 解釋器與 sphinx 進行文檔解析docstring 的基本約定見 PEP 257。MMCV 參考格式為 Google 風格同時結(jié)合了 OpenMMLab 自身慣例。以下按模塊、類、方法三種場景給出標準格式。1. 模塊文檔代碼風格規(guī)范推薦為每個模塊Python 文件編寫 docstring但目前 OpenMMLab 項目大部分沒有此類 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. 類文檔類文檔是貢獻者最常編寫的類型。按照 OpenMMLab 慣例這里使用了與 Google 風格不同的寫法不使用 Attributes 描述類屬性而是使用 Args 描述__init__函數(shù)的參數(shù)。Args 中遵照parameter (type): Description.格式描述每個參數(shù)的類型與功能多種類型可用(float or str)寫法可以為 None 的參數(shù)寫為(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): ...補充要求在算法實現(xiàn)的主體類中建議加入原論文鏈接如果參考了其他開源代碼實現(xiàn)應加入modified from直接復制了其他代碼庫實現(xiàn)則應加入copied from并注意源碼的 License如有必要可通過.. math::加入數(shù)學公式。# 參考實現(xiàn) # This func is modified from detectron2 # ..._. # 復制代碼 # 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 中三種引號功能不同here雙反引號表示一段代碼here單反引號表示斜體here雙引號無特殊含義一般表示字符串。其中單反引號的用法與 Markdown 不同需要多加留意。另外還有:obj:type 這種更規(guī)范的表示類的寫法鑒于長度不做特別要求一般僅用于表示非常用類型。3. 方法函數(shù)文檔函數(shù)文檔與類文檔結(jié)構基本一致但需要加入返回值文檔。對于較復雜的函數(shù)和類可使用Examples字段加入示例如果需要給參數(shù)加入較長備注可加入Note字段。示例最好能直接在 Python 交互式環(huán)境中運行并給出對應結(jié)果多個示例可用注釋分隔說明。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ù)接口在某個版本發(fā)生了變化需要在 docstring 中加入說明必要時添加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ù)或返回值里帶有需要展開描述字段的 dict應采用如下格式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 文檔格式編寫否則會產(chǎn)生文檔渲染錯誤。在提交 PR 前最好生成并預覽文檔效果方法見 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語法規(guī)范參考 reStructuredText PrimerSphinx 官方文檔與 Example Google Style Python Docstringssphinxcontrib-napoleon 文檔。OpenMMLab 使用 pytorch_sphinx_theme 與 napoleon 擴展見 requirements/docs.txt 與 docs/zh_cn/conf.py將上述 Google 風格的 docstring 自動渲染為 API reference 頁面如 docs/zh_cn/api/ 下各模塊的 .rst 文件。四、注釋規(guī)范4.1 為什么要寫注釋對于一個開源項目團隊合作以及社區(qū)之間的合作必不可少因此尤其要重視合理注釋。不寫注釋的代碼可能過幾個月連作者自己也難以理解造成額外的閱讀和修改成本。4.2 如何寫注釋最需要寫注釋的是代碼中技巧性的部分。如果你在下次代碼審查的時候必須解釋一下那么你應該現(xiàn)在就給它寫注釋。對于復雜的操作應該在其操作開始前寫上若干行注釋對于不是一目了然的代碼應在其行尾添加注釋。Google 開源項目風格指南# 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ī)則為了提高可讀性注釋應至少離開代碼2 個空格絕不要描述代碼。假設閱讀代碼的人比你更懂 Python他只是不知道你的代碼要做什么。Google 開源項目風格指南# 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 語法開發(fā)人員通常熟悉 Markdown便于交流理解如用單反引號表示代碼和變量——注意不要與 docstring 中的 reStructuredText 語法混淆# _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 注釋示例代碼風格文檔給出了兩類典型注釋場景復雜邏輯結(jié)構對優(yōu)先級關系進行說明。例如 registry 構建函數(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 修復的特殊處理附帶相關 issue 鏈接幫助其他人了解 bug 背景。例如 checkpoint 保存時針對 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)五、類型注解5.1 為什么要寫類型注解類型注解是對函數(shù)中變量的類型做限定或提示為代碼的安全性提供保障、增強可讀性、避免出現(xiàn)類型相關的錯誤。Python 對類型沒有強制限制類型注解只起提示作用IDE 會解析注解并在調(diào)用代碼時給出類型提示類型注解檢查工具如 mypy則會根據(jù)注解對代碼中可能出現(xiàn)的問題進行檢查減少 bug 的出現(xiàn)。通常不需要注釋模塊中的所有函數(shù)按以下原則權衡公共的 API 需要注釋在代碼的安全性、清晰性和靈活性之間權衡是否注釋對于容易出現(xiàn)類型相關錯誤的代碼進行注釋難以理解的代碼請進行注釋若代碼中的類型已經(jīng)穩(wěn)定可以進行注釋。對于一份成熟的代碼多數(shù)情況下即使注釋了所有函數(shù)也不會喪失太多靈活性。5.2 函數(shù) / 方法類型注解通常不對self和cls注釋。根據(jù)行寬有多種寫法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 # 單獨成行具體的應用場合與行寬有關建議結(jié)合 yapf 自動化格式使用 def my_method( self, first_var: int, second_var: float ) - Tuple[MyLongType1, MyLongType1, MyLongType1]: pass # 引用尚未被定義的類型 class MyClass: def __init__(self, stack: List[MyClass]) - None: pass類型注解中的類型可以是 Python 內(nèi)置類型、自定義類也可以使用typing提供的 wrapper 類進行裝飾。常用注解# 數(shù)值類型 from numbers import Number # 可選類型指參數(shù)可以為 None from typing import Optional def foo(var: Optional[int] None): pass # 聯(lián)合類型指同時接受多種類型 from typing import Union def foo(var: Union[float, str]): pass from typing import Sequence # 序列類型 from typing import Iterable # 可迭代類型 from typing import Any # 任意類型 from typing import Callable # 可調(diào)用類型 from typing import List, Dict # 列表和字典的泛型類型 from typing import Tuple # 元組的特殊格式 # 雖然在 Python 3.9 中l(wèi)ist, tuple 和 dict 本身已支持泛型但為了支持之前的版本 # 我們在進行類型注解時還是需要使用 List, Tuple, Dict 類型 # 另外在對參數(shù)類型進行注解時盡量使用 Sequence Iterable Mapping # List, Tuple, Dict 主要用于返回值類型注解5.3 變量類型注解一般用于難以直接推斷類型時# Recommend: 帶類型注解的賦值 a: Foo SomeUndecoratedFunction() a: List[int]: [1, 2, 3] # List 只支持單一類型泛型可使用 Union b: Tuple[int, int] (1, 2) # 長度固定為 2 c: Tuple[int, ...] (1, 2, 3) # 變長 d: Dict[str, int] {a: 1, b: 2} # Not Recommend行尾類型注釋 # 雖然這種方式被寫在了 Google 開源指南中但這是一種為了支持 Python 2.7 版本 # 而補充的注釋方式鑒于我們只支持 Python 3, 為了風格統(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]使用上述方法定義了一個擁有泛型能力的映射類mapping Mappingstr, float value: float example[a]另外可以利用TypeVar在函數(shù)簽名中指定聯(lián)動的多個類型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類型注解檢查工具mypy 是一個 Python 靜態(tài)類型檢查工具。它會根據(jù)類型注解檢查傳參、賦值等操作是否符合注解從而避免可能出現(xiàn)的 bug。考慮如下腳本test.pydef foo(var: int) - float: return float(var) a: str foo(2.0) b: int foo(3.0) # type: ignore運行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ù)和返回值賦值兩處的類型錯誤第 5 行同樣存在兩處類型錯誤但因為使用了type: ignore而被忽略——只有部分特殊情況才需要此類忽略。MMCV 在提交代碼時要求補充類型注解并通過 mypy 檢查mypy 鉤子已配置在 .pre-commit-config.yaml 中排除了 tests 與 docs 目錄。六、提交 PR 前的代碼規(guī)范自查清單結(jié)合 docs/zh_cn/community/contributing.md 與 docs/zh_cn/community/pr.md向 MMCV 提交代碼前應完成以下檢查pre-commit 檢查在 MMCV 目錄下執(zhí)行pre-commit run --all-files確保 flake8、yapf、isort、mdformat、docformatter、codespell、mypy 等鉤子全部通過若鉤子安裝被網(wǎng)絡中斷可重復執(zhí)行pre-commit run ...繼續(xù)安裝單元測試pytest tests通過全量測試至少保證修改模塊的測試通過例如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確認 reStructuredText 語法渲染無誤檢查docs/zh_cn/_build/html/index.html代碼風格Python 遵循 PEP 8 并遵循本文全部規(guī)范C 與 CUDA 遵循 Google C Style GuidePR 粒度與描述一個 PR 只做一件事粒度要細標題格式為[Prefix] Short description (Suffix)前綴包括[Feature]新功能、[Fix]修 bug、[Docs]文檔、[WIP]開發(fā)中描述中說明修改理由、修改內(nèi)容與影響并關聯(lián)相關 Issue。遵守這套規(guī)范既能保證你的代碼與 MMCV 現(xiàn)有代碼庫高度一致也能讓代碼在 Readthedocs 上正確渲染為 API 文檔惠及所有社區(qū)用戶。贊分享人工智能計算機視覺深度學習【免費下載鏈接】mmcvOpenMMLab Computer Vision Foundation項目地址https://gitcode.com/gh_mirrors/mm/mmcv點擊查看免費下載相關推薦QUANTAXIS Python 代碼規(guī)范完全指南PEP 8、類型注解、命名規(guī)范與質(zhì)量工具實戰(zhàn)QUANTAXIS Python 代碼規(guī)范完全指南PEP 8、類型注解、命名規(guī)范與質(zhì)量工具實戰(zhàn) 本文依據(jù)倉庫文檔 doc/development/code s金融科技后端數(shù)據(jù)分析DeepChem 開發(fā)規(guī)范指南從 pre-commit 到類型注解的完整代碼質(zhì)量保障體系DeepChem 開發(fā)規(guī)范指南從 pre commit 到類型注解的完整代碼質(zhì)量保障體系 本篇技術指南以 DeepChem 官方開發(fā)文檔中的 Coding C人工智能深度學習機器學習生物信息學科學計算Python 3編碼規(guī)范與最佳實踐PEP 8完全解讀指南Python 3編碼規(guī)范與最佳實踐PEP 8完全解讀指南 想要寫出專業(yè)、易讀且符合行業(yè)標準的Python代碼嗎掌握PEP 8編碼規(guī)范是每個Python開發(fā)者文檔教程上一篇告別氣候數(shù)據(jù)處理困境用sqlx構建高效驗證案例數(shù)據(jù)庫下一篇gh_mirrors/ove/overleaf代碼審查流程PR規(guī)范與自動化檢查創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考