cliV1 0.1.1__py3-none-any.whl

swagger_petstore_open_api_3_0/async_client.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from functools import cached_property
+from types import TracebackType
+
+from typing_extensions import Self
+
+from .apis.pet_api import AsyncPetApi
+from .apis.store import AsyncStore
+from .apis.user_api import AsyncUserApi
+from .auth import AsyncAuthSchemes
+from .base_client import DEFAULT_TIMEOUT, BaseSwaggerPetstoreOpenApi30Client
+from .core import (
+    OPERATING_SYSTEM,
+    PYTHON_RUNTIME,
+    ApiKeyHeaderScheme,
+    AsyncHttpClient,
+    AsyncHttpxClient,
+    AsyncRawClient,
+    no_auth,
+    param,
+)
+from .server.server_config import ServerConfigOrDict
+
+
+class AsyncSwaggerPetstoreOpenApi30Client(BaseSwaggerPetstoreOpenApi30Client[AsyncRawClient]):
+    def __init__(
+        self,
+        *,
+        server_config: ServerConfigOrDict | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        custom_async_http_client: AsyncHttpClient | None = None,
+        petstore_auth: str | None = None,
+        api_key: str | None = None,
+    ) -> None:
+        super().__init__(server_config=server_config, timeout=timeout)
+        self._raw_client = AsyncRawClient(
+            http_client=(
+                custom_async_http_client if custom_async_http_client is not None else AsyncHttpxClient(timeout=timeout)
+            ),
+            global_headers=[
+                param[str]("User-Agent", "SwaggerPetstoreOpenApi30Client/1.0.26 Python"),
+                param[str]("X-APIMatic-Lang", "Python"),
+                param[str]("X-APIMatic-Package-Version", "1.0.26"),
+                param[str]("X-APIMatic-Gen-Version", "4.0.0"),
+                param[str]("X-APIMatic-OS", OPERATING_SYSTEM),
+                param[str]("X-APIMatic-Runtime", PYTHON_RUNTIME),
+            ],
+        )
+        self._auth = AsyncAuthSchemes(
+            petstore_auth=ApiKeyHeaderScheme("Authorization", petstore_auth) if petstore_auth is not None else no_auth,
+            api_key=ApiKeyHeaderScheme("api_key", api_key) if api_key is not None else no_auth,
+        )
+
+    @cached_property
+    def pet_api(self) -> AsyncPetApi:
+        return AsyncPetApi(self._raw_client, self._server, self._auth)
+
+    @cached_property
+    def store(self) -> AsyncStore:
+        return AsyncStore(self._raw_client, self._server, self._auth)
+
+    @cached_property
+    def user_api(self) -> AsyncUserApi:
+        return AsyncUserApi(self._raw_client, self._server)
+
+    async def aclose(self) -> None:
+        await self._raw_client.http_client.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, exc_tb: TracebackType | None
+    ) -> None:
+        await self.aclose()
+
+
+AsyncClient = AsyncSwaggerPetstoreOpenApi30Client

swagger_petstore_open_api_3_0/auth.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .core import AsyncAuthScheme, AuthScheme
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AuthSchemes:
+    petstore_auth: AuthScheme
+    api_key: AuthScheme
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AsyncAuthSchemes:
+    petstore_auth: AsyncAuthScheme
+    api_key: AsyncAuthScheme

swagger_petstore_open_api_3_0/base_client.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Generic
+
+from .core import RawClientT
+from .server.server import Server
+from .server.server_config import ServerConfig, ServerConfigOrDict
+
+DEFAULT_TIMEOUT = 30.0
+
+
+class BaseSwaggerPetstoreOpenApi30Client(Generic[RawClientT]):
+    _raw_client: RawClientT
+
+    def __init__(self, *, server_config: ServerConfigOrDict | None = None, timeout: float = DEFAULT_TIMEOUT) -> None:
+        if not timeout > 0:
+            raise ValueError(f"timeout must be greater than 0; got {timeout!r}")
+        self._server = Server(ServerConfig.coerce(server_config))

swagger_petstore_open_api_3_0/client.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from functools import cached_property
+from types import TracebackType
+
+from typing_extensions import Self
+
+from .apis.pet_api import PetApi
+from .apis.store import Store
+from .apis.user_api import UserApi
+from .auth import AuthSchemes
+from .base_client import DEFAULT_TIMEOUT, BaseSwaggerPetstoreOpenApi30Client
+from .core import (
+    OPERATING_SYSTEM,
+    PYTHON_RUNTIME,
+    ApiKeyHeaderScheme,
+    HttpClient,
+    HttpxClient,
+    RawClient,
+    no_auth,
+    param,
+)
+from .server.server_config import ServerConfigOrDict
+
+
+class SwaggerPetstoreOpenApi30Client(BaseSwaggerPetstoreOpenApi30Client[RawClient]):
+    def __init__(
+        self,
+        *,
+        server_config: ServerConfigOrDict | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        custom_http_client: HttpClient | None = None,
+        petstore_auth: str | None = None,
+        api_key: str | None = None,
+    ) -> None:
+        super().__init__(server_config=server_config, timeout=timeout)
+        self._raw_client = RawClient(
+            http_client=custom_http_client if custom_http_client is not None else HttpxClient(timeout=timeout),
+            global_headers=[
+                param[str]("User-Agent", "SwaggerPetstoreOpenApi30Client/1.0.26 Python"),
+                param[str]("X-APIMatic-Lang", "Python"),
+                param[str]("X-APIMatic-Package-Version", "1.0.26"),
+                param[str]("X-APIMatic-Gen-Version", "4.0.0"),
+                param[str]("X-APIMatic-OS", OPERATING_SYSTEM),
+                param[str]("X-APIMatic-Runtime", PYTHON_RUNTIME),
+            ],
+        )
+        self._auth = AuthSchemes(
+            petstore_auth=ApiKeyHeaderScheme("Authorization", petstore_auth) if petstore_auth is not None else no_auth,
+            api_key=ApiKeyHeaderScheme("api_key", api_key) if api_key is not None else no_auth,
+        )
+
+    @cached_property
+    def pet_api(self) -> PetApi:
+        return PetApi(self._raw_client, self._server, self._auth)
+
+    @cached_property
+    def store(self) -> Store:
+        return Store(self._raw_client, self._server, self._auth)
+
+    @cached_property
+    def user_api(self) -> UserApi:
+        return UserApi(self._raw_client, self._server)
+
+    def close(self) -> None:
+        self._raw_client.http_client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, exc_tb: TracebackType | None
+    ) -> None:
+        self.close()
+
+
+Client = SwaggerPetstoreOpenApi30Client

swagger_petstore_open_api_3_0/core/__init__.py

@@ -0,0 +1,342 @@
+"""Public surface of the SDK runtime.
+
+Everything the generated layers (``api/``, ``models/``, ``errors/``, ``server/``, the two clients)
+need from the runtime is re-exported here, so a generated module imports from one place --
+``from <sdk>.core import ApiResult, RawClient, json_decoder`` -- instead of reaching into the
+runtime's internal module layout. That indirection is the point: the modules behind this facade are
+free to move without touching a single generated file.
+
+A symbol earns a place here by one test: a generator may emit it, or a caller may need to name it.
+Internal machinery the runtime only calls itself -- the adapter cache, the decoder implementation
+classes, the sentinel stripper -- is deliberately absent, and remains reachable at its own module
+path for the unit tests that target it.
+
+Everything remains importable from its fully-qualified module path as well."""
+
+from .auth import (
+    AllSchemes,
+    AnySchemes,
+    AsyncAllSchemes,
+    AsyncAnySchemes,
+    AsyncAuthScheme,
+    AsyncRefreshableTokenSource,
+    AsyncTokenSource,
+    AuthParams,
+    AuthScheme,
+    OAuthError,
+    OAuthProviderError,
+    OAuthToken,
+    OAuthTokenRefreshable,
+    RefreshableTokenSource,
+    RevocableAuthScheme,
+    TokenSource,
+    client_secret_basic,
+    client_secret_post,
+    invalidate,
+    is_configured,
+    no_auth,
+    oauth_error_response,
+    resolve_auth,
+)
+from .auth.schemes import (
+    ApiKeyCookieScheme,
+    ApiKeyHeaderScheme,
+    ApiKeyQueryScheme,
+    AsyncAuthorizationCodeCredentials,
+    AsyncAuthorizationCodeCredentialsDict,
+    AsyncAuthorizationCodeCredentialsOrDict,
+    AsyncAuthorizationCodePrompt,
+    AsyncAuthorizationCodeTokenSource,
+    AsyncClientCredentialsTokenSource,
+    AsyncOAuth2RefreshableScheme,
+    AsyncOAuth2Scheme,
+    AsyncPasswordTokenSource,
+    AuthorizationCodeCredentials,
+    AuthorizationCodeCredentialsDict,
+    AuthorizationCodeCredentialsOrDict,
+    AuthorizationCodePrompt,
+    AuthorizationCodeTokenSource,
+    BasicAuthCredentials,
+    BasicAuthCredentialsDict,
+    BasicAuthCredentialsOrDict,
+    BasicAuthScheme,
+    BearerAuthScheme,
+    ClientCredentials,
+    ClientCredentialsDict,
+    ClientCredentialsOrDict,
+    ClientCredentialsTokenSource,
+    OAuth2RefreshableScheme,
+    OAuth2Scheme,
+    PasswordCredentials,
+    PasswordCredentialsDict,
+    PasswordCredentialsOrDict,
+    PasswordTokenSource,
+    PkceMethod,
+)
+from .base_raw_response import BaseRawResponse, SecuredRawResponse
+from .bodies import (
+    BinaryBody,
+    FormBody,
+    JsonBody,
+    MultipartBody,
+    MultipartFile,
+    MultipartPart,
+    MultipartText,
+    RequestBody,
+    TextBody,
+    binary_body,
+    file_part,
+    form_body,
+    json_body,
+    json_part,
+    multipart_body,
+    text_body,
+)
+from .converters import (
+    Base16AsciiEncodedBytes,
+    Base16Cp1252EncodedBytes,
+    Base16Latin1EncodedBytes,
+    Base16Utf8EncodedBytes,
+    Base32AsciiEncodedBytes,
+    Base32Cp1252EncodedBytes,
+    Base32HexAsciiEncodedBytes,
+    Base32HexCp1252EncodedBytes,
+    Base32HexLatin1EncodedBytes,
+    Base32HexUtf8EncodedBytes,
+    Base32Latin1EncodedBytes,
+    Base32Utf8EncodedBytes,
+    Base64AsciiEncodedBytes,
+    Base64Cp1252EncodedBytes,
+    Base64Latin1EncodedBytes,
+    Base64UrlAsciiEncodedBytes,
+    Base64UrlCp1252EncodedBytes,
+    Base64UrlLatin1EncodedBytes,
+    Base64UrlUtf8EncodedBytes,
+    Base64Utf8EncodedBytes,
+    ByteField,
+    Date,
+    RFC1123DateTime,
+    RFC3339DateTime,
+    UnixSecondsDateTime,
+    open_enum_validator,
+)
+from .decoding import (
+    AsyncStreamDecoder,
+    ErrorMapper,
+    ResponseDecoder,
+    StreamDecoder,
+    async_file_decoder,
+    decode_json,
+    decode_text,
+    empty_response,
+    file_decoder,
+    json_decoder,
+    raw_error_response,
+    text_decoder,
+)
+from .exceptions import ApiError
+from .file_responses import AsyncFileResponse, FileResponse
+from .files import (
+    AsyncBinaryContent,
+    AsyncBinaryReader,
+    AsyncFileInput,
+    BinaryContent,
+    BinaryReader,
+    FileInput,
+    NamedFile,
+)
+from .httpx_transport import AsyncHttpxClient, HttpxClient
+from .models import SdkBaseModel
+from .optionality import UNSET, Optional, OptionalNullable, UnsetType
+from .params import SerializationFormat, UrlTemplate, param
+from .raw_client import (
+    AsyncRawClient,
+    RawClient,
+    RawClientT,
+)
+from .request_options import RequestOptions, RequestOptionsDict, RequestOptionsOrDict
+from .results import ApiResult, Failure, RawError, Success
+from .runtime_env import OPERATING_SYSTEM, PYTHON_RUNTIME
+from .servers import validate_one_of
+from .transport import (
+    AsyncHttpClient,
+    AsyncStreamedResponse,
+    HttpClient,
+    HttpRequest,
+    HttpResponse,
+    StreamedResponse,
+)
+
+__all__ = [
+    # Result and error types
+    "ApiResult",
+    "Success",
+    "Failure",
+    "RawError",
+    "ApiError",
+    # HTTP transport
+    "HttpClient",
+    "AsyncHttpClient",
+    "HttpRequest",
+    "HttpResponse",
+    "HttpxClient",
+    "AsyncHttpxClient",
+    # Request parameters and bodies
+    "param",
+    "SerializationFormat",
+    "UrlTemplate",
+    "RequestBody",
+    "JsonBody",
+    "json_body",
+    "FormBody",
+    "form_body",
+    "MultipartBody",
+    "multipart_body",
+    "MultipartPart",
+    "MultipartText",
+    "MultipartFile",
+    "file_part",
+    "json_part",
+    "BinaryBody",
+    "binary_body",
+    "TextBody",
+    "text_body",
+    # File input
+    "BinaryReader",
+    "AsyncBinaryReader",
+    "BinaryContent",
+    "AsyncBinaryContent",
+    "NamedFile",
+    "FileInput",
+    "AsyncFileInput",
+    # Streamed responses
+    "StreamedResponse",
+    "AsyncStreamedResponse",
+    "FileResponse",
+    "AsyncFileResponse",
+    # Per-call request options
+    "RequestOptions",
+    "RequestOptionsDict",
+    "RequestOptionsOrDict",
+    # Authentication
+    "AuthParams",
+    "AuthScheme",
+    "AsyncAuthScheme",
+    "no_auth",
+    "is_configured",
+    "resolve_auth",
+    "BasicAuthCredentials",
+    "BasicAuthCredentialsDict",
+    "BasicAuthCredentialsOrDict",
+    "BasicAuthScheme",
+    "BearerAuthScheme",
+    "ApiKeyHeaderScheme",
+    "ApiKeyQueryScheme",
+    "ApiKeyCookieScheme",
+    "AnySchemes",
+    "AsyncAnySchemes",
+    "AllSchemes",
+    "AsyncAllSchemes",
+    "RevocableAuthScheme",
+    "invalidate",
+    # Managed OAuth 2.0
+    "OAuth2Scheme",
+    "AsyncOAuth2Scheme",
+    "OAuth2RefreshableScheme",
+    "AsyncOAuth2RefreshableScheme",
+    "TokenSource",
+    "AsyncTokenSource",
+    "RefreshableTokenSource",
+    "AsyncRefreshableTokenSource",
+    "client_secret_basic",
+    "client_secret_post",
+    "OAuthToken",
+    "OAuthTokenRefreshable",
+    "OAuthProviderError",
+    "OAuthError",
+    "oauth_error_response",
+    # oauth2 / clientCredentials
+    "ClientCredentials",
+    "ClientCredentialsDict",
+    "ClientCredentialsOrDict",
+    "ClientCredentialsTokenSource",
+    "AsyncClientCredentialsTokenSource",
+    # oauth2 / password
+    "PasswordCredentials",
+    "PasswordCredentialsDict",
+    "PasswordCredentialsOrDict",
+    "PasswordTokenSource",
+    "AsyncPasswordTokenSource",
+    # oauth2 / authorizationCode
+    "AuthorizationCodeCredentials",
+    "AuthorizationCodeCredentialsDict",
+    "AuthorizationCodeCredentialsOrDict",
+    "AsyncAuthorizationCodeCredentials",
+    "AsyncAuthorizationCodeCredentialsDict",
+    "AsyncAuthorizationCodeCredentialsOrDict",
+    "AuthorizationCodePrompt",
+    "AsyncAuthorizationCodePrompt",
+    "PkceMethod",
+    "AuthorizationCodeTokenSource",
+    "AsyncAuthorizationCodeTokenSource",
+    # Response decoding and error mapping
+    "ResponseDecoder",
+    "ErrorMapper",
+    "StreamDecoder",
+    "AsyncStreamDecoder",
+    "json_decoder",
+    "text_decoder",
+    "decode_json",
+    "decode_text",
+    "empty_response",
+    "raw_error_response",
+    "file_decoder",
+    "async_file_decoder",
+    # Model base and optionality
+    "SdkBaseModel",
+    "UNSET",
+    "UnsetType",
+    "Optional",
+    "OptionalNullable",
+    # Wire-format converters
+    "Date",
+    "RFC3339DateTime",
+    "RFC1123DateTime",
+    "UnixSecondsDateTime",
+    # Wire-format binary aliases -- one per (RFC 4648 alphabet, charset) pair
+    "Base64AsciiEncodedBytes",
+    "Base64Utf8EncodedBytes",
+    "Base64Latin1EncodedBytes",
+    "Base64Cp1252EncodedBytes",
+    "Base64UrlAsciiEncodedBytes",
+    "Base64UrlUtf8EncodedBytes",
+    "Base64UrlLatin1EncodedBytes",
+    "Base64UrlCp1252EncodedBytes",
+    "Base32AsciiEncodedBytes",
+    "Base32Utf8EncodedBytes",
+    "Base32Latin1EncodedBytes",
+    "Base32Cp1252EncodedBytes",
+    "Base32HexAsciiEncodedBytes",
+    "Base32HexUtf8EncodedBytes",
+    "Base32HexLatin1EncodedBytes",
+    "Base32HexCp1252EncodedBytes",
+    "Base16AsciiEncodedBytes",
+    "Base16Utf8EncodedBytes",
+    "Base16Latin1EncodedBytes",
+    "Base16Cp1252EncodedBytes",
+    # Binary property declaration
+    "ByteField",
+    # Open enums
+    "open_enum_validator",
+    # Raw clients and the raw-response base
+    "RawClient",
+    "AsyncRawClient",
+    "RawClientT",
+    "BaseRawResponse",
+    "SecuredRawResponse",
+    # Host environment reported in the SDK identification headers
+    "OPERATING_SYSTEM",
+    "PYTHON_RUNTIME",
+    # Server layer
+    "validate_one_of",
+]

swagger_petstore_open_api_3_0/core/_internal/__init__.py

@@ -0,0 +1,7 @@
+"""Runtime plumbing.
+
+Nothing here is part of the SDK's public surface: these are the pure functions the raw client calls
+to turn parameters into a URL, a header mapping, and form fields. They are grouped under a private
+package so this runtime's own ``__init__`` stays the whole of what generated code imports."""
+
+__all__: list[str] = []

swagger_petstore_open_api_3_0/core/_internal/content_disposition.py

@@ -0,0 +1,154 @@
+"""``Content-Disposition``, both directions: the filename a response suggests, and the one a
+request carries.
+
+One header, one module. The RFC 6266/8187 grammar is the shared asset, so reading it and writing
+it stay together rather than putting one table in two files. ``headers.py`` remains the
+*parameter*-layer module, resolving the outbound layers a caller and the spec contribute; what
+this module renders is a value a body carries, exactly as its media type is.
+
+The standard library gets the reading wrong twice, both reproduced during planning
+(docs/plans/file-handling.md, verified facts). ``Message.get_filename()`` returns the plain
+``filename`` when both forms are present -- RFC 6266 §4.3 requires the extended ``filename*`` to
+win -- and the RFC 2231 machinery percent-decodes the extended value as latin-1 whatever charset
+it declares, so the text must be re-encoded through latin-1 and decoded with the declared charset
+to come back intact.
+
+The two readers treat their input as attacker-controlled. The parser is **total**: any malformed
+header yields ``None`` rather than raising, because it runs while a streamed connection is held
+and a raise there would leak it. The sanitiser is the paranoid half: a server-suggested name is
+reduced to a basename, stripped of everything Windows refuses, and refused outright when what
+survives is empty, a reserved device name, or too long to create.
+
+The writer needs no such paranoia, and by construction rather than by trust: every byte outside
+RFC 8187's ``attr-char`` is percent-encoded, so no name can splice a header and there is nothing
+to refuse."""
+
+from __future__ import annotations
+
+import re
+from email.message import Message
+from typing import Final
+from urllib.parse import quote
+
+_SEPARATORS: Final = re.compile(r"[\\/]")
+_WINDOWS_ILLEGAL: Final = frozenset('<>:"|?*')
+_WINDOWS_RESERVED: Final = frozenset(
+    {"CON", "PRN", "AUX", "NUL"} | {f"COM{d}" for d in "123456789"} | {f"LPT{d}" for d in "123456789"}
+)
+
+
+def content_disposition_filename(header: str | None) -> str | None:
+    """The filename a ``Content-Disposition`` suggests, or ``None``.
+
+    Prefers the RFC 8187 extended ``filename*`` (RFC 6266 §4.3) and recovers its text from the
+    standard library's latin-1 percent-decode; RFC 8187 §3.2.1 permits only UTF-8, so any other
+    declared charset falls back to the plain ``filename`` rather than guessing. Continuation
+    segments (``filename*0*``, ``filename*1*``) are collapsed by the same machinery.
+
+    Total by design: a malformed header returns ``None``, never raises -- this runs between a
+    streamed response's head arriving and its owner returning, where a raise would leak the
+    connection. The result is *not* trusted as a path; see :func:`safe_filename`.
+
+    Args:
+        header: The header's value, or ``None`` when the response carried none.
+
+    Returns:
+        The suggested filename, or ``None`` when there is no usable one."""
+    if header is None:
+        return None
+    try:
+        message = Message()
+        message["content-disposition"] = header
+        params = message.get_params(header="content-disposition")
+        if params is None:
+            return None
+
+        plain: str | None = None
+        extended: str | None = None
+        for name, raw in params:
+            if name != "filename":
+                continue
+            # The parser hands back a plain parameter as ``str`` and an RFC 2231 extended one as a
+            # ``(charset, language, text)`` tuple. A duplicated plain form keeps its first
+            # occurrence; duplicated extended forms never reach here -- the stdlib merges them as
+            # continuations before ``get_params`` returns.
+            value: object = raw
+            if isinstance(value, str) and plain is None:
+                plain = value
+            elif isinstance(value, tuple) and extended is None:
+                extended = _decode_extended(value)
+        return (extended or plain) or None
+    except Exception:
+        # Total by design -- the docstring says why. Bad wire data degrades, never raises.
+        return None
+
+
+def _decode_extended(value: tuple[object, ...]) -> str | None:
+    # (charset, language, text) -- text percent-decoded as latin-1 by the parser regardless of the
+    # declared charset, which is the mojibake the round trip below undoes.
+    if len(value) != 3:
+        return None
+    charset, _language, text = value
+    if not isinstance(charset, str) or not isinstance(text, str):
+        return None
+    if charset.lower() not in ("utf-8", "utf8"):
+        return None
+    try:
+        return text.encode("latin-1").decode("utf-8")
+    except (UnicodeEncodeError, UnicodeDecodeError):
+        return None
+
+
+def render_content_disposition(filename: str) -> str:
+    """The ``Content-Disposition`` value naming a raw request body.
+
+    RFC 6266's dual form: a quoted ``filename`` holding what a quoted-string can, and, whenever
+    that reduction lost something, the RFC 8187 ``filename*`` that did not. A conformant receiver
+    prefers the extended parameter (§4.3) and recovers the name exactly; one reading only the plain
+    parameter still gets a usable name.
+
+    Percent-encoding is what makes this safe rather than a character check: every byte outside
+    RFC 8187's ``attr-char`` becomes ``%XX``, so a CR, an LF or a ``"`` cannot reach the header
+    however the caller spelled the name. There is nothing to refuse.
+
+    Args:
+        filename: The name the caller gave the file, as ``NamedFile.filename`` holds it.
+
+    Returns:
+        The header value -- ``attachment``, and whichever parameters can carry the name."""
+    plain = "".join(c for c in filename if c.isascii() and c.isprintable() and c not in '"\\')
+    parameters = [f'filename="{plain}"'] if plain else []
+    if plain != filename:
+        parameters.append(f"filename*=UTF-8''{quote(filename, safe='', encoding='utf-8')}")
+    return "; ".join(["attachment", *parameters])
+
+
+def safe_filename(filename: str) -> str:
+    """Reduce a server-supplied filename to a name safe to create in a directory.
+
+    Basename first, under both separator flavours -- ``Content-Disposition`` is
+    attacker-controlled and ``filename="../../etc/passwd"`` reaches the parser unchanged -- then
+    strip what Windows refuses: ``<>:"|?*``, unprintable characters, and trailing dots or spaces.
+    Dropping the colon also neutralises an NTFS alternate-data-stream name. What remains is
+    refused rather than mangled when it cannot safely name a file: a reserved device-name stem
+    (``CON``, ``NUL``, ``COM1``... -- Windows 10 resolves even ``CON.pdf`` to the console device,
+    and a bare ``NUL`` open "succeeds" while the bytes go to the null device) or a name past 255
+    characters, the per-component ceiling on NTFS and most POSIX filesystems.
+
+    Args:
+        filename: The server's suggestion, as :func:`content_disposition_filename` returned it.
+
+    Returns:
+        The reduced name, never empty.
+
+    Raises:
+        ValueError: If nothing safe remains -- an empty reduction, ``.`` or ``..``, a reserved
+            device name, or a name too long to create."""
+    basename = _SEPARATORS.split(filename)[-1]
+    cleaned = "".join(ch for ch in basename if ch not in _WINDOWS_ILLEGAL and ch.isprintable())
+    cleaned = cleaned.rstrip(". ")
+    # A reserved stem is matched as Windows does: up to the first dot, trailing spaces ignored.
+    stem = cleaned.split(".", 1)[0].rstrip(" ")
+    if not cleaned or stem.upper() in _WINDOWS_RESERVED or len(cleaned) > 255:
+        raise ValueError(f"{filename!r} reduces to nothing safe to create -- pass an explicit file path instead")
+    return cleaned