WARNING: If you are reading this on GitHub, DON'T! Read the documentation at docs.plone.org so you have working references and proper formatting.
We want plone.api to be developed with PEP 20 idioms in mind, in particular:
Explicit is better than implicit.Readability counts.There should be one-- and preferably only one --obvious way to do it.Now is better than never.If the implementation is hard to explain, it's a bad idea.If the implementation is easy to explain, it may be a good idea.
All contributions to plone.api should keep these rules in mind.
Two libraries are especially inspiring:
- Arguably, the reason for SQLAlchemy's success in the developer community lies as much in its feature set as in the fact that its API is very well designed, is consistent, explicit, and easy to learn.
- If you look at the documentation for this library, or make a comparison between the urllib2 way and the requests way, you cannot but see a parallel between the way we have been and the way we should be writing code for Plone. At the least, we should have the option to write such clean code.
The API provides grouped functional access to otherwise distributed logic in Plone. This distribution is a result of two historical factors: re-use of CMF- and Zope-methods and reasonable but hard to remember splits like acl_users and portal_memberdata. Methods defined in plone.api implement best-practice access to the original distributed APIs. These methods also provide clear documentation of how best to access Plone APIs directly.
If you doubt those last sentences: We had five different ways to get the portal root with different edge-cases. We had three different ways to move an object. With this in mind, it's obvious that even the most simple tasks can't be documented in Plone in a sane way.
We do not intend to cover all possible use-cases, only the most common. We will cover the 20% of possible tasks on which we spend 80% of our time. If you need to do something that plone.api does not support, use the underlying APIs directly. We try to document sensible use cases even when we don't provide APIs for them, though.
from plone import api portal = api.portal.get() catalog = api.portal.get_tool(name="portal_catalog") user = api.user.create(email@example.com')
Always import the top-level package
from plone import api)
and then use the group namespace to access the method you want
portal = api.portal.get()).
All example code should adhere to this style, to encourage one and only one preferred way of consuming API methods.
We prefer using keyword arguments to positional arguments. Example code in plone.api will use this style, and we recommend users to follow this convention. For the curious, here are the reasons:
- There will never be a doubt when writing a method on whether an argument should be positional or not. Decision already made.
- There will never be a doubt when using the API on which argument comes first, or which ones are named/positional. All arguments are named.
- When using positional arguments, the method signature is dictated by the underlying implementation (think required vs. optional arguments). Named arguments are always optional in Python. Using keywords allows implementation details to change while the signature is preserved. In other words, the underlying API code can change substantially but code using it will remain valid.
- The arguments can all be passed as a dictionary.
# GOOD from plone import api alice = api.user.get(firstname.lastname@example.org') # BAD from plone.api import user alice = user.get('email@example.com')
We could wrap an object (like a user) with an API to make it more usable right now. That would be an alternative to the convenience methods.
Unfortunately a wrapper is not the same as the object it wraps, and answering the inevitable questions about this difference would be confusing. Moreover, functionality provided by
zope.interface such as annotations would need to be proxied.
This would be extremely difficult, if not impossible.
It is also important that developers be able to ensure that their tests continue to work even if wrappers were to be deprecated. Consider the failure lurking behind test code such as this:
if users['bob'].__class__.__name__ == 'WrappedMemberDataObject': # do something