Kurs Python · Moduł 3: Programowanie obiektowe
Type hints - precyzyjna klasyfikacja
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 / areaPodstawowe 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 NoneTypy 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 - strPython 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]"""
passList, 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"}) # OKUwaga: 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 >= 0Zaawansowane 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.pyPython 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 assignmentFunkcja 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):
pass2. 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:
pass4. 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:
passPodsumowanie
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. Type hints w Pythonie są:
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):