Python docstring

Dokumentationen er vigtig for enhver programmering for let at forstå koden. Det bruges til at forklare formålet med at bruge en hvilken som helst erklæring eller funktion eller klasse eller modul i programmet. Det hjælper hovedkoderen med at huske funktionen af ​​en hvilken som helst kode efter lang tid, og det hjælper også andre kodere, der ønsker at arbejde på det samme projekt. Koderen bruger en enkelt linje med kommentarer til kort fortalt at forklare den særlige del af kodens funktion. Python-dokumentstreng eller docstring bruges til at forklare funktionen af ​​et bestemt segment af koden i detaljer. Dokstringlinjen skal begynde med store bogstaver og slutte med en periode. Den første linje i dokstringen indeholder en kort beskrivelse af dokumentationen generelt. Den anden linje i dokstringen skal være blank for den store multi-line dokstring. Triple enkelt citater ('”) eller tredobbelt dobbelt anførselstegn (“” ”) bruges til at definere docstring i Python. Docstring-indholdet kan tilgås ved hjælp af den __doc__ objektets attribut og brug af Hjælp() metode. Måden at erklære og få adgang til docstring i Python har vist i denne vejledning.

Eksempel 1: Adgang til dokstring af en funktion ved hjælp af __doc__ attribut

Måden at erklære og få adgang til docstring af en brugerdefineret funktion er vist i det følgende script. Det følgende script beregner xⁿ hvor x og n vil blive taget fra brugeren. Strøm () funktion har defineret i scriptet til at udføre opgaven. Her er docstring defineret for denne funktion. __doc__ attribut er blevet brugt i scriptet til at udskrive docstring med output.

def magt (x, n):
"Beregn x til magt n
Læs værdierne for x og n fra funktionsargumenterne
og beregne og returnere værdien af ​​x til magten n."
returnere x ** n
# Tag værdien af ​​x
x = int (input ('Indtast værdien af ​​x:'))
# Tag værdien af ​​n
n = int (input ('Indtast værdien af ​​n:'))
# Udskriv returværdien af ​​funktionsfunktionen
print ("% d til magt% d =% d"% (x, n, effekt (x, n)))
# Udskriv docstringværdien
print ("Indholdet af dokstringen: \ n" + magt.__doc__)

Produktion:

Følgende output vises efter udførelse af ovenstående script.

Eksempel 2: Adgang til dokstring af klasse og metode ved hjælp af Hjælp() metode

Måden at erklære og få adgang til dokumentets dokstring og metoderne i denne klasse er vist i det følgende script. Scriptets hovedfunktion er at sortere en numerisk liste og vende dataene på listen. En numerisk liste med 8 elementer er blevet erklæret i klassen, og dokstringen er defineret i begyndelsen af ​​klassen ved hjælp af tredobbelte citater. Metoden sort_list () er defineret i klassen for at udskrive de sorterede data på listen, og dokumentet har defineret dette til denne metode. reverse_list () metode er defineret til at udskrive listens omvendte data, og docstring er også defineret for denne metode. Hjælp() metoden har kaldt tre gange i slutningen af ​​scriptet for at udskrive doktringen af liste_operationer klasse, sort_list () metode og reverse_list () metode.

klasseliste_operationer:

klasseliste_operationer:
"
Sortering og omvendelse af listedataene
Klassen indeholder to metoder,
sort_list () -metoden sorterer og udskriver listen,
sort_revers () -metoden vender og udskriver listen.
"
# Definer en liste med numeriske data
listdata = [23, 67, 23, 6, 45, 3, 90, 11]
def sort_list (selv):
"
Udskriv listeværdierne efter sortering
Funktionen tager et listeobjekt med numeriske data fra argumentet,
sortere listeværdierne ved hjælp af metoden sort ()
og udskriv værdierne på den sorterede liste.
"
# Sorter listen
selv.listedata.sortere()
# Udskriv den sorterede liste ved hjælp af loop
print ("Værdierne for den sorterede liste: \ n")
for værdi i sig selv.listedata:
print (værdi, "", slut = ")
def reverse_list (selv):
"
Udskriv listeværdierne efter reversering
Funktionen tager et listeobjekt med numeriske data fra argumentet,
vende listeværdierne ved hjælp af omvendt () -metoden
og udskriv værdierne på den omvendte liste.
"
# Vend listen
selv.listedata.baglæns()
# Udskriv den omvendte liste ved hjælp af loop
print ("Værdierne for den sorterede liste: \ n")
for værdi i sig selv.listedata:
print (værdi, "", slut = ")
# Udskriv klassens doktringværdi
hjælp (liste_operationer)
# Opret objekt af klassen
obj = liste_operationer ()
# Udskriv docstringværdien for den bestemte metode
hjælp (obj.sort_liste)
# Ring til metoden for at udskrive den sorterede liste
obj.sort_list ()

Produktion:

Følgende output vises efter udførelse af scriptet. Al dokumentation af manuskriptet er udskrevet for første gang Hjælp() fungere. Doktringen af sort_list () metoden er udskrevet for anden gang Hjælp() fungere.

Eksempel 3: Adgang til dokstring af det indbyggede Python-modul

I de foregående eksempler har dokstringen brugt i brugerdefineret klasse og funktion. Hvert indbygget Python-modul og klasse har sin dokstring, der forklarer formålet med at bruge det pågældende modul eller funktion. Koderen til modulet eller funktionen definerer docstring for at gøre koden forståelig for brugerne. Det følgende script udskriver den foruddefinerede dokstring af datetime-modulet ved hjælp af Hjælp() fungere.

# Importer datetime-modul
importer datatid
# Vis doktring af datetime
hjælp (datetime)

Produktion:

Følgende output vises efter udførelse af scriptet. Dokstring af datetime-modulet viser den detaljerede dokumentation for det for at hjælpe de andre til at kende funktionerne i de klasser og metoder, der er defineret i dette modul korrekt.

Konklusion:

Den korrekte dokumentation er vigtig, når ethvert modul eller funktion er implementeret til det specifikke formål for at hjælpe den anden kodeer med at bruge modulet i deres kode til at udføre den særlige opgave. Hvis dokumentationen ikke er defineret korrekt for modulet eller funktionen, vil de andre brugere have problemer med at bruge det. Så hver koderen skal bruge dokumentets doktring til at give detaljerede oplysninger, så de andre kan forstå koden.