Adnotacje (Python3)

PEP 3107 - Function Annotations

PEP 526 - Syntax for Variable Annotations

https://docs.python.org/3/howto/annotations.html
Annotations Best Practices. Najlepsze praktyki dostępu do adnotacji zależą od wersji Pythona, ze względu na ciągły rozwój nowych narzędzi.

https://docs.python.org/3/library/inspect.html
'inspect' - Inspect live objects [Py3.5+]. There are four main kinds of services provided by this module: type checking, getting source code, inspecting classes and functions, and examining the interpreter stack. inspect.get_annotations() [Py3.10+].

https://docs.python.org/3/library/typing.html
'typing' - Support for type hints [Py3.5+]. Tu jest podana lista odpowiednich PEPs.

ADNOTACJE FUNKCJI

Argumenty funkcji mogą mieć adnotacje (annotations) postaci ': expression', następującą po nazwie parametru. Podobnie może być dla parametrów postaci *identifier lub **identifier. Funkcje mogą mieć również adnotację 'return' postaci '-> expression', która następuje po liście parametrów. Jest to składnia do dołączania do funkcji dodatkowych informacji (metadata) dotyczących parametrów i wartości zwracanych. Jest to mechanizm całkowicie opcjonalny. W Pythonie 2 można było tylko w docstringu coś dopowiedzieć.

Wartości adnotacji są dostępne jako wartości słownika '__annotations__', gdzie kluczami są nazwy argumentów funkcji (string).

# Syntax.

def nazwa_funkcji(arg1: wyrażenie, arg2: wyrażenie = wartość) -> wyrażenie:
   instrukcje

def nazwa_funkcji(*arguments: wyrażenie, **keywords: wyrażenie = wartość) -> wyrażenie:
   instrukcje

# Adnotacje funkcji są zwykle używane jako podpowiedzi dla typów.

def sum_two_numbers(a: int, b: float) -> complex:
   return a + b

sum_two_numbers.__annotations__
# {'a': <class 'int'>, 'b': <class 'float'>, 'return': <class 'complex'>}

# https://stackoverflow.com/questions/14379753/what-does-mean-in-python-function-definitions

def kinetic_energy(m:'in kg', v:'in m/s')->'Joules': 
    return 0.5 * m * v**2
# dictionary kinetic_energy.__annotations__
# {'return': 'Joules', 'v': 'in m/s', 'm': 'in kg'}

ADNOTACJE ZMIENNYCH

# Podczas użycia adnotacji zmiennej lub atrybutu klasy
# może wystąpić podstawienie wartości.

class C:
    field: 'annotation'   #  adnotacja atrybutu klasy

# Adnotacje zmiennych są zwykle używane jako podpowiedzi do typów.
import typing

count: int = 0   # adnotacja zmiennej i podstawienie

some_list: typing.List[int] = [3, 5]
some_list: list[int] = [3, 5]   # Py3.9+

some_dict: typing.Dict[str, float] = {"a": 1.2}
some_dict: dict[str, float] = {"a": 1.2}   # Py3.9+

coords: typing.Tuple[int, float] = (12, 3.4)
coords: tuple[int, float] = (12, 3.4)   # Py3.9+

Podpowiedzi do typów są opcjonalne i nie są wymuszane w Pythonie. Bywają przydatne dla narzędzi do statycznej analizy typów.