Skip to content
UlionTsePublic

About

A Python library for enjoyable analysis of Chinese welfare & sports lotteries. 一个有趣好玩的中国福利彩票与体育彩票分析库。

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

128 stars

Watchers

1 watching

Forks

Repository files navigation

LotteryCN

LotteryCN

A Python library for enjoyable analysis of Chinese welfare & sports lotteries — official draw data, combinatorial odds & expected value, number-picking strategies with backtesting, and winning checks.

Documentation · 中文文档

CI Docs PyPI - Version Conda - Version PyPI - License PyPI - Python Downloads

English | 简体中文

Table of Contents


Why LotteryCN

  • Official data only — winning numbers and draw details (sales, prize pools, per-level results, province distribution) come straight from official channels; no third-party scrapers.
  • Combinatorial math for probabilities & expectations — exact prize-tier counts; current prize tiers, conditions and amounts in one auditable config with source URLs; probabilities, expected values and return rates derived from official prize tables, plus instant ticket checking.
  • Number-picking strategies & backtesting (core) — 11 strategies + a composable shrink engine + built-in rolling backtest; the backtest keeps proving every strategy matches the random baseline in expected value.
  • Full pipeline — collect (cached incrementally) → analyze → predict → backtest → check.

Supported Games, Strategies & Data Sources

Games

Code Game Operator Notes
ssq 双色球 (Double Color Ball) Welfare 6 red (1-33) + 1 blue (1-16)
qlc 七乐彩 (7 Happy Lotto) Welfare 7 from 30 + special number
kl8 快乐8 (Happy 8) Welfare 20 drawn from 80, pick 1-10
3d 福彩3D (Welfare 3D) Welfare 3-digit positional
dlt 超级大乐透 (Super Lotto) Sports 5 front (1-35) + 2 back (1-12)
pls 排列3 (P3) Sports 3-digit positional
plw 排列5 (P5) Sports 5-digit positional
qxc 7星彩 (7 Star Lotto) Sports 6-digit front (0-9) + last digit (0-14)

Strategies

lotterycn.predict ships eleven number-generation strategies plus a composable filter engine. None of them has any predictive power — draws are independent random events, so every strategy has exactly the same expected value as the random baseline. Full details: the Strategies page.

Method Aliases School Idea
random — baseline Uniform random — the baseline every strategy is compared against
frequency hot / cold trend charts Pick by frequency over a sliding window (recent_n); explore_ratio controls determinism
omission chase trend charts Mean-reversion chase: current omission / average omission
deviation chisq statistics Chi-square deviation (observed − expected)² / expected; side='hot' or 'cold'
repeat — community Repeat / neighbor (±1) / jump (second-last draw ±1) weighting
trend — stock framework Sum moving-average channel: keep candidates whose sum falls inside MA ± k·σ
tail — trend charts Two-level picks: tail digits by frequency, then numbers within those tails
markov — sequence First-order transition sampling — collapses to frequency under independence
markov2 — sequence Second-order transition (last two draws, 4 states)
filter — shape school Composable shrink: sum / odd / prime / AC value / consecutive ranges, exact-match zone ratio & 012-route, kill numbers
ensemble — integration Multi-strategy voting: members each contribute a top-k ticket, numbers ranked by votes

Honest disclaimer: historical statistics cannot predict future draws — play rationally.

Data Sources

All rules and draw data come from official channels only:

Rule and data sources exclude all company-operated portals (see CONTRIBUTING.md); the rule versions currently implemented are cited with URLs in lotterycn/config.py.

Installation

pip install --upgrade lotterycn
conda install -c conda-forge lotterycn

Requires Python 3.10 – 3.15.

Quickstart

One full pipeline — collect (cached & refreshed incrementally) → analyze → predict → backtest → check:

import lotterycn

df_ssq = lotterycn.load_history_data(lottery_name='ssq', if_cached=True, sleep_seconds=0.1)
stats = lotterycn.load_number_statistics(lottery_name='ssq', history=df_ssq)
print(lotterycn.load_prize_expectation(lottery_name='ssq'))

picks = lotterycn.load_predict_numbers(lottery_name='ssq', method='hot', amount=5)
results = lotterycn.backtest(lottery_name='ssq', methods=('random', 'hot'), window=10)
print(lotterycn.backtest_summary(results=results))

print(lotterycn.load_check_result(lottery_name='ssq', my_number='01,05,12,18,27,33|08', if_cached=True))

Every strategy matches random in expected value — the backtest above reproduces this conclusion every time; any "significantly better than random" observation is overfitting or noise. Ticket formats follow the published draw results; per-game play types (kl8 pick=1..10, dlt if_pool_over_800m / if_add_bet, compound bets) and all other parameters are documented in the API Reference.

Command Line

The package installs a lotterycn console script (also available as python -m lotterycn.cli):

lotterycn odds ssq
lotterycn expect dlt --pool-over-800m
lotterycn predict ssq --method hot --amount 5 --cached
lotterycn check ssq \
  --number '01,05,12,18,27,33|08' \
  --draw '01,05,12,18,27,33|08'

--cached reads the local cache and refreshes it incrementally (first run requires network).

Contributions are welcome — see CONTRIBUTING.md. For local checks: pip install pytest ruff && pytest (offline; network tests via pytest -m network).

License

MIT

Disclaimer

This project is for data analysis and educational purposes only. It is not affiliated with any lottery operator. Lottery data and rules may change at any time; always refer to official announcements. Play rationally — lotteries are for adults (18+) and should never be treated as an investment.

About

A Python library for enjoyable analysis of Chinese welfare & sports lotteries. 一个有趣好玩的中国福利彩票与体育彩票分析库。

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

128 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages