After having introduced Python to so many developers of varying skill levels and experience, I felt a growing need for this: a single printed sheet with a quick-reference to the language. I’m now sharing my first take on it, along with some context, thoughts, and possible challenges ahead.

Readers can download a PDF copy here, distributed under the CC BY-SA 4.0 license. It has been conceived to be printed on a single sheet of high quality paper, double-sided and in colour, with thick, glossy lamination for durability and increased contrast.

Such Sheet of Python is precisely what I’ve distributed for the first time to all participants in my most recent This is Python training session, last week. Given that it’s had a very positive initial feedback, I reckon I’ll keep improving it and handing it out to my trainees in the future.

Context

I put a very strong emphasis on fundamentals on every training session I deliver. The value of a clear and strong mental model of the semantics and behaviour of Python and its constructs — or any other technology or tool, for that matter — is often under-appreciated. Building it takes time and perseverance, things that many people and organisations seem to be lacking these days. Systematic training approaches, exercises, and mini-projects help with that. Real world¹ experience tends to help too, even if possibly somewhat chaotic… But, guess what? That can take even longer! On the other hand, advertised quick-wins, like a now fictional “Build a foobar in under 24h” thing, directed at beginners, while delivering (?) a sense of immediate satisfaction, don’t build sustainable, universally applicable skills… And that — developing sustainable, universally applicable skills — is precisely what I value the most and strive to deliver every time.

With that said, the sessions, while supported by a reasonably sized set of slides, tend to be very dynamic, even when new materials and concepts are being presented: questions and discussions start spontaneously, I illustrate concepts playing around with short live-coded examples, the whiteboard or flip-chart gets used all the time, and more².

When we dedicate time to exercises and mini-projects, mostly driven by printed hands-on guides, I ask participants to avoid searching the web for answers to their questions, or for solutions or shortcuts to the proposed challenges. Instead, I suggest trying things out in the REPL, reaching out for the excellent Python documentation at docs.python.org, which is also often available on their systems, or, of course, just asking out loud — within acceptable loudness levels, that is! 😉

Questions I have repeatedly addressed during hands-on exercises are along the lines of:

• “What was the syntax for declaring variable arguments on a function again?”
• “How do I specify the text encoding when opening a file for reading?”
• “Could you go back to that slide with the examples of multiple assignment?”
• “What was the name of that builtin function?”
• “How do we create class properties? What’s the syntax for the setter?”

Each of these is nothing but a minor inconvenience in the progress of each participant, and my answer is normally either going back to a particular slide, or writing something out on the whiteboard. It all makes sense, people are grasping the concepts and mapping their existing programming knowledge to the newly acquired information, but they lack the practice and, naturally, syntax and other details depend on an external reference.

I became aware of this nearly a year ago and wondered: What could be a good solution? Since then, I’ve been observing behaviours and questions during the exercise periods more attentively, taking notes, asking people what they would like/dislike, giving it all some thought, and, as time permitted, creating the Sheet of Python.

Aspirations

The Sheet of Python should be a tool to facilitate and support in session exercises and mini-projects, as well as the early days of Python newcomers. It should be a single sheet of paper, which is faster and less distractive than a web search and, thus, an effective learning tool.

Things I want it to be:

• Comprehensive Quick reference
  An effectively useful tool, serving minimally experienced programmers who are Python newcomers (welcome!).
  Covering most of the Python language, fundamentals, and widely used constructs.

• Distraction free
  Being a sheet of paper helps.
  Including no references to third-party packages, and minimal references to the Standard Library helps.

• Somehow open-ended
  Including hints and pointers to related, possibly useful topics.
  Stimulate curiosity around the ones that readers may not be familiar with, leading them to try out, explore, read and learn more.

• Consistent and Terse
  Conceptually. Structurally. Grammatically. Visually.

• Beautiful
  Beauty is, not only better than ugliness but, above all, in the eye of the beholder, I get that.
  Typography, pagination, layout, colour, and the general visual feel are important.

Things I clearly don’t want it to be:

• Serve total beginners
  I currently don’t target non-programmers in my training offers so I wouldn’t be in the best position to create such a tool. Moreover, a single-sheet variation for non-programmers would probably be of almost no use to experienced programmers who are new to Python. Different audiences benefit from different tools.

• Include Everything
  “Everything” is either too vague, needlessly distracting or overwhelming, or won’t possibly fit in a single sheet.
  As a learning tool for Python newcomers, I went for most of Python, and almost nothing of everything else.
  The focus is Python, the language.

• Have an HTML variant
  While that could be done, the fundamental idea around the Sheet of Python is to really have it printed, in colour, nicely laminated. It’s not even meant to be used as a PDF file to be viewed on a screen, forget that! Being a physical object makes it useful in ways different that what the web can be. Creating an HTML variant would be, at the moment, mostly pointless: there already are many high-quality HTML Python reference documents all over the web.

Challenges

The biggest challenge was, in and of itself, selecting which bits of Python to include, which to exclude, and how to cope with the limited physical space of a single sheet of ISO A4 paper.

As time went by, what I did want to include became progressively clear, while most exclusions, around more advanced topics, were pretty obvious from the start: the Sheet of Python would be no place for the likes of decorators, context managers, descriptors, meta-classes, coroutines, or the C API³. Those could be left to a future venture.

With a top-down approach, drawing the line between what would go in and what wouldn’t, then became a matter of balancing the available paper space, a reasonable font size, and the need for more or less verbose textual explanations for a given entry; for example, I would have liked to include references to a few more builtin functions, like repr or getattr, say, but that would imply less room for the built-in types, a very fundamental topic, which could have used a little bit more room themselves.

Another challenge was in laying it out in such a way that it became both visually balanced and, at the same time, somehow conceptually consistent, with simpler, more fundamental topics on one page and, generally speaking, more complex constructs on the other.

Trade-offs

The challenges above forced me into several trade-offs. Here are a few I faced and the key motives that made me decide the way I did:

• The Assignment and Iteration boxes, addressing two very important Python fundamentals, often misunderstood even by experienced Python programmers, feel very terse. I’m not sure a Python beginner will grasp those concepts strictly by what’s written in them. They serve a purpose, nonetheless: those that have participated in my trainings will probably remember enough such that these brief notes become helpful; others, interested and curious enough, will hopefully go from there and learn about each topic more in depth.

• String formatting is mostly absent, which is somewhat ironic given that there are three different ways of formatting strings in modern Python: the only existing hint is the reference to the format method of str typed objects in the Builtin Types box. I would have been very happy if I found a way of including a String Formatting box, without taking away any other thing… But I couldn’t, and figured that the trade-off would go this way: sorry, virtually no information or hints on the topic. At least until I find a solution I’m happy with.

• Striving for quick exploration and a relatively high degree of visual layout and typographic control, I created this first version with Apple’s Keynote, after having tried Serif’s Affinity Designer and LibreOffice. One side-effect of that is the fact that the PDF is not really ISO A4: AFAICT Keynote has no notion of physical distances on paper, but the document has the proper aspect ratio such that scaling up/down when printing won’t be a problem.
  The clear trade-offs I made are a) I created it with a proprietary tool which, in the future, may become unavailable, b) I created it by hand with a tool that makes working in collaboration with others very difficult, if not impossible, and, lastly, c) given that the document is to be printed on paper, the ISO A4 is not friendly to those using other paper formats like US Letter.

The Future

The future of the Sheet of Python is somewhat unclear at this time. I’ll certainly be using it in my training sessions and, as time progresses, making manual improvements to create increasingly refined versions.

Now, what if…

• It could be built from some kind of source?
  (and what source would that be that allows the fine control of typography, layout, and more? LaTeX? Python and a PDF library?)

If that could be done, then I could…

• Open its source and host it somewhere, for improved collaboration.
• Automatically generate ISO A4 and US Letter versions.
• And who knows what else! 🙃

For now, it is what it is. I’m sharing it in good will, hoping it may be useful to someone else.

Since the source is not collaboration friendly, I’ll keep it to my self, for the time being — I’d love to hear feedback, suggestions, and how others would address the unavoidable challenges and trade-offs of such a venture, though.

Thanks for that, in advance!