python3-cookbook: a Python 3.6 era translation with Sphinx docs on Read the Docs
Python Cookbook, 3rd Edition - Chinese translation.
At a glance
- What is it?
- A community Chinese translation of the third edition of the Python Cookbook, examined through the mechanics that shape it: a theme that depends on an environment variable, a Makefile where paper size is a variable, a PDF that lives on an external file host, and a contribution guide that steers pull requests away from master.
- Who is it for?
- Use it as a readable Python 3 reference in Chinese and as a working reStructuredText and Sphinx corpus if you are building documentation. Do not treat it as current Python guidance, and do not count on the repository for offline copies.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 54 days ago.
- What is it written in?
- Mainly Jupyter Notebook, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- yidao620c/python3-cookbook12,023 ★ · +9
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| yidao620c/python3-cookbook | 12k | 12k |
9 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The theme is chosen by whether READTHEDOCS is set to the string True
The documentation build decides which theme to use by asking whether it is running on Read the Docs, not by asking where the build is happening. The check reads the READTHEDOCS environment variable and compares it to the string 'True'.
# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# otherwise, readthedocs.org uses their theme by default, so no need to specify itIf the variable is absent or set to anything other than that exact value, the build counts as local, imports sphinx_rtd_theme and points html_theme and html_theme_path at it. If it is set, the import is skipped because the hosting platform supplies the theme itself. The theme in play is the one used by the official Python documentation, and it is also this project's default. What the arrangement cannot do is let a local build reproduce the hosted rendering, since the two branches take opposite actions on purpose. The comparison is also an equality test against a string rather than a truthiness check, so a value such as 'true' or '1' is treated as a local build and imports sphinx_rtd_theme.
Paper size is a make variable, and the i18n builder refuses to share doctrees
The Makefile exposes paper size as a variable rather than a constant, which is what lets one source tree produce both A4 and letter output. Four variables are declared and can be set from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = buildTwo derived options follow from them, one per paper size, and the main option string composes the doctree directory, whichever paper option matches the value of PAPER, the extra options, and the source directory.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sourceThe build carries a guard that aborts early with a long error naming three ways out if sphinx-build is not on the machine. Targets cover standalone HTML files, HTML split across directories, one large single HTML file, pickle and json output, help projects in several formats, epub, and latex, where setting PAPER=a4 or PAPER=letter selects the size. One option is deliberately kept separate.
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sourceIt omits the doctree directory because the i18n builder cannot share the environment and doctrees with the other builders. For a project whose whole purpose is a translated book, that comment is the one place the translation is treated as a first class build concern.
The PDF edition lives on an external file host, and the build instructions were moved off the project
The book can be read online with nothing installed, but the downloadable PDF is not part of this repository. The hosted preview sits at python3-cookbook.readthedocs.org under the zh_CN locale and is built on Read the Docs. For the 3.0.0 edition, two PDF links are given on Baidu Pan, one for simplified Chinese and one for traditional Chinese, and nothing in the tree produces them. The gap is acknowledged rather than hidden. A reader asked how to generate a PDF from the sources was answered with a blog post on the maintainer's own site that covers both hosting through Read the Docs and producing the PDF locally, with an explicit note that the procedure is too long to sit in the README. Separately, for the automatic heading numbering in the generated PDF, a contributor named CarlKing5019 proposed a solution, which the README points to in issue number 108. What this arrangement cannot do is give you a versioned offline copy that travels with the source. Offline access depends on an external host, the versioned artifacts are release tags rather than documents, and the newest of those tags, 3.0.0, is dated 2017-12-07 while the README still presents that edition as current.
Every recipe was checked against Python 3.6, and the newest tag predates the newest commit by years
The translation states its interpreter target plainly: all code in the book was run and passed under Python 3.6, with the sources placed under the cookbook package. That pin is the honest limit on how far the recipes travel. The repository is not archived and the last commit landed on 2026-09-22, so editing continues, but the release trail stopped long before that: 3.0.0 on 2017-12-07, 2.0.0 on 2016-04-01, and 1.0.2 on 2016-01-21. So a reader on a current interpreter gets prose that has been touched recently and code whose behaviour was confirmed against an older release. The top level contains a .travis.yml, but source does not show it re-running the recipes against newer Python versions. For a recipe that depends on standard library behaviour which has moved on, the only warning you get is the failure itself, which is why the 3.6 statement deserves to be read as a constraint rather than as a historical detail.
Pull requests are steered away from master, and no rule says which content directory to edit
Contribution is routed away from the branch most people open first. Pull requests sent directly to master are marked as not recommended, and develop is named as the more appropriate target. Contributors are also asked to follow common Python coding conventions and to add the license header to each source file, which makes the license a per-file obligation rather than a single top-level file. The listed ways to help are broader than code: forking and opening pull requests, adding or editing wiki pages, reporting or fixing an issue, code review, committing a new feature, and adding a testcase. The testcase line sits oddly against the rest of the repository. The top level holds .gitignore, .travis.yml, the Makefile, README.md, README_en.md, a cookbook directory, an exts directory, make.bat, a notebook directory, an image called qcode.jpg, requirements_.txt, and a source directory. What the guidelines cannot do is tell a newcomer where new content belongs. Neither the cookbook directory, the source directory nor the notebook directory is named in the contribution rules, so the first contribution is a guess about file placement even when the recipe itself is correct.
Apache 2.0 covers the repository, and the translated text has no license of its own stated
The licensing picture has two layers and only one is written down. The repository carries the Apache License, Version 2.0, with copyright 2014-2018 to Xiong Neng and other contributors, and each source file is expected to repeat that header. The content, though, is a translation of a third edition book written by David Beazley and published by O'Reilly Media. Beazley is described as an independent computer scientist and educator with 35 years of development experience, active in the Python community with his own packages, recorded talks and tutorials, and author of both Python Essential Reference and the cookbook itself. Nothing here states a license for the translated Chinese text separate from the repository-level Apache grant, and nothing says which edition or which scope of the underlying book the rights holder considers covered. For a reader planning to reuse the prose, that omission is the whole answer: the repository license governs the translation effort as a repository, and the terms covering the source book are not restated in it. The translator's note handles a different risk, taking responsibility for each line while acknowledging that mistakes and unclear phrasing slipped through and inviting corrections.
Content is split across notebook, cookbook and source directories with no stated source of truth
Content lives in more than one place and no directory is nominated as authoritative. The primary language recorded for the repository is Jupyter Notebook, and a notebook directory holds files in that form. Alongside it sit a cookbook directory holding the book's source code, a source directory holding the reStructuredText the documentation is built from, and an exts directory for extensions. The project statement says all documents are edited in reStructuredText, which points a contributor at the source directory, while the notebooks remain what a reader sees first when browsing the repository. A make.bat sits next to the Makefile so the same targets are reachable on Windows, and there is a requirements_.txt with an underscore in the name. What the layout cannot do is keep the two content formats in step. With notebooks and reStructuredText both present and no note describing how they relate, an edit made in one place has no documented route into the hosted build, and the preview at the readthedocs address will keep serving whatever the Sphinx tree currently holds. The practical consequence for a reader is that corrections need to go through a build rather than through the hosting site, which is why the reStructuredText and Sphinx setup is the part of this repository worth understanding before contributing anything.
Editorial conclusion
Use it as a readable Python 3 reference in Chinese and as a working reStructuredText and Sphinx corpus if you are building documentation. Do not treat it as current Python guidance, and do not count on the repository for offline copies. Before you rely on it, check whether the recipe you need touches library behaviour that has changed since Python 3.6, decide whether source/ or notebook/ is the place your edit belongs, and expect to build the documentation yourself since the PDFs are hosted elsewhere.
Frequently asked questions
What is a cookbook in programming?
This repository is a community Chinese translation of Python Cookbook 3rd Edition, a book by David Beazley published by O'Reilly Media. All code in it was run under Python 3.6 and the sources sit under the cookbook package.
What is the purpose of a cookbook?
The translator's stated purpose was Python 3 adoption: most manuals available at the time were in the 2.x series and few were based specifically on 3.x, so the third edition was chosen to fill that gap. The whole book was translated over a period of two years.
Where can I learn Python 3 for free?
The translated edition is readable online at python3-cookbook.readthedocs.org under the zh_CN locale, hosted on Read the Docs, and the README also links PDF downloads on Baidu Pan for simplified and traditional Chinese.
What is the best textbook for learning Python?
The repository does not rank textbooks. Its argument is narrower: the third edition of Python Cookbook is written entirely against Python 3, unlike the 2.x material that dominates most tutorials and manuals, and its code was verified under Python 3.6.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/yidao620c-python3-cookbook)Star history chart for your README
[](https://hysenlabs.com/projects/yidao620c-python3-cookbook)Was this useful?