# 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.

# Python Types Intro { #python-types-intro }

Python has support for optional "type hints" (also called "type annotations").

These **"type hints"** or annotations are a special syntax that allow declaring the <dfn title="for example: str, int, float, bool">type</dfn> of a variable.

By declaring types for your variables, editors and tools can give you better support.

在同樣的地方，你按 `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">

# Introducción a Tipos en Python { #python-types-intro }

Python tiene soporte para "anotaciones de tipos" opcionales (también llamadas "type hints").

Estas **"anotaciones de tipos"** o type hints son una sintaxis especial que permite declarar el <dfn title="por ejemplo: str, int, float, bool">tipo</dfn> de una variable.

Al declarar tipos para tus variables, los editores y herramientas te pueden proporcionar un mejor soporte.

O Python possui suporte para "type hints" opcionais (também chamados de "type annotations").

Esses **"type hints"** ou anotações são uma sintaxe especial que permite declarar o <dfn title="por exemplo: str, int, float, bool">tipo</dfn> de uma variável.

Ao declarar tipos para suas variáveis, editores e ferramentas podem oferecer um melhor suporte.

* You can check all the valid Pydantic data types here: [Pydantic data types](https://docs.pydantic.dev/latest/usage/types/types/).

## Example { #example }

Here's an example *path operation* with parameters using some of the above types.

{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *}

    * 在请求和响应中被当作 `str` 处理。
    * 生成的模式将指定这个 `str` 是 `binary` "格式"。
* `Decimal`:
    * 标准的 Python `Decimal`。
    * 在请求和响应中被当做 `float` 一样处理。
* 您可以在这里检查所有有效的 Pydantic 数据类型: [Pydantic data types](https://docs.pydantic.dev/latest/usage/types/types/)。

## 例子 { #example }

下面是一个*路径操作*的示例，其中的参数使用了上面的一些类型。

{* ../../docs_src/extra_data_types/tutorial001_an_py310.py hl[1,3,12:16] *}

注意，函数内的参数有原生的数据类型，你可以，例如，执行正常的日期操作，如:

# 額外的資料型別 { #extra-data-types }

到目前為止，你一直在使用常見的資料型別，例如：

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

但你也可以使用更複雜的資料型別。

而且你仍然會擁有目前為止所見的同樣功能：

* 極佳的編輯器支援。
* 將傳入請求的資料轉換。
* 回應資料的轉換。
* 資料驗證。
* 自動產生註解與文件。

## 其他資料型別 { #other-data-types }

以下是你可以使用的一些其他資料型別：

* `UUID`：
    * 一種標準的「通用唯一識別碼 (Universally Unique Identifier)」，常見於許多資料庫與系統的 ID。
    * 在請求與回應中會以 `str` 表示。
* `datetime.datetime`：