python3-cookbook: A Chinese Translation of Python Cookbook 3rd Edition

What yidao620c/python3-cookbook actually is

This repository is not a library you import. It is the source tree for a Chinese translation of the third edition of Python Cookbook, the O'Reilly book by David Beazley. The README opens with the announcement that the Chinese edition was released on 2017/12/07, and it points readers to an online copy at python3-cookbook.readthedocs.org/zh_CN/latest/. The translator explains the motivation plainly: most tutorials and manuals available at the time covered the 2.x series, and books written specifically for 3.x were scarce, so the goal was to make a Python 3 book available to Chinese-speaking readers. That framing tells you the audience. If you read Chinese and want worked recipes rather than a language tutorial, this is the intended reader. If you do not read Chinese, the translated prose is closed to you, though the code samples are still Python and the repository ships README_en.md for the English-facing part of the project. The scope is the whole book, and the README states the translation was completed over roughly two years.

How the documentation is built: Sphinx, reStructuredText and Read the Docs

The mechanism here is a standard Sphinx documentation pipeline, and the repository layout confirms it: a source/ directory, a Makefile, make.bat, a requirements_.txt, and an exts/ folder. The README says all documents are edited in reStructuredText and that the generated documentation is hosted on Read the Docs. It also names the theme, sphinx-rtd-theme, which is the same theme the Python project uses. The README quotes the conf.py fragment that switches themes depending on where the build runs, checking the READTHEDOCS environment variable and importing sphinx_rtd_theme only when the build is local. That is the whole data flow: reStructuredText sources in source/ become HTML on Read the Docs, and the same sources can become a PDF through the Makefile's latexpdf target. The Makefile itself is the stock Sphinx template, with targets for html, epub, latex, latexpdf, text, man and linkcheck, and it aborts early if sphinx-build is not on PATH. Nothing about this is bespoke, which is a point in its favour for anyone who has built Sphinx docs before. It is also the reason the project ages the way it does: a Sphinx tree from the 3.0.0 era carries the assumptions of that era.

Installing and building the docs locally

There is no package to install and no pip install line in the README, because this is a documentation project. What you install is the toolchain. The README's only dependency hint is requirements_.txt, and the Makefile expects sphinx-build to exist, so a virtual environment plus Sphinx is the starting point. Clone the repository, create an environment, install the requirements file, then run the html target.

git clone https://github.com/yidao620c/python3-cookbook.git
cd python3-cookbook
python -m venv .venv
source .venv/bin/activate
pip install -r requirements_.txt
make html

After make html finishes, the generated site lands under the build directory that the Makefile defines, and you open the index page from there in a browser. If sphinx-build is missing, the Makefile stops with an error telling you to install Sphinx or point the SPHINXBUILD variable at the executable, so a failed first run almost always means the requirements step was skipped. On Windows, make.bat is present for the same targets.

For a PDF rather than HTML, the Makefile provides latexpdf, and the README notes that PDF generation is long enough that the author wrote a separate blog post about hosting on Read the Docs and building the PDF yourself. It also records a known annoyance: title numbering that appears automatically in the generated PDF, with a workaround contributed in issue #108. If you only want to read the book, skip all of this and use the Read the Docs site.

The Python 3.6 constraint and what it means for the recipes

The README states directly that all code in the book was run under Python 3.6, and the sources live in the cookbook/ package. That single sentence is the most important limitation on the page. A recipe book is only as current as the interpreter it was validated against, and Python 3.6 is old enough that some idioms in the text read as period pieces rather than advice. The translation itself is stable: it is a book, and books do not get refactored. The repository still receives pushes (the last push was on 2026-09-12), but the release history tells a different story, with 3.0.0 tagged on 2017-12-07 and nothing newer. So you are reading a finished artifact that gets occasional housekeeping, not a living reference. Practically, that means recipes involving standard library modules are usually still correct, while anything touching newer language features simply will not appear, because the book predates them. If you are learning Python today, treat the recipes as patterns and check the current standard library documentation for the modules they use. If you are maintaining code written for 3.6, the match is closer.

Licence and the cost of forking it

The README puts the project under the Apache License, Version 2.0, with copyright from 2014 to 2018 held by Xiong Neng and other contributors, and it asks contributors to add that licence header to each source file. The badge at the top of the README links to the same Apache 2.0 text. One caveat sits outside the repository's control: the underlying book is an O'Reilly publication by David Beazley, and the repository's licence covers the translation sources, not the original work. That distinction matters if you plan to redistribute the text or the generated PDF. The README does not discuss the book publisher's terms, so anyone republishing at scale should look at the original rights before assuming Apache 2.0 settles the question. This is a description of what the repository states, not legal advice. For ordinary reading and for building your own PDF, the licence as stated is permissive, and the contribution rules are light: fork, open pull requests against the develop branch rather than master, follow common Python conventions, and add the licence header.

When a translation is the wrong tool

The obvious failure mode is language. If you do not read Chinese, this repository gives you code samples without the explanations that make a cookbook worth reading, and the recipe commentary is where the value sits. The README acknowledges this by shipping README_en.md, but that is the project's own English readme, not an English translation of the book. The second case is currency. Anyone who needs recipes for a modern interpreter, or who wants the book's later editions, will not find them here: the translation tracks the third edition, and the related searches for a fourth, fifth or sixth edition PDF point at material this repository does not contain. The third case is mechanical. If you want a pip-installable library, this is not one, and cloning it to get a dependency is a category error. The fourth is build friction: the Sphinx tree is from the 3.0.0 era, and while the Makefile is the standard template, a modern Sphinx install may not match the pinned requirements, so expect to adjust the environment rather than assume make html works on the first try.

Alternatives and how they differ

The direct alternative is the original English Python Cookbook, 3rd Edition from O'Reilly. The difference is not quality but access and language: the original is the source text, professionally edited and sold, while this repository is a volunteer translation of it, free to read on Read the Docs and free to rebuild locally. If English is not a barrier, the original gives you the author's exact wording, and the README itself points to David Beazley's site for his other work. A second alternative is the official Python documentation and its own recipe collections, which track the current interpreter and are updated with it. The trade-off is shape: the official docs are reference material organised by module, while a cookbook is organised by problem, which is why people reach for one. A third option is to read this repository's reStructuredText sources directly on GitHub without building anything, which gets you the text and the code with no Sphinx setup at all. That last path is the cheapest way to evaluate whether the translation suits you before you invest in a local build.

Who should clone it and who should close the tab

Clone it if you read Chinese and want the Python Cookbook 3rd Edition recipes in that language, either on the Read the Docs site or as a PDF you build yourself with make latexpdf. Clone it if you are comfortable on Python 3.6-era code and want a problem-indexed reference rather than a tutorial. Contribute if you want to fix translation errors; the README invites corrections and lists contributors, and it asks for pull requests against develop rather than master. Close the tab if you need English prose, if you need recipes validated against a recent interpreter, or if you are looking for an installable package. The one thing to verify first is the reading experience itself: open the Read the Docs site, pick a chapter that matches a problem you have right now, and see whether the translation and the 3.6-era code answer it. That check costs a few minutes and tells you more than any summary, because the value of a cookbook is entirely in whether its recipes fit the code you are writing.

Editorial conclusion

Adopt this translation if you read Simplified or Traditional Chinese and want a free, readable copy of the Python Cookbook 3rd Edition recipes, or if you want the reStructuredText sources to build your own PDF. Do not adopt it if you need English text, since the README points English readers to README_en.md and the recipe body is Chinese. Do not treat it as a maintained Python 3.13 reference either: the README states the code was run under Python 3.6, and the last push was on 2026-09-12, with the newest tagged release 3.0.0 from 2017-12-07. Before relying on it, open the chapter you care about at python3-cookbook.readthedocs.org/zh_CN/latest/ and check whether the recipe still matches your interpreter version.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. yidao620c/python3-cookbook on GitHub