Python'da birkaç farklı yazım öğretisi gördüm, resmi veya “üzerinde anlaşılan” bir tarz var mı?

Biçimleri

Python docstrings diğer yazıların gösterdiği gibi birkaç formatta yazılabilir. Ancak, varsayılan Sphinx docstring biçiminden bahsedilmedi ve reStructuredText (reST) yöntemini temel alıyor . Bu blog gönderisindeki ana biçimler hakkında bilgi edinebilirsiniz .

REST'nin PEP 287 tarafından önerildiğini unutmayın

Docstringler için kullanılan ana formatlar aşağıdadır.

- Ek metin

Tarihsel olarak javadoc benzeri bir stil yaygındı, bu nedenle Epydoc'ın (çağrılan Epytextformatla) dokümantasyon oluşturması için bir temel olarak alındı .

Misal:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- dinlenme

Günümüzde, muhtemelen daha yaygın olan biçim, Sphinx tarafından belge oluşturmak için kullanılan reStructuredText (reST) biçimidir . Not: JetBrains PyCharm'da varsayılan olarak kullanılır (bir yöntemi tanımladıktan sonra üçlü tırnaklar yazın ve enter tuşuna basın). Ayrıca, Pyment'ta varsayılan olarak çıktı biçimi olarak da kullanılır.

Misal:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- Google

Google'ın sıklıkla kullanılan kendi biçimi vardır. Ayrıca Sfenks tarafından yorumlanabilir (yani Napolyon eklentisi kullanılarak ).

Misal:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

Daha da fazla örnek

- Numpydoc

Numpy'nin Google formatına dayalı ve Sphinx tarafından kullanılabilen kendi numpydoc'larını takip etmeyi önerdiğini unutmayın .

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

Dönüştürme / Üretme

Henüz belgelenmemiş bir Python projesine otomatik olarak docstring oluşturmak veya mevcut docstring'leri (birkaç formatı karıştırabilir) bir formattan diğerine dönüştürmek için Pyment gibi bir araç kullanmak mümkündür .

Not: Örnekler Pyment belgelerinden alınmıştır.

Google stil kılavuzu mükemmel bir Python stil kılavuzu içerir. PEP-257'den daha iyi rehberlik sunan okunabilir doktora sözdizimi kurallarını içerir . Örneğin:

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

Ben de bu Sfenks dokümantasyon öğretici açıklandığı gibi, argümanlarda tür bilgilerini eklemek için genişletmek istiyorum . Örneğin:

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

Dokümantasyon kuralları PEP- 257'de PEP-8'den çok daha ayrıntılıdır.

Ancak, öğretiler diğer kod alanlarından çok daha kişisel görünmektedir. Farklı projelerin kendi standartları olacaktır.

Her zaman öğretileri dahil etme eğilimindeyim, çünkü işlevi nasıl kullanacağını ve çok hızlı bir şekilde ne yaptığını gösterme eğilimindedirler.

Dizenin uzunluğundan bağımsız olarak işleri tutarlı tutmayı tercih ederim. Girinti ve boşluk tutarlı olduğunda nasıl kodlamak gibi. Bu şu anlama gelir:

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

Bitmiş:

def sq(n):
    """Returns the square of n."""
    return n * n

Ve daha uzun docstrings ilk satırda yorum bırakma eğilimindedir:

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

Yani böyle başlayan dağınık öğretileri buluyorum.

def sq(n):
    """Return the squared result. 
    ...

Görünüşe göre hiç kimse bundan bahsetmediği gibi: Numpy Docstring Standardını da kullanabilirsiniz . Bilimsel toplulukta yaygın olarak kullanılmaktadır.

• Biçiminin özellikleri bir ile numpy, birlikte , örneğin
• Oluşturmak için bir sfenks uzantınız var: numpydoc
• Ve işlenmiş bir öğretinin nasıl güzel görünebileceğine bir örnek: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

Google tarzı doktrinleri ayrıştırmak için Napolean sfenks uzantısı (@Nathan cevabında önerilir) Numpy tarzı doktrinleri de destekler ve her ikisinin de kısa bir karşılaştırmasını yapar .

Ve nasıl göründüğüne dair bir fikir vermek için temel bir örnek verin:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True

PEP-8 resmi python kodlama standardıdır. Docstringlerle ilgili, PEP- 257'ye atıfta bulunan - docstrings için tam bir spesifikasyon olan bir bölüm içerir .

Bu Python; bir şey gider . Belgelerinizi nasıl yayınlayacağınızı düşünün . Docstringler kaynak kodunuzun okuyucuları dışında görünmez.

İnsanlar web'deki belgelere göz atmayı ve arama yapmayı gerçekten seviyor. Bunu başarmak için Sfenks dokümantasyon aracını kullanın . Python projelerini belgelemek için fiili standarttır. Ürün güzel - https://python-guide.readthedocs.org/en/latest/ adresine bakın . Dokümanları Oku web sitesi dokümanlarınızı ücretsiz olarak barındırır.

Parametrelerinizi, iadelerinizi vb. Tanımlamak için doktorlarınızı PEP-257 ve Numpy Docstring Standard'a karşı kontrol etmek için Vladimir Keleshev'in pep257 Python programını kullanmanızı öneririm .

pep257, standarttan yaptığınız sapmayı bildirir ve pylint ve pep8 gibi adlandırılır.