Python docstring

Dokumentācija ir būtiska, lai jebkura programmēšana viegli saprastu kodu. To lieto, lai izskaidrotu jebkura paziņojuma vai funkcijas, klases vai moduļa izmantošanas mērķi programmā. Tas palīdz galvenajam kodētājam pēc ilgāka laika atcerēties jebkura koda funkciju, kā arī citiem kodētājiem, kas vēlas strādāt pie tā paša projekta. Kodētājs izmanto vienu komentāru rindu, lai īsi izskaidrotu konkrēto koda funkcijas daļu. Python dokumenta virkne vai docstring tiek izmantota, lai detalizēti izskaidrotu konkrēta koda segmenta funkciju. Dokstringa rindai jāsākas ar lielo burtu un jābeidzas ar punktu. Docstring pirmajā rindā ir īss dokumentācijas apraksts kopumā. Dokstringa otrajai rindai jābūt tukšai lielai daudzrindu docstringai. Trīsvietīgas pēdiņas ('') vai trīskāršās pēdiņas (“” ”) tiek izmantoti, lai definētu docstring Python. Docstring saturam var piekļūt, izmantojot __doc__ objekta atribūtu un izmantojot palīdzība () metodi. Šajā apmācībā ir parādīts, kā deklarēt un piekļūt docstring Python.

1. piemērs: Piekļuve funkcijas docstring, izmantojot __doc__ atribūts

Pielāgotās funkcijas deklarēšanas un piekļuves veids ir parādīts šajā skriptā. Šis skripts aprēķina xⁿ kur x un n tiks ņemti no lietotāja. Jauda () Funkcija ir definēta skriptā, lai veiktu uzdevumu. Šeit šai funkcijai ir definēta docstring. __doc__ atribūts ir izmantots skriptā, lai izdrukātu docstringu ar izvadi.

def jauda (x, n):
"Aprēķiniet x līdz jaudai n
No funkcijas argumentiem nolasiet x un n vērtības
un aprēķiniet un atgrieziet x vērtību jaudai n."
atgriešanās x ** n
# Ņem x vērtību
x = int (ievade ('Ievadiet x vērtību:'))
# Ņem n vērtību
n = int (ievade ('Ievadiet n vērtību:'))
# Izdrukājiet funkcijas atgriešanās vērtību
drukāt ("% d līdz jaudai% d =% d"% (x, n, jauda (x, n)))
# Izdrukājiet docstring vērtību
drukāt ("Docstring saturs: \ n" + jauda.__doc__)

Izeja:

Pēc iepriekš minētā skripta izpildes parādīsies šāda izeja.

2. piemērs: Piekļuve klases un metodes docstring, izmantojot palīdzība () metodi

Veids, kā deklarēt un piekļūt dokumenta docstringam, un šīs klases metodes ir parādīts šajā skriptā. Skripta galvenā funkcija ir kārtot skaitlisko sarakstu un mainīt saraksta datus. Klasē ir deklarēts 8 elementu skaitliskais saraksts, un klases sākumā ir definēta dokstringa, izmantojot trīs atsevišķas pēdiņas. Klasē ir definēta metode sort_list (), lai izdrukātu sarindotos saraksta datus, un dokuments to ir definējis šai metodei. reverse_list () metode ir definēta, lai drukātu saraksta apgrieztos datus, un šai metodei ir definēta arī docstring. palīdzība () metode skripta beigās ir izsaukusi trīs reizes, lai izdrukātu saraksts_operācijas klasē, sort_list () metodi un reverse_list () metodi.

klases saraksts_operācijas:

klases saraksts_operācijas:
"
Saraksta datu kārtošana un atcelšana
Klasē ir divas metodes,
sort_list () metode kārtos un izdrukās sarakstu,
sort_reverse () metode mainīs un izdrukās sarakstu.
"
# Definējiet skaitlisko datu sarakstu
saraksta dati = [23, 67, 23, 6, 45, 3, 90, 11]
def sort_list (pats):
"
Pēc šķirošanas izdrukājiet saraksta vērtības
Funkcija no argumenta paņems skaitlisko datu saraksta objektu,
kārtojiet saraksta vērtības, izmantojot sort () metodi
un izdrukājiet sakārtotā saraksta vērtības.
"
# Kārtojiet sarakstu
pats.listdata.kārtot ()
# Izdrukājiet sakārtoto sarakstu, izmantojot cilpu
print ("Kārtotā saraksta vērtības: \ n")
par vērtību sevī.listdata:
drukāt (vērtība, "", beigas = ")
def reverse_list (pats):
"
Pēc atpakaļgaitas izdrukājiet saraksta vērtības
Funkcija no argumenta paņems skaitlisko datu saraksta objektu,
mainīt saraksta vērtības, izmantojot reverse () metodi
un izdrukājiet apgrieztā saraksta vērtības.
"
# Apgrieziet sarakstu atpakaļ
pats.listdata.reverss ()
# Izdrukājiet apgriezto sarakstu, izmantojot cilpu
print ("Kārtotā saraksta vērtības: \ n")
par vērtību sevī.listdata:
drukāt (vērtība, "", beigas = ")
# Izdrukājiet klases docstring vērtību
palīdzība (saraksts_operācijas)
# Izveidot klases objektu
obj = saraksts_operācijas ()
# Izdrukājiet konkrētās metodes docstring vērtību
palīdzība (obj.sort_list)
# Izsauciet metodi, lai izdrukātu kārtoto sarakstu
obj.sort_list ()

Izeja:

Pēc skripta izpildes parādīsies šāda izeja. Pirmais ir izdrukāts viss skripta dokstrings palīdzība () funkciju. Dokstrēšana sort_list () metode ir iespiesta jau otro palīdzība () funkciju.

3. piemērs: piekļuve iebūvētā Python moduļa docstring

Iepriekšējos piemēros docstring ir izmantots lietotāja definētā klasē un funkcijā. Katram iebūvētajam Python modulim un klasei ir sava instrukcija, kas izskaidro konkrētā moduļa vai funkcijas izmantošanas mērķi. Moduļa vai funkcijas kodētājs definē docstringu, lai padarītu kodu saprotamu lietotājiem. Šis skripts izdrukās datuma laika moduļa iepriekš noteikto docstring, izmantojot palīdzība () funkciju.

# Datuma laika moduļa importēšana
importēt datumu
# Parādiet datetime docstring
palīdzība (datuma laiks)

Izeja:

Pēc skripta izpildes tiks parādīta šāda izeja. Datetime moduļa docstring parāda detalizētu tā dokumentāciju, lai palīdzētu citiem pareizi izprast šajā modulī noteikto klašu un metožu funkcijas.

Secinājums:

Pareiza dokumentācija ir būtiska, ja kāds modulis vai funkcija tiek ieviesta konkrētam mērķim, lai palīdzētu citiem kodētājiem izmantot moduli savā kodā konkrētā uzdevuma veikšanai. Ja modulim vai funkcijai dokumentācija nav pareizi definēta, pārējiem lietotājiem būs grūtības to izmantot. Tātad katram kodētājam ir jāizmanto dokumenta docstring, lai citiem sniegtu detalizētu informāciju koda izpratnei.