Designing a Pythonic Interface
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Title of Series | ||
| Part Number | 39 | |
| Number of Parts | 169 | |
| Author | ||
| License | CC Attribution - NonCommercial - ShareAlike 3.0 Unported: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this | |
| Identifiers | 10.5446/21148 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
|
EuroPython 201639 / 169
1
5
6
7
10
11
12
13
18
20
24
26
29
30
31
32
33
36
39
41
44
48
51
52
53
59
60
62
68
69
71
79
82
83
84
85
90
91
98
99
101
102
106
110
113
114
115
118
122
123
124
125
132
133
135
136
137
140
143
144
145
147
148
149
151
153
154
155
156
158
162
163
166
167
169
00:00
Goodness of fitData miningElectronic program guideQuicksortType theoryStatement (computer science)Lecture/ConferenceUMLMeeting/Interview
00:36
Electronic program guideQuicksortType theoryStatement (computer science)Physical systemTraverse (surveying)Computer animationLecture/Conference
01:05
MereologyClient (computing)Elasticity (physics)Analytic setNetwork topologySet (mathematics)Computer animationLecture/Conference
01:41
BitHeat transferTranslation (relic)Computer animationLecture/Conference
02:11
BitCodeLecture/Conference
02:49
Elasticity (physics)Bookmark (World Wide Web)Right angleSummierbarkeitVideo gameCASE <Informatik>Library (computing)3 (number)Physical systemComplex (psychology)Computer animationLecture/Conference
03:53
Service (economics)Complex (psychology)CASE <Informatik>Service (economics)CodeCartesian coordinate systemDifferent (Kate Ryan album)Self-organizationQuicksortLatent heatClosed setDesign by contractRight angleLecture/Conference
04:56
Design by contractCodeDesign by contractDependent and independent variablesQuicksortMereologyPhysical systemComputer animationLecture/Conference
05:58
Cartesian coordinate systemCodeWordPower (physics)QuicksortProduct (business)Computer animationLecture/Conference
07:04
Complex (psychology)Group actionLine (geometry)MereologyComplex (psychology)Open setNetwork socketEmailDependent and independent variablesXMLUMLLecture/Conference
07:49
Dependent and independent variablesClient (computing)Price indexAbelian categoryKolmogorov complexityMaxima and minimaLibrary (computing)Functional (mathematics)Raw image formatComplex (psychology)Query languageCategory of beingDescriptive statisticsDistribution (mathematics)Maxima and minimaLine (geometry)TouchscreenBeta functionSet (mathematics)
09:05
Field (computer science)Client (computing)Digital filterAbelian categoryMeta elementMaxima and minimaKolmogorov complexityWordMereologyComplex (psychology)Sign (mathematics)Group actionBoilerplate (text)CodeCASE <Informatik>QuicksortLine (geometry)Goodness of fitLecture/ConferenceComputer animation
10:16
Line (geometry)Complex (psychology)QuicksortMereologyDecision theoryArithmetic meanQuery languageEmailImplementationStudent's t-testMechanism designPoint (geometry)Different (Kate Ryan album)CodeSocket-SchnittstelleParsingWordLecture/Conference
11:59
Client (computing)Dependent and independent variablesPrice indexMaxima and minimaAuto mechanicQuery languageMereologyBranch (computer science)CodeInformationFormal languageNetwork topologyMechanism designJSONXML
12:44
Video gameCASE <Informatik>Order (biology)Library (computing)Term (mathematics)Query languageLecture/Conference
13:15
Price indexClient (computing)Abelian categoryDigital filterField (computer science)Metropolitan area networkMatching (graph theory)Query languageArithmetic meanCASE <Informatik>Negative numberTerm (mathematics)Different (Kate Ryan album)TelecommunicationComputer animation
14:18
Dependent and independent variablesPrice indexMaxima and minimaClient (computing)Abelian categoryQuery languageField (computer science)ResultantMechanism designSquare numberField (computer science)Poisson-KlammerType theorySource codeLink (knot theory)Forcing (mathematics)CASE <Informatik>Query languageLine (geometry)Arithmetic meanDifferent (Kate Ryan album)Multiplication signCellular automatonWordLecture/ConferenceComputer animation
15:31
Formal languageWeb browserContext awarenessResultantLecture/Conference
16:04
Formal languageInternetworkingStandard deviationLine (geometry)WordQuicksortQuery languageComplete metric spaceAbstractionEntire functionLecture/Conference
16:47
Universe (mathematics)Different (Kate Ryan album)Type theoryQuery languageComputer animation
17:22
Object (grammar)Maxima and minimaLibrary (computing)Raw image formatCombinational logicInformation securityDifferent (Kate Ryan album)Type theoryPattern languageQuery languageWave packetLecture/Conference
18:12
Object (grammar)Maxima and minimaPersonal digital assistantConsistencyRule of inferenceType theoryRule of inferenceElectronic mailing listLecture/Conference
18:51
MereologyChainConsistencyObject (grammar)Wave packetInformation securityCodePhysical systemLecture/Conference
19:47
Abelian categoryField (computer science)Client (computing)Price indexSystem callCloningPattern languageCASE <Informatik>Query languageObject (grammar)Exception handlingMultiplication signComputer animation
20:17
System callWave packetPoint (geometry)Pattern languageCellular automatonGoodness of fitMereologyRule of inferenceLecture/Conference
21:10
Physical systemRule of inferenceMereologyArithmetic meanComputer animation
21:44
Online helpModule (mathematics)Function (mathematics)CountingFlagIntegrated development environmentCASE <Informatik>1 (number)Representation (politics)Multiplication signCodeLecture/Conference
22:39
Module (mathematics)Online helpFunction (mathematics)CountingMeta elementFlagProcess (computing)Representation (politics)String (computer science)Electric generatorElasticity (physics)Query languageCellular automatonObject (grammar)Queue (abstract data type)Lecture/Conference
23:20
Function (mathematics)Module (mathematics)Online helpCountingFlagRepresentation (politics)CodeLibrary (computing)String (computer science)Fiber (mathematics)Object (grammar)CASE <Informatik>Multiplication signCore dumpQuery languageCubeDifferent (Kate Ryan album)Lecture/Conference
24:35
Reading (process)Group actionCodeEmailParameter (computer programming)MereologyLecture/Conference
25:33
MereologySparse matrixSign (mathematics)Query languageTheoryCASE <Informatik>Forcing (mathematics)State of matterElasticity (physics)Computer animationLecture/Conference
26:38
Price indexClient (computing)Abelian categoryField (computer science)Line (geometry)CodeElasticity (physics)Term (mathematics)Matching (graph theory)
27:10
Matching (graph theory)Category of beingTerm (mathematics)Parameter (computer programming)MereologyState of matterObject (grammar)BuildingLecture/Conference
27:52
Abelian categoryTerm (mathematics)Field (computer science)Price indexClient (computing)Error messageState of matterDefault (computer science)UMLLecture/Conference
28:24
Default (computer science)Computer configurationElasticity (physics)Dependent and independent variablesCASE <Informatik>Decision theoryResultantGoodness of fitPoint (geometry)Computer animation
29:12
Dependent and independent variablesProduct (business)Regular graphLecture/Conference
29:43
Software testingCodeSocial classSoftware testingLibrary (computing)Set (mathematics)Vapor barrierQuicksortCASE <Informatik>Bookmark (World Wide Web)MereologyLecture/ConferenceComputer animation
30:49
CodeCodeDifferent (Kate Ryan album)CASE <Informatik>Cartesian coordinate systemDecision theoryQuicksortMereologyFunctional (mathematics)Set (mathematics)Library (computing)Parameter (computer programming)2 (number)Computer animationLecture/Conference
31:57
Elasticity (physics)CASE <Informatik>Query languageComputer configurationPoint (geometry)SequelCodeSet (mathematics)Raw image formatComputer animationLecture/Conference
32:54
Perfect groupSurvival analysisCartesian coordinate systemLine (geometry)CodeCombinational logicComputer configurationDifferent (Kate Ryan album)UMLLecture/Conference
34:08
Connected spaceMereologyFunctional (mathematics)Computer configurationCodeNetwork socketQuicksort
34:49
TwitterComputer animationLecture/Conference
35:18
ExpressionExecution unitSource codeComputer animationLecture/Conference
36:05
UsabilityComplex (psychology)Meta elementSocial classCross-correlationCorrelation and dependenceLecture/Conference
36:36
BuildingObject (grammar)Type theoryQuicksortResultantDifferent (Kate Ryan album)Multiplication signData dictionaryPoint (geometry)MereologyDegree (graph theory)Library (computing)Lecture/Conference
38:23
Red HatDemonConfluence (abstract rewriting)XML
Transcript: English(auto-generated)
00:01
Good morning, please. Welcome our next speaker. Honza kraal will be talking about designing and pythonic interface Thank you Hello, and good morning My name is and I would like to talk to you about designing a pythonic interface and
00:26
The better title probably for for my talk which only occurred to me later is an illustrated guide to this If you all know what happens in Python if you if you type import this you get sort of a mission statement instead of guiding
00:49
How it should look and how it should behave and that is what really this talk is about how to take those principles and apply them to designing an interface to to a foreign system
01:02
So first a little little motivation what what brought me here and that's that's elastic the company that I work for Where I actually create a python client for elastic search It's a search and analytics engine and it's not at all important for this talk But what is important is we'll be using it for some for some examples
01:23
So don't be I don't be alarmed if you see some Jason somewhere in there. So let's get to it So import this the the Zen of Python as I said a guiding set of principles and I always like them, you know, they sound cool and they they really make sense to me
01:44
But I always struggle a little bit. How do you actually apply them? How do you apply them to code? Does that actually? Translate does it make any sense? In this talk, I would like to share how I actually discovered or
02:00
Maybe I just rationalized it away. It doesn't really quite matter probably how I discovered how I use these principles when I design a new API and how I actually apply them in a real life and Because I actually said I a lot in just in the past sentence a little bit of disclaimer is in place
02:22
This is obviously my personal opinion. This is what I find that works for me and also Some of you may have seen my code and documentation or lack thereof So please do as I say and not as I do because I certainly am not am not perfect and
02:42
my code Definitely reflects that so Any good talk begins with the definition, right? So API, what do we mean by API? What do we mean by by an interface? So for for this talk in particular we mean a Python API an interface to a foreign system
03:06
So something that will allow you to talk to a third-party system in our case elastic search and This is something that typically you don't need in Python. I mean Python is Turing complete, right?
03:22
You can write absolutely anything in Python so you don't need these interfaces you can communicate directly Especially in case like like elastic search which actually just speaks HTTP and JSON you can just use Requests or any other favorite HTTP library and talk to it directly
03:41
But that's not really what you want to do You don't want to keep rediscovering the wheel and that's why we have a P eyes the some somebody Created an API to make things simpler to to hide away the complexity So you might talk about an API in this case that it is a service for code
04:04
for the real code for the code that actually does the work for the application code and there is a huge difference between The the code of the API and the code of the application the the real code because the API
04:20
is really Doesn't really apply for a specific use case Because the API doesn't know anything about the real code so it can be used by many different people in many different organization and Hopefully it will be like that's sort of what you hope for when you create an API, right?
04:42
That people will use it that it will spread so The application on the other hand is always written to solve a specific purpose So the API fulfills a contract for For that code and the contract can be either explicit or implicit
05:04
It can either be explicit via documentation. You can document the contract you can say these are the methods These are the responses and that's probably something that you should have either way but you can you can also have sort of an implicit contract a cultural one if you please which sort of
05:23
Makes the API behave as you would expect it. It should be it should be natural and you should be able to rationalize and and to think about the API and Avoid any any surprises that's sort of what you want for the users of your API
05:40
To be able to use it as if it were part of their system to not having to think about it too much But first of all, we need to we need to address some of the issues with the API The first one is that the API is vaguer then
06:00
Then application code and yes, I actually had to look this up. It is an actual word. I wasn't sure for a while It is actually it is actually accepted by the dictionary The British protest again What a surprise
06:21
So it is a lot bigger. It doesn't really know what it's going to be used for an application code is specific It solves and it solves a problem. You create an application to scratch an edge to to deliver a solution to your customer or To power your product, but your API can be used in so many different ways
06:43
That you never you never know and making any sort of assumptions on how your API is going to be used is Can be very can be very difficult So ultimately the API is just a tool and you always have to keep that in mind
07:00
That it's a tool that should be a that anyone should be able to wheel to create patient and it's a tool to simplify access and to simplify access the crucial part there is to simplify and We have our first line from design of Python simple is better than complex
07:24
Complex is better than complicated and that is the purpose of the API to actually facilitate this this line To take something that would be complicated opening a socket Creating an HTTP header sending it over Creating a JSON body sending it over receiving some responses determining if everything went okay, etc, etc
07:45
That's definitely unnecessary complex and that applies to to anything if you want to work with HTTP you also probably wouldn't start with raw socket, but you would use something like requests a
08:00
Well design library that just Gives you exactly the functionality that you need in a way that you can that you can use so That's that's what simplifying access is about it's about hiding complexity So this is a query for to elastic search. Don't worry if you if you don't understand it
08:26
Essentially what this is is I'm looking for something that that matches Python in the title It must not match beta in the description. So I'm looking for release. I'm filtering only those packages in
08:41
Category search and I want to do some aggregations. I want to see the distribution of tags and the maximum lines So just some just some query Assuming assuming a data set and that query is not important what is important that there is a lot more things on the screen than what I just read and
09:02
I read all that this does in The end I it just prints it out with the relevancy score and the and the title of the risk of the document So there isn't really a lot a lot of things actually going on But there is a lot of things that are being typed there So, how do we how do we simplify that? How do we hide the complexity?
09:25
well this is what I came up with and I'll spend the rest of my talk explaining to you why and how I came up with that. I Already see some people cringing because they've used this code before It's never a good sign
09:42
Okay, so in this case, I tried to extract only the things that are relevant Only and the stuff that I actually read only the action items not really Not really all the gravy all the boilerplate code and to me that's what an API should do It should hide away all the boilerplate
10:03
While leaving all and that's that's the crucial part while living all of the important parts Not just some but all of the important parts And that's sort of the embodiment of another line of design of Python be explicit
10:21
Explicit is better than implicit So while I I hid away a lot of the complexity. I didn't hide away the crucial parts and that's sort of the Very important decision what to hide and what not to hide Because you can always go then the next step you can always imagine how you could make this even simpler
10:43
for example just creating some sort of query language where you would just say the three words and Say this should be there the shouldn't and this must be there as a filter Etc, but at that point it's it's getting hard to read. It's getting hard to get into it's getting hard to reason about
11:02
so be explicit and In in the word of code what that means is when you're hiding Complexity do hide the mechanics do not hide the meaning So If you're doing an HTTP request
11:23
with Requests you still have to know what is the difference between get and post and put? That is the meaning that is not the mechanic what you don't really want to know about is about sockets and and Parsing of HTTP headers you just want a convenient access to it
11:42
So that's mechanics that's something that you should hide away That's something that's not specific to the problem. That's specific to the implementation So this is sort of how how you how you draw the line what to hide and what not to hide
12:00
So if we look into into the the original the original code So you get you see I've highlighted the parts that are actually just the mechanics Sorry about this Where you see that I have a I have a bool query which which has three branches must must not and filter and those can be those can be very confusing and
12:27
Also, they don't matter They don't come they don't carry any information. There are just a Way that the query DSL the language that elasticsearch uses based on JSON how it expresses
12:41
How to combine other queries it is it is the how it is not the what in this case? This is not what you want to do This is how you want to do it And this is something that I I don't want my my users to have to know in order to use my library
13:01
However, I am fully comfortable in forcing them to know all the rest So I that's all that I hid. I never I never hid the match or or the term query So This is the meaning You still have to know what is the difference between a term query a match query and how to do how to know negation in
13:24
This case the negation is in Python. So we should all be familiar with it, but That's the meaning that's the same as requests still asking you to know the difference between HTTP get and HTTP post If I if I hid this away it would make a lot of a lot of people's lives easier
13:46
But then you would have a very narrow ceiling after which there is nothing there is nothing you can do and also, this means that I don't have to Teach my users everything they can just use the skills that they already have
14:04
by understanding the query DSL of LSX search itself On the other side with the request example people understanding HTTP and HTTP methods. I don't have to Reinvent that it's already there people already know it. So all I have to do is give them access to it
14:25
And A similar thing goes for goes for the results Here I have some some crazy dictionaries with with underscore source and underscore score That can be a little difficult and again
14:40
It just bears no meaning 90% of the time people just want access to the fields or alternatively the metafields So again, just abstract it away Hide it and also provide a more convenient way to access it So instead of square brackets and quotes and underscore source in every single line just use the title
15:02
So this is something that just simplifies the mechanics while not actually taking anything away And also It's good to fully admit to the leakiness So in this case still showing all the different all the different query types
15:24
All the different aggregations you see that I still force The users to name their aggregations just as they would in the in the query DSL So they can then get them back in the results. It's a very thin abstract layer Exactly because I want people who use elasticsearch in some other context maybe from another language
15:46
Maybe directly through the browser or the command line. I want them to be more effective I don't want them to have to learn yet another tool to do what they already can do and Also, once they learn this tool
16:01
I don't want that to go to waste if they have to change to something else or If they have to ask for advice online If I if I created my own complete query language, and then I had to ask someone On the internet. So this is what I'm doing with ausik search. Can you help me?
16:21
Well, the answer will be no because nobody else will understand that query language. So the standardization the Leaky abstraction here is very very important and very deliberate and It is also because well, I'm lazy and I don't want to rewrite the entire documentation of elasticsearch. What query does what?
16:44
Here's that too So that's sort of another guiding guiding principles be familiar Present to the user something that they did they know from somewhere else whether it's a whether it's a universal concept like
17:04
Different types of HTTP requests or different types of queries in elasticsearch or something that's already been used before so Don't be afraid to just copy shamelessly from stuff that you've seen around
17:23
So essentially you could sum up the library that I created the elasticsearch DSL as a combination of these two things The second one we've already seen that's just using the raw elasticsearch API and the first one Well, that's Django where it says
17:41
so that I borrowed some Some patterns from Django some patterns from elasticsearch and combine them together So for example the the chaining the the fact that every additional filter whenever you add a filter You will get return a copy of the of the query that comes from that comes from Django. That's something that people
18:07
expect or at least are familiar with and Then you have all the different all the different query types that come from from elasticsearch so Python people who want to use elasticsearch should be familiar with both of these concepts and the API should feel
18:25
Homie to them should feel familiar. They shouldn't be surprised and they should be they should be effective so once I did that I Turn into to another rule be consistent once you figure out your approach stick to it
18:44
So special cases aren't special enough to break the rules so every single method that you have on this on the search Object in our secure DSL will return you copy the the chaining works just as expected and
19:03
The other important part that people sometimes forget about when talking about consistency is the naming Name things consistently name name things consistently with other systems, but more Exactly within your system
19:21
Always call it the same And that is both in your code and also in your in your documentation And of course only do this if this makes sense Because practicality always beats purity in in Python. Like we are we're practical people. We we're not
19:42
Really interested in the in the pure Purity just for just for its sake so Don't be afraid to make an exception Like try not to make one, but if you have to that's okay. So in our case
20:01
We have we have the queries on Of the top that follow the pattern every to every call to a method will create a clone of the query object mutated and return it However, when I try to do this for for aggregations This just didn't work
20:20
Because aggregations can be nested and the first way how people Me including try to represent nested aggregations would be just to nest nest the chaining calls and At that point it all broke down. I couldn't no longer be creating a copy after every after every call
20:43
So I had to I had to break the pattern. So when you access as the eggs, it's actually done in place So don't be afraid to break the rules Try not to but also keep in mind that it might happen that you just will have to and that's okay
21:02
the Zen of Python says so and Part of people then me wrote that so I'm okay with it Another very important rule when designing an API is be friendly Be friendly to your users
21:21
On both sides be friendly to the users of your API but also be be friendly to the system that you're trying to simplify access to and to me The only non-obvious part well hardly obvious because it's still pretty obvious
21:40
is to realize that Python is interactive a Lot of people use Python from stuff like IPython or They use fancy IDEs to explore that the API's and you should you should be able to support this You should be able to help them with that by providing them all the tools that they could that they could ever need
22:05
In the case of Python those those are the three main ones Their Representation and and doc strings, which if if implemented properly will greatly help
22:20
with With actually Allowing the users to explore the the API and start using it both the beginner users who just came to your code for the first time and are just exploring around and
22:40
Also the advanced users where this can greatly speed up speed up the process For example the the representation String is Often underestimated and it can be super useful One of the most common questions that I get with elastic search DSL is I have this crazy query in
23:05
JSON that somebody wrote or some other tool generated. How do I express this in elastic search DSL? Well, I say that's easy. You just create a query out of it by wrapping it in the in the queue object and
23:21
Just ask for the representation and what you get back is exactly the code that will that it would take to reconstruct that just using just using the DSL library So that's what really the representation string should be a
23:40
representation of the object that you can Essentially retype into Python and get the same thing In some cases, it's not practical if you have large objects, obviously Or you have something that can only exist exist once it's not that useful But in this case, it is definitely definitely very useful and it saves me a lot of time
24:03
Because this is something that I myself use quite often that I have this I have this crazy dictionary containing a crazy query with 10 different sub queries and 50 aggregations and I want to manipulate it and
24:20
Manipulating the dictionary itself is quite difficult. That's why I created this library in the first place so I just wrap it in the wrap it in the cube just get the Query object that I can work with and Then when I want to put it in my code, I can use the representation and and put it in there
24:44
And of course, of course docstrings Be be nice to your users Provide even some examples in your docstrings. Those are the most useful if you if you're reading if you're reading a header of a method like this
25:02
it's pretty Pretty evident what it does, but if it were anything more More involved with more parameters. It's always nice to include an example right there Both for when somebody is reading the code and also when somebody is just looking in their IPython
25:20
Of on what's what's actually what's actually going on? So that's one part of Python being interactive That's the more obvious part the second part is enable iterative build because again the Zen of Python teaches us that flat is better than nested and
25:41
Sparse is better than dense so what does that mean if you if you build something up if you if you want to build a Sophisticated query into elastic search you keep adding clauses first filter on this then on that add this aggregation And if the user requested this filtering add this kind of filter
26:01
so there is a complicated state that you need to remember what the query currently looks like and It's a sign of a polite API as I would call it that it doesn't force you to remember the state But it can store the state internally so you can use the API from the get-go and start building your
26:24
query in this case or your request in other cases And You don't have to store everything yourself so in our case it looks like this You can also see that this
26:40
enables for nice practices like commenting the code and actually explaining to to the users what they're doing and I can go line by line and very easily very easily deconstructed even if you're new to New to elastic search you would probably be more or less able to tell what this does
27:03
especially with the comments Sure, there's still some there's still some magic. There's still something that's specific to elastic search We've talked about the term and match and all the different Weirdness of the syntax, but overall this should not be surprising I Want to only filter category search, then I want to match the title to Python
27:25
Etc etc But the most important part is I don't have to first build up some weird dictionary containing all the keyword arguments or represent the state in any way I can just keep creating and keep adding to the search object and
27:44
Be be happy with that so iterative build. It's often something. That's that's Underappreciated Because it allows you to Not care about this about the state which can be which can be very hard and finally
28:06
When we're talking about being friendly safety is also very friendly You should always fail Explicitly unless unless it's explicitly silenced so all your defaults
28:21
Should should actually be the safest possible So if you have if you have any option to fail for example elastic search will always give you a response even if only 20% of your data is available. It will give you a response and say hey I only see 20% of your data, but here have some have some results anyway
28:42
And then it's up to the user to decide whether that's good for them or bad When Faced with the decision like this like do I do I fail in this case or is it okay? And do I leave it to the user I say always fail But allow the user to override it
29:02
Allow the user to say I I'm aware that this is a situation that might happen, and I don't care But at that point you force the user to explicitly own the responsibility To maybe even do some do some research You've noticed that that's something that that I've repeated quite often during this talk
29:26
to not be afraid to force the user to actually learn something about what they're doing and This one is particularly important because it deals with it deals with safety And it helps prevents nasty surprises once the user moves to production
29:48
also Think about how you test your code and how other people test their code Provide some sort of
30:00
Dummy interface or maybe just a set of test test case classes for For the your favorite testing libraries out there so that people Have lower barrier to entry to do some testing Essentially obey the testing code make the testing as simple as possible
30:24
Because that's what you want to do Ideally you already have some code like that somewhere somewhere in there already because you should be testing the API So it's only a matter of exposing exposing that part
30:40
Also to to your users sort of a test helpers or something like that and the final chapter is about API still being code it's Different from an application code and we've we've highlighted the reasons how?
31:00
But it's also similar in a lot of cases. It needs to be tested Things can change and you might need to you might need to adapt also There is a there is a lot of a lot of decisions going into how do you decide what goes in and
31:20
What doesn't what are what are the features that you want as part of your library as part of your API? And what do you leave sort of as an exercise to the user? Do I provide this set of helpers do I? Do I expose this functionality this this parameter or is it only used by a very few people and
31:42
There are there are several several ways how to how to do that First of all is the actual decision, but second is that's my favorite to avoid that decision and allow the more advanced users to sort of to always step away a little bit and
32:00
Provide them access to the lower light lower layer the more low-level API In case of elastic search I can always go one step back and just send in a raw dictionary if I don't want to create The query using that the iterative syntax that I just showed you I can always just create it myself
32:21
And at that point I don't have to care what options are supported by the DSL And which aren't I can just do everything manually and send it back the same again. It's not a novel idea it's the same with the dot raw method on Django query sets where you can just send in a SQL query
32:40
When you don't want to rely on the ORM to generate one for you so always allow access to the lower level if at all possible and Also admit that no code is perfect and That goes especially for especially for API's
33:00
Because there are bigger Than than the actual application code and When deciding what to include and whatnot keep in mind the last line of zenith Python that we'll deal with today Now is better than never although never is Often better than right now
33:22
And that's the that's an important. That's an important thing When you don't know whether to include something or not. It's perfectly fine to say no especially if you if you have a way for the user to move around you and So I always prefer to give them away around my code
33:43
Then to try and support all the different possible avenues through my code because that can lead to a nightmare They can lead to a nightmare for my users with an overwhelming amount of options And definitely for a in a nightmare for me supporting all the different all the different combinations
34:02
So so think about what makes sense and how hard it is To do it without direct support in your code if it means that When I'm not supporting this option a user will have to Create a dictionary and send it in manually. I'm okay with that
34:23
if it means that they will have to instantiate a new connection and talk to a socket directly and and do some other Complicated stuff maybe not that much and I want to I want to provide them that functionality directly so That's sort of the last part of how you decide what to support and what not to support
34:46
and Now I believe we have 10 minutes for questions If you don't get your questions answered or you just want to yell at me. There is my there is my Twitter and Anybody has any questions?
35:40
Thank you for your talk and I had a question so
35:44
If we create great API with expressive AP expressive syntax Don't you think that we're making the internals of the of the API more complex and really hard to maintain
36:02
Can we avoid that? Yes There is not necessarily a correlation between the complexity I and the and the ease of use Yes, sometimes you might need to resolve to more complex things like using meta classes and descriptors if you want to make
36:21
things nice But it's not it's not necessarily true so it might happen but it but it doesn't have to there is there is no direct correlation there Thanks Anyone else I
36:45
What role do you think Emulating built-in objects or using like Python types like the building types comes into writing a Python and KPI For example when like when should you do you think you should use dictionaries?
37:07
Lots or should you instead use like make a little DSL for your particular thing or I see so I prefer to Again
37:21
Decide what can you take away and then compare the results? So if I use raw dictionaries and if I if I create my own thing What part of the pain goes away is it enough to justify the the extra dependency the work that will go into the API etc just sort of do this exercise in your mind like
37:45
Okay, these things I can I can abstract away these things I can generate automatically so the user will only have to put in these these four things and Then compare the results it might be that the differences wouldn't be big enough to justify creating a DSL
38:01
Creating a library from both the point of putting the work in and also forcing the people to learn that so that's that's what I do like every time I Sort of mock up how the API would look like and then I compare is it worth it or is it not? Does it make sense?
38:24
Okay, if you have any more questions you can just grab them at coffee or during lunch give me a big hand applause