Как се пише добра функция в Python

Проблем

Функцията, която прави всичко

Имената от миналия урок вече са на място. Константите на магазина:

FREE_DELIVERY_FROM = 50
STANDARD_DELIVERY_FEE = 4.99
EXPRESS_SURCHARGE = 7
SPRING_COUPON = "SPRING10"
SPRING_DISCOUNT = 0.10

orders = []

А това е функцията, през която минава всяка поръчка:

def process_order(email, prices, coupon, express):
    amount = 0
    for price in prices:
        amount += price
    if coupon == SPRING_COUPON:
        amount = amount * (1 - SPRING_DISCOUNT)
    delivery = 0 if amount >= FREE_DELIVERY_FROM else STANDARD_DELIVERY_FEE
    if express:
        delivery += EXPRESS_SURCHARGE
    total = amount + delivery
    orders.append(total)
    print(f"До {email}: поръчката е приета, {total:.2f} €")
    print(f"[log] поръчка №{len(orders)} за {total:.2f} €")

process_order("maria@example.com", [24.50, 18.00], "SPRING10", True)
process_order("ivan@example.com", [64.00], "", False)

До maria@example.com: поръчката е приета, 50.24 €
[log] поръчка №1 за 50.24 €
До ivan@example.com: поръчката е приета, 64.00 €
[log] поръчка №2 за 64.00 €

Работи. Сега маркетингът иска купонът да не важи за доставката. Счетоводството иска таксата да се показва отделно в количката. Тестерът иска да провери доставката под и над 50 €, а за всяка проверка трябва да направи поръчка, тоест да я запише и да прати имейл. Всички пипат една и съща функция. А какво значи True в края на извикването, пак не се вижда.

Идеята

Една работа и едно ниво

Опитай да кажеш какво прави process_order: „събира цените, и прилага купона, и смята доставката, и записва, и праща имейл, и пише в лога“. Всяко „и“ е отделна работа. Всяка от тях се сменя по своя причина и от различен човек.

Правилото е една работа на функция. Функцията с една работа е малка, има име, което казва цялата работа, и малко параметри. Как разбираш, че работата е една:

описваш я с едно изречение без „и“;
от нея не може да се извади парче с име, което не е просто преразказ на кода.

Второто правило е едно ниво на абстракция. Горната функция се чете като съдържание на книга: смятай сумата, запиши, потвърди, запиши в лога. Как точно се събират цените (циклите, сравненията, форматът на низа) е едно ниво по-долу, в малките функции. Когато в един и същ метод са „запиши поръчката“ и amount += price, читателят прескача между двете нива на всеки ред.

Виж го

Същата поръчка, разделена

Отгоре е съдържанието:

def place_order(email, prices, coupon, express):
    total = order_total(prices, coupon, express)
    orders.append(total)
    send_confirmation(email, total)
    log_order(len(orders), total)


def send_confirmation(email, total):
    print(f"До {email}: поръчката е приета, {total:.2f} €")


def log_order(number, total):
    print(f"[log] поръчка №{number} за {total:.2f} €")

Под него е сметката, всяка работа в своя функция:

def subtotal(prices):
    amount = 0
    for price in prices:
        amount += price
    return amount


def apply_coupon(amount, coupon):
    if coupon == SPRING_COUPON:
        return amount * (1 - SPRING_DISCOUNT)
    return amount


def delivery_fee(amount, express):
    fee = 0 if amount >= FREE_DELIVERY_FROM else STANDARD_DELIVERY_FEE
    if express:
        fee += EXPRESS_SURCHARGE
    return fee

def order_total(prices, coupon, express):
    amount = subtotal(prices)
    discounted = apply_coupon(amount, coupon)
    return discounted + delivery_fee(discounted, express)

place_order("maria@example.com", [24.50, 18.00], "SPRING10", True)
place_order("ivan@example.com", [64.00], "", False)

До maria@example.com: поръчката е приета, 50.24 €
[log] поръчка №1 за 50.24 €
До ivan@example.com: поръчката е приета, 64.00 €
[log] поръчка №2 за 64.00 €

Изходът е същият. Сега купонът е в една функция от три реда, доставката в друга, и всяка се сменя, без да се пипа имейлът. Кодът е повече на брой редове, но всяко парче се чете, сменя и проверява отделно.

По-точно, за любопитните

Колко малка? Няма число. Функция от 30 реда, която прави едно нещо (например дълъг, но равен switch с еднакви клонове), е наред. Функция от 8 реда с три нива на влагане и два флага не е. Мерилото е описанието с едно изречение, не броят на редовете. Разделянето на дълга функция на стъпки, така че програмата да работи след всяка, е Extract Method в шестия урок от модула.

Пробвай

Подреди редовете

Подреди order_total така, че купонът да се приложи преди доставката. Защо редът има значение: отстъпката може да свали поръчката под 50 € и тогава доставката вече не е безплатна.

return discounted + delivery_fee(discounted, express)
discounted = apply_coupon(amount, coupon)
amount = subtotal(prices)
def order_total(prices, coupon, express):

Идеята

Малко параметри и без флагове

Всеки параметър е нещо, което читателят трябва да държи в главата си, и нещо, което всяко извикване трябва да подаде в правилния ред. Нула, един и два параметъра се четат лесно. Три вече е много. Четири и повече обикновено значат, че параметрите са едно нещо, разпиляно на части: имейлът, цените, купонът и доставката заедно са поръчка. Тогава те стават един обект. Това е refactoring-ът Introduce Parameter Object от шестия урок.

Най-лошият параметър е флагът: булева стойност, която избира какво да прави функцията.

def print_slip(prices, for_courier):
    if for_courier:
        print(f"Пратка: {len(prices)} бр.")
    else:
        for price in prices:
            print(f"{price:.2f} €")

cart = [24.50, 18.00]
print_slip(cart, True)
print_slip(cart, False)

Пратка: 2 бр.
24.50 €
18.00 €

При извикването True не казва нищо. А вътре функцията има два отделни пътя, тоест две работи. Поправката е две функции с имена:

def print_courier_slip(prices):
    print(f"Пратка: {len(prices)} бр.")


def print_receipt(prices):
    for price in prices:
        print(f"{price:.2f} €")

cart = [24.50, 18.00]
print_courier_slip(cart)
print_receipt(cart)

Пратка: 2 бр.
24.50 €
18.00 €

Понякога булевата стойност наистина е данни, а не избор на поведение: експресната доставка е част от поръчката. Тогава поне извикването трябва да казва какво значи:

Python има аргументи само по име: всичко след * в дефиницията може да се подаде само с името си. Опит без името е грешка:

def delivery_fee(amount, *, express=False):
    fee = 0 if amount >= FREE_DELIVERY_FROM else STANDARD_DELIVERY_FEE
    if express:
        fee += EXPRESS_SURCHARGE
    return fee


print(f"{delivery_fee(38.25, express=True):.2f} €")

try:
    delivery_fee(38.25, True)
except TypeError as error:
    print(error)

11.99 €
delivery_fee() takes 1 positional argument but 2 were given

Идеята

Страничен ефект

Всичко, което функцията сменя извън себе си, е страничен ефект: поле на обект, списък, който е получила, глобална променлива, файл, база, имейл, ред на екрана.

Страничните ефекти не са лоши сами по себе си. Поръчката трябва да се запише някъде, а имейлът трябва да тръгне. Лошо е, когато ефектът е скрит: името казва „питам“, а функцията и прави. Който я вика, не очаква нищо да се смени и я вика спокойно два пъти.

Виж го

Въпросът, който сменя отговора

Складът казва дали има лампи. Някой е решил, че щом има, е удобно веднага да ги запази:

class Warehouse:
    def __init__(self, stock):
        self.stock = stock

    def is_in_stock(self, quantity):
        if self.stock >= quantity:
            self.stock -= quantity
            return True
        return False

Количката пита, за да покаже „има“. После плащането пита същото:

lamps = Warehouse(3)
print("Количка: " + ("има" if lamps.is_in_stock(2) else "няма"))
print("Плащане: " + ("има" if lamps.is_in_stock(2) else "няма"))
print(f"На склад: {lamps.stock}")

Количка: има
Плащане: няма
На склад: 1

class Warehouse:
    def __init__(self, stock):
        self.stock = stock

    def is_in_stock(self, quantity):
        if self.stock >= quantity:
            self.stock -= quantity
            return True
        return False


lamps = Warehouse(3)
print("Количка: " + ("има" if lamps.is_in_stock(2) else "няма"))
print("Плащане: " + ("има" if lamps.is_in_stock(2) else "няма"))
print(f"На склад: {lamps.stock}")

Стъпка по стъпка, с думи

Складът има 3 лампи на рафта.
Количката иска само да покаже дали има 2. Тя пита is_in_stock(2): въпрос, съдейки по името.
3 >= 2: има достатъчно.
Но въпросът и взима лампите: self.stock става 1 от 3. Никой нищо не е купил, а количката не знае, че това е станало.
Количката получава True и показва „има“.
Клиентът отива към плащане. Плащането пита същото: is_in_stock(2).
1 >= 2 е False. Същият въпрос получава друг отговор, а клиентът вижда „няма“.
На склад: 1. Отговорът се смени, защото първият въпрос имаше скрит страничен ефект.

Никой нищо не е купил, а две лампи липсват, и клиентът не може да плати. В истински магазин това е поръчка, загубена заради страница, която пита за наличност. А грешката е трудна за намиране, защото всеки ред поотделно изглежда наред.

По-точно, за любопитните

Още по-коварно е в @property: lamps.stock изглежда като четене на атрибут, а може да е функция, която сменя нещо. Дебъгерът на PyCharm изчислява свойствата, за да ги покаже, и така може да смени състоянието.

Пробвай

Предвиди изхода

Складът с is_in_stock, който и запазва, вече има 5 лампи. Един и същ въпрос се задава три пъти. Какво печата програмата?

lamps = Warehouse(5)
print(lamps.is_in_stock(2))
print(lamps.is_in_stock(2))
print(lamps.is_in_stock(2))

Отговор

True / False / False

True / True / True

True / True / False

Идеята

Команда или въпрос, не и двете

Правилото се казва разделяне на команда и въпрос (command–query separation): функцията или отговаря на въпрос и не сменя нищо, или прави нещо и не се преструва на въпрос. Складът става така:

class Warehouse:
    def __init__(self, stock):
        self.stock = stock

    def is_in_stock(self, quantity):
        return self.stock >= quantity

    def reserve(self, quantity):
        if not self.is_in_stock(quantity):
            raise ValueError("Няма достатъчно наличност")
        self.stock -= quantity

lamps = Warehouse(3)
print("Количка: " + ("има" if lamps.is_in_stock(2) else "няма"))
print("Плащане: " + ("има" if lamps.is_in_stock(2) else "няма"))
lamps.reserve(2)
print(f"На склад: {lamps.stock}")

Количка: има
Плащане: има
На склад: 1

Количката и плащането питат колкото искат. Лампите се запазват на един ред, който казва точно това: reserve(2).

По-точно, за любопитните

Има известни изключения, и името ги издава: items.pop() маха елемента и го връща, next(iterator) мести напред и връща. Това са глаголи, не въпроси, затова никой не ги вика „просто да провери“. Правилото не е „командата никога не връща нищо“, а „въпросът никога не сменя нищо“.

Идеята

Чистата функция

delivery_fee от разделената поръчка отговаря само по параметрите си и не сменя нищо. Такава функция се казва чиста: при едни и същи параметри винаги връща едно и също, колкото и пъти и в какъвто и ред да я викаш.

print(f"{delivery_fee(38.25, False):.2f} €")
print(f"{delivery_fee(38.25, True):.2f} €")
print(f"{delivery_fee(64.00, False):.2f} €")
print(f"{delivery_fee(38.25, True):.2f} €")

4.99 €
11.99 €
0.00 €
11.99 €

Проверката на доставката под и над прага е четири реда. Няма склад, който да се напълни, няма имейл, който да тръгне, няма база. При process_order за същото трябваше да направиш поръчка. Затова сметките се пазят чисти, а страничните ефекти се събират в няколко ясно кръстени команди отгоре. Как такива проверки стават тестове, които пазят кода при всяка промяна, е темата на петия урок от модула.

Пробвай

Намери грешката

Бутонът „Махни последното“ трябва да маха продукта, който клиентът е добавил последен. Клиентът добавя мляко, ябълки и хляб. Преди това магазинът печата бележка, подредена по азбучен ред:

def print_receipt(items):
    items.sort()
    for item in items:
        print("  " + item)

cart = ["мляко", "ябълки", "хляб"]
print_receipt(cart)
print("Последно добавено: " + cart[-1])

  мляко
  хляб
  ябълки
Последно добавено: ябълки

Последен е добавен хлябът, а програмата казва ябълки. На кой ред е грешката?

Избери реда с грешката.

items.sort() подрежда самия списък, който функцията е получила, а той е количката на викащия. Бележката е искала само да печата, а тихо е сменила реда в количката. Поправката е да подредиш копие и да оставиш количката непокътната:

def print_receipt(items):
    for item in sorted(items):
        print("  " + item)

sorted(items) връща нов списък, а items.sort() сменя самия списък.

Упражнение

Известието за изпратена поръчка

Реши задачата в редактора си.

Известието. Тази функция смята текста, избира канала с флаг, печата и брои изпратените:

sent = 0


def notify_shipped(name, order_id, sms):
    global sent
    sent += 1
    text = f"Здравей, {name}! Поръчка {order_id} е изпратена."
    if sms:
        print("SMS: " + text)
    else:
        print("Имейл: " + text)

notify_shipped("Мария", 1042, False)
notify_shipped("Иван", 1043, True)
print("Изпратени: " + str(sent))

Имейл: Здравей, Мария! Поръчка 1042 е изпратена.
SMS: Здравей, Иван! Поръчка 1043 е изпратена.
Изпратени: 2

Раздели я на три функции: чиста, която само прави текста, и две команди, едната праща по имейл, другата по SMS, и всяка брои изпратеното. Флагът изчезва. Изходът трябва да остане същият:

Имейл: Здравей, Мария! Поръчка 1042 е изпратена.
SMS: Здравей, Иван! Поръчка 1043 е изпратена.
Изпратени: 2

Още задачи

Параметър обект. place_order има четири параметъра. Събери ги в обект order и виж как изглежда извикването.
Купонът не важи за доставката. Маркетингът сменя правилото. Коя функция пипаш и колко други остават непокътнати?
Опашката. Напиши peek_next() и take_next() за опашка от поръчки за куриера. Кое е въпрос и кое е команда?

Тест

Провери се

1. Как разбираш, че process_order прави повече от една работа?По това, че има цикълОписанието ѝ има много „и“: събира и прилага купона и смята доставката и записва и праща имейлПо броя на редовете

2. print_slip(cart, True). Какво не е наред?НищоФлагът казва, че функцията прави две различни неща. По-ясно е print_courier_slip(cart) и print_receipt(cart)Параметрите трябва да са повече

3. is_in_stock(2) намалява наличността, ако има достатъчно. Количката пита веднъж, плащането още веднъж. Какво става при 3 лампи?Количката получава „има“, плащането „няма“, а на склад остава 1И двете получават „има“Програмата спира с грешка

4. Коя от тези функции е чиста?delivery_fee(amount, express): смята таксата от двата параметъраprint_receipt(items): подрежда списъка, който получава, и го печатаplace_order(…): записва поръчката и праща имейл

5. Какво казва разделянето на команда и въпрос?Всяка функция трябва да връща стойностКомандите трябва да са в отделен класФункцията или прави нещо, или отговаря на въпрос, но не и двете

Функции: една работа, малко параметри, без скрити странични ефекти

Бисквитки