# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

# DO NOT EDIT IT MANUALLY. This file is generated by opendal/dev/generate/python.rs.

"""Typed options for operator methods.

Each `*Kwargs` is a `TypedDict` describing the keyword arguments accepted by
the corresponding `Operator` / `AsyncOperator` method, e.g. `ReadKwargs` for
`read`. Every key is optional; an unset key is equivalent to the method's
default.

Build an options dict, then unpack it into the call:

```python
import opendal

opts: opendal.options.ReadKwargs = {
    "offset": 1024,
    "size": 2048,
}
op.read("path/to/file", **opts)
```

A static type checker validates the keys and their value types against the
method's keyword arguments.
"""

from __future__ import annotations

from datetime import datetime
from typing import TypedDict


class ReadKwargs(TypedDict, total=False):
    """Options for `read` operations."""

    version: str
    """The version of the file."""
    concurrent: int
    """The number of concurrent readers."""
    chunk: int
    """The size of each chunk."""
    gap: int
    """The gap between each chunk."""
    offset: int
    """The offset of the file."""
    prefetch: int
    """The number of bytes to prefetch."""
    size: int
    """The size of the file."""
    if_match: str
    """The ETag of the file."""
    if_none_match: str
    """The ETag of the file."""
    if_modified_since: datetime
    """The last modified time of the file."""
    if_unmodified_since: datetime
    """The last modified time of the file."""
    content_type: str
    """The content type of the file."""
    cache_control: str
    """The cache control of the file."""
    content_disposition: str
    """The content disposition of the file."""


class WriteKwargs(TypedDict, total=False):
    """Options for `write` operations."""

    append: bool
    """Whether to append to the file instead of overwriting it."""
    chunk: int
    """The chunk size to use when writing the file."""
    concurrent: int
    """The number of concurrent requests to make when writing the file."""
    cache_control: str
    """The cache control header to set on the file."""
    content_type: str
    """The content type header to set on the file."""
    content_disposition: str
    """The content disposition header to set on the file."""
    content_encoding: str
    """The content encoding header to set on the file."""
    if_match: str
    """The ETag to match when writing the file."""
    if_none_match: str
    """The ETag to not match when writing the file."""
    if_not_exists: bool
    """Whether to fail if the file already exists."""
    user_metadata: dict[str, str]
    """The user metadata to set on the file."""


class ListKwargs(TypedDict, total=False):
    """Options for `list` operations."""

    limit: int
    """The maximum number of entries to return."""
    start_after: str
    """The entry to start after."""
    recursive: bool
    """Whether to list recursively."""
    versions: bool
    """Whether to list versions."""
    deleted: bool
    """Whether to list deleted entries."""


class StatKwargs(TypedDict, total=False):
    """Options for `stat` operations."""

    version: str
    """The version of the file."""
    if_match: str
    """The ETag of the file."""
    if_none_match: str
    """The ETag of the file."""
    if_modified_since: datetime
    """The last modified time of the file."""
    if_unmodified_since: datetime
    """The last modified time of the file."""
    content_type: str
    """The content type of the file."""
    cache_control: str
    """The cache control of the file."""
    content_disposition: str
    """The content disposition of the file."""


class DeleteKwargs(TypedDict, total=False):
    """Options for `delete` operations."""

    version: str
    """The version of the file to delete. Only supported on version-aware backends."""
    recursive: bool
    """If True, delete the path recursively.

    Only supported on backends that support recursive delete.
    """


class OpenKwargs(ReadKwargs, WriteKwargs, total=False):
    """Keyword arguments for `Operator.open`."""


__all__ = [
    "ReadKwargs",
    "WriteKwargs",
    "ListKwargs",
    "StatKwargs",
    "DeleteKwargs",
    "OpenKwargs",
]
