request

core.request

请求描述符与批量请求容器. 提供对 API 请求的抽象与调度.

BaseRequest `dataclass`

BaseRequest(
    *,
    _client: Client,
    response_model: type[BaseModel] | None = None,
    disable_parse: bool = False,
)

Bases: ABC, Generic[ResultT]

请求描述符基类.

该基类封装了由客户端执行请求时所需的元数据与行为契约.

ATTRIBUTE	DESCRIPTION
`_client`	请求执行的客户端实例, 用于调度请求. TYPE: `Client`
`response_model`	期望的响应模型类型, 支持 Pydantic BaseModel. TYPE: `type[BaseModel] \| None`
`disable_parse`	是否禁用响应解析, 直接返回原始响应数据. TYPE: `bool`

CgiRequestOptions

Bases: TypedDict

CGI 请求专用的可选配置.

CgiRequest `dataclass`

CgiRequest(
    *,
    _client: Client,
    response_model: type[BaseModel] | None = None,
    disable_parse: bool = False,
    module: str,
    method: str,
    param: dict[str, Any],
    comm: dict[str, int | str | bool] | None = None,
    override_comm: bool = False,
    preserve_bool: bool = False,
    credential: Credential | None = None,
    require_login: bool = False,
    platform: Platform | None = None,
    sign: bool = False,
    allow_error_codes: AllowErrorCodes | None = None,
    parse_on_allow: bool = False,
)

Bases: BaseRequest[CgiRequestResultT]

CGI 风格的请求述符, 用于封装模块/方法形式的 RPC 请求.

ATTRIBUTE	DESCRIPTION
`module`	请求所属的模块名称. TYPE: `str`
`method`	请求的方法名称. TYPE: `str`
`param`	请求参数字典. TYPE: `dict[str, Any]`
`comm`	可选的公共参数, 会与默认公共参数合并或覆盖. TYPE: `dict[str, int \| str \| bool] \| None`
`override_comm`	若为 True, 则直接使用 `comm` 作为公共参数而不合并默认值. TYPE: `bool`
`preserve_bool`	是否在参数中保留布尔值 (而非转换为整型等). TYPE: `bool`
`allow_error_codes`	允许的错误码集合, 如果响应中包含这些错误码, 将不会抛出异常. TYPE: `AllowErrorCodes \| None`
`parse_on_allow`	当响应包含允许的错误码时, 是否仍尝试解析响应数据, 优先级大于 `disable_parse`. TYPE: `bool`
`credential`	可选的凭证对象, 优先于客户端的全局凭证. TYPE: `Credential \| None`
`require_login`	请求是否需要凭证. TYPE: `bool`
`platform`	可选的平台标识, 优先于客户端的全局平台设置. TYPE: `Platform \| None`
`sign`	指示该请求是否需要签名处理. TYPE: `bool`

HttpRequestOptions

Bases: TypedDict

HTTP 请求专用的可选配置.

HttpRequest `dataclass`

HttpRequest(
    *,
    _client: Client,
    response_model: type[BaseModel] | None = None,
    disable_parse: bool = False,
    method: HttpMethodType,
    url: str,
    params: QueryParameterType | None = None,
    headers: HeadersType | None = None,
    cookies: CookiesType | None = None,
    json: Any | None = None,
    data: BodyType | AsyncBodyType | None = None,
    kwargs: HttpRequestOptions | None = None,
    credential: Credential | None = None,
)

Bases: BaseRequest[HttpRequestResultT]

标准 HTTP 请求描述符.

用于封装直接透传到 HTTP 客户端 (如 aiohttp/anyio AsyncSession)
的请求元数据.

ATTRIBUTE	DESCRIPTION
`url`	请求目标 URL. TYPE: `str`
`method`	HTTP 方法, 如 "GET", "POST" 等. TYPE: `HttpMethodType`
`params`	URL 查询参数字典. TYPE: `QueryParameterType \| None`
`headers`	HTTP 请求头字典. TYPE: `HeadersType \| None`
`cookies`	请求携带的 cookies 字典. TYPE: `CookiesType \| None`
`json`	当以 JSON 方式发送请求体时使用的对象. TYPE: `Any \| None`
`data`	原始请求体数据 (非 JSON 场景, 如表单、二进制等). TYPE: `BodyType \| AsyncBodyType \| None`
`kwargs`	透传给底层 HTTP 客户端的其它可选关键字参数字典. TYPE: `HttpRequestOptions \| None`
`credential`	可选的凭证对象, 优先于客户端的全局凭证. TYPE: `Credential \| None`

PaginatedCgiRequest `dataclass`

PaginatedCgiRequest(
    *,
    pager_strategy: PagerStrategy[RequestResultT],
    _client: Client,
    response_model: type[BaseModel] | None = None,
    disable_parse: bool = False,
    module: str,
    method: str,
    param: dict[str, Any],
    comm: dict[str, int | str | bool] | None = None,
    override_comm: bool = False,
    preserve_bool: bool = False,
    credential: Credential | None = None,
    require_login: bool = False,
    platform: Platform | None = None,
    sign: bool = False,
    allow_error_codes: AllowErrorCodes | None = None,
    parse_on_allow: bool = False,
)

Bases: CgiRequest[CgiRequestResultT], PaginatedMixin[CgiRequestResultT]

声明了连续翻页能力的 CGI 请求描述符.

通过组合 CgiRequest 与 PaginatedMixin, 赋予其自动跨页请求调度能力.

with_extractor

with_extractor(
    items_extractor: Callable[
        [CgiRequestResultT], Iterable[NewItemT]
    ],
) -> ItemPaginatedCgiRequest[CgiRequestResultT, NewItemT]

将当前分页请求转换为能够跨页提取数据项的请求.

PARAMETER	DESCRIPTION
`items_extractor`	数据项提取函数. TYPE: `Callable[[CgiRequestResultT], Iterable[NewItemT]]`

RETURNS	DESCRIPTION
`ItemPaginatedCgiRequest[CgiRequestResultT, NewItemT]`	转换后的带数据提取能力的连续翻页请求描述符.

Source code in qqmusic_api/core/request.py

def with_extractor(
    self, items_extractor: Callable[[CgiRequestResultT], Iterable[NewItemT]]
) -> "ItemPaginatedCgiRequest[CgiRequestResultT, NewItemT]":
    """将当前分页请求转换为能够跨页提取数据项的请求.

    Args:
        items_extractor: 数据项提取函数.

    Returns:
        转换后的带数据提取能力的连续翻页请求描述符.
    """
    from dataclasses import fields

    kwargs = {f.name: getattr(self, f.name) for f in fields(self)}
    return ItemPaginatedCgiRequest(**kwargs, items_extractor=items_extractor)

ItemPaginatedCgiRequest `dataclass`

ItemPaginatedCgiRequest(
    *,
    items_extractor: Callable[
        [CgiRequestResultT], Iterable[ItemT_co] | None
    ],
    pager_strategy: PagerStrategy[RequestResultT],
    _client: Client,
    response_model: type[BaseModel] | None = None,
    disable_parse: bool = False,
    module: str,
    method: str,
    param: dict[str, Any],
    comm: dict[str, int | str | bool] | None = None,
    override_comm: bool = False,
    preserve_bool: bool = False,
    credential: Credential | None = None,
    require_login: bool = False,
    platform: Platform | None = None,
    sign: bool = False,
    allow_error_codes: AllowErrorCodes | None = None,
    parse_on_allow: bool = False,
)

Bases: CgiRequest[CgiRequestResultT], ItemPaginatedMixin[CgiRequestResultT, ItemT_co]

声明了跨页数据项提取能力的连续翻页请求描述符.

通过组合 CgiRequest 与 ItemPaginatedMixin, 同时具备网络请求、翻页调度与条目流式展开能力.

request

core.request

BaseRequest dataclass

CgiRequestOptions

CgiRequest dataclass