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

package loggertypes

// TargetType indicates type of the target e.g. console, http, kafka
type TargetType uint8

//go:generate stringer -type=TargetType -trimprefix=Target $GOFILE

// Constants for target types
const (
	_ TargetType = iota
	TargetConsole
	TargetHTTP
	TargetKafka
)

// TargetStats contains statistics for a target.
type TargetStats struct {

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]

~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

 ---
 Default Dependency Types
 ---
 Hervé Boutemy
 ---
 2024-04-02
 ---

Default Dependency Types Reference

  Defined in <<<DefaultTypeProvider>>>
  ({{{./apidocs/org/apache/maven/repository/internal/type/DefaultTypeProvider.html}javadoc}},

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

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.

    * 在请求和响应中被当作 `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`：

Harshavardhana <******@****.***> 1622584780 -0700

# 進階 Python 型別 { #advanced-python-types }

以下是一些在使用 Python 型別時可能有用的額外想法。

## 使用 `Union` 或 `Optional` { #using-union-or-optional }

如果你的程式碼因某些原因無法使用 `|`，例如不是在型別註記中，而是在像 `response_model=` 之類的參數位置，那麼你可以用 `typing` 中的 `Union` 來取代豎線（`|`）。

例如，你可以宣告某個值可以是 `str` 或 `None`：

```python
from typing import Union


def say_hi(name: Union[str, None]):
        print(f"Hi {name}!")
```

在 `typing` 中也有用 `Optional` 宣告某個值可以是 `None` 的速記法。