Bu eğitimde Python dokümanları hakkında bilgi edineceğiz. Daha spesifik olarak, docstrings'in nasıl ve neden kullanıldığını örnekler yardımıyla öğreneceğiz.
Python docstrings, bir işlev, yöntem, sınıf veya modülün tanımından hemen sonra görünen dize değişmezleridir. Bir örnek alalım.
Örnek 1: Dokümanlar
def square(n): '''Takes in a number n, returns the square of n''' return n**2
Burada dize değişmezi:
'' 'N sayısını alır, n'nin karesini döndürür' ''
Üçlü tırnak işaretlerinin içinde, işlevin tanımından hemen sonra göründüğü şekliyle dokdizesi bulunur square().
Not:""" Dokümanlar oluşturmak için üçlü alıntılar da kullanabiliriz .
Python Yorumları vs Docstrings
Python Yorumları
Yorumlar, programcıların programın amacını ve işlevselliğini daha iyi anlamasına yardımcı olan açıklamalardır. Python yorumlayıcısı tarafından tamamen yok sayılırlar.
Python'da, #tek satırlık bir yorum yazmak için hash sembolünü kullanırız. Örneğin,
# Program to print "Hello World" print("Hello World")
Dizeleri Kullanan Python Yorumları
Herhangi bir değişkene dizge atamazsak, bunlar yorum görevi görür. Örneğin,
"I am a single-line comment" ''' I am a multi-line comment! ''' print("Hello World")
Not: Çok satırlı dizeler için üçlü tırnak işaretleri kullanırız.
Python dokümanları
Yukarıda belirtildiği gibi, Python docstrings, bir işlev, yöntem, sınıf veya modülün ( Örnek 1'deki gibi ) tanımından hemen sonra kullanılan dizelerdir . Kodumuzu belgelemek için kullanılırlar.
Bu dökümanlara bu __doc__niteliği kullanarak erişebiliriz .
Python __doc__ özniteliği
Dize değişmezleri bir işlev, modül, sınıf veya yöntemin tanımından hemen sonra mevcut olduğunda, __doc__öznitelikleri olarak nesneyle ilişkilendirilirler. Daha sonra bu dokümanı almak için bu niteliği kullanabiliriz.
Örnek 2: Doküman dizesini yazdırma
def square(n): '''Takes in a number n, returns the square of n''' return n**2 print(square.__doc__)
Çıktı
Bir n sayısını alır, n'nin karesini verir
Burada, square()fonksiyonumuzun dokümantasyonuna bu __doc__nitelik kullanılarak erişilebilir .
Şimdi, yerleşik işlev için docstrings'e bakalım print():
Örnek 3: Yerleşik print () işlevi için belgeler
print(print.__doc__)
Çıktı
print (değer,…, sep = '', end = ' n', file = sys.stdout, flush = False) Değerleri varsayılan olarak bir akışa veya sys.stdout'a yazdırır. İsteğe bağlı anahtar kelime argümanları: dosya: dosya benzeri bir nesne (akış); varsayılan olarak geçerli sys.stdout. sep: değerler arasına eklenen dizge, varsayılan olarak boşluk. end: son değerden sonra eklenen dize, varsayılan olarak yeni satır. floş: akışın zorla yıkanıp boşaltılmayacağı.
Burada, print()fonksiyonun dokümantasyonunun __doc__bu fonksiyonun niteliği olarak mevcut olduğunu görebiliriz .
Python'da tek satırlı dokümanlar
Tek satırlı dokümanlar, tek satıra sığan dokümanlardır.
Tek satırlık dokümanlar yazmak için standart kurallar:
- Tek satırlı olmalarına rağmen, daha sonra kolayca genişletilebilecekleri için bu belgelerin etrafındaki üçlü alıntıları hala kullanıyoruz.
- Kapanış teklifleri açılış teklifleriyle aynı satırdadır.
- Doküman dizisinden önce veya sonra boş satır yoktur.
- Açıklayıcı olmamalı, nokta ile biten "Bunu yap, şunu geri ver" yapısını takip etmelidirler.
Bir örnek alalım.
Örnek 4: Bir işlev için tek satırlı dokümanlar yazın
def multiplier(a, b): """Takes in two numbers, returns their product.""" return a*b
Python'da Çok Satırlı Dokümanlar
Çok satırlı dokümanlar, tıpkı tek satırlık dokümanlar gibi bir özet satırından, ardından boş bir satırdan ve ardından daha ayrıntılı bir açıklamadan oluşur.
PEP 257 belgesi, çeşitli nesneler için çok satırlı belge dizileri yazmak için standart kuralları sağlar.
Bazıları aşağıda listelenmiştir:
1. Python Modülleri için Dokümanlar
- Python Modülleri için belge dizileri, modül içe aktarıldığında içe aktarılan tüm kullanılabilir sınıfları, işlevleri, nesneleri ve istisnaları listelemelidir.
- They should also have a one-line summary for each item.
They are written at the beginning of the Python file.
Let's look at the docstrings for the builtin module in Python called pickle.
Example 4: Docstrings of Python module
import pickle print(pickle.__doc__)
Output
Create portable serialized representations of Python objects. See module copyreg for a mechanism for registering custom picklers. See module pickletools source for extensive comments. Classes: Pickler Unpickler Functions: dump(object, file) dumps(object) -> string load(file) -> object loads(string) -> object Misc variables: __version__ format_version compatible_formats
Here, we can see that the docstring written at the beginning of the pickle.py module file can be accessed as its docstring.
2. Docstrings for Python Functions
- The docstring for a function or method should summarize its behavior and document its arguments and return values.
- It should also list all the exceptions that can be raised and other optional arguments.
Example 5: Docstrings for Python functions
def add_binary(a, b): ''' Returns the sum of two decimal numbers in binary digits. Parameters: a (int): A decimal integer b (int): Another decimal integer Returns: binary_sum (str): Binary string of the sum of a and b ''' binary_sum = bin(a+b)(2:) return binary_sum print(add_binary.__doc__)
Output
Returns the sum of two decimal numbers in binary digits. Parameters: a (int): A decimal integer b (int): Another decimal integer Returns: binary_sum (str): Binary string of the sum of a and b
As you can see, we have included a short description of what the function does, the parameter it takes in and the value it returns. The string literal is embedded to the function add_binary as its __doc__ attribute.
3. Docstrings for Python Classes
- The docstrings for classes should summarize its behavior and list the public methods and instance variables.
- The subclasses, constructors, and methods should each have their own docstrings.
Example 6: Docstrings for Python class
Suppose we have a Person.py file with the following code:
class Person: """ A class to represent a person.… Attributes ---------- name : str first name of the person surname : str family name of the person age : int age of the person Methods ------- info(additional=""): Prints the person's name and age. """ def __init__(self, name, surname, age): """ Constructs all the necessary attributes for the person object. Parameters ---------- name : str first name of the person surname : str family name of the person age : int age of the person """ self.name = name self.surname = surname self.age = age def info(self, additional=""): """ Prints the person's name and age. If the argument 'additional' is passed, then it is appended after the main info. Parameters ---------- additional : str, optional More info to be displayed (default is None) Returns ------- None """ print(f'My name is (self.name) (self.surname). I am (self.age) years old.' + additional)
Here, we can use the following code to access only the docstrings of the Person class:
print(Person.__doc__)
Output
A class to represent a person.… Attributes ---------- name : str first name of the person surname : str family name of the person age : int age of the person Methods ------- info(additional=""): Prints the person's name and age
Using the help() Function for Docstrings
We can also use the help() function to read the docstrings associated with various objects.
Example 7: Read Docstrings with the help() function
We can use the help() function on the class Person in Example 6 as:
help(Person)
Output
Help on class Person in module __main__: class Person(builtins.object) | Person(name, surname, age) | | A class to represent a person. | |… | | Attributes | ---------- | name : str | first name of the person | surname : str | family name of the person | age : int | age of the person | | Methods | ------- | info(additional=""): | Prints the person's name and age. | | Methods defined here: | | __init__(self, name, surname, age) | Constructs all the necessary attributes for the person object. | | Parameters | ---------- | name : str | first name of the person | surname : str | family name of the person | age : int | age of the person | | info(self, additional='') | Prints the person's name and age. | | If the argument 'additional' is passed, then it is appended after the main info. | | Parameters | ---------- | additional : str, optional | More info to be displayed (default is None) | | Returns | ------- | None | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables (if defined) | | __weakref__ | list of weak references to the object (if defined)
Here, we can see that the help() function retrieves the docstrings of the Person class along with the methods associated with that class.
4. Docstrings for Python Scripts
- The docstrings for Python script should document the script's functions and command-line syntax as a usable message.
- It should serve as a quick reference to all the functions and arguments.
5. Docstrings for Python Packages
The docstrings for a Python package is written in the package's __init__.py file.
- It should contain all the available modules and sub-packages exported by the package.
Docstring Formats
We can write docstring in many formats like the reStructured text (reST) format, Google format or the NumPy documentation format. To learn more, visit Popular Docstring Formats
Sphinx gibi araçları kullanarak docstrings'ten de belgeler oluşturabiliriz. Daha fazla bilgi edinmek için Resmi Sfenks Belgelerini ziyaret edin
