I would recommend 4 repositories:

• Pydantic: It will show you all the “magic” of Python. Their codebase is typed, so it’s a mix of good practices. They have tests, a good CI setup, and docs. You can get some inspiration on how a “production-ready” Python package could look. Also, the amazing part is that they have Rust integration, so you can see how this happens in real-world scenarios - it’s a win-win.

• FastAPI: A very popular web framework that also uses Pydantic. They have a very good codebase with tests, so you can take a look at how you need/can structure them for web-like projects. They have translations for their docs, so it also can be interesting to see how it’s done on a production scale.

• SQLAlchemy: A very good and authoritative Python ORM. You can see how the ORM works under the hood, so while reading this codebase you can learn a lot about SQL. If you switch to some older version prior to typing, you can see how it was done in the good old days.

• Kedro: A top-notch quality codebase where you can learn about how data engineering frameworks are built. They have very vast CI pipelines and heavy use of Click plugins and package optional dependencies, so you can see how a package can be scaled.

Someone asked me this question just yesterday in a Python course I was teaching.

I told them:

1. look at the design (but not code) of long-time, major, popular, high-velocity third-party libraries that emerged after Python 3 was released
2. look at anything written by Dave Beazley
3. look at anything (greenfield) by Tom Caswell

Regarding ①, if you look at the code for NumPy, you’re going to get lost in lots of mechanical details. It’s an extremely successful tool, but it’s probably not how we would write Python code today. If you look at the design and user-facing API of NumPy, you’re going to see how things were designed in the early Python 2 era, which is missing many key features available today. This is the same for Matplotlib (which has set_ functions, because @property didn’t exist when Matplotlib was first created.) However if you look at pandas, you will see a tool that, as a consequence of its extreme popularity, was forced to evolve a very coherent and contemporary design, marred only by extreme inconsistencies at its most superficial level (e.g., nothing is spelt consistently—.swaplevel vs .reorder_levels) Skip PyMC as a reference—the API is just bizarre. (Use PyMC if you want to do Bayesian statistical modeling.)

Regarding ②, read Dave’s recent book: Python Distilled Anything Dave still maintains or has recently released will be good. (SWIG was a long time ago.) He’s one of the few programmers I have met who “just gets it”—his code is lucid, clear, and direct.

Regarding ③, Bluesky Project is a constellation of projects for data acquisition and management that is in use at a couple of x-ray beamlines in the US. I am not a physicist, and I don’t work on at a beamline, but I do a lot of Python and other training for scientific research facilities. I have taught two classes on the bluesky and databroker libraries from Bluesky Project to physicists. These classes weren’t about the physics—I have no background in that; they were about the software. In answering attendee questions, I have written lines of code that I have never written before in my life, using a library that is not in my field of expertise or something I use, and yet I could predict what the line of code would do before executing it… and I was right every time. (e.g., “How do I see if my experiment was in the output payload?” “Well, the example shows they implemented __iter__ and __getitem__ on the object representing your results, so it stands to reason they implemented __contains__ to determine membership using the __getitem__ key. … And that works.”) In my view, the marker for well-designed (Python) code is whether someone broadly familiar with the ecosystem can correctly intuit the operation of new libraries, using applicable general knowledge.

Unlike what other contributors have shared, I would skip Pydantic and FastAPI. I like FastAPI, and just used it very recently in a project, but the design itself is focused very heavily on convenience in a way that other projects may not be. As a consequence, the underlying code will require contortions (e.g., the use of advanced features) to support these conveniences. If I could, I would skip Pydantic entirely—I wouldn’t even use it, if I could avoid it. It’s the wrong approach solving an uninteresting problem.

The FastAI library moves with high velocity, so it may have improved since I looked at it some years back, but, if not, I would stay far, far away; it’s full of bizarre, wholly unnecessary choices in the service of a design overly-focused on an idiosyncratic notion of convenience.

People seem to like Textual, and they put out some great demos. I haven’t looked at the code, but I have looked at their user-code samples, and it looks like they picked the wrong metaphors completely. It might end up being a good example of how a project can be popular (and enable useful work!) irrespective of its technical merits.

I have a YouTube channel with instructional material where I cover some of these things. I have also given some talks at PyData and other conferences about these things.

I think contemporary, “fluent” Python code is typified by the following things (among others):

• precise, correct usage of the Python “vocabulary” offered by the data model
• use of ‘iteration helpers’ (and, e.g., the itertools module); “every line of Python code should be a sentence (which explains what you are trying to accomplish without burying the reader in mechanical details)”
• design around ‘restricted computation domains’
• ‘value disintermediation’ (which is a particular distinguishing mark of Python 2 vs Python 3 code); ; we can associate this with use of things like enum.Enum

The use of PEP-484 type hinting is on this list. Use them if you want; sometimes they are helpful, sometimes they’re just noise. Similarly, gratuitous use of new features is obviously never the mark of good code.

Here is a brief example of the use of ‘iteration helpers.’ (The other items above would require longer explanation.) Consider that the improvement in the below is not merely a superficial issue of performance or number-of-lines; the latter formulation is actually more nearly correct!

from random import Random
from itertools import accumulate, pairwise
from operator import add

rnd = Random(0)

# left scan; cumsum; random walk
values = [*accumulate((rnd.randint(-1, +1) for _ in range(5)), add, initial=100)]

# without iteration helper—noisy, mechanical, subtly wrong
prev_value = None
for curr_value in values:
  if prev_value is None:
    prev_value = curr_value
    continue
  print(f'\N{mathematical bold capital delta}: {curr_value - prev_value = :>2}')
  prev_value = curr_value

# with iteration helper
for prev_value, curr_value in pairwise(values):
  print(f'\N{mathematical bold capital delta}: {curr_value - prev_value = :>2}')

In the end, though, never forget the difference between good code and bad code is always been the same no matter the language:

Good code is code I wrote; bad code is code you wrote.

They’re mostly on the smaller side, but my go-tos these days are usually the encode codebases (e.g. httpx), and @hynek’s codebases (attrs / structlog might be the most widely used, but stamina and svcs are equally neat).

I too am very interested in this! I am writing a lot of Python these days and I can escape the feeling that it’s non-idiomatic and gross, even as it passes the various linters and such I have configured.

I have learned a lot by browsing the GH repos of packages I frequently import. I’ve recently delved quite a bit into the hrequests and undetected-chromedriver repos partly to deepen my understanding of what they’re doing but certainly also to sample other people’s programming styles and techniques. If you find yourself importing certain 3rd-party packages a lot, browse their GH repos!

Django is a great study case for a large project that has had a large number of contributors

I’ve read this the Paasta codebase a little bit and thought it was fun. Decently documented, README has some videos and talks about it as well.

I remember Mercurial was often given as an example of good Python source code. For a while I practiced touch typing by typing out it’s source code. Just checked and you can still do that: https://typing.io/lesson/python/mercurial/merge.py/1

I haven’t touched Python in a long time, but I remember the requests package being particularly well written. :)

Simon Willison recently suggested this one which maybe database centric, but still: https://simonwillison.net/2024/Mar/19/diskcache/

The discord.py package is well written and performance-optimized in some places (like slotted classes instead of @dataclass for classes, suprisingly that improves runtime creation a ton). It is also fully typed which is nice.