from typing import Annotated, Optional

import pytest
from fastapi import FastAPI, Header
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI()

# =====================================================================================
# Without aliases


@app.get("/optional-str")
async def read_optional_str(p: Annotated[Optional[str], Header()] = None):
    return {"p": p}

        setField(transport, "mid", new AtomicLong());
    }

    // Utility: reflectively set a private/protected field (searches up the hierarchy)
    private static void setField(Object target, String name, Object value) {
        try {
            Field f = findField(target.getClass(), name);
            f.setAccessible(true);
            f.set(target, value);
        } catch (Exception e) {

from typing import Annotated, Optional

import pytest
from fastapi import FastAPI, Header
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI()

# =====================================================================================
# Without aliases


@app.get("/optional-list-str")
async def read_optional_list_str(
    p: Annotated[Optional[list[str]], Header()] = None,
):

     * @param role The role.
     */
    public void addRole(final String role) {
        roles.add(role);
    }

    /**
     * Adds a field to filter by.
     * @param field The field name.
     */
    public void addField(final String field) {
        fields.add(field);
    }

    /**
     * Adds a kind to filter by.
     * @param kind The kind.
     */
    public void addKind(final String kind) {

                `username` string. The OAuth2 spec requires the exact field name
                `username`.
                """
            ),
        ],
        password: Annotated[
            str,
            Form(json_schema_extra={"format": "password"}),
            Doc(
                """
                `password` string. The OAuth2 spec requires the exact field name
                `password`.
                """

        assertNotNull(value);
        assertEquals(48, value.length);

        // Verify the size field (first 4 bytes)
        assertEquals(48, (value[0] & 0xFF) | ((value[1] & 0xFF) << 8) | ((value[2] & 0xFF) << 16) | ((value[3] & 0xFF) << 24));
        // Verify the zero field (next 4 bytes)
        assertEquals(0, (value[4] & 0xFF) | ((value[5] & 0xFF) << 8) | ((value[6] & 0xFF) << 16) | ((value[7] & 0xFF) << 24));

その追加情報はそのまま出力され、JSON Schemaに追加されます。

## `Field`の追加引数

後述する`Field`、`Path`、`Query`、`Body`などでは、任意の引数を関数に渡すことでJSON Schemaの追加情報を宣言することもできます:

{* ../../docs_src/schema_extra_example/tutorial002.py hl[4,10,11,12,13] *}

/// warning | 注意

これらの追加引数が渡されても、文書化のためのバリデーションは追加されず、注釈だけが追加されることを覚えておいてください。

///

## `Body`の追加引数

追加情報を`Field`に渡すのと同じように、`Path`、`Query`、`Body`などでも同じことができます。

    /**
     * Validates buffer size to prevent overflow
     *
     * @param size the buffer size to validate
     * @param maxSize the maximum allowed size
     * @param fieldName the field name for error reporting
     * @throws IllegalArgumentException if size is invalid
     */
    public static void validateBufferSize(int size, int maxSize, String fieldName) {
        if (size < 0) {

* `read(size)`: Lee `size` (`int`) bytes/caracteres del archivo.
* `seek(offset)`: Va a la posición de bytes `offset` (`int`) en el archivo.
    * Por ejemplo, `await myfile.seek(0)` iría al inicio del archivo.
    * Esto es especialmente útil si ejecutas `await myfile.read()` una vez y luego necesitas leer el contenido nuevamente.
* `close()`: Cierra el archivo.

Como todos estos métodos son métodos `async`, necesitas "await" para ellos.

* `seek(offset)`：移动至文件 `offset` （`int`）字节处的位置；
    * 例如，`await myfile.seek(0) ` 移动到文件开头；
    * 执行 `await myfile.read()` 后，需再次读取已读取内容时，这种方法特别好用；
* `close()`：关闭文件。

因为上述方法都是 `async` 方法，要搭配「await」使用。

例如，在 `async` *路径操作函数* 内，要用以下方式读取文件内容：

```Python
contents = await myfile.read()
```

在普通 `def` *路径操作函数*  内，则可以直接访问 `UploadFile.file`，例如：

```Python
contents = myfile.file.read()
```

/// note | `async` 技术细节