draws — Draw details¶

Full official announcement fields: sales, prize pool, winner counts and per-bet prizes per level, first-prize distribution by province — three tidy tables with incremental caching.

draws ¶

开奖详情：销售额、奖池、各奖级中奖注数与单注奖金、一等奖省级分布。

数据来源与 data.py 相同（cwl.gov.cn / lottery.gov.cn 官方网站），只是保留并归一化了原本被丢弃的字段，输出三张 tidy 表：

detail 宽表（每期一行）：期号 / 日期 / 号码 / 销售额 / 奖池 prizes 长表（期 × 奖级）：中奖注数、单注奖金（dlt 含追加档，未开出的单注奖金为 NaN） province 长表（期 × 省）：一等奖省级分布（仅 ssq / qlc / kl8 提供，3d 官网接口恒为空）

仅供娱乐，不构成任何预测力

这些字段刻画的是当期开奖结果与资金面，可作为特征工程的原材料，但它们由同一期随机开奖决定，与未来开奖号码之间不存在因果信息。请理性购彩。

Functions:¶

load_draw_detail ¶

load_draw_detail(lottery_name: str, records=None, if_cached: bool = False, cache_dir: Optional[str] = None, **fetch_kwargs) -> DataFrame

返回宽表（每期一行）：期号 / 开奖日期 / 号码 / 销售额 / 奖池累计金额。

Parameters:

Name	Type	Description	Default
`lottery_name`	`str`	str, 彩种代码。	required
`records`		list, 显式传入原始开奖记录（离线使用）；为 None 时联网拉取。	`None`
`if_cached`	`bool`	boolean, 启用本地 CSV 缓存与增量更新。	`False`
`cache_dir`	`Optional[str]`	str, optional, 缓存目录；None 时取环境变量或默认值。	`None`
`**fetch_kwargs`		透传给 load_history_data（timeout / max_retries / proxies 等）。	`{}`

Returns:

Type	Description
`DataFrame`	pandas.DataFrame, 宽表（每期一行）：期号 / 开奖日期 / 号码 / 销售额 / 奖池累计金额。

load_prize_results ¶

load_prize_results(lottery_name: str, records=None, if_cached: bool = False, cache_dir: Optional[str] = None, **fetch_kwargs) -> DataFrame

返回长表（期 × 奖级）：各奖级中奖注数与单注奖金。

dlt 含追加档（prize_level 带"(追加)"）；未开出的奖级单注奖金为 NaN； 3d 官网接口不提供奖级数据，返回空表。

Parameters:

Name	Type	Description	Default
`lottery_name`	`str`	str, 彩种代码。	required
`records`		list, 显式传入原始开奖记录（离线使用）；为 None 时联网拉取。	`None`
`if_cached`	`bool`	boolean, 启用本地 CSV 缓存与增量更新。	`False`
`cache_dir`	`Optional[str]`	str, optional, 缓存目录；None 时取环境变量或默认值。	`None`
`**fetch_kwargs`		透传给 load_history_data（timeout / max_retries / proxies 等）。	`{}`

Returns:

Type	Description
`DataFrame`	pandas.DataFrame, 长表（期 × 奖级）：中奖注数与单注奖金。

load_first_prize_by_province ¶

load_first_prize_by_province(lottery_name: str, records=None, if_cached: bool = False, cache_dir: Optional[str] = None, **fetch_kwargs) -> DataFrame

返回长表（期 × 省）：一等奖省级分布及注数。

仅部分玩法提供（ssq / qlc / kl8 的 content 字段），其余彩种返回空表。

Parameters:

Name	Type	Description	Default
`lottery_name`	`str`	str, 彩种代码。	required
`records`		list, 显式传入原始开奖记录（离线使用）；为 None 时联网拉取。	`None`
`if_cached`	`bool`	boolean, 启用本地 CSV 缓存与增量更新。	`False`
`cache_dir`	`Optional[str]`	str, optional, 缓存目录；None 时取环境变量或默认值。	`None`
`**fetch_kwargs`		透传给 load_history_data（timeout / max_retries / proxies 等）。	`{}`

Returns:

Type	Description
`DataFrame`	pandas.DataFrame, 长表（期 × 省）：一等奖省级分布及注数。