python之PEP注释规范范例

本是古典何须时尚 2022-12-28 04:04 228阅读 0赞

### 目录 ###

*  1.Class说明规范
 *  2.函数说明范例
 *  3.py文件说明范例
 *  4.引用包的注释范例
 *  5.package说明规范

# 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. """

# 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.]) """

# 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']

# 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

# 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.对于上面提到的关于注释的很多部分都是共用的，比如reference、notes可以用在函数说明中，也可以用在class说明规范里面，注意灵活使用。  
> 3.行注释：至少使用两个空格和语句分开，注意不要使用无意义的注释

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