request

core.request

请求描述符与分页请求容器. 只描述请求内容, 不构造参数或解析响应.

RequestExecutor

Bases: Protocol

执行绑定请求描述符所需的最小接口.

credential `property`

credential: Credential

返回默认凭证.

platform `property`

platform: Platform

返回默认平台.

version_policy `property`

version_policy: VersionPolicy

返回请求使用的版本策略.

execute `async`

execute(request: BaseRequest[ResultT]) -> ResultT

执行请求并返回解析结果.

Source code in qqmusic_api/core/request.py

async def execute(self, request: "BaseRequest[ResultT]") -> ResultT:
    """执行请求并返回解析结果."""
    ...

BaseRequest `dataclass`

BaseRequest(
    *,
    _executor: RequestExecutor,
    response_model: type[BaseModel] | None = None,
)

Bases: Generic[ResultT]

请求描述符基类.

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

ATTRIBUTE	DESCRIPTION
`_executor`	请求绑定的执行器, 用于调度请求. TYPE: `RequestExecutor`
`response_model`	期望的响应模型类型, 支持 Pydantic BaseModel. TYPE: `type[BaseModel] \| None`

CgiRequestOptions

Bases: TypedDict

CGI 请求专用的可选配置.

CgiRequest `dataclass`

CgiRequest(
    *,
    _executor: RequestExecutor,
    response_model: type[BaseModel] | None = None,
    module: str,
    method: str,
    param: dict[str, Any],
    comm: dict[str, Any] | 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`	可选的公共参数. 值在发送前转换为字符串; 合并模式下的 None 或空字符串会删除同名默认参数. TYPE: `dict[str, Any] \| None`
`override_comm`	若为 True, 则直接使用 `comm` 作为公共参数而不合并默认值. TYPE: `bool`
`preserve_bool`	是否在参数中保留布尔值 (而非转换为整型等). TYPE: `bool`
`allow_error_codes`	允许的错误码集合, 如果响应中包含这些错误码, 将不会抛出异常. TYPE: `AllowErrorCodes \| None`
`parse_on_allow`	当响应包含允许的错误码时, 是否仍尝试解析响应数据. TYPE: `bool`
`credential`	可选的凭证对象, 优先于客户端的全局凭证. TYPE: `Credential \| None`
`require_login`	请求是否需要凭证. TYPE: `bool`
`platform`	可选的平台标识, 优先于客户端的全局平台设置. TYPE: `Platform \| None`
`sign`	指示该请求是否需要签名处理. TYPE: `bool`

HttpRequestOptions

Bases: TypedDict

HTTP 请求专用的可选配置.

HttpRequest `dataclass`

HttpRequest(
    *,
    _executor: RequestExecutor,
    response_model: type[BaseModel] | None = None,
    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,
    raw: bool = False,
)

Bases: BaseRequest[HttpRequestResultT]

标准 HTTP 请求描述符.

用于封装直接透传到统一传输边界的请求元数据.

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`
`raw`	是否返回原始载荷快照 (RawPayload) 而非解析结果; 快照为值语义, 无需释放. TYPE: `bool`

PaginatedCgiRequest `dataclass`

PaginatedCgiRequest(
    *,
    pager_strategy: PagerStrategy[RequestResultT],
    _executor: RequestExecutor,
    response_model: type[BaseModel] | None = None,
    module: str,
    method: str,
    param: dict[str, Any],
    comm: dict[str, Any] | 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) if f.name != "items_extractor"}
    return ItemPaginatedCgiRequest(**kwargs, items_extractor=items_extractor)

ItemPaginatedCgiRequest `dataclass`

ItemPaginatedCgiRequest(
    *,
    items_extractor: Callable[
        [CgiRequestResultT], Iterable[ItemT_co] | None
    ],
    pager_strategy: PagerStrategy[RequestResultT],
    _executor: RequestExecutor,
    response_model: type[BaseModel] | None = None,
    module: str,
    method: str,
    param: dict[str, Any],
    comm: dict[str, Any] | 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: PaginatedCgiRequest[CgiRequestResultT], ItemPaginatedMixin[CgiRequestResultT, ItemT_co]

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

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

with_extractor

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

替换当前的数据项提取函数并返回新的请求对象.

Source code in qqmusic_api/core/request.py

def with_extractor(
    self, items_extractor: Callable[[CgiRequestResultT], Iterable[NewItemT]]
) -> "ItemPaginatedCgiRequest[CgiRequestResultT, NewItemT]":
    """替换当前的数据项提取函数并返回新的请求对象."""
    from dataclasses import fields

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

request

core.request

RequestExecutor

credential property

platform property

version_policy property

execute async

BaseRequest dataclass

CgiRequestOptions

CgiRequest dataclass

HttpRequestOptions

HttpRequest dataclass

PaginatedCgiRequest dataclass

with_extractor

ItemPaginatedCgiRequest dataclass

with_extractor

credential `property`

platform `property`

version_policy `property`

execute `async`

BaseRequest `dataclass`

CgiRequest `dataclass`

HttpRequest `dataclass`

PaginatedCgiRequest `dataclass`

ItemPaginatedCgiRequest `dataclass`