On Zhihu, many people ask and care about reading the source code of open source projects, such as “what Pythonic source code is recommended for beginners to read?” “, “What Python projects on Github are suitable for newcomers to read? “, “How to read and learn the source code of some good open source frameworks? And so on. This article will discuss this topic in terms of recommending Python projects to read and how to read them.

There are three main reasons to read Python open-source project code:

I ran into some problems while working, and sites like Google and StackOverFlow couldn’t find a solution and had to dig through the source code.

Very interested in some project or direction and want to go further.

Learning bottlenecks need to learn from the experience and usage of open source projects to improve.

Reading open source projects without a purpose is going rogue. It’s a waste of time, but you learn very little. How to read according to their own situation?

It fits in with your interests and your job. For example, there is no chance to use Celery in work and not want to build a wheel by yourself, why read its source code? So choose from projects that you normally have access to. For me, I definitely don’t look at Django code, because I don’t see it in my daily work.

Just look at one or two typical ones in each direction. For Web frameworks, FOR example, I’ve only seen the source code for Bottle and Flask (I’ve seen Django before, only dabbled in it), and Bottle has been around for a few years now. It’s not that the heap is better, but sometimes too many choices will be confused.

For projects with different code volume and complexity at different technical stages, specific recommendations will be made below.

Be clear about why you’re looking at the code. Do you look at code to learn how it was designed, to debug bugs, or just to learn proper programming? There’s no need to go into every detail of the code, sometimes you just need to know the input and output when looking at the black box.

My personal preference

Similar to reading code at work, each person, project, and team has their own style of writing code, such as variable naming style, the use of certain language features, code specification requirements, directory style, etc. The same is true for authors of open source projects. Look at code, like people (teams). First, I would like to introduce my hobbies (ranked in order) :

Kennethreitz. Requests and Python-guide authors. He has a very inspirational story, interested can look at Who says that the programmer is not potential shares (https://zhuanlan.zhihu.com/p/22275595)

Mitsuhiko. Author of Flask, Jinja2, Werkzeug and Flask-SQLAlchemy.

Sigmavirus24. Major contributor and maintainer of Flake8, PyCodeStyle (formerly PEP8), Requests, URllib3, and more.

Ask. Celery and related dependencies.

Ajdavis. Major contributor to Mongo-Python-Driver (PyMongo), Tornado and other projects.

Bitprophet. Fabric, Paramiko (SSH library for Python) author. The first two are generally considered to be the best and most creative engineers writing Python code.

Recommended reading items for beginners

Beginners can start by reading some small code, preferably a single file project:

GitHub – kennethreitz/pip-pop: Tools for managing requirements files.

GitHub – kennethreitz/envoy: Python Subprocesses for Humans™.

GitHub – kennethreitz/records: SQL for Humans™

GitHub – mitsuhiko/pluginbase: A simple but flexible plugin system for Python.

GitHub – mitsuhiko/pipsi: pip script installer

GitHub – mitsuhiko/unp: Unpacks things.

GitHub – chrisallenlane/cheat

GitHub – jek/blinker: A fast Python in-process signal/event dispatching system.

GitHub – mitsuhiko/platter: A useful helper for wheel deployments.

GitHub – kennethreitz/tablib: Python Module for Tabular Datasets in XLS, CSV, JSON, YAML, &c. The point of looking at code is to understand how other people write code, syntax practices and so on. After reading this, you can write your own project for the problems that these projects can solve, and then compare it to the above project to see what did not work well.

Advanced reading projects

As you advance, read some relatively complex projects that will help you improve your Python programming skills:

Faif/python – patterns. Implement some examples of design patterns using Python.

Pallets/werkzeug. Flask’s WSGI toolset. These include well-implemented LocalProxy, cached_property, import_string, find_modules, TypeConversionDict, and more.

Bottlepy/bottle. Flask is too big, bottle is 4k many lines, of course if you have the perseverance and interest to directly look at flask is the best.

Msiemens/tinydb. Know how to implement databases in Python.

Coleifer/peewee. Understand ORM implementation.

Pallets/click. Click is built into Flask 0.11 and provides command line functionality, which is worth reading.

Mitsuhiko/flask – sqlalchemy. Learn how a Flask plugin is implemented.

In addition, Web developers can read some related projects:

Runscope/httpbin. In Flask, the site is httpbin(1): HTTP Client Testing Service.

Jahaja/psdash. Flask and Psutils for obtaining Linux system information panel application.

Pallets/flask – website. Flask official website app.

Pypa/warehouse. If you use PYRAMID, the new version of the PYPI website, it can help you understand a lot.

Of course, 2 important learning flask resources must be exploded:

GitHub – RealPython/Discover – Flask: Full Stack Web Development with flask.

The Flask Mega – Tutorial. Flask Web Development: Python Based Web Application Development In Action.

500lines

Github-aosabook / 500Lines: 500 Lines or Less is a great project that contains 22 sub-projects by experts in the field that implement a particular feature in Less than 500 Lines of code. Even Guido van Rossum wrote the asyncio based crawler himself, Nick Coghlan, ajdavis also appeared. What are the recommended Python training projects? – The little porter’s reply.

How to read the source code of an open source project

I have read some open source projects based on my personal interests and daily development needs. Here are some common experiences and insights:

Don’t be afraid. I found that we often sigh that XXX is strong, YYY is popular, virtually you will put it in an untouchable position, feel it is difficult, and make themselves dare not to challenge it. Humans produce bugs, and if you find something wrong with it, you should take the opportunity to verify it. In the process, the mystery is lost, and after a few experiences like this you have confidence. Second, don’t be afraid that your PR will be rejected. This is very normal, I have a lot of PR was rejected, especially the Patch submitted to the standard library, most of them were rejected.

Read the code with questions in mind, which I find most effective. This will give you a thread to focus your reading.

Breakpoint debugging. It’s not always easy to use PDB in Python code because the code is complex and the breakpoint requires you to use multiple n’s to jump to the corresponding location. I usually throw an exception first and use PDB’s up/down/ N commands to debug. It is also possible to add some print logs or comment part of the code at the target location and use exit() directly to exit.

Make good use of documentation and examples on the website. Reading a project can be a bit confusing at first, so focus on these items first. They are usually the first entry point for the author to express the project. Examples of minimization in Quickstart, Tutorial and other contents are actually the best entry point for reading. First, look at the corresponding implementation of these referenced modules and corresponding methods or functions called, and read from bottom to top.

Understand the author’s way of thinking. Different projects should have different thinking ways to read, do not cling to their own habits to read, this will be very tired, we have to try to accept others’ opinions, or even change their own.

Read an earlier version of the project. Some projects have become too complex to read over time, so you can go back to earlier versions of the project, look at the relatively simple version first, and then set a few points or release nodes to read it gradually.

Memorize and draw the project architecture. A project is a collection of code. In addition to learning programming skills, you also need to understand the architectural decisions of the project, which is very useful for writing large projects in the future. The more complementary this understanding is, the clearer it becomes to you.

To participate in. If you just look and think and don’t participate, the effect is greatly reduced. I suggest participating in issue discussions, asking authors questions, asking for PR to add new features, helping improve documentation, etc. Most of the time, what you understand is in conflict with the author. Whether you convince him or be convinced by him, it is very helpful for your growth.