Plone api


Published on

My talk about plone.api on the Plone Conference 2012 in Arnhem.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • \n
  • - non-coders sit down\n- from where to import getToolByName\n- get site root\n- copy content object\n
  • Hi, I’m Nejc and this is a story about how Plone development went to a dark place ... and what we are doing to bring it back!\n
  • \n
  • we were building a portal for a student organization\n
  • The workshop was organized by EESTEC.\nEESTEC = electrical engineering students in 53 universities,\nAll event applications go through, a Plone portal.\nMultiple events per year, more than 2000 users\n
  • More than 25 hundred EE students using Plone, many of them programmers.\n\n
  • Out of that 25 hundred potential Plonistas how many did we manage to keep in the development team?\n\n\n
  • Two. Less than 0.1 percent of potential pool of students and 50+ of them attending week-long development workshops. \n\n
  • Main reason? This thing.\n
  • Plone 3, for us, made it:\n
  • Now, Plone 4 did make *a lot* of things easier. But numerous problems still persist:\n
  • All the time you need to search for where does that one thing import from\n
  • There are many ways to achieve tasks: how to know which is correct?\n
  • Manipulating objects is not trivial, you need to search for code.\n
  • Let’s look at workflow states: you *have* to Google for snippets.\n\nThe list goes on an on.\n
  • This is BAD. This is why we couldn’t keep developers in. This is why our documentation is hard to follow. This is why it’s hard to train.\n
  • Enter plone.api. An elegant and simple API,\nbuilt for humans wishing to develop with Plone\n
  • The initiative for having a unified API for common Plone tasks started this year at the Plone Konferenz in Munich\n\n- Antwerp Beer Sprint: teaching students how to develop with Plone -> when stumbled upon a part that was ugly, a team of Ploners made a plone.api method for it\n\n- +15 commiters\n\n
  • Explicit is better than implicit.\nReadability counts.\nThere should be only one way to do it.\nNow is better than never.\nWe only want to cover the most common tasks and use-cases, not all.\n\n
  • Looking back to the question of from where to import that thing?\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • And one of my favorites, as I could *never* remember how to do it.\n
  • It’s now this simple to do it.\n
  • \n
  • Document Driven Development\n- plenty of room for discussion\n- not much to re-program if we fail with the first try\n- a nice looking and usable api because we already used it (in the docs)\n\n(NEXT SLIDE HERE!)\n\n
  • Plone.api comes with narrative documentation,\nthat guides you through common use-cases of how to use the api.\n\nNarrative documentation means written in a way that guides you through how you can\nuse the API, but does not cover all use-cases, to keep text simple.\n\nHowever, if you click on one of these links, you get to the full-spec advanced documentation\n
  • Besides that you have the full-specs documentation of every method.\nWith all possible parameters and edge-cases explained.\n\nThe information here is pulled directly from the code, so it is always up-to-date.\n\nIt describes all possible parameters you can pass to a method, its return value, etc.\n\nExample links back to narrative documentation from the previous slide.\n
  • \n
  • * high test coverage\n * all code examples in the narrative documentation is also tested so we make sure the examples actually work\n * everytime there is a commit, an online service called Travis CI runs all tests (more about Travis in my talk tomorrow morning)\n
  • here it is, history of builds and their statuses\n
  • Methods are grouped by their field of usage:\nPortal, Content, Users and Groups.\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • Integration: project specific, you know the stakes.\nAdd-on: very likely you may use it, but maybe you’ll have to use some underlying APIs later on to cover edge cases\nCore code: Nope, core code needs to cover *all* possible scenarios.\n
  • However, our work is far from finished.\nYou can expect the following features in the future:\n
  • - maintenance tasks and scripts\n- tests!\n
  • - for debugging addons\n- for tests\n- for code dependant on Plone version\n
  • \n
  • Now this is a HUGE one!\n
  • Sysadmins I’m looking at you!\n
  • - todo-app coding dojo to go through the tutorial and test it while learning sth. new\n- coding new plone.api methods -- doable by human-only developers\n- increasing test-coverage\n- we need a native english speaker that is a solid in writing to go through our narrative text and give it some love\n
  • What if someday, plone.api is widely used in most of integration code and add-ons. \nImagine:\n- a non-suicidal learning curve\n- single point of reference for common tasks\n- standardized AJAX/WebServices access\n- upgrades to Plone core code would keep add-ons working!\n
  • Let’s start living this dream.\n\nCrying over how Plone is getting impossible to work with is not enough.\n\nFight for your rights as a developer. Do something to make your\nday-to-day Plone experience better. Let’s live the utopia.\n\nGive plone.api a spin, report bugs, propose ideas, join our sprint!\n
  • It’s now up to you, humans using Plone, to\n - try out plone.api\n - shout out what bothers you or what is missing\n - and help with development\n
  • Plone api

    1. 1. plone.apiNejc Zupan, NiteoWeb Ltd. Plone Conference 2012
    2. 2. Everybody stand up please!
    3. 3. self.context
    4. 4. • 2006• Student workshop• Plone 2.5• Life was good!
    5. 5.• Online since 2009• Switched to Plone 3 during development• +2500 users• Several events per month
    6. 6. +2500 ElectricalEngineering Students
    7. 7. no. of newcontributors:
    8. 8. no. of newcontributors: 2
    9. 9.• Online since 2009• ***Switched to Plone 3 during development***• +2500 users• Several events per month
    10. 10. Plone 3Impossible to: - train - write docs for - stay productive - keep devs happy
    11. 11. Plone 4?
    12. 12. From where toimport that thing?
    13. 13. Many ways to getthe Site root: which is correct?
    14. 14. Copy/move objects?target.manage_pasteObjects( source.manage_cutObjects(source_id))
    15. 15. Workflow state?workflow = getToolByName( portal, portal_workflow)workflow.getInfoFor(obj, review_state)
    16. 16. plone.api
    17. 17. plone.api• Started at Plone Konf Munich• Alpha release at Belgian Beer Sprint• Gaining momentum!
    18. 18. Inspiration• PEP20• PEP8• Pareto Principle• SQLAlchemy• Requests
    19. 19. From where toimport that thing?
    20. 20. from plone import api
    21. 21. Many ways to getthe Site root: which is correct?
    22. 22. api.portal.get()
    23. 23. Copy/move objects?target.manage_pasteObjects( source.manage_cutObjects(source_id))
    24. 24. portal = api.portal.get()contact = portal[about][contact]api.content.move( source=contact, target=portal,)
    25. 25. Workflow state?workflow = getToolByName( portal, portal_workflow)workflow.getInfoFor(obj, review_state)
    26. 26. api.content.get_state( obj=portal[about])api.content.transition( obj=portal[about], transition=publish,)
    27. 27. It’s documented!
    28. 28. It’s documented• Document first• Narrative documentation• Advanced usage documentation
    29. 29. It’s tested!
    30. 30. It’s tested• ~95% test coverage• Narrative documentation included• Continuous Integration
    31. 31. Import and Usage stylefrom plone import apiportal = api.portal.get()user = api.user.create(username=bob)api.content.move( source=portal[blog], id=old-blog,)
    32. 32. api.portal• get()• get_navigation_root()• get_tool()• get_localized_time()• send_email()• show_message()• get_registry_record()
    33. 33. api.content• create() • get_uuid()• get() • get_view()• delete() • get_state()• copy() • transition()• move()• rename()
    34. 34. api.user• create() • is_anonymous()• get() • get_roles()• get_users() • get_permissions()• get_current() • grant_roles()• delete() • revoke_roles()
    35. 35.• create() • add_user()• get() • remove_user()• get_groups() • get_roles()• delete() • get_permissions() • grant_roles() • revoke_roles()
    36. 36. In the wild• tutorial.todoapp• eestec.portal• 100k objects / 300 users production site
    37. 37. Where to use plone.api• Integration code? Yes.• Add-on code? Likely.• Core code? No.
    38. 38. Coming up
    39. 39. api.rolewith api.role(Manager): # do something bypassing all # constraints, permissions, etc.with api.role(Reviewer): # do something as a reviewer to see # if permissions are set correctly
    40. 40. api.env• api.env.debug_mode()• api.env.test_mode()• api.env.plone_version()• api.env.zope_version()
    41. 41. api.system• Run upgrades• Cleanup broken objects, utilities, interfaces ...• Mount things• Make sysadmins happy!
    42. 42. JSON WebServices• Probably packaged as plone.jsonapi• One-to-one mapping to plone.api methods• @@jsonapi view• Standardized JavaScript writing!
    43. 43. Help us!• Translating documentation into your language• Multilingual Sphinx on RTD anyone?• Show us your home-baked maintenance scripts• All this and more, at the post-conference sprint
    44. 44. Post-Conference sprint• TodoApp coding dojo• Implement remaining plone.api methods• Get the test coverage even higher!• Native speakers’ love to our docs• Let’s get beta release out there!
    45. 45. Utopia
    46. 46. Thanks! Give it a spin! propose ideas! Join the sprint!