Rozdział 13 · Automatyzacja z funkcjami
Rozdział 13 · Automatyzacja z funkcjamiDockstringi i wskazówki typu
Profesjonalnym nawykiem, który należy wypracować wcześnie, jest dokumentowanie funkcji, aby można ją było zrozumieć bez czytania implementacji.
Docstring — dokumentacja funkcji
docstring.py
def rectangle_area(width, height):
"""Zwraca pole prostokąta."""
return width * height| Komentarz (# ...) | Dokstring ("""...""") | |
|---|---|---|
| Wyjaśnia | dlaczego kod napisano dokładnie w ten sposób | co dokładnie robi ta funkcja – jak API |
| Widoczne z zewnątrz? | nie, tylko w źródle | tak, przez help() i __doc__ |
help() pokazuje docstring podczas działania programu
help_primer.py
help(rectangle_area)
print(rectangle_area.__doc__)Help on function rectangle_area in module __main__:
rectangle_area(width, height)
Возвращает площадь прямоугольника.Type hints - Wskazówki typu
type_hints.py
def rectangle_area(width: float, height: float) -> float:
return width * height| Część | Znaczenie |
|---|---|
width: float | oczekiwany typ parametru |
-> float | oczekiwany typ zwrotu |
Wskazówki typu nie są automatycznie sprawdzane w czasie działania
def add(a: int, b: int) -> int: NIE zaszkodzi zadzwonić add("2", "3") — Python nie będzie automatycznie zamieniać linii na liczby i samo z siebie nie wygeneruje błędu. Adnotacje typów to dokumentacja i wskazówka dla narzędzi programistycznych, a nie runtime-sprawdzenie.Adnotacje do kolekcji
annotacii_kollekcij.py
def average(scores: list[float]) -> float:
return sum(scores) / len(scores)
def count_words(text: str) -> dict[str, int]:
...Wartość opcjonalna w adnotacji
optional_annotation.py
def find_user(name: str) -> str | None:
...str | None czyta się jako „łańcuch znaków lub None”
Taka adnotacja mówi: funkcja albo zwróci łańcuch znaków, albo
Nonejeśli nic nie zostanie znalezione. To nie jest osobny temat, a jedynie sposób na wyraźne opisanie słowami tego, co już widzieliśmy w praktyce (np. dict.get()).Adnotacje nie nadpisują domyślnej pułapki mutowalnej
annotacii_ne_spasayut.py
def add(item: str, items: list[str] = []):
...
# wciąż ta sama pułapka z §13.7!Adnotacje typów są dokumentacją, a nie ochroną przed błędami w czasie wykonywania
Nawet z pełnymi adnotacjami
items: list[str] = [] pozostaje tą samą zmienną wartością domyślną co wcześniej — adnotacja nie zmienia nic w rzeczywistym zachowaniu funkcji.Praktyka: docstringi i wskazówki typów
interaktywny laptop bezpośrednio w przeglądarce – Python 3.14 przez Pyodide, bez instalacji