Nejc Zupan - plone.api

Nejc Zupan talks about plone.api during the Plone conference 2012.

This is a story about how Plone development went to a bit of a dark place and is now coming into the light again.

http://eestec.net is a website for more than 2500 European engineering students. Running in Plone 3. Two of those engineers stayed in Plone. The main reason was that we switched to Plone 3 during development. It got harder to train people. Plone 4 has improvements, but there are still problems.

You always have to remember from where you should import that function or class. Copying or moving objects is hard to remember how to do programmatically. Sample code is harder to read because of this.

So the idea of plone.api was born during the Plone Konferenz in Munich early this year. Work was done during the Belgium Beer Sprint. Eestec students new to Plone were working on rewriting the site in Plone 4. They gave feedback about what should become part of plone.api.

Inspiration came from:

• PEP20 (import this)
• PEP8
• Pareto principle: we document and support the 20 percent of tasks that you use 80 percent of the time.
• Documentation first.

Getting the site root: api.portal.get().

Moving an item: api.content.move(source=..., target=...).

It is documented. We document first. We write narrative documentation. The online documentation is pulled from the code and the comments in the code.

It is tested. We have about 95 percent test coverage. Narrative documentation is included in the tests. We have Continuous Integration set up with Travis CI.

Import and usage style:

from plone import api
portal = api.portal.get()
user = api.user.create(username='bob')

We have api.content, api.user, api.group.

It is used in the wild. There is tutorial.todoapp as a tutorial application you can try out. eestec.portal uses it. We have been using it in production for about a month on a portal with 100k objects and 300 users. No problems, although it is alpha code.

Where should you use it? In integration code? Yes. In add-on code? Likely. In core code? No.

In the future we should get api.role:

with api.role('Manager'):
    # Do something as manager

• api.env.debug_mode(), api.env.plone_version()
• api.system for running upgrades and things like that

We could create plone.jsonapi to package code around json.

We need lots of help.

• We want more translations of the documentation.
• Multilingual Sphinx on readthedocs.org?
• Show us your home-baked maintenance scripts.
• Sprint on this during the conference sprints.

Utopia would be that the Plone learning curve gets lower because of this and we can put up a small cheat sheet for new (or old) developers.

Fight for your rights as a developer!

Download plone.api and give it a spin on your development environment.

Code: https://github.com/plone/plone.api

Documentation: https://readthedocs.org/docs/ploneapi/en/latest/index.html

Steve and Andy: I think we should actually use this in the core code too. At least if a new package is using plone.api and this package gets moved into the core, then we should not require a rewrite without plone.api before it is accepted into the core.