0
Pythonic                              APIs                                Anthony Baxter                             antho...
Some good and bad                                examplesSunday, November 21, 2010and speaking of bad examples...
O Hai!Sunday, November 21, 2010
started with python ‘92                          or ‘93Sunday, November 21, 2010I forget which. I do recall that back then...
Sunday, November 21, 2010
I’ve written a lot of                                  PythonSunday, November 21, 2010
and used a lot moreSunday, November 21, 2010
Python is like a virusSunday, November 21, 2010Python gets into your brain and makes you annoyed at other languages. And l...
inevitablySunday, November 21, 2010
Sunday, November 21, 2010
did that for 5 yearsSunday, November 21, 2010primary language from 1996-2007, now have to do Java and C++ as well, boo
Then Google ate my                                 free timeSunday, November 21, 2010
some APIsSunday, November 21, 2010On of the ways of spreading Python is to make it possible to do new stuff, simply.I’ve b...
miniSQLSunday, November 21, 2010mid 90s - first of the small open embedded databases, by David Hughes. wrapped it incustom ...
snmpySunday, November 21, 2010wrapper around UCD-SNMP. wanted to manage some small ethernet switches. subsequently,used it...
shtoomSunday, November 21, 2010voice over IP
lots of other stuff...Sunday, November 21, 2010whenever I come across a new protocol, I spend some time implementing it. s...
So you’re building an                                APISunday, November 21, 2010
Why would you do                                 this?Sunday, November 21, 2010
Wrap existing codeSunday, November 21, 2010
New code to achieve a                        purposeSunday, November 21, 2010
Generalise existing                                  codeSunday, November 21, 2010
LearningSunday, November 21, 2010I’ve done a lot of this - the easiest way I find to understand something new, especially a...
for the hell of itSunday, November 21, 2010
sheer                            bloodymindednessSunday, November 21, 2010shtoom was originally written for one reason. I ...
“Scripting Language, My                         Arse”Sunday, November 21, 2010I kept working on it, adding all sorts of st...
SIP                   IVRs audio  tftp                                  STUN                       rtp UPnP      codecs   ...
~ 25K LOCSunday, November 21, 2010
“Pythonic”Sunday, November 21, 2010
Guido is Watching YouSunday, November 21, 2010Guido has been successful as BDFL because of his excellent taste.
“I know it when I see it”                                                              Justice Potter Stewart,            ...
What makes an API                               Pythonic?Sunday, November 21, 2010
principle of least                                surpriseSunday, November 21, 2010
Sunday, November 21, 2010
principle of least                                surpriseSunday, November 21, 2010it should feel safe and comfortable and...
Zen of PythonSunday, November 21, 2010when designing an API, bear the words of Sensei Tim Peters in mind. Type ‘import thi...
“Python fits in my                                 brain”Sunday, November 21, 2010Your API should also fit in my brain. I sh...
Python isn’t always                                PythonicSunday, November 21, 2010
map, filter, reduceSunday, November 21, 2010we fixed that. list comprehensions for map and filter. reduce, we have sum(). map...
print >> fpSunday, November 21, 2010
lambdaSunday, November 21, 2010
Common mistkaesSunday, November 21, 2010
Over-ambitionSunday, November 21, 2010I’m gonna TAKE OVER THE WORLD
“Frameworks”Sunday, November 21, 2010
Why don’t I like them?Sunday, November 21, 2010
I just want one pieceSunday, November 21, 2010
e.g.Sunday, November 21, 2010
twisted                great stuff                  but...Sunday, November 21, 2010twisted has a wide variety of protocol ...
Frameworks                                 ==                            do it my waySunday, November 21, 2010I want to be...
Mistaik #2:                    Reinventing the wheelSunday, November 21, 2010
We don’t need:Sunday, November 21, 2010
another web                             frameworkSunday, November 21, 2010
every time you write a                             new web framework,                               god kills a kitten    ...
another #!*$^#?@&                            templating language                            noooo!Sunday, November 21, 201...
another interface for                         postgresql or mysqlSunday, November 21, 2010I counted at least 6 PG adapters...
makes no-one’s life                                 betterSunday, November 21, 2010it’s harder for python developers.it’s ...
#3: complexitySunday, November 21, 2010
Steep learning curveSunday, November 21, 2010
Sunday, November 21, 2010this is a ‘hello world’ for pysnmp. OMG.ideally you should be able to play at the interactive int...
#4: being too cleverSunday, November 21, 2010
back to snmpy...Sunday, November 21, 2010
SNMP OIDsSunday, November 21, 2010
interfaces.ifTable.ifEntry.ifIndex.1 = 1               interfaces.ifTable.ifEntry.ifDescr.1 = "Ethernet"               int...
.iso.org.dod.internet.mgmt.mib-2.system.sysUpTimeSunday, November 21, 2010here’s a full OID. where is the problem as far a...
.iso.org.dod.internet.mgmt.mib-2.system.sysUpTimeSunday, November 21, 2010impedence mismatch
OID names != python                          identifiersSunday, November 21, 2010
.iso.org.dod.internet.mgmt[‘mib-2’].system.sysUpTimeSunday, November 21, 2010suddenly things got nasty
worse yetSunday, November 21, 2010overloading attribute lookup meant all sorts of horrible and strange errors would pop up...
cleverness will chew off                       your faceSunday, November 21, 2010
cleverness will bite                                your usersSunday, November 21, 2010
similarlySunday, November 21, 2010
leave import alone!!!!Sunday, November 21, 2010please don’t play games with module import.yes, you can write something tha...
and don’t monkeypatch                       the stdlibSunday, November 21, 2010
oh noes!Sunday, November 21, 2010patching the stdlib summons hideous demons that will eat your soul.
Sunday, November 21, 2010
so don’t be too clever                           or cuteSunday, November 21, 2010making things that “act like a list, sort...
just because you can                       abuse ‘with’ doesn’t                        mean you shouldSunday, November 21,...
Sunday, November 21, 2010I question the use of the phrase “reusable components” there.
what you do in the                      privacy of your own                     codebase is your own                      ...
don’t make it mine...Sunday, November 21, 2010
Next big mistakeSunday, November 21, 2010
Writing in the wrong                             languageSunday, November 21, 2010
you can tellSunday, November 21, 2010after a while, you can almost spot someone who’s not a python programmer from their c...
don’t port APIs directlySunday, November 21, 2010unfortunately, the stdlib has a few great examples of how and why this is...
don’t believe me?Sunday, November 21, 2010
import xml.domSunday, November 21, 2010a direct port of the “standard” DOM APIs.
Sunday, November 21, 2010Even Javascript programmers don’t like working with the DOM - this is why jquery &c arewinning ou...
import loggingSunday, November 21, 2010logging was a direct port of Java’s log4j. I just want to log something to a file. W...
import unittestSunday, November 21, 2010a direct port of junit, initially. it’s getting better. but pretty much every majo...
Python is not C/C++Sunday, November 21, 2010
...but makes a good                     wrapper around themSunday, November 21, 2010
important:Sunday, November 21, 2010
provide higher level                                 wrappersSunday, November 21, 2010At Google, much of the lower level m...
recommended:Sunday, November 21, 2010
ctypes                            SWIG                            pyrexSunday, November 21, 2010
maintainability                             readabilitySunday, November 21, 2010
cross platformSunday, November 21, 2010compiling C extensions on Windows is one of the worst things you can do to a unixde...
classic example:Sunday, November 21, 2010
pygame vs pygletSunday, November 21, 2010pygame is custom wrappers around SDL.pyglet is ctypes around openglI understand p...
more learnings from                                   pygletSunday, November 21, 2010sorry. I work for a large corporation...
wrap the lower level                                   codeSunday, November 21, 2010
provide higher-level                                 interfacesSunday, November 21, 2010we’re not writing C code for a rea...
Python is really not JavaSunday, November 21, 2010
getters and setters?                                 seriously?Sunday, November 21, 2010
dozens and dozens of                     classes to do anythingSunday, November 21, 2010
method overloadingSunday, November 21, 2010I’ve seen this too often - a method that can take a Foo, or a Bar, or a Baz, an...
@classmethod                            @staticmethodSunday, November 21, 2010There’s only a couple of places to use a cla...
How to design an APISunday, November 21, 2010this is all from personal experience, of course, and from watching other peop...
Have a use-caseSunday, November 21, 2010
better:Sunday, November 21, 2010
have multiple use casesSunday, November 21, 2010
think about how it will                           be usedSunday, November 21, 2010
yes, including unicode                                     _ = str.upperSunday, November 21, 2010
start off:                            solve one problemSunday, November 21, 2010
start off simpleSunday, November 21, 2010
don’t overdesignSunday, November 21, 2010
YAGNISunday, November 21, 2010
what worked? what                                  didn’t?Sunday, November 21, 2010
now solve a second                                 problemSunday, November 21, 2010
or ask a friend to trySunday, November 21, 2010your first couple of users are the equivalent of doing user testing. do they...
be ruthless early on                              with refactoringSunday, November 21, 2010it’s much much harder once you ...
build on what’s thereSunday, November 21, 2010
lists, dicts, setsSunday, November 21, 2010
go go duck typingSunday, November 21, 2010
more on ducks.                             be sensible.Sunday, November 21, 2010ducks are widely known for their common se...
getattr and setattrSunday, November 21, 2010just say no.
start with a bunch of                              functionsSunday, November 21, 2010
don’t over-engineerSunday, November 21, 2010
aggregate common                               functionalitySunday, November 21, 2010
think about testingSunday, November 21, 2010
I learned this the hard                              waySunday, November 21, 2010
SIP is incredibly                                complexSunday, November 21, 2010
shtoom’s SIP support:                        one long spikeSunday, November 21, 2010I implemented SIP based on reading pac...
Sunday, November 21, 2010SIP is incredibly complex. core RFC is 269 pages.lack of testing killed me over and over again.la...
testable APIsSunday, November 21, 2010
an interesting discoverySunday, November 21, 2010
testing is goodSunday, November 21, 2010
motherhood, apple pie,                   american flag, all that                          stuffSunday, November 21, 2010
but it turns outSunday, November 21, 2010
testing actually makes                           an API betterSunday, November 21, 2010and not just how you might think...
testing using mocksSunday, November 21, 2010there’s a bunch of mock libraries - I like “mox”, but pick and choose what wor...
python uses duck-                                 typingSunday, November 21, 2010
duck-typing + testable                          APIs = :-)Sunday, November 21, 2010if your code is in small, testable piec...
people will find new                   ways to use your codeSunday, November 21, 2010
oh and btw,Sunday, November 21, 2010
don’t rely on _methodsSunday, November 21, 2010people are bastards. you can’t try and mark part of your API “off limits”py...
and _ _ methods are                                  right outSunday, November 21, 2010double underscore is a namespace ma...
all of your API is publicSunday, November 21, 2010we got burnt on this in appengine - we had _methods for internal impleme...
Python’s ethos is we’re                  all “consenting adults”Sunday, November 21, 2010
sometimes it’s best not                   to look too closelySunday, November 21, 2010
the best you can do is                               saySunday, November 21, 2010
Sunday, November 21, 2010
How to make your API                        popularSunday, November 21, 2010
DocumentationSunday, November 21, 2010I can’t emphasise enough how important this is. I will actually make choices on an l...
anything is better than                           nothingSunday, November 21, 2010
even just generated                              from docstringsSunday, November 21, 2010this will of course encourage you...
ExamplesSunday, November 21, 2010You should have a few hello world type examples - over time, build these up. If you arelu...
Frequent releasesSunday, November 21, 2010more importantly, make it clear what’s going onthis is something I’ve done badly
Frequent, or at least                              regular, releases.Sunday, November 21, 2010
Frequent, or at least                               some, releases.Sunday, November 21, 2010“just build from the revision ...
Be open to feedbackSunday, November 21, 2010... and patches. as soon as you release code, suddenly you have more users. Th...
Think about stabilitySunday, November 21, 2010once your library gets users, they want their apps to keep working. This bec...
Python releases                             linux kernelSunday, November 21, 2010
plan for extensibilitySunday, November 21, 2010your users will find new ways to use your library than you could have ever i...
finally:Sunday, November 21, 2010
what happens if you                              don’t succeed?Sunday, November 21, 2010
nothing badSunday, November 21, 2010this goes back to why you wrote an API in the first place.assuming you haven’t based a ...
the good ideas will live                             onSunday, November 21, 2010bits of shtoom turned up in unexpected pla...
and you might be able                to get a talk or two out                           of itSunday, November 21, 2010
finally...Sunday, November 21, 2010
the most important                    thing about API designSunday, November 21, 2010
no matter what you                                  thinkSunday, November 21, 2010
no matter how much                            you planSunday, November 21, 2010
expect the unexpectedSunday, November 21, 2010
Sunday, November 21, 2010
Upcoming SlideShare
Loading in...5
×

Pythonic APIs - Anthony Baxter

4,795

Published on

Anthony Baxter talks about Pythonic APIs in the 2nd keynote at Kiwi PyCon 2010.

1 Comment
8 Likes
Statistics
Notes
  • Hi Anthony,

    Excellent presentation.

    Many thanks for this and also the huge amounts of code you developed and released.

    And needless to say, the process of experiment->measure->advance/retreat works in many other fields of life too ...

    Live long and prosper!
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Views
Total Views
4,795
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
70
Comments
1
Likes
8
Embeds 0
No embeds

No notes for slide

Transcript of "Pythonic APIs - Anthony Baxter"

  1. 1. Pythonic APIs Anthony Baxter anthonybaxter@gmail.com @anthonybaxterSunday, November 21, 2010notes
  2. 2. Some good and bad examplesSunday, November 21, 2010and speaking of bad examples...
  3. 3. O Hai!Sunday, November 21, 2010
  4. 4. started with python ‘92 or ‘93Sunday, November 21, 2010I forget which. I do recall that back then, Guido wrote a webcrawler in Python that crawled theentire web, and crashed a lot of machines.
  5. 5. Sunday, November 21, 2010
  6. 6. I’ve written a lot of PythonSunday, November 21, 2010
  7. 7. and used a lot moreSunday, November 21, 2010
  8. 8. Python is like a virusSunday, November 21, 2010Python gets into your brain and makes you annoyed at other languages. And like all goodviruses, it makes you want to spread it.
  9. 9. inevitablySunday, November 21, 2010
  10. 10. Sunday, November 21, 2010
  11. 11. did that for 5 yearsSunday, November 21, 2010primary language from 1996-2007, now have to do Java and C++ as well, boo
  12. 12. Then Google ate my free timeSunday, November 21, 2010
  13. 13. some APIsSunday, November 21, 2010On of the ways of spreading Python is to make it possible to do new stuff, simply.I’ve built far too many APIs and libraries for Python. Mostly I build them to get somethingdone, then eventually get bored of them and hand them on or move on.Learn from my mistakes.
  14. 14. miniSQLSunday, November 21, 2010mid 90s - first of the small open embedded databases, by David Hughes. wrapped it incustom C code wrapper. Eventually taken over by Mark Shuttleworth, who used it at Thawte.
  15. 15. snmpySunday, November 21, 2010wrapper around UCD-SNMP. wanted to manage some small ethernet switches. subsequently,used it at a large ISP to collect stats from thousands of interfaces for billing purposes.got a bit silly eventually, I used it as a backend to gadfly so I could do SQL-style queriesacross network devices and interfaces.
  16. 16. shtoomSunday, November 21, 2010voice over IP
  17. 17. lots of other stuff...Sunday, November 21, 2010whenever I come across a new protocol, I spend some time implementing it. sometimes Ieven get around to releasing that code.
  18. 18. So you’re building an APISunday, November 21, 2010
  19. 19. Why would you do this?Sunday, November 21, 2010
  20. 20. Wrap existing codeSunday, November 21, 2010
  21. 21. New code to achieve a purposeSunday, November 21, 2010
  22. 22. Generalise existing codeSunday, November 21, 2010
  23. 23. LearningSunday, November 21, 2010I’ve done a lot of this - the easiest way I find to understand something new, especially anetwork protocol, is to implement it.
  24. 24. for the hell of itSunday, November 21, 2010
  25. 25. sheer bloodymindednessSunday, November 21, 2010shtoom was originally written for one reason. I got sick of hearing Python called a “scriptinglanguage”. So I thought implement voice over IP in it and write a talk, just to say “shut up”
  26. 26. “Scripting Language, My Arse”Sunday, November 21, 2010I kept working on it, adding all sorts of stuff to it. It kinda grew out of control.
  27. 27. SIP IVRs audio tftp STUN rtp UPnP codecs ulaw gsm06.10 UIs tk qt gnome G.72x wx speex cocoa ... text ...Sunday, November 21, 2010by the time I got bored, I had implemented about 5 different audio capture/playbackinterfaces, and 7 or 8 different UI layers. As well as about 4 different firewall avoidancemechanisms. It worked on Unixes, Windows, the Mac, and sometimes even Gentoo.
  28. 28. ~ 25K LOCSunday, November 21, 2010
  29. 29. “Pythonic”Sunday, November 21, 2010
  30. 30. Guido is Watching YouSunday, November 21, 2010Guido has been successful as BDFL because of his excellent taste.
  31. 31. “I know it when I see it” Justice Potter Stewart, Jacobellis v. Ohio 378 U.S. 184 (1964)Sunday, November 21, 2010of course he was talking about obscenity, but the principle remains
  32. 32. What makes an API Pythonic?Sunday, November 21, 2010
  33. 33. principle of least surpriseSunday, November 21, 2010
  34. 34. Sunday, November 21, 2010
  35. 35. principle of least surpriseSunday, November 21, 2010it should feel safe and comfortable and familiar to a Python programmer, even if they’venever come across it before.
  36. 36. Zen of PythonSunday, November 21, 2010when designing an API, bear the words of Sensei Tim Peters in mind. Type ‘import this’ if youhaven’t already
  37. 37. “Python fits in my brain”Sunday, November 21, 2010Your API should also fit in my brain. I shouldn’t have to keep referring to the docs. Also, if Ilearn one bit of the API, it should be consistent enough that the rest of the API naturallyfollows.
  38. 38. Python isn’t always PythonicSunday, November 21, 2010
  39. 39. map, filter, reduceSunday, November 21, 2010we fixed that. list comprehensions for map and filter. reduce, we have sum(). map(None, foo),we have zip()
  40. 40. print >> fpSunday, November 21, 2010
  41. 41. lambdaSunday, November 21, 2010
  42. 42. Common mistkaesSunday, November 21, 2010
  43. 43. Over-ambitionSunday, November 21, 2010I’m gonna TAKE OVER THE WORLD
  44. 44. “Frameworks”Sunday, November 21, 2010
  45. 45. Why don’t I like them?Sunday, November 21, 2010
  46. 46. I just want one pieceSunday, November 21, 2010
  47. 47. e.g.Sunday, November 21, 2010
  48. 48. twisted great stuff but...Sunday, November 21, 2010twisted has a wide variety of protocol implementations, often of high quality. but interfacingwith them means buying into the whole framework in most cases. and there’s often semi-heroic efforts needed to interface with other APIs that weren’t designed for twisted.Twisted evangelists will probably disagree with me.
  49. 49. Frameworks == do it my waySunday, November 21, 2010I want to be able to pick up an individual piece of code or a library, and run with it. I don’twant to have to restructure my entire application around a new framework.This also often leads to a situation where I’m forced to pick a framework at the start ofcoding, before I’ve figured out how exactly I want to achieve my goal.
  50. 50. Mistaik #2: Reinventing the wheelSunday, November 21, 2010
  51. 51. We don’t need:Sunday, November 21, 2010
  52. 52. another web frameworkSunday, November 21, 2010
  53. 53. every time you write a new web framework, god kills a kitten please, think of the kittensSunday, November 21, 2010
  54. 54. another #!*$^#?@& templating language noooo!Sunday, November 21, 2010you make KITTY SAD.
  55. 55. another interface for postgresql or mysqlSunday, November 21, 2010I counted at least 6 PG adapters on pypi, and a similar number of mysql adapters.
  56. 56. makes no-one’s life betterSunday, November 21, 2010it’s harder for python developers.it’s harder for you (less users).
  57. 57. #3: complexitySunday, November 21, 2010
  58. 58. Steep learning curveSunday, November 21, 2010
  59. 59. Sunday, November 21, 2010this is a ‘hello world’ for pysnmp. OMG.ideally you should be able to play at the interactive interpreter.
  60. 60. #4: being too cleverSunday, November 21, 2010
  61. 61. back to snmpy...Sunday, November 21, 2010
  62. 62. SNMP OIDsSunday, November 21, 2010
  63. 63. interfaces.ifTable.ifEntry.ifIndex.1 = 1 interfaces.ifTable.ifEntry.ifDescr.1 = "Ethernet" interfaces.ifTable.ifEntry.ifType.1 = ethernet-csmacd(6) interfaces.ifTable.ifEntry.ifMtu.1 = 1536 interfaces.ifTable.ifEntry.ifSpeed.1 = Gauge: 10000000 woot - __getattr__!Sunday, November 21, 2010so I thought using getattr would be cute. but there’s a problem...
  64. 64. .iso.org.dod.internet.mgmt.mib-2.system.sysUpTimeSunday, November 21, 2010here’s a full OID. where is the problem as far as using getattr?
  65. 65. .iso.org.dod.internet.mgmt.mib-2.system.sysUpTimeSunday, November 21, 2010impedence mismatch
  66. 66. OID names != python identifiersSunday, November 21, 2010
  67. 67. .iso.org.dod.internet.mgmt[‘mib-2’].system.sysUpTimeSunday, November 21, 2010suddenly things got nasty
  68. 68. worse yetSunday, November 21, 2010overloading attribute lookup meant all sorts of horrible and strange errors would pop up.they made debugging awful.
  69. 69. cleverness will chew off your faceSunday, November 21, 2010
  70. 70. cleverness will bite your usersSunday, November 21, 2010
  71. 71. similarlySunday, November 21, 2010
  72. 72. leave import alone!!!!Sunday, November 21, 2010please don’t play games with module import.yes, you can write something that will fetch modules from a URL. But you shouldn’t.if you’ve ever been bitten by this, you know how utterly irritating it can bemultiple custom importers make everyone sad
  73. 73. and don’t monkeypatch the stdlibSunday, November 21, 2010
  74. 74. oh noes!Sunday, November 21, 2010patching the stdlib summons hideous demons that will eat your soul.
  75. 75. Sunday, November 21, 2010
  76. 76. so don’t be too clever or cuteSunday, November 21, 2010making things that “act like a list, sort of” is all well and good until you discover that it’s notquite list-like enough.
  77. 77. just because you can abuse ‘with’ doesn’t mean you shouldSunday, November 21, 2010
  78. 78. Sunday, November 21, 2010I question the use of the phrase “reusable components” there.
  79. 79. what you do in the privacy of your own codebase is your own businessSunday, November 21, 2010
  80. 80. don’t make it mine...Sunday, November 21, 2010
  81. 81. Next big mistakeSunday, November 21, 2010
  82. 82. Writing in the wrong languageSunday, November 21, 2010
  83. 83. you can tellSunday, November 21, 2010after a while, you can almost spot someone who’s not a python programmer from their code.at google, I work with a bunch of super-smart people. but often Java or C++ has pollutedtheir brains.
  84. 84. don’t port APIs directlySunday, November 21, 2010unfortunately, the stdlib has a few great examples of how and why this is a terrible terribleidea:
  85. 85. don’t believe me?Sunday, November 21, 2010
  86. 86. import xml.domSunday, November 21, 2010a direct port of the “standard” DOM APIs.
  87. 87. Sunday, November 21, 2010Even Javascript programmers don’t like working with the DOM - this is why jquery &c arewinning out. it’s an awful awful API to work with. use elementree instead if at all possible.
  88. 88. import loggingSunday, November 21, 2010logging was a direct port of Java’s log4j. I just want to log something to a file. Why shouldthis be so hard? Fortunately, logging now has a .basicConfig() function to do this, but itreally, really shouldn’t be so hard. It’s also huge and complicated. I’d rather use print.
  89. 89. import unittestSunday, November 21, 2010a direct port of junit, initially. it’s getting better. but pretty much every major project ends upfixing it.consider also py.test. I plan on trying to open source google’s wrapper around unittest thisyear.
  90. 90. Python is not C/C++Sunday, November 21, 2010
  91. 91. ...but makes a good wrapper around themSunday, November 21, 2010
  92. 92. important:Sunday, November 21, 2010
  93. 93. provide higher level wrappersSunday, November 21, 2010At Google, much of the lower level magic is exposed via SWIG. This is a blessing and a curse.A blessing, because we *have* the lower level magic exposed in Python. A curse, because theSWIG interfaces are often extremely unintuitive to a Python programmer, and can be a bit of anightmare.
  94. 94. recommended:Sunday, November 21, 2010
  95. 95. ctypes SWIG pyrexSunday, November 21, 2010
  96. 96. maintainability readabilitySunday, November 21, 2010
  97. 97. cross platformSunday, November 21, 2010compiling C extensions on Windows is one of the worst things you can do to a unixdeveloper. ctypes makes this pain go away.
  98. 98. classic example:Sunday, November 21, 2010
  99. 99. pygame vs pygletSunday, November 21, 2010pygame is custom wrappers around SDL.pyglet is ctypes around openglI understand pygame reloaded has made more efforts here to fix this.
  100. 100. more learnings from pygletSunday, November 21, 2010sorry. I work for a large corporation that also has marketing people. these words slip inoccasionally.
  101. 101. wrap the lower level codeSunday, November 21, 2010
  102. 102. provide higher-level interfacesSunday, November 21, 2010we’re not writing C code for a reason. if you have to do all the same calls, and all you’resaving yourself is the compile cycle, you’re missing out.additionally, providing the higher level interfaces lets you maintain some level of sanecompatibility when your underlying libraries change under you.
  103. 103. Python is really not JavaSunday, November 21, 2010
  104. 104. getters and setters? seriously?Sunday, November 21, 2010
  105. 105. dozens and dozens of classes to do anythingSunday, November 21, 2010
  106. 106. method overloadingSunday, November 21, 2010I’ve seen this too often - a method that can take a Foo, or a Bar, or a Baz, and does differentthings based on them.
  107. 107. @classmethod @staticmethodSunday, November 21, 2010There’s only a couple of places to use a classmethod - alternate constructors. There’s almostnever a use for a staticmethod.
  108. 108. How to design an APISunday, November 21, 2010this is all from personal experience, of course, and from watching other people.
  109. 109. Have a use-caseSunday, November 21, 2010
  110. 110. better:Sunday, November 21, 2010
  111. 111. have multiple use casesSunday, November 21, 2010
  112. 112. think about how it will be usedSunday, November 21, 2010
  113. 113. yes, including unicode _ = str.upperSunday, November 21, 2010
  114. 114. start off: solve one problemSunday, November 21, 2010
  115. 115. start off simpleSunday, November 21, 2010
  116. 116. don’t overdesignSunday, November 21, 2010
  117. 117. YAGNISunday, November 21, 2010
  118. 118. what worked? what didn’t?Sunday, November 21, 2010
  119. 119. now solve a second problemSunday, November 21, 2010
  120. 120. or ask a friend to trySunday, November 21, 2010your first couple of users are the equivalent of doing user testing. do they get what you aretrying to achieve?
  121. 121. be ruthless early on with refactoringSunday, November 21, 2010it’s much much harder once you have users.
  122. 122. build on what’s thereSunday, November 21, 2010
  123. 123. lists, dicts, setsSunday, November 21, 2010
  124. 124. go go duck typingSunday, November 21, 2010
  125. 125. more on ducks. be sensible.Sunday, November 21, 2010ducks are widely known for their common sense.but see earlier, be rational about duck typing. don’t do it for the hell of it.caches - dict.result sets - iterthere is almost no case for pretending to be a string, or a tuple, or an int
  126. 126. getattr and setattrSunday, November 21, 2010just say no.
  127. 127. start with a bunch of functionsSunday, November 21, 2010
  128. 128. don’t over-engineerSunday, November 21, 2010
  129. 129. aggregate common functionalitySunday, November 21, 2010
  130. 130. think about testingSunday, November 21, 2010
  131. 131. I learned this the hard waySunday, November 21, 2010
  132. 132. SIP is incredibly complexSunday, November 21, 2010
  133. 133. shtoom’s SIP support: one long spikeSunday, November 21, 2010I implemented SIP based on reading packets and making it work, rather than implementingthe hundreds and hundreds of pages of RFCs. Bad mistake.
  134. 134. Sunday, November 21, 2010SIP is incredibly complex. core RFC is 269 pages.lack of testing killed me over and over again.lack of testability killed me over and over again - it eventually killed my will to live and/orwork on shtoom any more.
  135. 135. testable APIsSunday, November 21, 2010
  136. 136. an interesting discoverySunday, November 21, 2010
  137. 137. testing is goodSunday, November 21, 2010
  138. 138. motherhood, apple pie, american flag, all that stuffSunday, November 21, 2010
  139. 139. but it turns outSunday, November 21, 2010
  140. 140. testing actually makes an API betterSunday, November 21, 2010and not just how you might think...
  141. 141. testing using mocksSunday, November 21, 2010there’s a bunch of mock libraries - I like “mox”, but pick and choose what works for you.
  142. 142. python uses duck- typingSunday, November 21, 2010
  143. 143. duck-typing + testable APIs = :-)Sunday, November 21, 2010if your code is in small, testable pieces - pieces that rely on something shaped like aparticular type of duck, people can find new and interesting ways to use it.
  144. 144. people will find new ways to use your codeSunday, November 21, 2010
  145. 145. oh and btw,Sunday, November 21, 2010
  146. 146. don’t rely on _methodsSunday, November 21, 2010people are bastards. you can’t try and mark part of your API “off limits”python’s standard library had this problem at multiple points - to get some stuff done, youhad to override an _ prefixed method.
  147. 147. and _ _ methods are right outSunday, November 21, 2010double underscore is a namespace mangling thing. it doesn’t protect you. it just means userswho just want to do stuff have to mess about a little. I rate __ methods as one of Python’sbigger mistakes.
  148. 148. all of your API is publicSunday, November 21, 2010we got burnt on this in appengine - we had _methods for internal implementation details.People used these, overrode these and generally made it impossible for us to change them.you can say “don’t do this” but people will.
  149. 149. Python’s ethos is we’re all “consenting adults”Sunday, November 21, 2010
  150. 150. sometimes it’s best not to look too closelySunday, November 21, 2010
  151. 151. the best you can do is saySunday, November 21, 2010
  152. 152. Sunday, November 21, 2010
  153. 153. How to make your API popularSunday, November 21, 2010
  154. 154. DocumentationSunday, November 21, 2010I can’t emphasise enough how important this is. I will actually make choices on an lib basedon the quality of the docs.
  155. 155. anything is better than nothingSunday, November 21, 2010
  156. 156. even just generated from docstringsSunday, November 21, 2010this will of course encourage you to do docstrings.but the main thing is to make sure your docs aren’t just a reference.logging used to have that. it didn’t answer the “HOW DO I ACTUALLY USE THIS THING!?1”
  157. 157. ExamplesSunday, November 21, 2010You should have a few hello world type examples - over time, build these up. If you arelucky, people will contribute more.
  158. 158. Frequent releasesSunday, November 21, 2010more importantly, make it clear what’s going onthis is something I’ve done badly
  159. 159. Frequent, or at least regular, releases.Sunday, November 21, 2010
  160. 160. Frequent, or at least some, releases.Sunday, November 21, 2010“just build from the revision control” isn’t a great plan.
  161. 161. Be open to feedbackSunday, November 21, 2010... and patches. as soon as you release code, suddenly you have more users. They can thinkof use cases you’ve never, ever thought of. Don’t be precious about your code or your library.especially in the early days...
  162. 162. Think about stabilitySunday, November 21, 2010once your library gets users, they want their apps to keep working. This becomes harder onceyou have paying users - your entire API becomes somewhat frozen.
  163. 163. Python releases linux kernelSunday, November 21, 2010
  164. 164. plan for extensibilitySunday, November 21, 2010your users will find new ways to use your library than you could have ever imagined.
  165. 165. finally:Sunday, November 21, 2010
  166. 166. what happens if you don’t succeed?Sunday, November 21, 2010
  167. 167. nothing badSunday, November 21, 2010this goes back to why you wrote an API in the first place.assuming you haven’t based a business model on a library or API you’re releasing...
  168. 168. the good ideas will live onSunday, November 21, 2010bits of shtoom turned up in unexpected places.UPnP was based on a module called ‘soapsucks’ which turned up in a number of otherprojects, although they usually renamed it.
  169. 169. and you might be able to get a talk or two out of itSunday, November 21, 2010
  170. 170. finally...Sunday, November 21, 2010
  171. 171. the most important thing about API designSunday, November 21, 2010
  172. 172. no matter what you thinkSunday, November 21, 2010
  173. 173. no matter how much you planSunday, November 21, 2010
  174. 174. expect the unexpectedSunday, November 21, 2010
  175. 175. Sunday, November 21, 2010
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×