python之PEP注释规范范例_python pep注释转换

1.Class说明规范

Class说明，对于传入的参数，属于parameters， Attributes是指的class的属性，对于传入的参数一般是为了初始化类的实例的属性，而atrributes是指的根据传入的参数，创建的新的属性，这些属性没有在parameters中出现. method表示类中的方法。

class PreparedConstraint(object):
    """Constraint prepared from a user defined constraint.

    On creation it will check whether a constraint definition is valid and
    the initial point is feasible. If created successfully, it will contain
    the attributes listed below.

    Parameters
    ----------
    constraint : {NonlinearConstraint, LinearConstraint`, Bounds}
        Constraint to check and prepare.
    x0 : array_like
        Initial vector of independent variables.
    sparse_jacobian : bool or None, optional
        If bool, then the Jacobian of the constraint will be converted
        to the corresponded format if necessary. If None (default), such
        conversion is not made.
    finite_diff_bounds : 2-tuple, optional
        Lower and upper bounds on the independent variables for the finite
        difference approximation, if applicable. Defaults to no bounds.

    Attributes
    ----------
    fun : {VectorFunction, LinearVectorFunction, IdentityVectorFunction}
        Function defining the constraint wrapped by one of the convenience
        classes.
    bounds : 2-tuple
        Contains lower and upper bounds for the constraints --- lb and ub.
        These are converted to ndarray and have a size equal to the number of
        the constraints.
    keep_feasible : ndarray
         Array indicating which components must be kept feasible with a size
         equal to the number of the constraints.
         
	Methods
    -------
    solve
        Returns J^-1 * v
    update
        Updates Jacobian to point `x` (where the function has residual `Fx`)
    matvec : optional
        Returns J * v
    rmatvec : optional
        Returns A^H * v
        
    Notes
    -----
    There may be additional attributes not listed above depending of the
    specific solver. Since this class is essentially a subclass of dict
    with attribute accessors, one can see which attributes are available
    using the `keys()` method.
    """
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

2.函数说明范例

对于编写的接口函数必须要有说明，对于一些不开放的函数也尽量写说明（一些工具函数以及不是很重要或简单的函数可以没有函数说明）。函数说明主要包括以下几个部分（有序）：函数概述、Parameters、Returns、See also 、Notes、References、Examples。 每个部分都以“----------”开始，在这行符号的下面开始正式说明每个部分，每个部分结束后以回车隔开，然后接着写下一个部分。See also是指的其他地方与之关联的模块，可有可无。References表示引用，该部分的实现参考文献。Examples部分写出如何调用，尽量写范例展示调用以及结果的整个过程。

def __init__(self, spacing, height, SNR, x_min, x_max, y_min, y_max,
             collection_direction):
    """Minimization of scalar function of one or more variables.

    Parameters
    ----------
    fun : callable
        The objective function to be minimized.

            ``fun(x, *args) -> float``

        where ``x`` is an 1-D array with shape (n,) and ``args``
        is a tuple of the fixed parameters needed to completely
        specify the function.
    x0 : ndarray, shape (n,)
        Initial guess. Array of real elements of size (n,),
        where 'n' is the number of independent variables.

    Returns
    -------
    res : OptimizeResult
        The optimization result represented as a ``OptimizeResult`` object.
        Important attributes are: ``x`` the solution array, ``success`` a
        Boolean flag indicating if the optimizer exited successfully and
        ``message`` which describes the cause of the termination. See
        `OptimizeResult` for a description of other attributes.

	See also
    --------
    minimize_scalar : Interface to minimization algorithms for scalar univariate functions
	show_options : Additional options accepted by the solvers

	Notes
    -----
    This section describes the available solvers that can be selected by the
	'method' parameter. The default method is *BFGS*.
	**Unconstrained minimization**
	Method :ref:`Nelder-Mead <optimize.minimize-neldermead>` uses the
	Simplex algorithm [1]_, [2]_. This algorithm is robust in many
	applications. However, if numerical computation of derivative can be
	trusted, other algorithms using the first and/or second derivatives.
	**Bound-Constrained minimization**
	。。。。

	References
	----------
	.. [1] Nelder, J A, and R Mead. 1965. A Simplex Method for Function
	    Minimization. The Computer Journal 7: 308-13.
	.. [2] Wright M H. 1996. Direct search methods: Once scorned, now
	    respectable, in Numerical Analysis 1995: Proceedings of the 1995
	    Dundee Biennial Conference in Numerical Analysis (Eds. D F
	    Griffiths and G A Watson). Addison Wesley Longman, Harlow, UK.
	    191-208.
	
	Examples
	--------
	Let us consider the problem of minimizing the Rosenbrock function. This
	function (and its respective derivatives) is implemented in `rosen`
	(resp. `rosen_der`, `rosen_hess`) in the `scipy.optimize`.
	>>> from scipy.optimize import minimize, rosen, rosen_der
	A simple application of the *Nelder-Mead* method is:
	>>> x0 = [1.3, 0.7, 0.8, 1.9, 1.2]
	>>> res = minimize(rosen, x0, method='Nelder-Mead', tol=1e-6)
	>>> res.x
	array([ 1.,  1.,  1.,  1.,  1.])
    """
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

3.py文件说明范例

每个.py文件注意最开头要有说明，先简单介绍下该文件的作用，然后指出该文件中开放的函数，然后通过__all__把开放的函数放进去，以便于通过import *这种方式导入包的时候，可以全部将开放的接口导入，而避免非开放的接口导入。对于每个文件的说明，可以通过导入该文件，然后通过__doc__查看该模块的说明。

"""
Unified interfaces to minimization algorithms.

Functions
---------
- minimize : minimization of a function of several variables.
- minimize_scalar : minimization of a function of one variable.
"""

__all__ = ['minimize', 'minimize_scalar']
1
2
3
4
5
6
7
8
9
10

4.引用包的注释范例

对于需要比较多的引用，注意把引用的给进行分类，按照应用模块进行说明下

# unconstrained minimization
from ._trustregion_dogleg import _minimize_dogleg
from ._trustregion_ncg import _minimize_trust_ncg
from ._trustregion_krylov import _minimize_trust_krylov

# constrained minimization
from .lbfgsb import _minimize_lbfgsb
from .tnc import _minimize_tnc
1
2
3
4
5
6
7
8

5.package说明规范

package的说明主要注释在__init__.py文件的开头，对于主包，首先写明包名，以”=====”与下面的内容进行分隔。然后是Provides，指明该包支持的内容。接着是How to use the documentation，指明如何查看说明文档。Available subpackages指明该包下可利用的子包有哪些。Utilities指明包的一些工具或基础内容：如配置、测试、版本等信息。Viewing documentation using Ipython信息可有可无，对于咱们这个平台如果包发布了的话，可以写明，没发布的话就不用写这部分了。子包的内容和这个类似,给这些包添加说明的时候，一定要把这个包解释清楚，可以在注释里面添加除了上面提到这些模块以外的内容。

"""
NumPy
=====

Provides
  1. An array object of arbitrary homogeneous items
  2. Fast mathematical operations over arrays
  3. Linear Algebra, Fourier Transforms, Random Number Generation

How to use the documentation
----------------------------
Documentation is available in two forms: docstrings provided
with the code, and a loose standing reference guide, available from
`the NumPy homepage <https://www.scipy.org>`_.

Available subpackages
---------------------
doc
    Topical documentation on broadcasting, indexing, etc.
lib
    Basic functions used by several sub-packages.

Utilities
---------
test
    Run numpy unittests
show_config
    Show numpy build configuration
__version__
NumPy version string

Viewing documentation using IPython
-----------------------------------
Start IPython with the NumPy profile (``ipython -p numpy``),
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

其他注意点：

1.说明尽量以一句话概述，换行再加以具体解释说明，对于重要的注释，以双行等号突出说明：
2.对于上面提到的关于注释的很多部分都是共用的，比如reference、notes可以用在函数说明中，也可以用在class说明规范里面，注意灵活使用。
3.行注释：至少使用两个空格和语句分开，注意不要使用无意义的注释

参考：https://github.com/scipy/scipy/blob/master/scipy/optimize/optimize.py