精华内容
下载资源
问答
  • 本文分析了python3新特性函数注释Function Annotations用法。分享给大家供大家参考,具体如下: Python 3.X新增加了一个特性(Feature),叫作函数注释 Function Annotations 它的用途虽然不是语法级别的硬性要求,...
  • keil插件包,导入这些插件实现(格式化代码 文件注释 函数注释 当前日期 当前时间)等功能,更加方便嵌入式开发。使用教程:https://blog.csdn.net/qq_44078824/article/details/109349611
  • VS 添加函数注释片段

    2019-02-20 16:24:21
    vs添加代码片段,在vs代码管理里面选择相应的语言,会出现代码片段地址,将该文件添加到相应文件夹
  • 主要介绍了Android Studio生成函数注释的实现方法的相关资料,希望通过本文大家能够实现这样的功能,需要的朋友可以参考下
  • 在vscode中用于生成文件头部注释和函数注释的插件,经过多版迭代后,插件:支持所有主流语言,灵活方便,文档齐全,食用简单觉得插件不错的话,就给个 :star:吧〜 使用效果: 头部注释和注释图案 函数注释:自动提取...
  • Python 函数注释

    万次阅读 多人点赞 2017-07-03 19:30:18
    在 Python 3.x 中,增加了一个新特性 - 函数注释(Function Annotations),顾名思义,可做为函数额外的注释来用。 函数注释是一个可选功能,它允许在函数参数和返回值中添加任意的元数据。无论是 Python 本身还是...

    简述

    在 Python 3.x 中,增加了一个新特性 - 函数注释(Function Annotations),顾名思义,可做为函数额外的注释来用。

    函数注释是一个可选功能,它允许在函数参数和返回值中添加任意的元数据。无论是 Python 本身还是标准库,都使用了函数注释,第三方项目可以很方便的使用函数注释来进行文档编写、类型检查、或者是其他用途。

    | 版权声明:一去、二三里,未经博主允许不得转载。

    为何要引入函数注释?

    在 Python 2.x 中,由于缺少对函数参数和返回值进行注释的标准方法,所以很多工具和库为了填补这一空白,使用了不同的方式:

    • 自定义 decorator
    • 自定义 docstring 格式
    • 向函数对象添加自定义属性

    显然,由于机制和语法的广泛差异,这会在一定程度上引起混乱。

    为了解决这个问题,Python 3.x 引入了函数注释(详见:PEP-3107),旨在提供了一种单一的、标准的方法,来将元数据与函数参数和返回值相关联。

    注意: 注释是完全可选的。

    函数注释语法

    函数注释包括:

    • 参数注释:以冒号(:)标记
    • 返回值注释:以 -> 标记

    语法结构大体如下:

    def foo(a: expression, b: expression = 5) -> expression:
        ...

    在伪语法中,参数看起来像:identifier [: expression] [= expression]。也就是说,参数注释总在其默认值之前。当函数定义被执行时,所有的注释表达式都被求值,就像默认值一样。

    参数列表后面可以跟一个 -> 和一个 Python 表达式。与参数的注释一样,在执行函数定义时,将对该表达式求值。

    单个注释

    函数注释可以包含类型、帮助字符串,以及其他更多信息。

    来看一个例子,有一个函数 sum(),接受三个参数 a、b、c,并返回它们的和。

    >>> def sum(a, b: int, c: 'The default value is 5' = 5) -> float:
    ...     return a + b + c
    ... 
    >>> 

    其中,第一个参数 a 没有注释,第二个参数 b 带有类型为 int 的注释,第三个参数 c 带有一个帮助字符串注释并且拥有默认值,返回值用类型 float 来注释。

    调用 sum() 两次,一次使用 int,一次使用字符串:

    >>> sum(1, 2)
    8
    >>> 
    >>> sum('Hello', ', ', 'Python!')
    'Hello, Python!'

    显然,注释对函数的执行没有任何影响。在这两种情况下,sum() 都做了正确的事情,只不过注释被忽略了而已。

    访问函数注释

    函数对象有一个名为 __annotations__ 的属性,它是一个映射(dict),用于将每个参数名(key)映射到其相关的注释(value)。

    注意: 映射中有一个特殊的 key,叫做“return”,仅当为函数的返回值提供注释时,才会显示该 key。

    回到上述示例,并检查它的注释:

    >>> type(sum.__annotations__)
    <class 'dict'>
    >>>
    >>> sum.__annotations__
    {'c': 'The default value is 5', 'return': <class 'float'>, 'b': <class 'int'>}

    之所以选择 “return”,是因为它不会与任何参数名冲突。“return”是 Python 中的一个关键字,任何使用“return”作为参数名的尝试都会引发 SyntaxError。

    多个注释

    倘若,函数注释中要同时包含类型和帮助字符串,怎么办?很容易,可以使用具有两个 key(例如:type 和 help)的 dict:

    >>> def div(a: dict(type=float, help='the dividend'),
    ...         b: dict(type=float, help='the divisor (must be different than 0)')
    ...     ) -> dict(type=float, help='the result of dividing a by b'):
    ...     """Divide a by b"""
    ...     return a / b
    ... 
    >>> 

    调用 div():

    >>> div.__annotations__
    {'a': {'type': <class 'float'>, 'help': 'the dividend'}, 'return': {'type': <class 'float'>, 'help': 'the result of dividing a by b'}, 'b': {'type': <class 'float'>, 'help': 'the divisor (must be different than 0)'}}
    >>>
    >>> div(5, 2)
    2.5

    注意: 如果要包含更多的注释(示例中是 2 个),可以在 dict 中包含更多的 key:value 对。

    动态注释

    __annotations__ 是函数的一个属性,类型为 dict。由于 dict 是可变的,这意味着,可以在程序运行时动态地修改注释。

    假设,想知道是否使用了参数的默认值,或者想把所有的返回值都加起来。

    >>> def sum(a, b) -> 0:
    ...     result = a + b
    ...     sum.__annotations__['return'] += result
    ...     return result
    ... 
    >>> sum.__annotations__['return']
    0
    >>> 
    >>> sum(1, 2)
    3
    >>> sum.__annotations__['return']
    3
    >>> 
    >>> sum(3, 4)
    7
    >>> sum.__annotations__['return']
    10

    PS: 动态注释可以在函数内部完成,也可以由装饰器完成。

    展开全文
  • Python 3函数注释

    千次阅读 2020-06-12 10:54:10
    函数注释是Python 3的一项功能,可让您向函数参数添加任意元数据并返回值。 它们是原始Python 3.0规范的一部分。 在本教程中,我将向您展示如何利用通用功能注释并将其与装饰器结合使用。 您还将了解功能注释的优...

    函数注释是Python 3的一项功能,可让您向函数参数添加任意元数据并返回值。 它们是原始Python 3.0规范的一部分。

    在本教程中,我将向您展示如何利用通用功能注释并将其与装饰器结合使用。 您还将了解功能注释的优缺点,何时使用它们以及何时最好使用其他机制,例如文档字符串和普通修饰符。

    功能注释

    功能注释在PEP-3107中指定。 主要动机是提供一种将元数据关联到函数参数和返回值的标准方法。 许多社区成员发现了新颖的用例,但是使用了不同的方法,例如自定义装饰器,自定义docstring格式以及向功能对象添加自定义属性。

    重要的是要理解Python不会使用任何语义来祝福注释。 它纯粹为关联元数据提供了一个不错的语法支持,并提供了一种简单的访问方式。 另外,注释完全是可选的。

    让我们看一个例子。 这是一个函数foo() ,它接受三个称为a,b和c的参数并输出其总和。 注意foo()不返回任何内容。 第一个参数a不带注释。 第二个参数b用字符串“ annotating b”注释,第三个参数cint类型注释。 返回值用float类型注释。 请注意用于注释返回值的“->”语法。

    def foo(a, b: 'annotating b', c: int) -> float:
        print(a + b + c)

    注释对函数的执行没有任何影响。 让我们两次调用foo() :一次使用int参数,一次使用string参数。 在这两种情况下, foo()都会做正确的事,并且注释将被忽略。

    foo('Hello', ', ', 'World!')
    Hello, World!
    
    foo(1, 2, 3)
    6

    默认参数

    在注解后指定默认参数:

    def foo(x: 'an argument that defaults to 5' = 5):
        print(x)
    
    foo(7)
    7
    
    foo()
    5

    访问功能注释

    函数对象具有称为“ 批注 ”的属性。 它是将每个参数名称映射到其注释的映射。 返回值注释映射到键“ return”,该键不能与任何参数名称冲突,因为“ return”是一个保留字,不能用作参数名称。 请注意,可以将名为return的关键字参数传递给函数:

    def bar(*args, **kwargs: 'the keyword arguments dict'):
        print(kwargs['return'])
    
    d = {'return': 4}
    bar(**d)
    4

    让我们回到第一个示例并检查其注释:

    def foo(a, b: 'annotating b', c: int) -> float:
        print(a + b + c)
        
    print(foo.__annotations__)
    {'c': <class 'int'>, 'b': 'annotating b', 'return': <class 'float'>}

    这很简单。 如果用参数数组和/或关键字参数数组对函数进行注释,则显然不能注释单个参数。

    def foo(*args: 'list of unnamed arguments', **kwargs: 'dict of named arguments'):
        print(args, kwargs)
    
    print(foo.__annotations__)
    {'args': 'list of unnamed arguments', 'kwargs': 'dict of named arguments'}

    如果您阅读了PEP-3107中有关访问功能注释的部分,则说明您通过功能对象的'func_annotations'属性访问它们。 从Python 3.2开始,这已经过时了。 不要困惑。 它只是“ 注解 ”属性。

    您可以使用注释做什么?

    这是个大问题。 注释没有标准含义或语义。 有几种通用用途。 您可以将它们用作更好的文档,并将参数和返回值文档移出文档字符串。 例如,此功能:

    def div(a, b):
        """Divide a by b  
        args:
            a - the dividend
            b - the divisor (must be different than 0)
        return:
            the result of dividing a by b
        """
        return a / b

    可以转换为:

    def div(a: 'the dividend',
            b: 'the divisor (must be different than 0)') -> 'the result of dividing a by b':
        """Divide a by b"""
        return a / b

    在捕获相同信息的同时,注释版本有很多好处:

    1. 如果重命名参数,则文档文档字符串版本可能已过期。
    2. 更容易查看是否未记录参数。
    3. 无需在文档字符串中提出要由工具解析的参数文档的特殊格式。 注解属性提供了直接的标准访问机制。

    我们稍后将讨论的另一种用法是可选类型。 Python是动态类型的,这意味着您可以将任何对象作为函数的参数传递。 但是函数通常需要参数为特定类型。 通过注释,您可以非常自然地在参数旁边指定类型。

    请记住,仅指定类型不会强制执行它,并且将需要其他工作(很多工作)。 尽管如此,即使仅指定类型也可以使意图比在文档字符串中指定类型更具可读性,并且可以帮助用户理解如何调用该函数。

    与文档字符串相比,注释的另一个好处是您可以将不同类型的元数据作为元组或字典附加。 同样,您也可以使用docstring进行此操作,但是它将基于文本,并且需要特殊的解析。

    最后,您可以附加很多元数据,这些元数据将由特殊的外部工具使用,或在运行时通过装饰器使用。 我将在下一部分中探讨此选项。

    多个注释

    假设您想用一个类型和一个帮助字符串来注释一个参数。 使用批注非常容易。 您可以简单地用具有两个键的dict注释自变量:'type'和'help'。

    def div(a: dict(type=float, help='the dividend'),
            b: dict(type=float, help='the divisor (must be different than 0)')
        ) -> dict(type=float, help='the result of dividing a by b'):
        """Divide a by b"""
        return a / b
        
    print(div.__annotations__)
    {'a': {'help': 'the dividend', 'type': float},
     'b': {'help': 'the divisor (must be different than 0)', 'type': float},
     'return': {'help': 'the result of dividing a by b', 'type': float}}

    结合Python注释和装饰器

    注解和装饰器齐头并进。 有关Python装饰器的一个很好的介绍,请查看我的两个教程:“ 深入研究Python装饰器”和“ 编写您自己的Python装饰器”

    首先,注释可以完全实现为装饰器。 您只需定义一个@annotate装饰器,并使其使用参数名称和Python表达式作为参数,然后将其存储在目标函数的注解属性中即可。 对于Python 2也可以做到这一点。

    但是,装饰器的真正功能是它们可以对注释起作用。 当然,这需要对注释的语义进行协调。

    让我们来看一个例子。 假设我们要验证参数是否在一定范围内。 注释将是一个元组,其中每个参数的最小值和最大值。 然后,我们需要一个装饰器,该装饰器将检查每个关键字参数的注释,验证该值是否在范围内,否则引发异常。 让我们从装饰器开始:

    def check_range(f):
        def decorated(*args, **kwargs):
            for name, range in f.__annotations__.items():
                min_value, max_value = range
                if not (min_value <= kwargs[name] <= max_value):
                    msg = 'argument {} is out of range [{} - {}]'
                    raise ValueError(msg.format(name, min_value, max_value))
            return f(*args, **kwargs)
        return decorated

    现在,让我们定义函数并使用@check_range装饰器对其进行装饰。

    @check_range
    def foo(a: (0, 8), b: (5, 9), c: (10, 20)):
        return a * b - c

    让我们用不同的参数调用foo() ,看看会发生什么。 当所有参数都在其范围内时,就没有问题。

    foo(a=4, b=6, c=15)
    9

    但是,如果将c设置为100(超出(10,20)范围),则会引发异常:

    foo(a=4, b=6, c=100)
    ValueError: argument c is out of range [10 - 20]

    什么时候应该使用装饰器而不是注释?

    在许多情况下,装饰器比附加元数据的注释要好。

    一种明显的情况是您的代码是否需要与Python 2兼容。

    另一种情况是,如果您有很多元数据。 如您先前所见,虽然可以通过使用dict作为注释来附加任何数量的元数据,但它相当麻烦并且实际上会损害可读性。

    最后,如果元数据应该由特定的修饰器操作,则最好将元数据关联为修饰器本身的参数。

    动态注释

    注释只是函数的dict属性。

    type(foo.__annotations__)
    dict

    这意味着您可以在程序运行时即时修改它们。 有哪些用例? 假设您想确定是否使用了参数的默认值。 每当使用默认值调用该函数时,都可以增加注释的值。 或者,也许您想总结所有返回值。 动态方面可以在函数本身内部或由装饰器完成。

    def add(a, b) -> 0:
        result = a + b
        add.__annotations__['return'] += result
        return result
        
    print(add.__annotations__['return'])
    0
    
    add(3, 4)
    7
    print(add.__annotations__['return'])
    7
    
    add(5, 5)
    10
    print(add.__annotations__['return'])
    17

    结论

    功能注释功能多样且令人兴奋。 他们有可能进入自省工具的新时代,以帮助开发人员掌握越来越复杂的系统。 它们还为更高级的开发人员提供了一种标准且可读的方法,可将元数据直接与参数和返回值关联,以创建自定义工具并与装饰器进行交互。 但是需要一些工作才能从中受益并发挥其潜力。

    无论您是刚刚起步还是想学习新技能的经验丰富的程序员,都可以通过我们完整的python教程指南学习Python。

    翻译自: https://code.tutsplus.com/tutorials/python-3-function-annotations--cms-25689

    展开全文
  • VS宏_自动函数注释

    2012-04-11 10:04:51
    VS宏,为C++文件与函数自动添加格式化注释,方便规范代码。 其中为文件添加注释自动写入文件名和时间戳。 为函数添加注释自动写入函数名与参数,但不能智能分辨输入与输出参数,需手动更改。 为函数添加注释时,如果...
  • 1、文件添加方式: ...2、自动生成函数注释,包括参数和返回值。使用方法,函数定义时,直接输入三个双引号后回车。 也可以将光标放在方法上,会弹出一个小灯,选择第一个就好了。 显示如下: 补充知
  • goland函数注释生成插件

    千次阅读 热门讨论 2020-12-05 21:00:16
    goland函数注释生成插件goanno使用方式 网上存在很多如何使用goland生成函数注释模版的介绍,比如有介绍在Live Template中编写。 可以参考这篇文章配置Preferences | Editor | Live Templates 配置文档 先说一下,...

    goland函数注释生成插件

    网上存在很多如何使用goland生成函数注释模版的介绍,比如有介绍在Live Template中编写。

    可以参考这篇文章配置Preferences | Editor | Live Templates 配置文档

    先说一下,可以生效,但是前提是你的光标在函数内,不能放在函数头部,并且生成的注释也在函数内部,之后需要手动复制出来。除此之外,goland的一些特性比如函数接受者,多个return都无法支持。

    由于目前暂时没有发现一个完全可以使用用的方案,所以抽空简单写了一个自动生成goland注释的插件,目前已经有3000+的下载用户使用。
    在这里插入图片描述

    goanno

    可以通过goland或者idea的插件市场通过搜索goanno下载。
    也可以直接通过如下的网址下载release包,通过本地安装插件安装。
    https://plugins.jetbrains.com/plugin/14988-goanno
    https://github.com/loveinsky100/goanno

    完美支持goland的函数注释,包括interface/普通函数/函数接受者/多个出参
    在这里插入图片描述
    请添加图片描述

    使用方式

    目前有两种方式
    生成注释
    1.快捷键control + commond + / (windows用户快捷键配置参考:GoLand 快速添加方法注释
    2.手动生成:鼠标右键 -> 选择Generate -> 选择Goanno

    PS:新增一个键位支持 ctrl + alt + /

    调整模版(默认模版为java样式,可以通过修改模版调整成golang官方推荐的样式)
    选择导航栏"Tools - Goanno Setting"

    默认模版:

    /**
     * @Description: ${todo}
     * @receiver ${receiver}
     * @param ${params}
     * @return ${return_types}
     */
    

    当然可以手动修改模版 (中间为 tab ,这样在goland中查看注释排版会进行换行)

    //
    //	${function_name}
    //	@Description: ${todo}
    //	@receiver ${receiver_name_type}
    //	@param ${param_name_type}
    //	@return ${ret_name_type}
    //
    
    

    模版设置位置
    模版编辑
    V2.2.0支持注释覆盖

    展开全文
  • pycharm使用笔记3-自动生成文件注释和函数注释

    万次阅读 多人点赞 2018-10-26 09:57:38
    1. 文件注释 pycharm提供了一个在新建文件自动生成文件头注释的功能,可以实现自动生成运行环境,作者、日期等必要信息,使用比较方便,配置十分简单。 按照1-5的路径选项即可。在5中填写想要的注释。 我的模板:...

    1. 文件注释

    pycharm提供了一个在新建文件自动生成文件头注释的功能,可以实现自动生成运行环境,作者、日期等必要信息,使用比较方便,配置十分简单。
    在这里插入图片描述按照1-5的路径选项即可。在5中填写想要的注释。
    我的模板:

    #!/usr/bin/env python
    # -*- encoding: utf-8 -*-
    '''
    @File    :   ${NAME}.py    
    @Contact :   raogx.vip@hotmail.com
    @License :   (C)Copyright 2017-2018, Liugroup-NLPR-CASIA
    
    @Modify Time      @Author    @Version    @Desciption
    ------------      -------    --------    -----------
    ${DATE} ${TIME}   gxrao      1.0         None
    '''
    
    # import lib
     
    

    2. 函数注释

    自动生成函数注释,包括参数和返回值。
    使用方法,函数定义时,直接输入三个双引号后回车,例如:

    def a(b,c):
    

    另起一行,输入三个引号,后回车

    def a(b,c):
    """
    

    结果:

    def a(b,c):
        """
        :param b:
        :param c:
        :return:
        """
    
    展开全文
  • pycharm 自动生成文件注释和函数注释

    千次阅读 2020-06-22 10:29:56
    1. 文件注释 pycharm提供了一个在新建文件自动生成文件头注释的功能,可以实现自动生成运行环境,作者、日期等必要信息,使用比较方便,配置十分简单。在anaconda 的spider也有类似的功能, 按照1-5的路径选项...
  • Qt creator 函数注释

    2020-07-28 10:05:54
    /** * internal is algorithm used data,using * float type */ using InternalType = itk::Image<float, 3>; qtcreator 可以添加函数注释模块。只需要输入/** ,在加上回车键。
  • pycharm 自动函数注释

    2020-09-09 10:46:38
    pycharm 自动函数注释
  • vs 添加函数注释说明

    千次阅读 2020-06-14 10:36:12
    </CodeSnippet> </CodeSnippets> 3、这里我创建了hssm.snippet (函数说明的缩写) 进入 vs工具栏,后续操作步骤如下图 导入新建的hssm.snippet 如果提示已经存在就覆盖原来的文件 4.在写代码时输入fuc就会自动跳出...
  • C语言:标准的函数注释格式

    千次阅读 2020-03-14 20:58:01
    标准的函数注释格式; //================================================================== //函数名: //作者: //日期: //功能: //输入参数: //返回值: //修改记录: //=================================...
  • pycharm函数注释

    2020-04-02 19:29:12
  • goland函数注释生成插件 goanno 使用方式 网上存在很多如何使用goland生成函数注释模版的介绍,比如有介绍在Live Template中编写。 可以参考这篇文章配置Preferences | Editor | Live Templates 配置文档 先说...
  • 1.下载插件 koroFileHeader ...要添加函数注释时,将光标移动到函数上方,按下 ctrl+alt+m 组合键 /** * @description: * @param {*} type * @param {*} value * @return {*} */ init (type, value) {
  • python函数注释, :与 -> 如图: add1函数中的:意思是:函数中的参数说明 add2函数中:->意思是:函数的返回值为整型 这两种方法都是函数的注释方法,具体使用时要别人能看懂就行,也没有什么严格的限制 ...
  • Pycharm函数注释模板的简单修改方法

    千次阅读 2020-04-21 15:23:50
    在pycharm中定义函数时,不喜欢默认自动生成的函数注释模板,希望换成更美观的格式。 Pycharm默认自动生成的函数注释模板 如下图,在pycharm定义函数时,单/双三引号添加函数注释,pycharm会自动帮助生成注释模板。...
  • PyCharm 不能自动生成函数注释

    千次阅读 2020-07-01 23:52:55
    另外,PyCharm在定义函数之后,可以自动生成包括参数和返回值在内的注释,具体使用方法为1: 函数定义后,另起一行,输入三个引号(单引号和双引号均可),后回车。 def f(b,c): ''' 结果为: def a(b,c): '''...
  • Doxygen 函数注释

    千次阅读 2019-05-16 20:18:48
    一 demo class FunctionDemo{ ... * @brief func是一个普通成员函数 * * @param a [in] param a * @param b [in, out] param b * @param c [out] output * @return int * @retval * 1...
  • 解决Pycharm不能自动生成函数注释

    千次阅读 2020-10-11 22:42:32
    PyCharm在定义函数之后,可以自动生成包括参数和返回值在内的注释,具体使用方法为: 函数定义后,另起一行,输入三对引号(单引号和双引号均可),后回车def f(b,c): ''' 输出结果为def a(b,c): '...
  • vscode-函数注释插件-正则插件

    千次阅读 2019-10-07 20:24:07
    1、安装插件KoroFileHeader(函数标准注释) 2、设置 在vscode左下角点击设置按钮,选择...函数注释:Fileheader:cursor Mode 随便点击哪个"在setting.json"中编辑,输入以下设置后保存,然后重启vsco...
  • VsCode自动生成头部注释和函数注释(无插件,python为例)进入用户代码代码片段进入python.json文件添加头注释和函数注释使用效果 进入用户代码代码片段 进入File > Preferences > User Snippets 选择语言,...
  • VsCode 添加文件头部注释和函数注释[koroFileHeader] https://juejin.im/post/6844903694165606408 https://github.com/OBKoro1/koro1FileHeader

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 739,143
精华内容 295,657
关键字:

函数注释