This document is there to describe the current state of the idea plone.api.
At the german Plone Konferenz we had a open space with eleddy and realized at some point that the documentation about plone is not only badly organized, but that it's also pretty hard to write good documentation.
If you want to teach users how to get the site root, there are about five different methods and none of them is recommended for a 100% usecase even from plone professionals. In addition you first have to teach the whole ZCA for the required knowledge about adapters. An acquisition tutorial would also be required.
Then, as we tried to find ideas how to make this all easier, we came up with the idea plone.api. As soon as we had this idea, we saw endless possibilities to make our lifes easier with the very same thing. We all know that there's a manage_something method to copy an object. But what's that something? And wasn't there a paste-method too?
So we discussed how this plone.api could look like. But there was one thing we agreed on from the beginning. This was it:
By starting with the documentation we will make sure that there will be
So we started with three possible structural layouts for the API.
Just create a bunch of methods to make life simple. Name them like what they do (e.g. remove_user_from_group). That way, the API would be easy to document and use. But not very pretty.
get_object(path=path) create_object(path=path, id='some', title='...') create_object(parent=site, id='some', title='...') set_password(user_id='some', password='qwert')
That's like the PHP style, but we group similar functions into namespaces. Like to put all functions to do something on users into plone.api.users. Inside, there would be a function called 'leave_group'. Function names would be shorter, because the context of the function would be the group namespace.
content.get(path=path) content.create(path=path, id='some', title='...') users.set_password(user_id='some', password='qwert')
Another approach was to wrap us around plone. We wanted to emulate dict-style access to anything anywhere.
site = plone.api.site() site['folder']['obj'] = plone.api.create(title='The object') users['bob'].password = 'asdfg' users['eliza'] = plone.api.create_user(password='secret')
In this document I don't want to get into details about the advantages or disadvantages of the seperate possibilites for the api. All I want to say is that we are not 100% sure about it ourselves. So this whole idea is still subject to discussion.
As I already mentioned: Right now, we only set up the framework for the documentation. No code has been written. We are trying out if we can reach the goals to simplify documentation and to make our lifes as programmers easier.
We have a good selection of functions that we think make sense for a start of all this. You can find it here (currently in namespace style) as narrative and API documentation: http://readthedocs.org/docs/ploneapi/en/latest/index.html
Any discussion and examples of different approaches are very welcome. Not only about the amount or arguments of functions, but also about the style of the api. We will now slow down and let this settle.
We know that we must make the api right in the first place. When the api will be widely used (maybe, but hopefully not by plone core products), we won't be able to change it anymore. We know about that responsibility.