4. Більше інструментів керування потоком

Besides the while statement just introduced, Python uses the usual flow control statements known from other languages, with some twists.

4.1. if Інструкції

Мабуть, найвідомішим типом операторів є оператор if. Наприклад:

>>> x = int(input("Please enter an integer: "))
Please enter an integer: 42
>>> if x < 0:
...     x = 0
...     print('Negative changed to zero')
... elif x == 0:
...     print('Zero')
... elif x == 1:
...     print('Single')
... else:
...     print('More')
...
More

Частин elif може бути нуль або більше, а частина else необов’язкова. Ключове слово „elif“ є скороченням від „else if“ і корисне, щоб уникнути надмірних відступів. Послідовність if … elif … elif … є заміною знайдених операторів switch або case іншими мовами.

4.2. for Заяви

Оператор for у Python дещо відрізняється від того, до чого ви звикли в C або Pascal. Замість того, щоб завжди повторювати арифметичну прогресію чисел (як у Паскалі) або давати користувачеві можливість визначати крок ітерації та умову зупинки (як C), оператор Python for повторює елементи будь-яка послідовність (список або рядок) у тому порядку, в якому вони з’являються в послідовності. Наприклад (без каламбуру):

>>> # Measure some strings:
... words = ['cat', 'window', 'defenestrate']
>>> for w in words:
...     print(w, len(w))
...
cat 3
window 6
defenestrate 12

Код, який змінює колекцію під час ітерації над цією ж колекцією, може бути складним для правильного визначення. Замість цього зазвичай простіше виконати цикл по копії колекції або створити нову колекцію:

# Strategy:  Iterate over a copy
for user, status in users.copy().items():
    if status == 'inactive':
        del users[user]

# Strategy:  Create a new collection
active_users = {}
for user, status in users.items():
    if status == 'active':
        active_users[user] = status

4.3. Функція range()

Якщо вам все-таки потрібно виконати ітерацію по послідовності чисел, стане в нагоді вбудована функція range(). Він створює арифметичні прогресії:

>>> for i in range(5):
...     print(i)
...
0
1
2
3
4

Дана кінцева точка ніколи не є частиною згенерованої послідовності; range(10) генерує 10 значень, законних індексів для елементів послідовності довжиною 10. Можна дозволити діапазону починатися з іншого числа або вказати інший крок (навіть від’ємний; іноді це називається «крок»):

>>> list(range(5, 10))
[5, 6, 7, 8, 9]

>>> list(range(0, 10, 3))
[0, 3, 6, 9]

>>> list(range(-10, -100, -30))
[-10, -40, -70]

Щоб перебирати індекси послідовності, ви можете поєднати range() і len() таким чином:

>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
>>> for i in range(len(a)):
...     print(i, a[i])
...
0 Mary
1 had
2 a
3 little
4 lamb

Однак у більшості таких випадків зручно використовувати функцію enumerate(), див. Техніка циклу.

Дивна річ трапляється, якщо ви просто друкуєте діапазон:

>>> range(10)
range(0, 10)

Багато в чому об’єкт, який повертає range(), поводиться так, ніби це список, але насправді це не так. Це об’єкт, який повертає послідовні елементи потрібної послідовності, коли ви перебираєте його, але насправді він не входить до списку, таким чином економлячи місце.

Ми кажемо, що такий об’єкт є iterable, тобто придатним як ціль для функцій і конструкцій, які очікують чогось, з чого вони можуть отримувати послідовні елементи, доки запас не буде вичерпано. Ми бачили, що оператор for є такою конструкцією, тоді як прикладом функції, яка приймає ітерований елемент, є sum():

>>> sum(range(4))  # 0 + 1 + 2 + 3
6

Пізніше ми побачимо більше функцій, які повертають iterables і приймають iterables як аргументи. У розділі Структури даних ми більш детально обговоримо list().

4.4. break і continue Інструкції та else пропозиції циклів

The break statement, like in C, breaks out of the innermost enclosing for or while loop.

Loop statements may have an else clause; it is executed when the loop terminates through exhaustion of the iterable (with for) or when the condition becomes false (with while), but not when the loop is terminated by a break statement. This is exemplified by the following loop, which searches for prime numbers:

>>> for n in range(2, 10):
...     for x in range(2, n):
...         if n % x == 0:
...             print(n, 'equals', x, '*', n//x)
...             break
...     else:
...         # loop fell through without finding a factor
...         print(n, 'is a prime number')
...
2 is a prime number
3 is a prime number
4 equals 2 * 2
5 is a prime number
6 equals 2 * 3
7 is a prime number
8 equals 2 * 4
9 equals 3 * 3

(Так, це правильний код. Подивіться уважно: пропозиція else належить циклу for, не оператору if.)

При використанні з циклом пропозиція else має більше спільного з пропозицією else оператора try, ніж з пропозицією if: a : Речення else інструкції за try виконується, коли не відбувається винятків, а речення else циклу виконується, коли не відбувається розрив. Щоб дізнатися більше про оператор try та винятки, перегляньте Обробка винятків.

Оператор continue, також запозичений з C, продовжує наступну ітерацію циклу:

>>> for num in range(2, 10):
...     if num % 2 == 0:
...         print("Found an even number", num)
...         continue
...     print("Found an odd number", num)
...
Found an even number 2
Found an odd number 3
Found an even number 4
Found an odd number 5
Found an even number 6
Found an odd number 7
Found an even number 8
Found an odd number 9

4.5. pass Інструкції

Оператор pass нічого не робить. Його можна використовувати, коли оператор потрібен синтаксично, але програма не вимагає жодних дій. Наприклад:

>>> while True:
...     pass  # Busy-wait for keyboard interrupt (Ctrl+C)
...

Це зазвичай використовується для створення мінімальних класів:

>>> class MyEmptyClass:
...     pass
...

Інше місце, яке можна використовувати pass, це як заповнювач для функції або умовного тіла, коли ви працюєте над новим кодом, що дозволяє вам продовжувати мислити на більш абстрактному рівні. pass мовчки ігнорується:

>>> def initlog(*args):
...     pass   # Remember to implement this!
...

4.6. Визначення функцій

Ми можемо створити функцію, яка записує ряд Фібоначчі до довільної границі:

>>> def fib(n):    # write Fibonacci series up to n
...     """Print a Fibonacci series up to n."""
...     a, b = 0, 1
...     while a < n:
...         print(a, end=' ')
...         a, b = b, a+b
...     print()
...
>>> # Now call the function we just defined:
... fib(2000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597

Ключове слово def вводить визначення функції. Після нього має йти ім’я функції та список формальних параметрів у дужках. Оператори, які утворюють тіло функції, починаються з наступного рядка та мають бути з відступом.

Перший оператор тіла функції необов’язково може бути рядковим літералом; цей рядковий літерал є рядком документації функції, або docstring. (Більше про рядки документів можна знайти в розділі Рядки документації.) Існують інструменти, які використовують рядки документів для автоматичного створення онлайнової або друкованої документації або для того, щоб користувач міг інтерактивно переглядати код; добре включати рядки документації в код, який ви пишете, тож візьміть це за звичку.

Виконання функції вводить нову таблицю символів, яка використовується для локальних змінних функції. Точніше, усі призначення змінних у функції зберігають значення в локальній таблиці символів; тоді як посилання на змінні спочатку шукають у локальній таблиці символів, потім у локальних таблицях символів охоплюючих функцій, потім у глобальній таблиці символів і, нарешті, у таблиці вбудованих імен. Таким чином, глобальним змінним і змінним охоплюючих функцій не можна безпосередньо присвоїти значення в межах функції (якщо для глобальних змінних, названих у операторі global, або для змінних охоплюючих функцій, названих у nonlocal), хоча на них можна посилатися.

Фактичні параметри (аргументи) виклику функції вводяться в локальну таблицю символів викликаної функції під час її виклику; таким чином, аргументи передаються за допомогою виклику за значенням (де значення завжди є посиланням на об’єкт, а не значенням об’єкта). 1 Коли функція викликає іншу функцію або рекурсивно викликає саму себе, для цього виклику створюється нова локальна таблиця символів.

Визначення функції пов’язує назву функції з об’єктом функції в поточній таблиці символів. Інтерпретатор розпізнає об’єкт, на який вказує це ім’я, як функцію, визначену користувачем. Інші імена також можуть вказувати на той самий об’єкт функції та також можуть використовуватися для доступу до функції:

>>> fib
<function fib at 10042ed0>
>>> f = fib
>>> f(100)
0 1 1 2 3 5 8 13 21 34 55 89

Виходячи з інших мов, ви можете заперечити, що fib — це не функція, а процедура, оскільки вона не повертає значення. Фактично, навіть функції без оператора return повертають значення, хоча й досить нудне. Це значення називається None (це вбудоване ім’я). Запис значення None зазвичай пригнічується інтерпретатором, якщо це буде єдине записане значення. Ви можете побачити це, якщо дійсно хочете використовувати print():

>>> fib(0)
>>> print(fib(0))
None

Дуже просто написати функцію, яка повертає список чисел ряду Фібоначчі, замість того, щоб друкувати його:

>>> def fib2(n):  # return Fibonacci series up to n
...     """Return a list containing the Fibonacci series up to n."""
...     result = []
...     a, b = 0, 1
...     while a < n:
...         result.append(a)    # see below
...         a, b = b, a+b
...     return result
...
>>> f100 = fib2(100)    # call it
>>> f100                # write the result
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]

Цей приклад, як завжди, демонструє деякі нові функції Python:

• Оператор return повертає значення з функції. return без аргументу-виразу повертає None. Випадання кінця функції також повертає None.

• The statement result.append(a) calls a method of the list object result. A method is a function that „belongs“ to an object and is named obj.methodname, where obj is some object (this may be an expression), and methodname is the name of a method that is defined by the object’s type. Different types define different methods. Methods of different types may have the same name without causing ambiguity. (It is possible to define your own object types and methods, using classes, see Класи) The method append() shown in the example is defined for list objects; it adds a new element at the end of the list. In this example it is equivalent to result = result + [a], but more efficient.

4.7. Докладніше про визначення функцій

Також можна визначати функції зі змінною кількістю аргументів. Є три форми, які можна комбінувати.

4.7.1. Значення аргументів за замовчуванням

Найбільш корисною формою є вказати значення за умовчанням для одного або кількох аргументів. Це створює функцію, яку можна викликати з меншою кількістю аргументів, ніж це дозволено. Наприклад:

def ask_ok(prompt, retries=4, reminder='Please try again!'):
    while True:
        ok = input(prompt)
        if ok in ('y', 'ye', 'yes'):
            return True
        if ok in ('n', 'no', 'nop', 'nope'):
            return False
        retries = retries - 1
        if retries < 0:
            raise ValueError('invalid user response')
        print(reminder)

Цю функцію можна викликати кількома способами:

• вказуючи лише обов’язковий аргумент: ask_ok('Ви дійсно хочете вийти?')

• надання одного з необов’язкових аргументів: ask_ok('ОК перезаписати файл?', 2)

• або навіть надавши всі аргументи: ask_ok('Добре перезаписати файл?', 2, 'Давай, тільки так чи ні!')

У цьому прикладі також представлено ключове слово in. Це перевіряє, чи містить послідовність певне значення.

Значення за замовчуванням оцінюються в точці визначення функції в області defining, так що:

i = 5

def f(arg=i):
    print(arg)

i = 6
f()

надрукує 5.

Важливе попередження: Значення за замовчуванням оцінюється лише один раз. Це має значення, коли за умовчанням є змінний об’єкт, наприклад список, словник або екземпляри більшості класів. Наприклад, наступна функція накопичує аргументи, передані їй під час наступних викликів:

def f(a, L=[]):
    L.append(a)
    return L

print(f(1))
print(f(2))
print(f(3))

Це надрукує

[1]
[1, 2]
[1, 2, 3]

Якщо ви не хочете, щоб значення за замовчуванням використовувалися для наступних викликів, ви можете написати функцію так:

def f(a, L=None):
    if L is None:
        L = []
    L.append(a)
    return L

4.7.2. Аргументи ключових слів

Функції також можна викликати за допомогою аргументів ключового слова у формі kwarg=значення. Наприклад, така функція:

def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
    print("-- This parrot wouldn't", action, end=' ')
    print("if you put", voltage, "volts through it.")
    print("-- Lovely plumage, the", type)
    print("-- It's", state, "!")

приймає один обов’язковий аргумент (напруга) і три необов’язкові аргументи (стан, дія і тип). Цю функцію можна викликати будь-яким із наведених нижче способів:

parrot(1000)                                          # 1 positional argument
parrot(voltage=1000)                                  # 1 keyword argument
parrot(voltage=1000000, action='VOOOOOM')             # 2 keyword arguments
parrot(action='VOOOOOM', voltage=1000000)             # 2 keyword arguments
parrot('a million', 'bereft of life', 'jump')         # 3 positional arguments
parrot('a thousand', state='pushing up the daisies')  # 1 positional, 1 keyword

але всі наступні виклики будуть недійсними:

parrot()                     # required argument missing
parrot(voltage=5.0, 'dead')  # non-keyword argument after a keyword argument
parrot(110, voltage=220)     # duplicate value for the same argument
parrot(actor='John Cleese')  # unknown keyword argument

Під час виклику функції ключові аргументи повинні слідувати за позиційними аргументами. Усі передані ключові аргументи мають відповідати одному з аргументів, прийнятих функцією (наприклад, actor не є дійсним аргументом для parrot функції), і їх порядок не важливий. Це також включає необов’язкові аргументи (наприклад, parrot(voltage=1000) також дійсний). Жоден аргумент не може отримати значення більше одного разу. Ось приклад, який не працює через це обмеження:

>>> def function(a):
...     pass
...
>>> function(0, a=0)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: function() got multiple values for argument 'a'

Коли присутній остаточний формальний параметр у формі **name, він отримує словник (див. Типи зіставлення — dict), який містить усі ключові аргументи, за винятком тих, що відповідають формальному параметру. Це можна поєднати з формальним параметром у формі *name (описано в наступному підрозділі), який отримує tuple, що містить позиційні аргументи поза формальним списком параметрів. (*name має бути перед **name.) Наприклад, якщо ми визначимо таку функцію:

def cheeseshop(kind, *arguments, **keywords):
    print("-- Do you have any", kind, "?")
    print("-- I'm sorry, we're all out of", kind)
    for arg in arguments:
        print(arg)
    print("-" * 40)
    for kw in keywords:
        print(kw, ":", keywords[kw])

Це можна назвати так:

cheeseshop("Limburger", "It's very runny, sir.",
           "It's really very, VERY runny, sir.",
           shopkeeper="Michael Palin",
           client="John Cleese",
           sketch="Cheese Shop Sketch")

і, звичайно, він буде друкувати:

-- Do you have any Limburger ?
-- I'm sorry, we're all out of Limburger
It's very runny, sir.
It's really very, VERY runny, sir.
----------------------------------------
shopkeeper : Michael Palin
client : John Cleese
sketch : Cheese Shop Sketch

Зауважте, що порядок друку ключових аргументів гарантовано збігається з порядком, у якому вони були надані під час виклику функції.

4.7.3. Спеціальні параметри

За замовчуванням аргументи можуть передаватися функції Python за позицією або явно за ключовим словом. Для зручності читання та продуктивності має сенс обмежити спосіб передачі аргументів, щоб розробнику потрібно було дивитися лише на визначення функції, щоб визначити, чи передаються елементи за позицією, за позицією чи ключовим словом або за ключовим словом.

Визначення функції може виглядати так:

def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
      -----------    ----------     ----------
        |             |                  |
        |        Positional or keyword   |
        |                                - Keyword only
         -- Positional only

де / і * необов’язкові. Якщо використовуються, ці символи вказують на тип параметра за допомогою того, як аргументи можуть бути передані до функції: лише позиційні, позиційні чи ключові слова та лише ключові слова. Параметри ключових слів також називають іменованими параметрами.

4.7.3.1. Позиційні або ключові аргументи

Якщо / і * відсутні у визначенні функції, аргументи можуть бути передані функції за позицією або за ключовим словом.

4.7.3.2. Лише позиційні параметри

Розглянувши це трохи детальніше, можна позначити певні параметри як тільки позиційні. Якщо лише позиційний, порядок параметрів має значення, і параметри не можуть бути передані за ключовим словом. Лише позиційні параметри розміщуються перед / (коса риска). / використовується для логічного відокремлення лише позиційних параметрів від решти параметрів. Якщо у визначенні функції немає /, немає позиційних параметрів.

Параметри після / можуть бути positional-or-keyword або keyword-only.

4.7.3.3. Аргументи лише за ключовими словами

Щоб позначити параметри як лише ключове слово, вказавши, що параметри повинні бути передані аргументом ключового слова, помістіть * у списку аргументів безпосередньо перед першим параметром лише ключове.

4.7.3.4. Приклади функцій

Розглянемо наступні приклади визначення функцій, звертаючи особливу увагу на маркери / і *:

>>> def standard_arg(arg):
...     print(arg)
...
>>> def pos_only_arg(arg, /):
...     print(arg)
...
>>> def kwd_only_arg(*, arg):
...     print(arg)
...
>>> def combined_example(pos_only, /, standard, *, kwd_only):
...     print(pos_only, standard, kwd_only)

Перше визначення функції, standard_arg, найвідоміша форма, не накладає обмежень на угоду про виклики, і аргументи можуть передаватися за позицією або ключовим словом:

>>> standard_arg(2)
2

>>> standard_arg(arg=2)
2

Друга функція pos_only_arg обмежена використанням лише позиційних параметрів, оскільки у визначенні функції є /:

>>> pos_only_arg(1)
1

>>> pos_only_arg(arg=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: pos_only_arg() got some positional-only arguments passed as keyword arguments: 'arg'

Третя функція kwd_only_args дозволяє лише ключові аргументи, як зазначено * у визначенні функції:

>>> kwd_only_arg(3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: kwd_only_arg() takes 0 positional arguments but 1 was given

>>> kwd_only_arg(arg=3)
3

І останній використовує всі три угоди про виклики в одному визначенні функції:

>>> combined_example(1, 2, 3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: combined_example() takes 2 positional arguments but 3 were given

>>> combined_example(1, 2, kwd_only=3)
1 2 3

>>> combined_example(1, standard=2, kwd_only=3)
1 2 3

>>> combined_example(pos_only=1, standard=2, kwd_only=3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: combined_example() got some positional-only arguments passed as keyword arguments: 'pos_only'

Нарешті, розглянемо це визначення функції, яке має потенційну колізію між позиційним аргументом name і **kwds, який має name як ключ:

def foo(name, **kwds):
    return 'name' in kwds

Немає можливого виклику, який змусить його повернути True, оскільки ключове слово 'name'' завжди прив’язуватиметься до першого параметра. Наприклад:

>>> foo(1, **{'name': 2})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: foo() got multiple values for argument 'name'
>>>

Але використання / (лише позиційні аргументи) є можливим, оскільки воно дозволяє name як позиційний аргумент і 'name' як ключ в аргументах ключового слова:

def foo(name, /, **kwds):
    return 'name' in kwds
>>> foo(1, **{'name': 2})
True

Іншими словами, назви лише позиційних параметрів можна використовувати в **kwds без двозначності.

4.7.3.5. Підведення підсумків

Варіант використання визначить, які параметри використовувати у визначенні функції:

def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):

Як керівництво:

• Використовуйте тільки позиційне значення, якщо ви хочете, щоб назва параметрів була недоступна для користувача. Це корисно, коли назви параметрів не мають реального значення, якщо ви хочете забезпечити порядок аргументів під час виклику функції або якщо вам потрібно взяти деякі позиційні параметри та довільні ключові слова.

• Використовуйте ключові слова лише тоді, коли імена мають значення, а визначення функції є більш зрозумілим через чіткі імена або ви хочете запобігти тому, щоб користувачі покладалися на позицію переданого аргументу.

• Для API використовуйте тільки позиційний, щоб запобігти несправним змінам API, якщо назву параметра буде змінено в майбутньому.

4.7.4. Списки довільних аргументів

Нарешті, найменш часто використовуваний варіант - це вказати, що функція може бути викликана з довільною кількістю аргументів. Ці аргументи будуть загорнуті в кортеж (див. Кортежі та послідовності). Перед змінною кількістю аргументів може бути нуль або більше нормальних аргументів.

def write_multiple_items(file, separator, *args):
    file.write(separator.join(args))

Зазвичай ці варіативні аргументи будуть останніми в списку формальних параметрів, оскільки вони збирають усі вхідні аргументи, що залишилися, які передаються функції. Будь-які формальні параметри, які виникають після параметра *args, є аргументами «тільки ключового слова», тобто їх можна використовувати лише як ключові слова, а не як позиційні аргументи.

>>> def concat(*args, sep="/"):
...     return sep.join(args)
...
>>> concat("earth", "mars", "venus")
'earth/mars/venus'
>>> concat("earth", "mars", "venus", sep=".")
'earth.mars.venus'

4.7.5. Розпакування списків аргументів

Зворотна ситуація виникає, коли аргументи вже є в списку або кортежі, але їх потрібно розпакувати для виклику функції, що потребує окремих позиційних аргументів. Наприклад, вбудована функція range() очікує окремих аргументів start і stop. Якщо вони недоступні окремо, напишіть виклик функції з оператором *, щоб розпакувати аргументи зі списку або кортежу:

>>> list(range(3, 6))            # normal call with separate arguments
[3, 4, 5]
>>> args = [3, 6]
>>> list(range(*args))            # call with arguments unpacked from a list
[3, 4, 5]

Таким же чином словники можуть надавати аргументи ключових слів за допомогою оператора **::

>>> def parrot(voltage, state='a stiff', action='voom'):
...     print("-- This parrot wouldn't", action, end=' ')
...     print("if you put", voltage, "volts through it.", end=' ')
...     print("E's", state, "!")
...
>>> d = {"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"}
>>> parrot(**d)
-- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !

4.7.6. Лямбда-вирази

Невеликі анонімні функції можна створювати за допомогою ключового слова lambda. Ця функція повертає суму своїх двох аргументів: лямбда a, b: a+b. Лямбда-функції можна використовувати скрізь, де потрібні функціональні об’єкти. Вони синтаксично обмежені одним виразом. Семантично вони є лише синтаксичним цукром для нормального визначення функції. Як і визначення вкладених функцій, лямбда-функції можуть посилатися на змінні з області видимості:

>>> def make_incrementor(n):
...     return lambda x: x + n
...
>>> f = make_incrementor(42)
>>> f(0)
42
>>> f(1)
43

У наведеному вище прикладі використовується лямбда-вираз для повернення функції. Інше використання - передача невеликої функції як аргумент:

>>> pairs = [(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]
>>> pairs.sort(key=lambda pair: pair[1])
>>> pairs
[(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')]

4.7.7. Рядки документації

Ось деякі умовності щодо вмісту та форматування рядків документації.

Перший рядок завжди має бути коротким, лаконічним описом призначення об’єкта. Для стислості, він не повинен явно вказувати ім’я чи тип об’єкта, оскільки вони доступні іншими засобами (окрім випадків, коли ім’я є дієсловом, що описує роботу функції). Цей рядок повинен починатися з великої літери і закінчуватися крапкою.

Якщо в рядку документації є більше рядків, другий рядок має бути порожнім, візуально відокремлюючи резюме від решти опису. Наступні рядки мають бути одним або декількома абзацами, що описують умови виклику об’єкта, його побічні ефекти тощо.

Синтаксичний аналізатор Python не видаляє відступи з багаторядкових рядкових літералів у Python, тому інструменти, які обробляють документацію, за бажанням мають видаляти відступи. Це робиться за допомогою наступної угоди. Перший непорожній рядок після першого рядка рядка визначає величину відступу для всього рядка документації. (Ми не можемо використати перший рядок, оскільки він зазвичай примикає до початкових лапок рядка, тому його відступ не видно в рядковому літералі.) Пробіли, «еквівалентні» цьому відступу, потім видаляються з початку всіх рядків рядка . Рядки з меншим відступом не повинні з’являтися, але якщо вони трапляються, усі їх початкові пробіли мають бути видалені. Еквівалентність пробілів слід перевіряти після розширення табуляції (зазвичай до 8 пробілів).

Ось приклад багаторядкового документального рядка:

>>> def my_function():
...     """Do nothing, but document it.
...
...     No, really, it doesn't do anything.
...     """
...     pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.

    No, really, it doesn't do anything.

4.7.8. Анотації до функцій

Анотації функцій є абсолютно необов’язковою інформацією метаданих про типи, які використовуються визначеними користувачем функціями (див. PEP 3107 і PEP 484 для отримання додаткової інформації).

Annotations are stored in the __annotations__ attribute of the function as a dictionary and have no effect on any other part of the function. Parameter annotations are defined by a colon after the parameter name, followed by an expression evaluating to the value of the annotation. Return annotations are defined by a literal ->, followed by an expression, between the parameter list and the colon denoting the end of the def statement. The following example has a required argument, an optional argument, and the return value annotated:

>>> def f(ham: str, eggs: str = 'eggs') -> str:
...     print("Annotations:", f.__annotations__)
...     print("Arguments:", ham, eggs)
...     return ham + ' and ' + eggs
...
>>> f('spam')
Annotations: {'ham': <class 'str'>, 'return': <class 'str'>, 'eggs': <class 'str'>}
Arguments: spam eggs
'spam and eggs'

4.8. Intermezzo: стиль кодування

Тепер, коли ви збираєтеся писати довші, складніші частини Python, саме час поговорити про стиль кодування. Більшість мов можуть бути написані (або стисло, форматовано) різними стилями; деякі більш читабельні, ніж інші. Полегшити читання вашого коду для інших – це завжди гарна ідея, і застосування гарного стилю кодування надзвичайно допомагає в цьому.

Для Python PEP 8 став керівництвом зі стилю, якого дотримуються більшість проектів; він сприяє дуже читабельному та приємному оку стилю кодування. Кожен розробник Python повинен колись прочитати його; ось найважливіші моменти, виділені для вас:

• Використовуйте відступ із 4 пробілами без табуляції.

  4 пробіли є хорошим компромісом між малим відступом (дозволяє більшу глибину вкладення) та великим відступом (легше читати). Вкладки створюють плутанину, тому їх краще не використовувати.

• Переносити рядки так, щоб вони не перевищували 79 символів.

  Це допомагає користувачам із невеликими дисплеями та дає змогу мати декілька файлів коду поруч на більших дисплеях.

• Використовуйте порожні рядки для розділення функцій і класів, а також більші блоки коду всередині функцій.

• Якщо можливо, розмістіть коментарі в окремому рядку.

• Використовуйте рядки документів.

• Використовуйте пробіли навколо операторів і після ком, але не безпосередньо всередині конструкцій у дужках: a = f(1, 2) + g(3, 4).

• Послідовно назвіть свої класи та функції; Угода передбачає використання UpperCamelCase для класів і lowercase_with_underscores для функцій і методів. Завжди використовуйте self як назву для першого аргументу методу (перегляньте Перший погляд на заняття для отримання додаткової інформації про класи та методи).

• Не використовуйте химерні кодування, якщо ваш код призначений для використання в міжнародних середовищах. За замовчуванням Python, UTF-8 або навіть звичайний ASCII найкраще працюють у будь-якому випадку.

• Так само не використовуйте в ідентифікаторах символи, відмінні від ASCII, якщо є лише найменший шанс, що люди, які розмовляють іншою мовою, прочитають або збережуть код.

Виноски

1

Насправді виклик за посиланням на об’єкт був би кращим описом, оскільки якщо передано змінний об’єкт, абонент побачить будь-які зміни, внесені до нього викликаним (елементи, вставлені в список).