API Design is Hard By Dave Halter @davidhalter on Github - - PowerPoint PPT Presentation

▶
api design is hard
SMART_READER_LITE
LIVE PREVIEW

API Design is Hard By Dave Halter @davidhalter on Github - - PowerPoint PPT Presentation

Sep 08, 2022 314 likes •528 views

API Design is Hard By Dave Halter @davidhalter on Github @jedidjah_ch on Twitter Me Creator of Jedi and jedi-vim Both have ~ 2000 stars on Github Starting to really like clean code! Of course some parts of the API of Jedi suck.

slide-1
SLIDE 1

API Design is Hard

By Dave Halter @davidhalter on Github @jedidjah_ch on Twitter

slide-2
SLIDE 2

2

Me

  • Creator of Jedi and jedi-vim
  • Both have ~ 2000 stars on Github
  • Starting to really like clean code!
  • Of course some parts of the API of Jedi suck.
slide-3
SLIDE 3

3

Influences & Inspirations

  • API Design: Lessons Learned by Raimond

Hettinger

  • Good API Design by Alex Martelli
slide-4
SLIDE 4

4

Writing clean code

  • Clean Code / Good Architecture
  • Testing (py.test/tox)
  • Documentation (sphinx)
  • Code Reviews
slide-5
SLIDE 5

5

API

  • “Application Program Interface”
  • Let's just talk about Python “interfaces”.
  • Are there interfaces in Python?
slide-6
SLIDE 6

6

API

  • “Application Program Interface”
  • Let's just talk about Python “interfaces”.
  • Are there interfaces in Python?
  • Yes: “abc.ABCMeta”
slide-7
SLIDE 7

7

Bad APIs #1

  • No API
  • But everything has an interface
slide-8
SLIDE 8

8

Bad APIs #2

Going for both, it shouldn't be possible to write both:

jedi.names(source) jedi.Script(source).names()

Decide!

slide-9
SLIDE 9

9

Bad APIs #3

  • Inconsistency
  • Not following standards like

class Foo(object): def getRange(self): # Java style return self._range

But: BeautifulSoup 3 was still awesome.

slide-10
SLIDE 10

10

Think!

  • Brainstorm – Design / Performance
  • Think about data types
  • Don't do IO that is not readable by other

languages, like pickle.

  • Simple is better than complex.
  • PEP 20: The Zen of Python
slide-11
SLIDE 11

11

Be conservative!!!

slide-12
SLIDE 12

12

Private/Protected/Public

  • _variable for protected
  • __variable for private (don't use it a lot though)
  • Use _ a lot!
slide-13
SLIDE 13

13

Named Arguments

  • What is this doing:

twitter_search('python', 3, False)

  • Way better:

twitter_search('python', num_results=3, retweets=False)

  • In Python 3:

def twitter_search(name, *, num_results=20, retweets=False):

slide-14
SLIDE 14

14

Properties

  • Use them, but only for clear defined “getters”:

@property

def line_nr(self): return 42

  • For more compliated things:

def docstring(self):

return ... # maybe in the future parametrize

slide-15
SLIDE 15

15

Transitions

  • Do transitions incrementally, big transitions like

Python 2 → 3 are hard.

  • Deprecate with Warnings & Documentation
slide-16
SLIDE 16

16

Transitions

def call_name(self): """ .. deprecated:: 0.8.0 Use :attr:`.name` instead. The name (e.g. 'isinstance') as a string. """ warnings.warn("Use name instead.", DeprecationWarning) [...]

slide-17
SLIDE 17

17

Service Oriented Architecture

  • Amazon:

~2002: Use service interfaces only. “Anyone who doesn’t do this will be fired. Thank you; have a nice day!”

slide-18
SLIDE 18

18

Good Code

  • Use what you learned in API Design for your

internal API's.

  • You should be able to go public with a sub-

package without refactoring.

slide-19
SLIDE 19

19

KTHXBYE

  • Like writing APIs? We're looking for Python/DevOps Engineers:

job16@cloudscale.ch

  • @davidhalter on Github
  • @jedidjah_ch on Twitter