Python Docstring’leri Eğitimi: Pydoc, Numpy, Sphinx Docstring’leri için Örnekler ve Format

Eğer Python’a yeni başladıysanız ve daha fazla öğrenmek istiyorsanız, DataCamp’in Python ile Veri Bilimine Giriş kursunu alın.

Bu uygulamalı alıştırma ile Python’da Docstring yazmayı pratik edin.

Python Docstring’leri nedir? 

Python dokümantasyon dizgesi, yaygın adıyla docstring, bir dizge sabitidir ve sınıf, modül, fonksiyon veya metot tanımında kullanılır. Docstring’lere herhangi bir Python nesnesi için (__doc__) doc özniteliğinden ve yerleşik help() fonksiyonuyla erişilebilir. Bir nesnenin docstring’i, nesnenin tanımındaki ilk ifade olarak bir dizge sabiti eklenerek tanımlanır.

Tek tek kod satırlarını açıklayan normal yorumlardan farklı olarak, docstring’ler bir fonksiyonun, sınıfın veya modülün ne yaptığını yüksek seviyede açıklar. İyi yazılmış docstring’ler kodun okunabilirliğini, sürdürülebilirliğini ve iş birliğini artırır; bu da bir Python geliştiricisi olarak Python kodunuzu belgelemenin en iyi uygulamalarından biridir.

Docstring’ler bir modülün veya fonksiyonun yeteneklerini anlamanıza yardımcı olur. Örneğin, scikit-learn kütüphanesini yüklediğinizi ve açıklama, paket modülleri vb. gibi sklearn paketi hakkında her şeyi bilmek istediğinizi varsayalım; tüm bu bilgileri almak için basitçe help fonksiyonunu kullanabilirsiniz.

Paketi hızlıca içe aktaralım.

import sklearn

help(sklearn)

Aşağıda gösterilene benzer bir çıktı görürsünüz:

Python Docstring’leri ve Yorum Yazımı

Docstring’ler, yorum yazma fikrine benzer olsa da daha gelişmiş, daha mantıklı ve daha kullanışlı bir versiyonudur. Docstring’ler sınıf, modül ve paketler için dokümantasyon görevi görür.

Öte yandan yorumlar, ağırlıklı olarak kodun bariz olmayan kısımlarını açıklamak için kullanılır ve hata düzeltme ile yapılması gereken görevler için faydalı olabilir.

Docstring’ler açılış ve kapanış tırnaklarıyla gösterilirken, yorumlar başında # ile başlar.

Yorumlara yerleşik doc özniteliği ve help fonksiyonuyla erişilemeyeceğini unutmayın. Bunu denerseniz ne olduğuna bakalım:

def string_reverse(str1):
    #Returns the reversed String.

    #Parameters:
    #    str1 (str):The string which is to be reversed.

    #Returns:
    #    reverse(str1):The string which gets reversed.   

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse.__doc__)

None

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)

Bir Docstring yazmanın veya kullanmanın birkaç yolu vardır; tek satırlık docstring ve çok satırlı docstring. Bunları tek tek öğrenelim.

Tek Satırlık Docstring

Tek satırlık docstring’ler tek satıra sığan kısa açıklamalardır. Üçlü tırnaklar (''' veya """) ile çevrelenir ve kapanış tırnakları aynı satırda olmalıdır.

Üç tek tırnak da üç çift tırnak da çalışsa da, Python’da standart gelenek üç çift tırnak (""") kullanmaktır.

İşte bir örnek: 

def square(a):
    """Returns the square of the given number."""
    return a ** 2  # Corrected exponentiation

# Accessing the docstring
print(square.__doc__)

Çıktı:

Returns the square of the given number.

Bu dokümantasyonu Python’un help() fonksiyonuyla da alabilirsiniz:

help(square)

Çıktı:

Help on function square in module __main__:

square(a)
    Returns the square of the given number.

Çok Satırlı Docstring

Çok satırlı Docstring’ler de tek satırlı Docstring’lerdeki gibi dizge sabitini içerir, ancak bunun ardından açıklayıcı metinden önce tek bir boş satır gelir.

Çok satırlı bir Docstring yazmanın genel formatı aşağıdaki gibidir:

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

help(some_function)

Help on function some_function in module __main__:

some_function(argument1)
    Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

Çok satırlı dizgelerin ayrıntılı şekilde nasıl kullanılabileceğini gösteren örneğe bakalım:

def string_reverse(str1):
    '''
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.   
    '''

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse('DeepLearningDataCamp'))

pmaCataDgninraeLpeeD

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.

Yukarıda, özet satırının tek bir satırda olduğunu ve diğer içerikten tek bir boş satırla ayrıldığını görebilirsiniz. Bu gelenek, otomatik indeksleme araçları için faydalıdır ve takip edilmelidir.

Python Yerleşik Docstring

Yerleşik Python Docstring’lerine bakalım.

Tüm yerleşik fonksiyonlar, sınıflar ve metotlar için gerçek insan tarafından yazılmış açıklamalar bulunur. Bunlara iki yoldan biriyle erişebilirsiniz.

• doc özniteliği
• help fonksiyonu

help fonksiyonunun çıktısının, __doc__ özniteliğinden daha ayrıntılı olduğunu fark edersiniz.

Örneğin:

import math
print(math.__doc__)

This module provides access to the mathematical functions
defined by the C standard.

Benzer şekilde, help fonksiyonunu kullanabilirsiniz:

help(math)

Sınıflarda Python Docstring

Bir sınıf tanımında, docstring sınıfın tamamı için dokümantasyon sağlamak amacıyla kullanılabilir. Genellikle sınıf tanımının hemen ardından yerleştirilir ve üçlü tırnaklar (""") içine alınır. Örneğin:

class MyClass:
    """This is the documentation for MyClass."""

    def __init__(self):
        """This is the documentation for the __init__ method."""
        pass

Docstring’lere sınıfın veya metodun __doc__ özniteliği kullanılarak erişilebilir. Örneğin, MyClass için docstring’e MyClass.__doc__ ile erişebilirsiniz.

Şimdi bazı popüler Docstring Formatlarına bakalım ve bunları ayrıntılı olarak anlayalım.

Python Docstring Formatları

Birçok Docstring formatı mevcuttur, ancak Docstring ayrıştırıcıları ve diğer Veri Bilimciler/programcılar tarafından kolayca tanınan formatları kullanmak her zaman daha iyidir. Bir Docstring formatı seçmek için katı kurallar yoktur, ancak proje boyunca aynı formatı tutarlı şekilde kullanmak gereklidir. Ayrıca, çoğunlukla Sphinx tarafından desteklenen biçim türünü kullanmanız tercih edilir.

En yaygın kullanılan formatlar aşağıda listelenmiştir.

Farklı dokümantasyon dizgeleri mevcut olabilir. Hepsini baştan öğrenmek zorunda olduğunuz için endişelenmeyin. Tüm Dokümantasyon dizgelerinin formatları neredeyse benzerdir. Kalıplar benzer, yalnızca her formatta küçük ayrıntı farklılıkları vardır. Kullanımlarıyla birlikte mevcut popüler bir dokümantasyon dizgesi formatının örneğini göreceksiniz.

Önce Sphinx Stilini ayrıntılı biçimde görecek, ardından diğer formatları da kolayca takip edebileceksiniz.

Sphinx Stili

Sphinx, kullanımı kolay ve geleneksel, ayrıntılı bir stildir ve başlangıçta özellikle Python Dokümantasyonu için oluşturulmuştur. Sphinx, kullanımı Markdown’a benzeyen bir reStructured Text kullanır.

class Vehicle(object):
    '''
    The Vehicle object contains lots of vehicles
    :param arg: The arg is used for ...
    :type arg: str
    :param `*args`: The variable arguments are used for ...
    :param `**kwargs`: The keyword arguments are used for ...
    :ivar arg: This is where we store arg
    :vartype arg: str
    '''


    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel a certain distance in vehicles without fuels, so here's the fuels

        :param distance: The amount of distance traveled
        :type amount: int
        :param bool destinationReached: Should the fuels be refilled to cover required distance?
        :raises: :class:`RuntimeError`: Out of fuel

        :returns: A Car mileage
        :rtype: Cars
        '''  
        pass

Sphinx, çoğu programlama dilinde olduğu gibi anahtar sözcük (reserved word) kullanır; ancak Sphinx’te buna özel olarak role denir. Yukarıdaki kodda, Sphinx’te param bir role’dür ve type da param için Sphinx veri tipi olan bir role’dür. type role’ü isteğe bağlıdır, ancak param zorunludur. Dönüş role’leri döndürülen nesneyi belgele. Bu, param role’ünden farklıdır. Dönüş role’ü rtype’a bağlı değildir ve tersi de geçerlidir. rtype, verilen fonksiyondan döndürülen nesnenin türüdür.

Google Stili

Google Stili daha kolay ve sezgiseldir. Daha kısa dokümantasyonlar için kullanılabilir. Başlamak için bir Python yapılandırması yapmak gerekir; bu nedenle conf.py içindeki extensions listesine sphinx.ext.napoleon veya sphinxcontrib.napoleon eklemeniz gerekir.

class Vehicles(object):
    '''
    The Vehicle object contains a lot of vehicles

    Args:
        arg (str): The arg is used for...
        *args: The variable arguments are used for...
        **kwargs: The keyword arguments are used for...

    Attributes:
        arg (str): This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance,destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Args:
            distance (int): The amount of distance traveled
            destination (bool): Should the fuels refilled to cover the distance?

        Raises:
            RuntimeError: Out of fuel

        Returns:
            cars: A car mileage
        '''
        pass

Google Stili Sphinx stilinden daha iyidir. Ancak yukarıdaki kodda olduğu gibi, mesafenin çok satırlı açıklaması karmaşık görünebilir. Bu nedenle daha uzun biçimli dokümantasyon için Numpy kullanılabilir.

Numpy Stili

Numpy stili dokümantasyonda çok fazla ayrıntı içerir. Diğer dokümantasyonlara göre daha ayrıntılıdır, ancak tüm fonksiyonlar ve parametreler için kapsamlı dokümantasyon istediğinizde mükemmel bir seçimdir.

class Vehicles(object):
    '''
    The Vehicles object contains lots of vehicles

    Parameters
    ----------
    arg : str
        The arg is used for ...
    *args
        The variable arguments are used for ...
    **kwargs
        The keyword arguments are used for ...

    Attributes
    ----------
    arg : str
        This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Parameters
        ----------
        distance : int
            The amount of distance traveled
        destination : bool
            Should the fuels refilled to cover the distance?

        Raises
        ------
        RuntimeError
            Out of fuel

        Returns
        -------
        cars
            A car mileage
        '''
        pass

Yukarıdaki örnek diğer dokümantasyonlardan daha ayrıntılıdır. Daha uzundur ve yalnızca uzun ve detaylı dokümantasyon için kullanılmalıdır.

PyDoc

Docstring’lere yerleşik Python __doc__ özniteliği ve help() fonksiyonu aracılığıyla erişilebildiğini öğrendiniz. Ayrıca, doc özniteliği ve help fonksiyonuyla karşılaştırıldığında sahip olduğu özellikler ve işlevler bakımından oldukça farklı olan Pydoc adlı yerleşik modülü de kullanabilirsiniz.

Pydoc, kodu ekip arkadaşlarınızla paylaşmak istediğinizde veya açık kaynak yapmak istediğinizde —yani çok daha geniş bir kitleyi hedeflediğinizde— işe yarayacak bir araçtır. Python dokümantasyonunuzdan web sayfaları üretebilir ve bir web sunucusu da başlatabilir.

Nasıl çalıştığına bakalım.

Pydoc modülünü çalıştırmanın en kolay ve en uygun yolu onu bir betik olarak çalıştırmaktır. Bunu jupyter lab hücresi içinde çalıştırmak için ünlem işareti (!) karakterini kullanırsınız.

• Modül olarak Pydoc

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Yukarıdaki çıktıya bakarsanız, Pydoc’un ilk kullanımının bir fonksiyon, modül, sınıf vb. hakkında metin dokümantasyonu göstermek olduğunu görürsünüz; o halde bunu help fonksiyonundan daha iyi nasıl kullanabileceğinize bakalım.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Şimdi glob dokümantasyonunu help fonksiyonunu kullanarak çıkaralım.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-6-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Gördüğünüz gibi, glob tanımlı olmadığı için bir name error fırlatıyor. Dolayısıyla dokümantasyonu çıkarmak için help fonksiyonunu kullanmak isterseniz, önce o modülü içe aktarmanız gerekir; bu durum Pydoc’ta gerekli değildir.

• Web servisi olarak Pydoc

Pydoc modülünün en ilginç özelliğini, yani Pydoc’u bir web servisi olarak çalıştırmayı keşfedelim.

Bunu yapmak için, Pydoc’u bir betik olarak ancak -b argümanıyla çalıştırırsınız; bu da kullanılmayan rastgele bir bağlantı noktasında bir HTTP sunucusu başlatır ve belgeleri etkileşimli olarak gezinmek için bir Web tarayıcısı açar. Bu, özellikle sisteminizde çeşitli diğer servisler çalışırken ve hangi bağlantı noktasının boşta olduğunu hatırlamadığınızda faydalıdır.

!python -m pydoc -b

^C

Yukarıdaki hücreyi çalıştırdığınız anda, rastgele bir bağlantı noktasında yeni bir pencere açılır ve web tarayıcısı aşağıda gösterilene benzer görünür.

Sinir ağı mimarisinin ağırlıklarını depolamak için kullanılan bir dosya biçimi olan h5py modülünün dokümantasyonuna bakalım.

Docstring formatlarının karşılaştırması 

Aşağıdaki tabloda, yukarıda bahsettiğimiz farklı docstring formatlarının bir karşılaştırmasını görebilirsiniz: 

• Sphinx Stili: Kapsamlı dokümantasyon gereken büyük projelerde sıklıkla kullanılır. Sphinx’in dokümantasyon üreticisiyle iyi entegre olur.
• Google Stili: Özellikle Google’ın stil kılavuzlarını kullanan organizasyonlarda, sadelik ve okunabilirliğin önceliklendirildiği projeler için idealdir.
• NumPy Stili: Veri bilimi ve bilimsel hesaplamada yaygın olan, ayrıntılı ve kapsamlı dokümantasyon gereken projeler için en uygunudur.
• PyDoc: Metin ve HTML dokümantasyonu üretmek için kullanışlıdır; ancak diğerlerinin yapılandırılmış formatından yoksundur.

Sonuç

Python’da docstring eğitiminin sonuna geldiğiniz için tebrikler.

Bu eğitim, temel konuları kapsayarak docstring’lere başlamanıza odaklandı. Ancak Docstring’ler geniş bir konudur ve bazı kavramlar kapsanmamış olabilir. Daha fazla öğrenmek isterseniz, Python string eğitimimize ve Python’da fonksiyon yazma kursumuza göz atın.

Eğer Python’a yeni başladıysanız ve daha fazla öğrenmek istiyorsanız, DataCamp’in Python ile Veri Bilimine Giriş kursunu alın. Ayrıca Python kariyer yollarımızdan birini seçebilir ve Python Geliştiricisi ya da Python ile Veri Bilimci olma yolculuğunuza başlayabilirsiniz.