The plone.api is an elegant and simple API, built for humans wishing to develop with Plone. It comes with cookbook-like documentation with step-by-step instructions for doing common development tasks in Plone. Recipes try to assume the user does not have extensive knowledge about Plone internals. The talk will be about the philosophy and rationale behind it, what it offers and how to use it. Since recently plone.api's code conventions and style guide have been adopted by the Framework Team as the Plone Core conventions. We'll go through these recommendations and discuss why they are there and why you should start using them in your own code also. Finally, we'll walk through some bits and pieces of plone.api's internal code, to give you the idea of how modern Plone code should be organized and formatted, as an example of coding conventions mentioned above.

1. plone.api
Plone development best practices revealed
@nzupan
petek, 04. oktober 13

2. Everybody stand up please!
petek, 04. oktober 13

3. petek, 04. oktober 13

4. self.context
petek, 04. oktober 13

5. • 2006
• Student
workshop
• Plone 2.5
• Life was good!
petek, 04. oktober 13

6. eestec.net
• Online since 2009
• Switched to Plone 3 during development
• +2500 users
• Several events per month
petek, 04. oktober 13

7. +2500
Electrical
Engineering
Students
petek, 04. oktober 13

8. no. of new
contributors:
petek, 04. oktober 13

9. no. of new
contributors:
2
petek, 04. oktober 13

10. eestec.net
• Online since 2009
• ***Switched to Plone 3 during development***
• +2500 users
• Several events per month
petek, 04. oktober 13

11. Plone 3
Impossible to:
- train
- write docs for
- stay productive
- keep devs happy
petek, 04. oktober 13

12. Plone 4?
petek, 04. oktober 13

13. From where to
import that thing?
petek, 04. oktober 13

14. Many ways to get
the Site root: which
is correct?
petek, 04. oktober 13

15. Copy/move objects?
target.manage_pasteObjects(
source.manage_cutObjects(source_id)
)
petek, 04. oktober 13

16. Workflow state?
workflow = getToolByName(
portal,
'portal_workflow'
)
workflow.getInfoFor(obj, 'review_state')
petek, 04. oktober 13

17. petek, 04. oktober 13

18. plone.api
petek, 04. oktober 13

19. plone.api
• Started at Plone Konf Munich (2012)
• Alpha release at Belgian Beer Sprint
(2012)
• Beta release at Plone Conference in
Arnhem (2013)
• RC at Wine Sprint Munich (2013)
• 1.0 this week?
petek, 04. oktober 13

20. Inspiration
• PEP20
• PEP8
• Pareto Principle
• SQLAlchemy
• Requests
petek, 04. oktober 13

21. From where to
import that thing?
petek, 04. oktober 13

22. from plone import api
petek, 04. oktober 13

23. Many ways to get
the Site root: which
is correct?
petek, 04. oktober 13

24. api.portal.get()
petek, 04. oktober 13

25. Copy/move objects?
target.manage_pasteObjects(
source.manage_cutObjects(source_id)
)
petek, 04. oktober 13

26. portal = api.portal.get()
contact = portal['about']['contact']
api.content.move(
source=contact,
target=portal,
)
petek, 04. oktober 13

27. Workflow state?
workflow = getToolByName(
portal,
'portal_workflow'
)
workflow.getInfoFor(obj, 'review_state')
petek, 04. oktober 13

28. api.content.get_state(
obj=portal['about']
)
api.content.transition(
obj=portal['about'],
transition='publish',
)
petek, 04. oktober 13

29. It’s documented!
petek, 04. oktober 13

30. It’s documented
• Document first
• Narrative documentation
• Advanced usage documentation
• Good code comments
petek, 04. oktober 13

31. petek, 04. oktober 13

32. petek, 04. oktober 13

33. It’s documented
• Document first
• Narrative documentation
• Advanced usage documentation
• Good code comments
petek, 04. oktober 13

34. petek, 04. oktober 13

35. It’s tested!
petek, 04. oktober 13

36. It’s tested
• ~99% test coverage
• Narrative documentation included
• Continuous Integration
petek, 04. oktober 13

37. petek, 04. oktober 13

38. Import and Usage style
from plone import api
portal = api.portal.get()
user = api.user.create(username='bob')
api.content.move(
source=portal['blog'],
id='old-blog',
)
petek, 04. oktober 13

39. • get()
• get_navigation_root()
• get_tool()
• get_localized_time()
• send_email()
• show_message()
• get_registry_record()
api.portal
petek, 04. oktober 13

40. api.content
• create()
• get()
• delete()
• copy()
• move()
• rename()
• get_uuid()
• get_view()
• get_state()
• transition()
petek, 04. oktober 13

41. api.user
• create()
• get()
• get_users()
• get_current()
• delete()
• is_anonymous()
• get_roles()
• get_permissions()
• grant_roles()
• revoke_roles()
petek, 04. oktober 13

42. api.group
• create()
• get()
• get_groups()
• delete()
• add_user()
• remove_user()
• get_roles()
• get_permissions()
• grant_roles()
• revoke_roles()
petek, 04. oktober 13

43. api.env
• adopt_roles() • adopt_user()
petek, 04. oktober 13

44. In the wild
• tutorial.todoapp
• 150k objects / +1000 users production
site
• hands up?
petek, 04. oktober 13

45. Latest Additions
• Various bug fixes
• api.env.adopt_user() & api.env.adopt_roles()
• Coding style guide!
petek, 04. oktober 13

46. api.env.adopt_roles
petek, 04. oktober 13

47. api.env.adopt_user
petek, 04. oktober 13

48. The Style Guide
(included in Plone 5 core)
petek, 04. oktober 13

49. The Style Guide
• PEP 8
• PEP 257
• Rope project
• Google Style Guide
• Pylons Coding Style
• Tim Pope on Git commit messages
petek, 04. oktober 13

50. Line Length
• 80 chars
• # noqa if you need to break it
• configure your editor!
petek, 04. oktober 13

51. Breaking Lines
• 1. Break into next line with one
additional indent block
petek, 04. oktober 13

52. Breaking Lines
• 2. If this still doesn’t fit the 80-char
limit, break into multiple lines
petek, 04. oktober 13

53. Docstrings
petek, 04. oktober 13

54. unittest2
• http://www.voidspace.org.uk/python/articles/unittest2.shtml
• fail* -> use assert* instead
• assertEquals -> assertEqual is the one
true way
petek, 04. oktober 13

55. unittest2
• Deprecated:
failUnlessEqual, failIfEqual,
failUnlessAlmostEqual,
failIfAlmostEqual,
failUnless,failUnlessRaises and
failIf
petek, 04. oktober 13

56. unittest2
• assertGreater / assertLess /
assertGreaterEqual /
assertLessEqual
• assertRegexpMatches(text, regexp)
• assertIn(value, sequence)
• assertIs(first, second)
• assertIsNone
petek, 04. oktober 13

57. unittest2
• assertIsInstance /
assertNotIsInstance
• assertDictContainsSubset(subset,
full)
• assertSequenceEqual(actual,
expected)
• assertItemsEqual(actual, expected)
petek, 04. oktober 13

58. unittest2
petek, 04. oktober 13

59. unittest2
• assertMultiLineEqual
• assertSetEqual
• assertDictEqual
• assertListEqual
• assertTupleEqual
petek, 04. oktober 13

60. unittest2
petek, 04. oktober 13

61. String Formatting
• Prefer new-style format()
• Use numbering to support Python 2.6
petek, 04. oktober 13

62. Imports
petek, 04. oktober 13

63. Tracking Changes
petek, 04. oktober 13

64. Versioning Scheme
petek, 04. oktober 13

65. Commit Messages
petek, 04. oktober 13

66. Many More
• String quoting
• Git workflow & branching model
• Release process
petek, 04. oktober 13

67. Bonus Slide: plone.dotfiles
petek, 04. oktober 13

68. Coming up
petek, 04. oktober 13

69. api.env
• api.env.debug_mode()
• api.env.test_mode()
• api.env.plone_version()
• api.env.zope_version()
petek, 04. oktober 13

70. api.system
• Run upgrades
• Cleanup broken objects, utilities, interfaces ...
• Mount things
• Make sysadmins happy!
petek, 04. oktober 13

71. JSON WebServices
• Probably packaged as plone.jsonapi
• One-to-one mapping to plone.api methods
• @@jsonapi view
• Standardized JavaScript writing!
petek, 04. oktober 13

72. BONUS SLIDE!
petek, 04. oktober 13

73. Post-Conference sprint
• Implement remaining plone.api methods
• Get the test coverage even higher!
• Native speakers’ love to our docs
• Let’s get 1.0 release out there!
petek, 04. oktober 13

74. Open Tasks
• Deprecate plone.api on RTD
• Sphinx warnings should break the build
• plone.recipe.codeanalysis
• Coveralls.io
• Various bugs
• Proof-reading documentation
petek, 04. oktober 13

75. Open Tasks
• Changelog decision:
• CHANGES.rst or docs/CHANGES.rst
• “CHANGELOG” or “Changelog” or
“CHANGES” or “Changes” for heading
petek, 04. oktober 13

76. Open Tasks
• Permission checks decision:
• apply them?
• go around them?
• let the user decide with “strict=True”?
petek, 04. oktober 13

77. Open Tasks
• THE BIG ONE: usage scope
• use in core? performance issues ...
• use in add-ons? might creep into core
• only allow usage in integration code?
petek, 04. oktober 13

78. Thanks!
&
See you at the sprint
http://github.com/plone/plone.api
petek, 04. oktober 13