Ачааллж байна...
Өмнөх хичээлд бид сайн нэр олон тайлбарын хэрэгцээг арилгадаг гэж ярьсан. Гэхдээ хамгийн сайн нэр ч бүх асуултад хариулж чадахгүй. line_total гэсэн нэр функц нэг мөрийн нийт дүнг буцаадгийг хэлдэг ч price ямар нэгжтэй вэ, бөөний хөнгөлөлт хэдэн ширхэгээс эхэлдэг вэ, хөнгөлөлтийг тойруулдаг уу, тайрдаг уу гэдгийг хэлдэггүй. Эдгээр нь функцийг ашиглах гэж буй хүнд хэрэгтэй мэдээлэл. Тэр мэдээллийг хаана хадгалах вэ? Тусдаа баримт бичигт бичвэл код өөрчлөгдөхөд хуучирна. Тайлбар болгон бичвэл функцийн доторх кодын дунд нуугдана. Python-д үүнд зориулсан тусгай газар бий: docstring.
Docstring бол функц, модуль, классын хамгийн эхэнд бичигддэг тусгай текст бөгөөд тэр нь юу хийдэг, хэрхэн хэрэглэхийг тайлбарладаг. Энэ хичээлд бид docstring-ийн дүрмүүдийг сурч, 10.1 дүгээр хичээлийн order модульд модулийн болон функцийн docstring бичнэ. Дараа нь энэ хичээлийн бяцхан гайхамшигтай мөч ирнэ: Python-ий help() функц таны бичсэн docstring-ийг Python-ий өөрийн баримт бичигтэй яг ижил хэлбэрээр харуулна. Мөн VS Code docstring-ийг хэрхэн ашигладгийг харж, docstring ба тайлбарын хуваарийг тодорхой болгоно.
Бүлэг 1-ээс хойш бид нэг санааг олон удаа давтсан: commit message бол ирээдүйн өөртөө бичсэн захидал. Docstring бол түүний ах дүү, гэхдээ өөр хүлээн авагчтай. Commit message "энэ өөрчлөлт яагаад хийгдсэн бэ" гэж түүх сонирхсон хүнд хариулдаг. Docstring "энэ функцийг хэрхэн хэрэглэх вэ" гэж функцийг дуудах гэж буй хүнд хариулдаг.
Тэр хүн ихэвчлэн яаралтай байдаг. Тэр функцийн кодыг бүхэлд нь уншиж, хоёр давталт, гурван нөхцлийг ойлгож байж хэрэглэхийг хүсэхгүй. Тэр зүгээр л мэдэхийг хүсдэг: юу өгөх вэ, юу буцаж ирэх вэ, ямар нөхцөлд анхаарах вэ. Сайн docstring бол бүтээгдэхүүний хайрцаг дээрх заавар: дотор нь хэрхэн ажилладгийг биш, хэрхэн хэрэглэхийг хэлдэг. Ирээдүйн уншигч, хэдэн сарын дараах та ч мөн, кодыг нээлгүйгээр функцийг зөв хэрэглэж чадах ёстой.
Техникийн хувьд docstring бол функц, модуль, эсвэл классын доторх хамгийн эхний мөр болох текст юм. Python тэр текстийг энгийн тайлбар шиг хаяхгүй, харин объекттой нь хамт __doc__ гэсэн тусгай шинжид хадгалдаг. Ингэснээр программ ажиллаж байх үед ч docstring-д хүрч болно: help() функц, VS Code, баримт бичиг үүсгэдэг хэрэгслүүд бүгд түүнийг тэндээс уншдаг. Энэ бол “#” тайлбараас гол ялгаа: тайлбар зөвхөн кодын текстэд байдаг, docstring программын нэг хэсэг болдог.
Docstring-ийг гурвалсан давхар хашилтаар бичдэг: """. Гурвалсан хашилт олон мөрт текст бичих боломж олгодог бөгөөд Python-ий заншил үргэлж давхар хашилтыг шаарддаг. Docstring-ийн дүрмүүдийг PEP 257 гэдэг тусдаа заавар тогтоосон, PEP 8-ийн ах дүү. Түүний гол санаанууд энгийн.
Эхний мөр бол товч хураангуй: нэг өгүүлбэр, цэгээр төгссөн, функц юу хийдгийг хэлнэ. Энэ өгүүлбэрийг тушаах хэлбэрээр бичдэг: “Returns the total” биш, “Return the total”. 2.2 дугаар хичээлийн commit message-ийн “Add”, “Fix” дүрэмтэй ижил. Хэрвээ нэг мөр хангалттай бол docstring тэгээд дуусна. Хэрвээ дэлгэрэнгүй хэрэгтэй бол эхний мөрийн дараа хоосон мөр, дараа нь дэлгэрэнгүй тайлбар. Хаах гурвалсан хашилт олон мөрт docstring-д тусдаа мөрөнд байна.
Алхам 1: Docstring-гүй код
VS Code-д pytest-dadlaga фолдероо нээж, venv идэвхтэй эсэхийг шалгаарай. 10.1 дүгээр хичээлд засварласан order.py-г нээнэ үү. Тэр одоо ингэж харагдах ёстой.
python
from prices import add_vat
def line_total(price, qty):
total = price * qty
if qty >= 10:
total = total - total * 5 // 100
return total
def order_total(items):
subtotal = 0
for name, price, qty in items:
subtotal += line_total(price, qty)
return add_vat(subtotal)Python-оос line_total-ийн тухай асууя. help() бол Python-ий суурь функц: аливаа объектын баримт бичгийг харуулдаг.
Command:
python -c "import order; help(order.line_total)"Гаралт:
Help on function line_total in module order:
line_total(price, qty)Python бидэнд мэдэх бүхнээ хэлсэн: энэ бол order модулийн line_total функц, хоёр параметртэй. Бусад нь хоосон. Хэрвээ та энэ функцийг анх удаа харж байгаа бол price нь нэг ширхэгийн үнэ үү, нийт үнэ үү? Бөөний хөнгөлөлт бий юу? Кодыг нээхээс өөр арга алга.
Алхам 2: Функцийн docstring
line_total-ийг дараах байдлаар өөрчилнө үү.
python
def line_total(price, qty):
"""Return the total for one line of an order.
Ten or more pieces of the same item get a 5% bulk discount,
rounded down to whole tugrik.
Args:
price: Price of one piece, in tugrik.
qty: Number of pieces.
Returns:
The line total in tugrik, after any bulk discount.
"""
total = price * qty
if qty >= 10:
total = total - total * 5 // 100
return totalХэсэг бүрийг уншъя. Эхний мөр “Return the total for one line of an order.” бол хураангуй: тушаах хэлбэр, нэг өгүүлбэр, цэгтэй. Хоосон мөрийн дараах догол мөр функцийн зан төлөвийн чухал нарийн зүйлийг хэлж байна: бөөний хөнгөлөлт аравнаас эхэлдэг, таван хувь, доош тайрдаг. Энэ бол уншигчийн кодоос хайх байсан мэдээлэл.
Дараа нь хоёр хэсэг: “Args:” ба “Returns:”. Энэ бол Google компанийн хэв маягийн заавраас гаралтай, олон төсөлд хэрэглэгддэг docstring-ийн бүтэц. “Args:” нь параметр бүрийг нэрээр нь тайлбарлана: price нь нэг ширхэгийн үнэ, төгрөгөөр. 11.3 дугаар хичээлийн "нэгжийг нэрэнд" дадлыг санаарай: нэрэнд нэгж оруулаагүй тохиолдолд docstring түүнийг тодорхой болгоно. “Returns:” буцаах утгыг тайлбарлана. Функц алдаа гаргадаг бол “Raises:” хэсэг ч нэмдэг бөгөөд доор жишээг нь харна. Python-д docstring-ийн хэд хэдэн хэв маяг бий, хамгийн чухал нь нэг төсөлд нэгийг тууштай хэрэглэх, 11.3 дугаар хичээлийн тууштай байдлын зарчим.
Docstring-ийн хэлний тухай нэг тэмдэглэл: энэ сургалтын жишээнүүдэд docstring-ийг англиар бичиж байгаа нь 11.3 дугаар хичээлийн нэрсийн сонголттой ижил шалтгаантай: код, нэрс англиар бол тэдгээрийн баримт бичиг ч англиар байх нь жигд. Хувийн, Монгол уншигчдад зориулсан төсөлд монгол docstring бүрэн зөв, гагцхүү нэг төсөлд нэг хэлийг тууштай хэрэглээрэй.
Алхам 3: Гайхамшигтай мөч
Command:
python -c "import order; help(order.line_total)"Гаралт:
Help on function line_total in module order:
line_total(price, qty)
Return the total for one line of an order.
Ten or more pieces of the same item get a 5% bulk discount,
rounded down to whole tugrik.
Args:
price: Price of one piece, in tugrik.
qty: Number of pieces.
Returns:
The line total in tugrik, after any bulk discount.Таны бичсэн docstring Python-ий албан ёсны тусламжийн нэг хэсэг болж харагдаж байна. Одоо Python-ий өөрийн функцийн тусламжийг харьцуулъя.
Command:
python -c "help(len)"Гаралт:
Help on built-in function len in module builtins:
len(obj, /)
Return the number of items in a container.Хоёрыг зэрэгцүүлэн хараарай. Ижил бүтэц: гарчиг, функцийн гарын үсэг, догол мөртэй тайлбар. len-ийн docstring ч яг таны бичсэн дүрмийг баримталдаг: тушаах хэлбэрийн нэг өгүүлбэр, цэгтэй, “Return...”-ээр эхэлсэн. Python-ий хөгжүүлэгчид өөрсдийн функцуудад бичсэн docstring, таны line_total-д бичсэн docstring хоёр ижил механизмаар ажилладаг. Таны функц одоо Python-ий өөрийн функцуудын адил баримтжсан. Энэ бол жижиг боловч чухал мөч: таны код мэргэжлийн экосистемийн бүрэн эрхт гишүүн болж байна.
help(len)-ийн гарын үсгийн “/” тэмдгийг тоохгүй байж болно: тэр нь obj параметрийг нэрээр нь биш, зөвхөн байрлалаар өгөх ёстой гэсэн техникийн тэмдэглэгээ.
Алхам 4: Модулийн docstring
Функцээс гадна модуль бүхэлдээ docstring-тэй байж болно. Тэр нь файлын хамгийн эхэнд, import-уудаас ч өмнө бичигдэж, модуль юуны тухай болохыг тайлбарладаг. order.py-ийн хамгийн эхэнд нэмнэ үү.
python
"""Order totals with bulk discount and VAT.
An order is a list of items, where each item is a tuple
(name, price, qty) and price is a whole number of tugrik.
"""
from prices import add_vatМодулийн docstring нь бүх функцэд хамаатай ерөнхий мэдээллийг нэг газар хэлэх тохиромжтой газар: энд "захиалга" гэж юу болохыг, түүний бүтцийг тодорхойлсон. Ингэснээр функц бүрийн docstring тэр тодорхойлолтыг давтах шаардлагагүй. Одоо order_total-д ч docstring нэмье.
python
def order_total(items):
"""Return the total of an order, including VAT.
Bulk discounts are applied per line before VAT is added.
An empty order costs 0.
Args:
items: The order, as described in the module docstring.
Returns:
The order total in tugrik.
"""
subtotal = 0
for name, price, qty in items:
subtotal += line_total(price, qty)
return add_vat(subtotal)“An empty order costs 0.” гэсэн өгүүлбэрийг анзаараарай. Энэ бол 7.3 дугаар хичээлээс хойш бидний онцолсон хил дээрх тохиолдол. Docstring-д хил дээрх зан төлөвийг тодорхой бичих нь дуудагчийг "хоосон жагсаалт өгвөл юу болох вэ" гэж туршихаас чөлөөлнө.
Command:
python -c "import order; help(order)"Гаралт:
Help on module order:
NAME
order - Order totals with bulk discount and VAT.
DESCRIPTION
An order is a list of items, where each item is a tuple
(name, price, qty) and price is a whole number of tugrik.
FUNCTIONS
line_total(price, qty)
Return the total for one line of an order.
Ten or more pieces of the same item get a 5% bulk discount,
rounded down to whole tugrik.
Args:
price: Price of one piece, in tugrik.
qty: Number of pieces.
Returns:
The line total in tugrik, after any bulk discount.
order_total(items)
Return the total of an order, including VAT.
Bulk discounts are applied per line before VAT is added.
An empty order costs 0.
Args:
items: The order, as described in the module docstring.
Returns:
The order total in tugrik.
FILE
c:\users\bat\pytest-dadlaga\order.pyМодулийн бүтэн баримт бичиг, хэсгүүдэд хуваагдсан. “NAME” мөрөнд модулийн нэрийн хажууд docstring-ийн эхний мөр, хураангуй харагдаж байна: тийм учраас эхний мөр богино, бие даасан өгүүлбэр байх ёстой. “DESCRIPTION” бол docstring-ийн үлдсэн хэсэг. “FUNCTIONS” модулийн бүх функцийг docstring-тэй нь жагсаана. add_vat жагсаалтад байхгүйг анзаараарай: тэр prices модулиас import хийгдсэн тул help түүнийг order-ийн функц гэж тоолоогүй. “FILE” файлын зам, Windows дээр жижиг үсгээр харагдаж болно. Нэг ч баримт бичгийн файл бичилгүйгээр бид модулийнхоо бүрэн гарын авлагатай боллоо. Хэрвээ тусламж урт бөгөөд дэлгэцэнд багтахгүй бол terminal “-- More --” гэж зогсож болно: Space-ээр үргэлжлүүлж, q-ээр гарна.
Нэг мөрт docstring
Бүх функцэд урт docstring хэрэггүй. Энгийн, ойлгомжтой функцэд нэг мөр хангалттай.
python
def is_free(amount):
"""Return True if the amount is zero."""
return amount == 0Нээх ба хаах хашилт нэг мөрөнд. “Args”, “Returns” хэсгүүд энд илүүц: параметр нэг, нэр нь ойлгомжтой, буцаах утгыг эхний өгүүлбэр аль хэдийн хэлсэн. Docstring-ийн урт функцийн нарийн төвөгтэй байдалтай тэнцүү байх ёстой: 11.3 дугаар хичээлийн "нэр хүрээтэйгээ тэнцүү урттай" санааны ах дүү.
Алдааг баримтжуулах
Функц санаатайгаар алдаа гаргадаг бол, 8.4 дүгээр хичээлийн apply_discount шиг, тэр нь гэрээний нэг хэсэг тул docstring-д “Raises:” хэсэгт бичигдэх ёстой. prices.py-д apply_discount-ийг нээж docstring нэмнэ үү.
python
def apply_discount(price, percent):
"""Return the price after a percentage discount, rounded down.
Args:
price: Price in tugrik.
percent: Discount from 0 to 100.
Returns:
The discounted price in tugrik.
Raises:
ValueError: If percent is below 0 or above 100.
"""
if percent < 0 or percent > 100:
raise ValueError(f"Discount must be between 0 and 100, got {percent}")
return price - price * percent // 100Одоо apply_discount-ийг дуудах хүн буруу хувь өгвөл юу болохыг кодыг уншилгүйгээр мэднэ, мөн try/except-ээр ямар алдааг барих ёстойг мэднэ. Docstring болон 8.4 дүгээр хичээлийн pytest.raises тестүүд хоорондоо нийцэж байгааг анзаараарай: docstring гэрээг үгээр хэлдэг, тест түүнийг баталгаажуулдаг.
Docstring ба тайлбарын хуваарь
11.3 дугаар хичээлд тайлбар "яагаад" гэдгийг хэлэх ёстой гэж ярьсан. Одоо хуваарийг бүрэн гаргая. Docstring функцийг гаднаас нь харж буй дуудагчид зориулагдсан: юу хийдэг, юу өгөх, юу буцаах, ямар алдаа гарах. Тайлбар функцийн дотор ажиллаж, кодыг засах гэж буй хүнд зориулагдсан: тодорхой мөр яагаад яг ингэж бичигдсэн бэ. Docstring "хөнгөлөлтийг доош тайрна" гэж хэлдэг, тайлбар "нягтлан бодох бүртгэлийн дүрмээр доош тайрна" гэж шалтгааныг хэлдэг. Хоёулаа хэрэгтэй, гэхдээ өөр уншигчид.
VS Code-д docstring
VS Code docstring-ийг шууд ашигладаг. order_total-ийг дууддаг ямар ч файлд, жишээ нь report_app.py-д, түүний нэр дээр хулганаа аваачвал жижиг цонх гарч функцийн гарын үсэг болон docstring-ийг харуулна. Мөн функцийн нэрийг бичиж байхад, хаалт нээх мөчид, параметрүүдийн тайлбар гарна. Ингэснээр та өөр файлын функцийг тэр файлыг нээлгүйгээр зөв хэрэглэнэ. Энэ нь Python-ий өөрийн функцуудад ч ажилладаг: len дээр хулганаа аваачвал Алхам 3-ын docstring харагдана.
Хүсвэл зарлагын бүртгэлийнхээ функцуудад docstring бичиж үзээрэй: report.py-ийн total, average, total_by_category, expenses.py-ийн make_expense. Тус бүрд хамгийн түрүүнд нэг мөрт хураангуйг бичээрэй, дараа нь шаардлагатай бол л дэлгэрэнгүйг нэмээрэй. average-д хоосон жагсаалтын зан төлөвийг, make_expense-д “Raises:” хэсгийг заавал бичээрэй: эдгээр нь 6.1 болон 9.3 дугаар хичээлүүдийн гэрээ. Дараа нь python -c "import report; help(report)" ажиллуулж, өөрийн модулийн гарын авлагыг харцгаа. Хүсвэл энэ ажлыг шинэ салаа, “Add docstrings” commit, pull request-ээр хийгээрэй.
Docstring эхний мөр биш байх. Docstring зөвхөн функц, модулийн хамгийн эхний мөр байвал л docstring болдог. Хэрвээ түүний өмнө өөр мөр, жишээ нь total = price * qty, байвал Python гурвалсан хашилттай текстийг зүгээр л ашиглагдаагүй текст гэж үзэж, хаядаг. help() Алхам 1-ийн хоосон тусламжийг харуулна. Модулийн docstring-ийн хувьд ч ижил: import-уудын өмнө байх ёстой.
“#” тайлбараар docstring бичих. Функцийн эхэнд “#”-ээр эхэлсэн мөрүүд бичвэл тэд кодын текстэд харагдах ч Python тэднийг хадгалахгүй: help() хоосон, VS Code-ийн hover хоосон. Функцийн тухай мэдээлэл гурвалсан хашилтанд байх ёстой.
Хуучирсан docstring. 11.3 дугаар хичээлийн "худлаа ярьдаг нэр"-ийн нэгэн адил кодын өөрчлөлтийг дагаж өөрчлөгдөөгүй docstring худлаа ярьдаг. Хэрвээ бөөний хөнгөлөлтийг арван ширхэгээс тав болгосон ч docstring “Ten or more” гэж хэвээр байвал уншигч кодыг биш, docstring-ийг итгэнэ. Функцийн зан төлөвийг өөрчлөх бүрт docstring-ийг шалга. 6.2 дугаар хичээлийн pull request-ийн өөрийгөө хянах үед “docstring одоо ч үнэн үү” гэсэн асуулт нэмэх нь сайн дадал.
Нэрийг давтсан docstring. def line_total(...)-ийн docstring “Line total.” бол юу ч нэмээгүй: нэр аль хэдийн хэлсэн. Docstring нэрийн хэлээгүй зүйлийг хэлэх ёстой: нэгж, хил дээрх зан төлөв, алдаа, нарийн дүрэм.
Кодыг дахин тайлбарлах. “First multiplies price by qty, then checks if qty is at least 10, then...” гэх мэт docstring функцийн кодыг үгээр давтаж байна. Docstring хэрхэн биш, юу хийдгийг хэлнэ: дотоод ажиллагаа өөрчлөгдсөн ч гэрээ хэвээр бол docstring хэвээр байх ёстой.
docstring хэв маягийн шалгалт. ruff-д docstring-ийн хэв маягийг шалгадаг “D” бүлэг бий. 11.2 дугаар хичээлийн select-д түүнийг нэмбэл ruff docstring-гүй функц, буруу хэлбэртэй эхний мөр зэргийг анзаарч эхэлнэ. Энэ бүлэг маш олон дүрэмтэй бөгөөд зарим нь хоорондоо зөрчилддөг, тиймээс түүнийг нэмэх бол ruff-ийн баримт бичгийн зөвлөмжийн дагуу тодорхой хэв маягтай хамт тохируулах хэрэгтэй. Эхлэхэд энэ хичээлийн дүрмүүдийг гараар баримтлахад хангалттай.
Docstring бол функц, модуль, классын хамгийн эхний мөр болох гурвалсан давхар хашилттай текст бөгөөд Python түүнийг __doc__-д хадгалдаг тул help(), VS Code болон бусад хэрэгслүүд уншдаг: энэ бол “#” тайлбараас гол ялгаа. PEP 257-ийн дүрмээр эхний мөр нэг өгүүлбэр, тушаах хэлбэр, цэгтэй хураангуй, шаардлагатай бол хоосон мөрийн дараа дэлгэрэнгүй. Google хэв маягийн “Args:”, “Returns:”, “Raises:” хэсгүүд параметр, буцаах утга, санаатай алдааг тайлбарлана, нэг төсөлд нэг хэв маягийг тууштай хэрэглэнэ. Модулийн docstring import-уудын өмнө, бүх функцэд хамаатай ерөнхий тодорхойлолтыг хэлнэ. help(функц) ба help(модуль) таны docstring-ийг Python-ий өөрийн функцуудтай ижил хэлбэрээр харуулдаг. Docstring дуудагчид юу ба хэрхэн хэрэглэхийг, тайлбар засагчид яагаад гэдгийг хэлнэ. Docstring нэрийн хэлээгүй зүйлийг, ялангуяа нэгж, хил дээрх зан төлөв, алдааг хэлэх ёстой, кодын өөрчлөлтийг дагаж шинэчлэгдэх ёстой, энгийн функцэд нэг мөр хангалттай.
Ингээд Бүлэг 11 дууслаа. Та одоо black-ээр хэлбэрийг, ruff-ээр урхийг, нэр болон бүтцээр ойлгомжтой байдлыг, docstring-ээр баримтжуулалтыг удирдаж чадна. Дараагийн Бүлэг энэ сургалтын сүүлийнх. Бүлэг 12-ын эхний хичээлд энэ сургалтад сурсан бүх дадлыг нэг өдөр тутмын давталт болгон холбоно: салаа, код, тест, хэлбэржүүлэлт, commit, push. Мөн энэ давталтыг автоматжуулдаг CI-ийн тухай нэг шударга догол мөр бий.
Бүртгэлтэй болсноор энэ сургалтын бүх хичээлд хандах эрх авна.