Conas a oibríonn type hints agus cad iad na buntáistí atá orthu?

Question

Accepted Answer

**Type hints** (PEP 484+) a bhaineann leat a chur in iúl na cineálacha ionchasaithe na guthanna, pharaméadair fheidhm, agus luachanna tuairisce. Tá siad **roghnach** agus **gan a bhith á fhorfheidhmniú ag an am rite** — déanann Python neamhshuim orthu agus á reáchtáil — ach tugann siad cumhacht don anailís statach, fearr tooling, agus soiléir a chóid.

## Gnáth-chomhréir

```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}
```

An `: type` a chur in iúl na bharaméadair/athróga agus `-> type` an tuairisceáin. Tugann siad doiciméad intinn agus déantar iad a sheiceáil ag uirlisí, ach déanann Python **gan** iad a chur i bhfeidhm ag an am rite (ní thaidhfidh sé earráid a chaitheamh ar a dhroim má chuireann tú cineál mícheart isteach).

## Tógálacha tipiciúla an cineáil

```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
```

## Seiceáil statacha cineálacha bailí roimh rite

```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
```

Gach uirlís seiceála cineáil ar nós **mypy** nó **pyright** agus anailís ar na nod agus tuairiscí earráidí cineáil *roimh* a reáchtáil do an chóid — ag gealadh ar dhóigheanna ar fad na earráidí (cineál droch-arguiminte, mísúil None) tapa, cosúil le traslatóir a dhéanfadh.

## Na buntáistí

```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)
```

## Tá siad roghnach agus mall

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

## Ag úsáid fhraithí a bhreacann ar iad ag an am rite

```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
```

Léann cuid leabharlann (Pydantic, FastAPI) na nod cineáil agus fíor-bhail ar an sonraí agus scríobh doiciméid — dhéanfaidh siad go bhfuil an brí gníomhachtúil ag an am rite.

## Cén fáth a bhíonn sé tábhachtach

Tabhairt isteach type hints go leor buntáistí de thaibhsíonn statacha go Python gan a bheith ag tabhairt suas a leith-fhiúntas: gealadh ar nós earráidí bhaineann le cineál go tapa (trí mypy/pyright), feabhas ar thúr an IDE agus athfhocail-iomlánú, fóinse-dhoiciméadúchán a bheo, agus cumhacht ar bhonneagar nua-aimseartha (FastAPI, Pydantic) a bhaint úsáide as siúd le haghaidh bailíochtú agus cruthú doiciméid--an-uachtar. Ar a laghad roghnach agus gan a bhith á fhorfheidhmniú ag Python féin ag an am rite, tá siad ina gnáthamh i gcodanna gealadh agus ollmhór Python toisc go ndéanann siad an chóid níos darbha geal, intuigthe, agus fhéindhoiciméid—gealadh go bhfuil sé ina dhúil iontu go fóill tráth a fhéachaint ar thionscnamh a bhárra.