from __future__ import annotations
from typing import Any, Dict, Mapping, Optional, Union
import requests


def POST(
    url: str,
    data: Optional[Union[Mapping[str, Any], bytes, str]] = None,
    json: Optional[Any] = None,
    headers: Optional[Dict[str, str]] = None,
    cookies: Optional[Dict[str, str]] = None,
    timeout: Union[int, float] = 10,
    allow_redirects: bool = True,
    verify: bool = True,
    proxies: Optional[Dict[str, str]] = None,
) -> Optional[requests.Response]:
    """
    发送 HTTP POST 请求并返回响应对象（requests.Response）。

    本函数面向“工具库”场景设计，强调稳定与可控：
        - 成功返回 requests.Response
        - 任意异常（网络错误/超时/参数错误等）返回 None
        - 函数内部不抛出异常

    发送内容说明:
        - 优先使用 json 参数（requests 会自动序列化为 JSON 并设置合适的 Content-Type）
        - 否则使用 data 参数（常用于表单、原始文本或 bytes）

    Args:
        url (str): 目标 URL，例如 "https://example.com/api".
        data (Optional[Union[Mapping[str, Any], bytes, str]]):
            请求体内容（非 JSON 场景）。
            - dict/Mapping：按表单方式提交（application/x-www-form-urlencoded 或 multipart，取决于你是否传 files）
            - str/bytes：原样作为请求体发送
        json (Optional[Any]):
            JSON 请求体。可以是 dict/list 等可 JSON 序列化对象。
            注意：当 json 不为 None 时，将优先使用 json。
        headers (Optional[Dict[str, str]]): 请求头字典，例如 {"User-Agent": "..."}。
        cookies (Optional[Dict[str, str]]): Cookie 字典。
        timeout (Union[int, float]): 超时时间（秒），例如 10 或 3.5。
        allow_redirects (bool): 是否允许自动跟随重定向。
        verify (bool): 是否验证 HTTPS 证书。为 False 时可能降低安全性。
        proxies (Optional[Dict[str, str]]): 代理配置，例如：
            {"http": "http://127.0.0.1:7890", "https": "http://127.0.0.1:7890"}。

    Returns:
        Optional[requests.Response]:
            - 成功：返回 响应对象（requests.Response）
            - 失败：返回 None
    """
    if not isinstance(url, str) or not url.strip():
        return None

    try:
        # 约定：json 优先，其次 data
        if json is not None:
            响应 = requests.post(
                url=url,
                json=json,
                headers=headers,
                cookies=cookies,
                timeout=timeout,
                allow_redirects=allow_redirects,
                verify=verify,
                proxies=proxies,
            )
            return 响应

        响应 = requests.post(
            url=url,
            data=data,
            headers=headers,
            cookies=cookies,
            timeout=timeout,
            allow_redirects=allow_redirects,
            verify=verify,
            proxies=proxies,
        )
        return 响应
    except Exception:
        return None
