[Product-Developers] plone.api idioms

[Sean Upton]

Folks,

Not trying to troll on wholly subjective matters, but...

I know that plone.api is a procedural API.  Is it intended to only be
such at the exclusion of other idioms (e.g. mappings)?

Here's where I'm coming from: I want to add some functionality to
plone.api.user.

I would really much rather have callers ask these questions:

    >>> assert my_user_id in api.user.users
    >>> assert groupname in api.group.groups
    >>> print len(api.user.users)   # without iterating
    762

... than these (possible) questions:

    >>> assert api.user.has_user(my_user_id)  # not pythonic
    >>> assert my_user_id in api.user.get_users()  # slow iteration forced
    >>> assert groupname in api.groups.get_groups()
    >>> print len(api.users.get_users())  # again, forced iteration
    762

>From my perspective making mapping proxies for simple things is more
pythonic at the expense of violating the norm of only using procedural
idioms.

But what is the value of being strict to only procedural idioms (and
are such idioms artifacts of literature on API design influenced by
the C language)?  Being too strictly procedural here could have
downsides:

(1) Makes any (future) remote wrappers much more like RPC than REST
for a system that is fundamentally resource-based

(2) Ugly, less pythonic.  Making complex things simpler mappings of
names to values is one of the best graces the Python language gives
us.  We trade succinct clarity of expression for consistency with
language-neutral idioms of procedure naming.


OTOH, is making this procedural the cost of making it accessible?
Maybe it is subjective, but a strict interpretation to that end seems
to sacrifice both beauty and clarity.  And I guess that if plone.api
intends to be more than just an accessible wrapper, but have core use
too, I would hope that there is some pragmatic wiggle-room here
("practicality beats purity")?

Sean