Back to schedule

How to Write Python Code Others Like to Use

What makes an API Pythonic? If you are writing Python code you want to share with the world, or maybe just within your team - how can you design it in a way that's intuitive to use and easy to navigate for both the beginner and the expert.

Abstract

We all know "the Zen of Python". Maybe we even put it into practice in writing our own code. But what does it mean when designing an API?

What kind of design patterns do Python developers naturally look for, and which patterns confuse them and force them to browse your (hopefully published and comprehensive) documentation?

When we set out to write a new set of SDKs for our cloud services, we studied the APIs of popular, widely-used libraries. We also conducted a series of user experience studies with Python developers of varying levels of experience, to determine not only how to design an intuitive API, but one that doesn't become needlessly complex even when the subject matter gets complicated.

Finally, once your code has been distributed, as a published library, open source sample, or internal module - how can you effectively supplement your module with useful documentation that doesn't slow down developers with too much detail?

Here I will be presenting the results of that research in a series of easy to adopt steps that we have incorporated into our own SDKs.

1. SDK structure: An API surface area will often have a natural hierarchy; parent objects with one or more child objects. However Pythonic design states that "flat is better than nested'. How far should we flatten an object hierarchy before it actually becomes less intuitive to use?

2. Object models: For developers coming from other languages (I'm looking at you: .Net, Java), it is common practice to represent data as an object. But Python is all about dictionaries. So what makes a Python dictionary so great to use? And how can we maybe get the benefits of both the humble dictionary and the complex object type.

3. Making the complex simple: Even the most experienced users don't need all the details of all the features from the very beginning. How can we write a clean API the appeals to users of all experience levels, while providing additional complexity on a "need to know" basis.

4. Documentation: There are many ways to document your code; reference docs are an important tool for developers. However they're not the only tool, and often not the first place that developers land when needing to get started. How can we guide developers from "Getting Started" to "Advanced Concepts".