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