data — 官方开奖数据

从 cwl.gov.cn 与 lottery.gov.cn 官方网站拉取 8 个彩种的历史开奖数据，输出统一格式的 pandas.DataFrame。

data

Attributes

lottery_pool module-attribute

lottery_pool = _cl.cl_projects

load_history_data module-attribute

load_history_data = _cl.load_history_data

load_random_data module-attribute

load_random_data = _cl.load_random_data

Classes

ChinaWelfareLottery

ChinaWelfareLottery()

Bases: Tse

Methods:

check_params

check_params(lottery_name: str, begin_date: str, end_date: str) -> tuple

校验并规整福彩系请求参数。

Parameters:

Name	Type	Description	Default
lottery_name	str	str, must in ('ssq', 'qlc', 'kl8', '3d').	required
begin_date	str	str, 起始日期（含）。	required
end_date	str	str, 结束日期（含）。	required

Returns:

Type	Description
tuple	tuple, 规整后的 (lottery_name, begin_date, end_date)：日期范围收敛到 各彩种最早可得日期与今天。

cwl

cwl(lottery_name: str = 'ssq', begin_date: str = '2013-01-01', end_date: str = '3022-01-01', **kwargs) -> Union[list, DataFrame]

https://www.cwl.gov.cn http://www.cwl.gov.cn/fcpz/yxjs

Parameters:

Name	Type	Description	Default
lottery_name	str	str, must in ('ssq', 'qlc', 'kl8', '3d'). # 双色球、七乐彩、快乐8、福彩3D	'ssq'
begin_date	str	str, eg: '2022-01-01'.	'2013-01-01'
end_date	str	str, eg: '2022-01-01'.	'3022-01-01'
**kwargs		:param is_detail_result: boolean, default False. :param timeout: float, default 15. :param max_retries: int, default 3. :param proxies: dict, default None. :param sleep_seconds: float, default random.random().	{}

Returns:

Type	Description
Union[list, DataFrame]	list or pandas.DataFrame

ChinaSportsLottery

ChinaSportsLottery()

Bases: Tse

Methods:

get_params

get_params(game_no: str = '85', page_no: int = 1) -> dict

构造体彩分页查询参数。

Parameters:

Name	Type	Description	Default
game_no	str	str, 体彩游戏编号（官方接口的 gameNo）。	'85'
page_no	int	int, 页码，从 1 起。	1

Returns:

Type	Description
dict	dict, 官方接口所需的查询参数。

csl_warmup

csl_warmup(timeout: float, proxies: Optional[dict], max_retries: int) -> int

建立会话并探测体彩历史总页数（幂等；返回总页数，调用方据此翻页）。

csl

csl(lottery_name: str = 'dlt', **kwargs) -> Union[list, DataFrame]

https://www.lottery.gov.cn https://www.lottery.gov.cn/bzzx/yxgz 大乐透、排列3、排列5、7星彩、双色球、七乐彩、快乐8、福彩3D

Parameters:

Name	Type	Description	Default
lottery_name	str	str, must in ('dlt', 'pls', 'plw', 'qxc'). # 大乐透、排列3、排列5、7星彩	'dlt'
**kwargs		:param is_detail_result: boolean, default False. :param timeout: float, default 15. :param max_retries: int, default 3. :param proxies: dict, default None. :param sleep_seconds: float, default random.random().	{}

Returns:

Type	Description
Union[list, DataFrame]	list or pandas.DataFrame

ChinaLottery

ChinaLottery()

Bases: ChinaWelfareLottery, ChinaSportsLottery

Methods:

load_history_data

load_history_data(lottery_name: str, **kwargs) -> Union[list, DataFrame]

Load draw history for all 8 games as a tidy DataFrame.

Fetches from the official websites (cwl.gov.cn / lottery.gov.cn) with retry/backoff; supports incremental CSV caching.

中文说明

拉取 8 个彩种（大乐透/排列3/排列5/7星彩/双色球/七乐彩/快乐8/福彩3D） 的历史开奖数据，输出统一列结构的 DataFrame （lottery_name / lottery_order / lottery_date / lottery_red / lottery_blue）。

• if_cached=True 启用本地 CSV 缓存与增量更新（目录默认 ~/.lotterycn/history，可用 cache_dir 或环境变量 lotterycn_cache_dir 覆盖）；
• 福彩系支持 begin_date 日期区间增量，体彩系全量刷新后去重。

Parameters:

Name	Type	Description	Default
lottery_name	str	str, must in ('dlt', 'pls', 'plw', 'qxc', 'ssq', 'qlc', 'kl8', '3d').	required
**kwargs		:param is_detail_result: boolean, default False. :param if_cached: boolean, default False. Enable local CSV cache + incremental update. :param cache_dir: str, default None (~/.lotterycn/history). :param begin_date: str, welfare games only. :param timeout: float, default 15. :param max_retries: int, default 3. :param proxies: dict, default None. :param sleep_seconds: float, default random.random().	{}

Returns:

Type	Description
Union[list, DataFrame]	list or pandas.DataFrame

load_random_data

load_random_data(lottery_name: str = 'ssq', amount: int = 1, **kwargs) -> Union[list, DataFrame]

https://www.lottery.gov.cn, https://www.cwl.gov.cn https://www.lottery.gov.cn/bzzx/yxgz, https://www.cwl.gov.cn/fcpz/yxjs 大乐透、排列3、排列5、7星彩、双色球、七乐彩、快乐8、福彩3D

Parameters:

Name	Type	Description	Default
lottery_name	str	str, default 'ssq'. must in ('dlt', 'pls', 'plw', 'qxc', 'ssq', 'qlc', 'kl8', '3d')	'ssq'
amount	int	int, default 1.	1
**kwargs		:param is_detail_result: boolean, default False.	{}

Returns:

Type	Description
Union[list, DataFrame]	list or pandas.DataFrame

get_random_base

get_random_base(k: int, max_n: int, min_n: int = 1, if_sort: bool = True, if_str: bool = True) -> Union[str, list]

基础随机采样：从 [min_n, max_n] 中不重复抽取 k 个。

Parameters:

Name	Type	Description	Default
k	int	int, 抽取个数。	required
max_n	int	int, 号码上限。	required
min_n	int	int, optional, 号码下限，默认 1。	1
if_sort	bool	bool, optional, 是否升序排序，默认 True。	True
if_str	bool	bool, optional, True 返回逗号连接字符串，False 返回 list，默认 True。	True

Returns:

Type	Description
Union[str, list]	Union[str, list], 采样结果。

get_random_lottery

get_random_lottery(lottery_name: str = 'ssq') -> list

按彩种规则生成一注随机号码（范围 / 去重 / 红蓝分区 / 位数）。

Parameters:

Name	Type	Description	Default
lottery_name	str	str, 彩种代码。	'ssq'

Returns:

Type	Description
list	list, 各区号码（与 data.py 的 lottery_red / lottery_blue 拆分一致）。

get_random_data_dataframe

get_random_data_dataframe(data_list: list, lottery_name: str, amount: int) -> DataFrame

把随机号码列表规整为与历史开奖同列结构的 DataFrame。

Parameters:

Name	Type	Description	Default
data_list	list	list, get_random_lottery 产出的号码列表。	required
lottery_name	str	str, 彩种代码。	required
amount	int	int, 注数。	required

Returns:

Type	Description
DataFrame	pandas.DataFrame, 列与 cl_cols 一致（lottery_order 为 0..amount-1）。

get_history_data_dataframe

get_history_data_dataframe(data_frame: DataFrame, lottery_name: str) -> DataFrame

把官方接口原始记录规整为统一列结构的历史 DataFrame。

Parameters:

Name	Type	Description	Default
data_frame	DataFrame	pandas.DataFrame, 官方接口返回的原始记录。	required
lottery_name	str	str, 彩种代码（体彩系需从空格分隔串拆分前区/后区列）。	required

Returns:

Type	Description
DataFrame	pandas.DataFrame, 列与 cl_cols 一致。