# ADR-0003 - Avoid introducing Groovy types to public API

## Status

- ACCEPTED on 2024-01-12

## Context

Gradle's public API requires equal access from all JVM-based languages.
Kotlin, Groovy, Java, and other JVM-based languages should be able to use the Gradle API without relying on another language's standard library.

Historically, Gradle has shipped with some Groovy types in very prominent APIs.

import types
from collections.abc import Callable
from enum import Enum
from typing import Any, TypeVar, Union

from pydantic import BaseModel
from pydantic.main import IncEx as IncEx

DecoratedCallable = TypeVar("DecoratedCallable", bound=Callable[..., Any])
UnionType = getattr(types, "UnionType", Union)
ModelNameMap = dict[type[BaseModel] | type[Enum], str]

    print(data)
```

### Generic types { #generic-types }

Some types can take "type parameters" in square brackets, to define their internal types, for example a "list of strings" would be declared `list[str]`.

These types that can take type parameters are called **Generic types** or **Generics**.

You can use the same builtin types as generics (with square brackets and types inside):

* `list`
* `tuple`
* `set`

在同樣的地方，你按 `Ctrl+Space` 嘗試自動完成，然後你會看到：

<img src="/img/python-types/image02.png">

有了這些，你可以往下捲動查看選項，直到找到一個「看起來眼熟」的：

<img src="/img/python-types/image03.png">

## 更多動機 { #more-motivation }

看這個函式，它已經有型別提示了：

{* ../../docs_src/python_types/tutorial003_py310.py hl[1] *}

因為編輯器知道變數的型別，你不只會得到自動完成，還會得到錯誤檢查：

<img src="/img/python-types/image04.png">

現在你知道要修正它，把 `age` 用 `str(age)` 轉成字串：

在同样的位置，你用 `Ctrl+Space` 触发自动补全，就能看到：

<img src="/img/python-types/image02.png">

这样，你可以滚动查看选项，直到找到那个“看着眼熟”的：

<img src="/img/python-types/image03.png">

## 更多动机 { #more-motivation }

看这个已经带有类型提示的函数：

{* ../../docs_src/python_types/tutorial003_py310.py hl[1] *}

因为编辑器知道变量的类型，你不仅能得到补全，还能获得错误检查：

<img src="/img/python-types/image04.png">

现在你知道需要修复它，用 `str(age)` 把 `age` 转成字符串：

<img src="/img/python-types/image02.png">

これであれば、あなたは「ベルを鳴らす」ものを見つけるまで、オプションを見てスクロールできます:

<img src="/img/python-types/image03.png">

## より強い動機 { #more-motivation }

この関数を見てください。すでに型ヒントを持っています:

{* ../../docs_src/python_types/tutorial003_py310.py hl[1] *}

エディタは変数の型を知っているので、補完だけでなく、エラーチェックをすることもできます:

<img src="/img/python-types/image04.png">

# Advanced Python Types { #advanced-python-types }

Here are some additional ideas that might be useful when working with Python types.

## Using `Union` or `Optional` { #using-union-or-optional }

If your code for some reason can't use `|`, for example if it's not in a type annotation but in something like `response_model=`, instead of using the vertical bar (`|`) you can use `Union` from `typing`.

Escribes el primer parámetro de la función, `first_name`, luego un punto (`.`) y luego presionas `Ctrl+Espacio` para activar el autocompletado.

Pero, tristemente, no obtienes nada útil:

<img src="/img/python-types/image01.png">

### Añadir tipos { #add-types }

Modifiquemos una sola línea de la versión anterior.

Cambiaremos exactamente este fragmento, los parámetros de la función, de:

```Python
    first_name, last_name
```

a:

Mas, infelizmente, você não obtém nada útil:

<img src="/img/python-types/image01.png">

### Adicionar tipos { #add-types }

Vamos modificar uma única linha da versão anterior.

Vamos mudar exatamente esse fragmento, os parâmetros da função, de:

```Python
    first_name, last_name
```

para:

Up to now, you have been using common data types, like:

* `int`
* `float`
* `str`
* `bool`

But you can also use more complex data types.

And you will still have the same features as seen up to now:

* Great editor support.
* Data conversion from incoming requests.
* Data conversion for response data.
* Data validation.
* Automatic annotation and documentation.