Kurs Python · Moduł 3: Programowanie obiektowe

Type hints - precyzyjna klasyfikacja

14 min czytania ·
W tej lekcji10

Witaj ponownie! Tu Darwin, dziś lekcja o precyzji i dokumentowaniu kodu.

W biologii precyzyjna klasyfikacja jest kluczowa - "duże zwierzę" to nie to samo co "Panthera leo (lew afrykański), samiec, dorosły, 190kg". W Pythonie type hints (adnotacje typów) pozwalają na taką samą precyzję w kodzie!

# Nieprecyzyjne - co to jest?
def count_animals(animals):
    return len(animals)

# Precyzyjne - wiadomo co i dlaczego!
def count_animals(animals: list[str]) -> int:
    """Zlicz zwierzęta w liście"""
    return len(animals)

Czym są type hints?

Type hints to adnotacje typów w Pythonie - dodatkowe informacje o typach zmiennych, parametrów funkcji i wartości zwracanych.

WAŻNE: Type hints są opcjonalne i NIE wpływają na działanie programu! Python je ignoruje podczas wykonywania kodu. Służą:

  • Dokumentacji - wyjaśniają intencje programisty
  • IDE - lepsze podpowiedzi i autouzupełnianie
  • Narzędziom - mypy, pyright mogą wykrywać błędy typów
  • Czytelności - łatwiej zrozumieć kod
# Bez type hints - musimy zgadywać
def calculate_density(count, area):
    return count / area

# Z type hints - wszystko jasne!
def calculate_density(count: int, area: float) -> float:
    """Oblicz gęstość populacji (osobniki/km²)"""
    return count / area

Podstawowe type hints

Zmienne

Adnotację zmiennej zapisujesz po dwukropku, między nazwą a znakiem =. Przy kontenerach możesz w nawiasach kwadratowych podać też typ elementów:

# Podstawowe typy
name: str = "Lew"
age: int = 5
weight: float = 190.5
is_dangerous: bool = True

# Same typy kontenerów (bez typów elementów)
animals: list = ["Lew", "Słoń"]
habitat_map: dict = {"Lew": "sawanna"}

# Python 3.9+ - jeszcze lepiej z typami elementów
animals: list[str] = ["Lew", "Słoń", "Żyrafa"]
populations: dict[str, int] = {"Lew": 500, "Słoń": 300}
coordinates: tuple[float, float] = (51.5, -0.1)
unique_species: set[str] = {"Lew", "Słoń"}

Funkcje - parametry i typ zwracany

W funkcji typ każdego parametru zapisujesz po dwukropku, a typ wyniku po strzałce ->, przed końcowym dwukropkiem:

def greet(name: str) -> str:
    """Przyjmuje str, zwraca str"""
    return f"Witaj, {name}!"

def add_numbers(a: int, b: int) -> int:
    """Przyjmuje dwa inty, zwraca int"""
    return a + b

def calculate_average(numbers: list[float]) -> float:
    """Przyjmuje listę floatów, zwraca float"""
    return sum(numbers) / len(numbers)

def print_info(message: str) -> None:
    """None oznacza "nic nie zwraca" """
    print(message)
    # brak return lub return None

Typy z modułu typing

Optional - może być None

Optional[str] mówi, że funkcja zwraca tekst albo None. Przydaje się przy wyszukiwaniu, które może niczego nie znaleźć:

from typing import Optional

def find_species(name: str) -> Optional[str]:
    """
    Zwraca gatunek lub None jeśli nie znaleziono

    Optional[str] = str | None
    """
    database = {"Lew": "Panthera leo", "Słoń": "Loxodonta africana"}
    return database.get(name)  # Może zwrócić str albo None

result = find_species("Lew")  # Optional[str]
if result is not None:
    print(f"Znaleziono: {result}")

Union - jeden z kilku typów

Union wymienia kilka dozwolonych typów. Identyfikator zwierzęcia może być liczbą albo tekstem:

from typing import Union

def process_id(animal_id: Union[int, str]) -> str:
    """
    Przyjmuje int LUB str

    Python 3.10+: int | str
    """
    return f"ID: {animal_id}"

process_id(123)       # OK - int
process_id("LEO-45")  # OK - str

Python 3.10+: Możesz użyć | zamiast Union!

def process_id(animal_id: int | str) -> str:
    """Nowsza składnia - Python 3.10+"""
    return f"ID: {animal_id}"

# Optional też można zapisać krócej
def find_species(name: str) -> str | None:
    """str | None = Optional[str]"""
    pass

List, Dict, Tuple, Set - z konkretnymi typami

Wbudowane kontenery przyjmują w nawiasach kwadratowych typy elementów. Krotka może mieć stałą liczbę pozycji albo dowolną, zapisaną jako ...:

# Python 3.9+ - używaj małych liter!
def process_animals(names: list[str]) -> dict[str, int]:
    """Lista stringów → słownik string:int"""
    return {name: len(name) for name in names}

# Tuple - stała liczba elementów z określonymi typami
def get_coordinates() -> tuple[float, float]:
    """Zwraca (latitude, longitude)"""
    return (51.5074, -0.1278)

# Tuple - zmienna liczba elementów tego samego typu
def get_observations() -> tuple[int, ...]:
    """Tuple z dowolną liczbą intów"""
    return (12, 45, 23, 67, 89)

# Set
def get_unique_habitats() -> set[str]:
    """Zbiór unikalnych siedlisk"""
    return {"sawanna", "dżungla", "góry"}

Any - dowolny typ

Any oznacza, że wartość może mieć dowolny typ, więc narzędzia przestają ją sprawdzać:

from typing import Any

def log_data(data: Any) -> None:
    """Przyjmuje cokolwiek - używaj oszczędnie!"""
    print(f"Logging: {data}")

log_data(123)           # OK
log_data("text")        # OK
log_data([1, 2, 3])     # OK
log_data({"key": "val"})  # OK

Uwaga: Używaj Any tylko gdy naprawdę akceptujesz dowolny typ! To jak rezygnacja z type hints.

Type hints dla klas

W klasie adnotacje dopisujesz do atrybutów klasowych, do parametrów __init__ i metod oraz do atrybutów instancji. Nazwę klasy, której Python jeszcze nie zna, podajesz w cudzysłowie, np. 'Species':

class Species:
    """Gatunek z type hints"""

    # Atrybuty klasowe
    kingdom: str = "Animalia"
    all_species: list['Species'] = []  # Forward reference

    def __init__(
        self,
        scientific_name: str,
        common_name: str,
        population: int,
        endangered: bool = False
    ) -> None:
        """Konstruktor z type hints"""
        self.scientific_name: str = scientific_name
        self.common_name: str = common_name
        self.population: int = population
        self.endangered: bool = endangered
        self.observations: list[dict[str, Any]] = []

        Species.all_species.append(self)

    def add_observation(
        self,
        location: str,
        count: int,
        date: str | None = None
    ) -> None:
        """Dodaj obserwację - zwraca None"""
        obs: dict[str, str | int] = {
            "location": location,
            "count": count
        }
        if date:
            obs["date"] = date
        self.observations.append(obs)

    def get_population_trend(self) -> float:
        """Zwraca float"""
        if len(self.observations) < 2:
            return 0.0

        first = self.observations[0]["count"]
        last = self.observations[-1]["count"]
        return (last - first) / first * 100

    @classmethod
    def get_endangered_species(cls) -> list['Species']:
        """Zwraca listę Species - forward reference!"""
        return [s for s in cls.all_species if s.endangered]

    @staticmethod
    def is_valid_population(pop: int) -> bool:
        """Zwraca bool"""
        return pop >= 0

Zaawansowane type hints

Callable - funkcje jako typy

Gdy parametr jest funkcją, Callable[[Species], bool] opisuje, co ta funkcja przyjmuje i co zwraca:

from typing import Callable

def apply_filter(
    species_list: list[Species],
    filter_func: Callable[[Species], bool]
) -> list[Species]:
    """
    Filtruj listę przez funkcję

    Callable[[Species], bool] = funkcja przyjmująca Species, zwracająca bool
    """
    return [s for s in species_list if filter_func(s)]

# Użycie
def is_endangered(species: Species) -> bool:
    return species.endangered

endangered = apply_filter(Species.all_species, is_endangered)

TypeAlias - aliasy dla złożonych typów

Długi typ możesz nazwać raz i używać tej nazwy w wielu miejscach. Taki alias tworzysz z adnotacją TypeAlias:

from typing import TypeAlias

# Alias dla czytelności
PopulationData: TypeAlias = dict[str, list[int]]
Coordinates: TypeAlias = tuple[float, float]
SpeciesDict: TypeAlias = dict[str, Species]

def analyze_populations(data: PopulationData) -> float:
    """Typ PopulationData jest bardziej czytelny niż dict[str, list[int]]"""
    all_counts: list[int] = []
    for counts in data.values():
        all_counts.extend(counts)
    return sum(all_counts) / len(all_counts)

def get_location(name: str) -> Coordinates:
    """Coordinates jasno określa co zwracamy"""
    locations: dict[str, Coordinates] = {
        "Serengeti": (-2.3333, 34.8333),
        "Masai Mara": (-1.5, 35.1667)
    }
    return locations.get(name, (0.0, 0.0))

Generic - klasy generyczne

Klasa generyczna dostaje typ elementów jako parametr, tak jak list[str]. Ten sam stos może przechowywać napisy albo liczby, a IDE i tak wie, co z niego wyjmiesz:

from typing import Generic, TypeVar

T = TypeVar('T')  # Typ generyczny

class Stack(Generic[T]):
    """Stos generyczny - może przechowywać dowolny typ"""

    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        """Dodaj element typu T"""
        self._items.append(item)

    def pop(self) -> T:
        """Usuń i zwróć element typu T"""
        return self._items.pop()

    def is_empty(self) -> bool:
        return len(self._items) == 0

# Użycie
string_stack: Stack[str] = Stack[str]()
string_stack.push("Lew")
string_stack.push("Słoń")
animal: str = string_stack.pop()  # IDE wie, że to str!

int_stack: Stack[int] = Stack[int]()
int_stack.push(123)
int_stack.push(456)
number: int = int_stack.pop()  # IDE wie, że to int!

Przykład z safari - kompletny system z type hints

Teraz wszystko razem: aliasy typów, enumy dla statusu ochrony i siedliska, klasa z adnotacjami w każdej metodzie oraz funkcje pomocnicze, które z niej korzystają.

from typing import Optional, TypeAlias
from datetime import date
from enum import Enum

# === TYPE ALIASES ===

SpeciesID: TypeAlias = str
Coordinates: TypeAlias = tuple[float, float]
ObservationData: TypeAlias = dict[str, str | int | date]

# === ENUMS ===

class ConservationStatus(Enum):
    """Status ochrony gatunku"""
    EXTINCT = "extinct"
    EXTINCT_IN_WILD = "extinct_in_wild"
    CRITICALLY_ENDANGERED = "critically_endangered"
    ENDANGERED = "endangered"
    VULNERABLE = "vulnerable"
    NEAR_THREATENED = "near_threatened"
    LEAST_CONCERN = "least_concern"

class Habitat(Enum):
    """Typ siedliska"""
    SAVANNA = "sawanna"
    JUNGLE = "dżungla"
    MOUNTAINS = "góry"
    DESERT = "pustynia"
    WETLANDS = "mokradła"

# === MAIN CLASS ===

class Species:
    """
    Klasa gatunku z pełnymi type hints

    Precyzyjna klasyfikacja jak w biologii!
    """

    # Atrybut klasowy
    _registry: dict[SpeciesID, 'Species'] = {}

    def __init__(
        self,
        scientific_name: str,
        common_name: str,
        population: int,
        habitat: Habitat,
        status: ConservationStatus,
        dangerous: bool = False
    ) -> None:
        """
        Inicjalizacja gatunku

        Args:
            scientific_name: Nazwa naukowa (np. "Panthera leo")
            common_name: Nazwa zwyczajowa (np. "Lew")
            population: Liczba osobników
            habitat: Typ siedliska (enum)
            status: Status ochrony (enum)
            dangerous: Czy niebezpieczny dla ludzi
        """
        self.id: SpeciesID = scientific_name
        self.scientific_name: str = scientific_name
        self.common_name: str = common_name
        self.population: int = population
        self.habitat: Habitat = habitat
        self.status: ConservationStatus = status
        self.dangerous: bool = dangerous

        # Lista obserwacji
        self.observations: list[ObservationData] = []

        # Lokalizacje
        self.locations: set[Coordinates] = set()

        # Rejestruj
        Species._registry[self.id] = self

    def add_observation(
        self,
        location: str,
        coordinates: Coordinates,
        count: int,
        observation_date: date | None = None
    ) -> None:
        """
        Dodaj obserwację gatunku

        Args:
            location: Nazwa lokalizacji
            coordinates: (latitude, longitude)
            count: Liczba zaobserwowanych osobników
            observation_date: Data obserwacji (opcjonalna)
        """
        obs: ObservationData = {
            "location": location,
            "count": count,
            "date": observation_date or date.today()
        }
        self.observations.append(obs)
        self.locations.add(coordinates)

    def get_total_observed(self) -> int:
        """Zwróć łączną liczbę zaobserwowanych osobników"""
        return sum(
            int(obs["count"])
            for obs in self.observations
        )

    def get_observation_locations(self) -> list[str]:
        """Zwróć listę unikalnych lokalizacji obserwacji"""
        locations: set[str] = {
            str(obs["location"])
            for obs in self.observations
        }
        return sorted(locations)

    def is_threatened(self) -> bool:
        """Sprawdź czy gatunek jest zagrożony"""
        threatened_statuses: set[ConservationStatus] = {
            ConservationStatus.CRITICALLY_ENDANGERED,
            ConservationStatus.ENDANGERED,
            ConservationStatus.VULNERABLE
        }
        return self.status in threatened_statuses

    def get_risk_assessment(self) -> dict[str, str | int | bool]:
        """
        Ocena ryzyka dla ekspedycji

        Returns:
            Słownik z oceną ryzyka
        """
        risk_level: int = 0

        if self.dangerous:
            risk_level += 5

        if self.population < 100:
            risk_level += 3  # Rzadkie - trudne do znalezienia

        if self.habitat == Habitat.JUNGLE:
            risk_level += 2  # Trudny teren

        return {
            "species": self.common_name,
            "risk_level": min(10, risk_level),
            "dangerous": self.dangerous,
            "rare": self.population < 100,
            "recommendation": "Extreme caution" if risk_level >= 7 else "Normal protocol"
        }

    @classmethod
    def get_by_id(cls, species_id: SpeciesID) -> Optional['Species']:
        """
        Znajdź gatunek po ID

        Returns:
            Species lub None jeśli nie znaleziono
        """
        return cls._registry.get(species_id)

    @classmethod
    def get_by_habitat(cls, habitat: Habitat) -> list['Species']:
        """Zwróć wszystkie gatunki z danego siedliska"""
        return [
            species for species in cls._registry.values()
            if species.habitat == habitat
        ]

    @classmethod
    def get_endangered(cls) -> list['Species']:
        """Zwróć wszystkie zagrożone gatunki"""
        return [
            species for species in cls._registry.values()
            if species.is_threatened()
        ]

    @staticmethod
    def calculate_biodiversity_index(
        species_list: list['Species']
    ) -> float:
        """
        Oblicz indeks bioróżnorodności Simpsona

        Args:
            species_list: Lista gatunków do analizy

        Returns:
            Indeks (0.0 - 1.0, wyższy = większa różnorodność)
        """
        if not species_list:
            return 0.0

        total: int = sum(s.population for s in species_list)
        if total == 0:
            return 0.0

        sum_squares: float = sum(
            (s.population / total) ** 2
            for s in species_list
        )

        return 1.0 - sum_squares

    def __str__(self) -> str:
        return f"{self.common_name} ({self.population} osobników)"

    def __repr__(self) -> str:
        return (f"Species(scientific_name='{self.scientific_name}', "
                f"population={self.population}, "
                f"habitat={self.habitat.value})")

# === FUNKCJE POMOCNICZE ===

def generate_report(species: Species) -> str:
    """
    Wygeneruj raport o gatunku

    Args:
        species: Gatunek do raportu

    Returns:
        Sformatowany raport tekstowy
    """
    threatened: str = "TAK" if species.is_threatened() else "Nie"
    risk: dict[str, str | int | bool] = species.get_risk_assessment()

    report: str = f"""
╔══════════════════════════════════════════════════╗
  {species.common_name.upper()}
╠══════════════════════════════════════════════════╣
  Nazwa naukowa: {species.scientific_name}
  Populacja: {species.population} osobników
  Siedlisko: {species.habitat.value}
  Status: {species.status.value}
  Zagrożony: {threatened}
  Niebezpieczny: {"TAK" if species.dangerous else "Nie"}
  Poziom ryzyka: {risk['risk_level']}/10
  Obserwacje: {len(species.observations)}
  Lokalizacje: {', '.join(species.get_observation_locations()) or 'Brak'}
╚══════════════════════════════════════════════════╝
    """.strip()

    return report

def filter_by_population(
    species_list: list[Species],
    min_pop: int,
    max_pop: int | None = None
) -> list[Species]:
    """
    Filtruj gatunki po populacji

    Args:
        species_list: Lista gatunków
        min_pop: Minimalna populacja
        max_pop: Maksymalna populacja (opcjonalna)

    Returns:
        Przefiltrowana lista
    """
    filtered: list[Species] = [
        s for s in species_list
        if s.population >= min_pop
    ]

    if max_pop is not None:
        filtered = [s for s in filtered if s.population <= max_pop]

    return filtered

# === DEMONSTRACJA ===

print("=== KATALOG GATUNKÓW Z TYPE HINTS ===\n")

# Tworzenie gatunków
lion = Species(
    scientific_name="Panthera leo",
    common_name="Lew",
    population=120,
    habitat=Habitat.SAVANNA,
    status=ConservationStatus.VULNERABLE,
    dangerous=True
)

rhino = Species(
    scientific_name="Diceros bicornis",
    common_name="Nosorożec czarny",
    population=45,
    habitat=Habitat.SAVANNA,
    status=ConservationStatus.CRITICALLY_ENDANGERED,
    dangerous=True
)

elephant = Species(
    scientific_name="Loxodonta africana",
    common_name="Słoń afrykański",
    population=450,
    habitat=Habitat.SAVANNA,
    status=ConservationStatus.ENDANGERED,
    dangerous=False
)

# Dodaj obserwacje
lion.add_observation("Serengeti", (-2.3333, 34.8333), 12)
lion.add_observation("Masai Mara", (-1.5, 35.1667), 8)
rhino.add_observation("Ngorongoro", (-3.1792, 35.5500), 3)
elephant.add_observation("Amboseli", (-2.6527, 37.2606), 35)

# Raporty
print(generate_report(lion))
print()
print(generate_report(rhino))

# Filtrowanie
print("\n=== GATUNKI ZAGROŻONE ===")
endangered: list[Species] = Species.get_endangered()
for species in endangered:
    print(f"   {species.common_name}: {species.status.value}")

# Filtrowanie po populacji
print("\n=== GATUNKI Z POPULACJĄ < 100 ===")
rare: list[Species] = filter_by_population(
    list(Species._registry.values()),
    min_pop=0,
    max_pop=99
)
for species in rare:
    print(f"  - {species.common_name}: {species.population} osobników")

# Indeks bioróżnorodności
biodiversity: float = Species.calculate_biodiversity_index(
    list(Species._registry.values())
)
print(f"\nIndeks bioróżnorodności: {biodiversity:.3f}")

Narzędzia do sprawdzania typów

mypy - statyczne sprawdzanie typów

Narzędzie mypy czyta adnotacje i sprawdza typy, zanim uruchomisz program. Instalujesz je przez pip i wskazujesz plik do sprawdzenia:

# Instalacja
pip install mypy

# Sprawdź plik
mypy script.py

Python uruchomi ten kod bez błędu, ale mypy go zatrzyma:

def add(a: int, b: int) -> int:
    return a + b

result: str = add(5, 10)  # mypy: Incompatible types in assignment

Funkcja zwraca int, a zmienna ma zadeklarowany typ str. Python nie sprawdza adnotacji podczas działania programu, więc taki błąd wychwyci dopiero mypy albo edytor.

Sprawdzanie typów w IDE

Nowoczesne IDE (VS Code, PyCharm) automatycznie sprawdzają type hints:

  • Autouzupełnianie - podpowiedzi bazują na typach
  • Wykrywanie błędów - niezgodne typy widać jeszcze przed uruchomieniem
  • Refaktoryzacja - bezpieczniejsze zmiany
  • Dokumentacja - szybki podgląd sygnatur

Dobre praktyki type hints

1. Zawsze dodawaj type hints do publicznych API

Metody, z których korzysta reszta programu, to umowa z innymi programistami. Adnotacje od razu mówią, czego te metody oczekują i co zwracają:

# Dobre - API publiczne z type hints
class Species:
    def add_observation(self, location: str, count: int) -> None:
        pass

# Złe - publiczne API bez typów
class Species:
    def add_observation(self, location, count):
        pass

2. Używaj konkretnych typów zamiast Any

Any niczego nie mówi czytelnikowi i niczego nie sprawdza. Jeśli wiesz, jakie dane przychodzą, zapisz to w adnotacji:

# Złe - zbyt ogólne
def process_data(data: Any) -> Any:
    return data

# Dobre - konkretne typy
def process_data(data: dict[str, int]) -> list[int]:
    return list(data.values())

3. Używaj Optional dla wartości None

Jeśli funkcja może zwrócić None, napisz to w adnotacji. Wtedy każdy, kto ją wywoła, wie, że musi sprawdzić wynik:

# Dobre - jasno określone
def find_species(name: str) -> Species | None:
    pass

# Mylące - czy zwraca None?
def find_species(name: str) -> Species:
    pass

4. Dokumentuj złożone typy przez TypeAlias

Gdy ten sam złożony typ pojawia się w kilku miejscach, nadaj mu nazwę. Sygnatura funkcji robi się krótsza i od razu widać, co oznacza:

# Czytelne
ObservationData: TypeAlias = dict[str, str | int | date]

def add_observation(data: ObservationData) -> None:
    pass

# Nieczytelne
def add_observation(data: dict[str, str | int | date]) -> None:
    pass

Podsumowanie

W tej lekcji nauczyłeś/aś się:

  • Czym są type hints i po co ich używać
  • Podstawowych adnotacji: int, str, float, bool, list, dict
  • Optional i Union (oraz składni | w Pythonie 3.10+)
  • Type hints dla funkcji (parametry i typy zwracane)
  • Type hints dla klas i metod
  • Zaawansowanych technik: Callable, TypeAlias, Generic
  • Enumów dla bezpiecznych wartości
  • Narzędzi jak mypy
  • Dobrych praktyk type hints

Checkpoint

Przed przejściem dalej:

  • Rozumiesz różnicę między type hints a runtime behavior
  • Potrafisz dodać type hints do funkcji
  • Znasz Optional i Union (oraz |)
  • Wiesz jak używać list[T], dict[K, V]
  • Rozumiesz TypeAlias i Generic

Analogia Safari: Type hints to precyzyjna klasyfikacja biologiczna - zamiast "duży kot" mówimy "Panthera leo, samiec, 5 lat, 190kg" - wszystko jasne!

W następnej lekcji Darwin nauczy Cię dekoratorów - potężnego narzędzia do modyfikowania zachowań funkcji i klas!

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Type hints w Pythonie są:

  2. 2. Jak oznaczyć typ zwracany funkcji?

Zadania praktyczne w grze

  • Układanie w pionie

    Uporządkuj typowe elementy definicji klasy:

  • Edytor kodu

    Stwórz klasę Animal z type hints: name: str, age: int, weight: float

  • Układanie w poziomie

    Ułóż nagłówek metody speak, która zwraca tekst (adnotacja typu str):

  1. PytanieType hints
  2. PytanieReturn type hint
  3. Ułóż w kolejnościMetody klasy - kolejność definicji
  4. Zadanie z kodemType hints w klasie
  5. Ułóż w kolejnościType hint

Przydatne artykuły