Most "pythonic" syntax to use for an API client library

[DL Neil]

On 29/04/19 4:52 PM, Chris Angelico wrote:
> On Mon, Apr 29, 2019 at 2:43 PM DL Neil <PythonList at danceswithmice.info> wrote:
>>
>> On 29/04/19 3:55 PM, Chris Angelico wrote:
>>> On Mon, Apr 29, 2019 at 1:43 PM DL Neil <PythonList at danceswithmice.info> wrote:
>>>> Well, seeing you ask: a more HTTP-ish approach *might* be:
>>>>
>>>> api.update.customer( 1, name='Bob' )
>>>>
>>>> ie
>>>> api.verb.subject( adjectives and adverbs )
>>>>
>>>> Thus:
>>>> api_label/intro/ID.what_we're_going_to_do.who/what_we'll_do_it_to(
>>>> customerID, support_data)
>>>>
>>>> Yet, it doesn't really *look right* does it?
>>>> (and someone might complain about mixing the 'different' variable-values...)
>>>>
>>>
>>> The point here is not to make an HTTP-like interface, but a
>>> Python-like interface :)
>>
>> OK, I'll bite...
>>
>> ...shouldn't the Python-like interface reflect what it is wrapping?
> 
> It should. But if you just want an HTTP-like interface, you don't
> really need much of a wrapper. All you need is a hyperthin wrapper
> around the requests library - something like:
> 
> api.post("customer", {...})
> api.get("customer", 1)
> api.patch("customer", 1, {...})
> 
> And that's fine if what you want is HTTP. But if you want something a
> bit more Pythonic, you want something that more adequately represents
> the underlying concepts, not the intermediate transport layer. In this
> case, the concepts are customers (and, presumably, other types of
> queryable information), and the things you can do with them (get info,
> update info, enumerate, create).
> 
> There may be some useful inspiration to be gained from looking at database ORMs.


Yes. I certainly read "thin" into the OP - see also your own comment 
earlier re: "metaprogramming model", which presumed a likelihood of 'more'.

Once bring ORMs, etc, into the equation, then (and depending upon the 
selected tool), recommend maintaining a consistency* to avoid future 
reader-confusion/cognitive-load.

* "hobgoblins" of the world unite!

(having just unravelled some poor soul's vacillation about whether 'it' 
is "width" before "height" or v-v; who then doubled-down by falling into 
the 'where is this-package's Cartesian origin' confusion, aka in which 
direction does *this* y-axis flow?)
-- 
Regards =dn