Podstawy funkcji

https://docs.python.org/3/reference/compound_stmts.html#function-definitions

https://peps.python.org/pep-0257/
PEP 257 - Docstring Conventions

WPROWADZENIE

Funkcja jest narzędziem grupującym zbiór instrukcji w taki sposób, aby mogły one być wykonane w programie więcej niż jeden raz. Funkcje służą do maksymalizowania możliwości ponownego wykorzystania kodu i minimalizowania powtarzalności kodu. Ciało funkcji jest bezpieczną przestrzenią nazw (namespace). Korzystanie z funkcji pomaga w usuwaniu błędów w programie.

Instrukcje i wyrażenia związane z funkcjami
+-------------+-------------------------------+
| Instrukcja  | Przykłady                     |
+-------------+-------------------------------+
| Wywołania   | my_func(12, word="alpha")     |
| def, return | def func(x, y=1):             |
|             |     return x + y              |
| global      | def changer():                |
|             |     global x ; x = "fresh"    |
| nonlocal    | def changer(): # Py3 PEP 3104 |
|             |     nonlocal x ; x = "fresh"  |
| yield       | generatory                    |
| lambda      | funkcje anonimowe             |
+-------------+-------------------------------+

Definicja funkcji tworzy obiekt funkcji. Istnieją dwie odmiany obiektów funkcji: funkcje wbudowane i funkcje zdefiniowane przez użytkownika. Obie odmiany obsługują wywoływanie funkcji, ale ich implementacja jest różna.

# Składnia funkcji.
def nazwa_funkcji(argumenty_funkcji):   # wiersz nagłówkowy
    docstring                       # opcjonalnie
    instrukcje
    return obiekt_wynikowy          # opcjonalne

def do_nothing():   # szkielet funkcji, do uzupełnienia w przyszłości
    pass            # return None

# Zalecane formy docstring.
# Postać jednowierszowa.
"""Jeden wiersz zakończony kropką."""

# Postać wielowierszowa.
# Tutaj mogą się pojawić wiersze dla modułu doctest.
"""Pierwszy wiersz podsumowania.

Od trzeciego wiersza może być dłuższy opis.
"""

def func(): ...          # utworzenie obiektu funkcji
func()                   # wywołanie funkcji (wyrażenie)
other_name = func        # przypisanie obiektu funkcji
other_name()             # ponowne wywołanie funkcji func
func.atrr = value        # dołączenie atrybutu do obiektu funkcji
dir(func)                # lista atrybutów obiektu funkcji
print(func.__name__)     # wypisze nazwę funkcji
print(func.__doc__)      # wypisze docstring
func(x, y)               # dwa argumenty pozycyjne
func((x, y))             # jeden argument pozycyjny (tuple)

Instrukcja def jest kodem wykonywalnym. Tworzy ona obiekt funkcji i przypisuje go do nazwy. Nazwa funkcji powinna być zapisana w stylu joined_lower. Funkcje mogą zwracać obiekt wynikowy value z powrotem do wywołującego przez return value. Funkcje mogą też zwracać None przez samo return lub kiedy w kodzie funkcji nie pojawia się return.

Argumenty funkcji są do niej wprowadzane przez wartość, tj. przekazywana jest referencja do obiektu. Argumenty funkcji mogą mieć określoną wartość domyślną. Wartość domyślna jest obliczana tylko raz, dlatego trzeba być ostrożnym z domyślnymi argumentami, które są zmienne, jak listy i słowniki. Funkcje mogą być wywoływane z argumentami postaci keyword=value. Są jeszcze inne możliwości, np. zmienna lista argumentów, rozpakowywanie argumentów z listy, wyrażenia lambda.

Własne atrybuty funkcji mogą być sposobem implementacji odpowiednika mechanizmu "statycznych zmiennych lokalnych" dostępnych w innych językach programowania.

POLIMORFIZM

W Pythonie nie ma deklaracji typu argumentów, dlatego cechą funkcji jest polimorfizm: Zachowanie funkcji zależy od tego, co do niej przekażemy.

def times(x, y):
    """Zwraca iloczyn argumentów."""
    return x * y   # uruchamia metodę __mul__ lub __rmul__

times(2, 3)                   # 6
times(2, 3.14)                # 6.28
times("Bum!", 3)              # "Bum!Bum!Bum!"

# Polimorficzna funkcja len() bazuje na metodzie __len__.

len("Python")                      # 6, długość stringu
len(["Python", "C++", "Java"])     # 3, liczba elementów listy
len({"Name": "Adam", "Age": 30})   # 2, liczba kluczy
len(set([1, 3, 5, 7]))             # 4, liczność zbioru

ZMIENNE LOKALNE

Podstawienia do zmiennych wewnątrz funkcji tworzą zmienne lokalne. Odniesienie do zmiennej najpierw oznacza odniesienie do zmiennej lokalnej; jeżeli nie istnieje, to szukana jest zmienna globalna; jeżeli też nie istnieje, to szukane są zmienne wbudowane. Można od razu zadeklarować zmienną globalną przez instrukcję global.

Wszystkie zmienne lokalne pojawiają się w momencie wywołania funkcji i znikają, kiedy funkcja przestaje działać.

def my_len(sequence):              # 'sequence' jest lokalne
    """Obliczanie długości sekwencji."""
    length = 0                     # 'length' jest lokalne
    for item in sequence:          # 'item' jest lokalne
        length += 1
    return length

ZWRACANIE WIELU WARTOŚCI

Instrukcja return może zwracać wiele wartości pakując je w krotkę lub inny typ kolekcji.

def find_minmax(x, y):
    """Zwraca jednocześnie min i max jako krotkę."""
    return (x, y) if x < y else (y, x)

a, b = find_minmax(5, 3)   # (a, b) = (3, 5)