Si funksionojnë type hints dhe cilat janë përfitimet e tyre?

Question

Accepted Answer

**Type hints** (PEP 484+) ju lejojnë të shënoni llojet e pritshmërisë të variablave, parametrave të funksioneve dhe vlerave kthyese. Ato janë **opsionale** dhe **nuk zbatohen në kohën e ekzekutimit** — Python i injoron ato gjatë ekzekutimit — por ato mundësojnë analizën statike, pajisjet më të mira dhe kodin më të qartë.

## Sintaksa bazë

```python
def greet(name: str, times: int = 1) -> str:
    return name * times

age: int = 30
names: list[str] = ["Ann", "Bob"]
scores: dict[str, int] = {"math": 90}
```

Shënuesit `: type` shënojnë parametrat/variablat dhe `-> type` kthimin. Këto dokumentojnë qëllimin dhe kontrollohen nga mjetet, por Python **nuk** i zbaton ato në kohën e ekzekutimit (kalimi i një lloji të gabuar nuk do të ngrysë vetë).

## Konstrukte të zakonshme të typing

```python
from typing import Optional, Union, Callable, Any

def find(id: int) -> Optional[str]:    # str OR None (= str | None in 3.10+)
    ...

x: int | str                           # Union (3.10+ syntax)
handler: Callable[[int], bool]         # a function taking int, returning bool
items: list[dict[str, int]]            # nested generics
```

## Kontrollimi statik i llojeve kapin gabimet para ekzekutimit

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

add("hello", 3)   # ✅ Python runs it (and crashes); ❌ mypy/pyright flags it BEFORE running
```

Një kontrollues lloji si **mypy** ose **pyright** analizon shënimet dhe raporton gabime në lloje *para* se të ekzekutonit kodin — duke kapur një klasë të tërë gabimesh (lloje argumentesh të gabuara, keqpërdorimi i None) herët, siç do të bënte një kompajler.

## Përfitimet

```text
✓ Catch type bugs early via static checkers (mypy, pyright) — before runtime
✓ IDE support — better autocomplete, refactoring, inline error detection
✓ Self-documenting code — signatures show exactly what's expected/returned
✓ Powers frameworks — FastAPI/Pydantic USE hints for validation & docs
✓ Easier maintenance of large codebases (catch breaking changes)
```

## Ato janë opsionale dhe graduale

```text
You can add hints incrementally — a few functions, or strictly everywhere.
Unannotated code still works. "Gradual typing" suits adopting them over time.
```

## Kornizat i përdorin ato në kohën e ekzekutimit

```python
from pydantic import BaseModel
class User(BaseModel):
    name: str
    age: int            # Pydantic USES the hint to VALIDATE data at runtime
User(name="Ann", age="x")   # raises a validation error
```

Disa biblioteka (Pydantic, FastAPI) lexojnë type hints për të validuar të dhënat dhe për të gjeneruar dokumentacion — duke i bërë ato funksionalisht domethënëse në kohën e ekzekutimit.

## Pse ka rëndësi

Type hints sjellë shumë përfitime të tipizimit statik në Python pa sakrifikuar fleksibilitetin e tij dinamik: ato kapin gabime të lidhura me llojin herët (përmes mypy/pyright), përmirësojnë ndjeshëm tooling-un e IDE dhe refaktorimin, shërbejnë si dokumentacion jetues dhe fuqizojnë korniza moderne (FastAPI, Pydantic) që i përdorin ato për validim dhe dokumentacion të gjeneruar automatikisht.

Ndërsa janë opsionale dhe nuk zbatohen në kohën e ekzekutimit nga vetë Python, ato janë bërë standarde në bazat e kodit Python profesionale dhe të mëdha sepse e bëjnë kodin më të sigurt, më të lehtë për t'u mirëmbartur dhe vetëdokumentuese — gjithnjë e më shumë një praktikë e pritur, veçanërisht ndërsa projektet rriten.