plone.api: plone development best practices revealed

1,147 views

Published on

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.

Published in: Technology
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,147
On SlideShare
0
From Embeds
0
Number of Embeds
15
Actions
Shares
0
Downloads
16
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

plone.api: plone development best practices revealed

  1. 1. plone.api Plone development best practices revealed @nzupan petek, 04. oktober 13
  2. 2. Everybody stand up please! petek, 04. oktober 13
  3. 3. petek, 04. oktober 13
  4. 4. self.context petek, 04. oktober 13
  5. 5. • 2006 • Student workshop • Plone 2.5 • Life was good! petek, 04. oktober 13
  6. 6. eestec.net • Online since 2009 • Switched to Plone 3 during development • +2500 users • Several events per month petek, 04. oktober 13
  7. 7. +2500 Electrical Engineering Students petek, 04. oktober 13
  8. 8. no. of new contributors: petek, 04. oktober 13
  9. 9. no. of new contributors: 2 petek, 04. oktober 13
  10. 10. eestec.net • Online since 2009 • ***Switched to Plone 3 during development*** • +2500 users • Several events per month petek, 04. oktober 13
  11. 11. Plone 3 Impossible to: - train - write docs for - stay productive - keep devs happy petek, 04. oktober 13
  12. 12. Plone 4? petek, 04. oktober 13
  13. 13. From where to import that thing? petek, 04. oktober 13
  14. 14. Many ways to get the Site root: which is correct? petek, 04. oktober 13
  15. 15. Copy/move objects? target.manage_pasteObjects( source.manage_cutObjects(source_id) ) petek, 04. oktober 13
  16. 16. Workflow state? workflow = getToolByName( portal, 'portal_workflow' ) workflow.getInfoFor(obj, 'review_state') petek, 04. oktober 13
  17. 17. petek, 04. oktober 13
  18. 18. plone.api petek, 04. oktober 13
  19. 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. 20. Inspiration • PEP20 • PEP8 • Pareto Principle • SQLAlchemy • Requests petek, 04. oktober 13
  21. 21. From where to import that thing? petek, 04. oktober 13
  22. 22. from plone import api petek, 04. oktober 13
  23. 23. Many ways to get the Site root: which is correct? petek, 04. oktober 13
  24. 24. api.portal.get() petek, 04. oktober 13
  25. 25. Copy/move objects? target.manage_pasteObjects( source.manage_cutObjects(source_id) ) petek, 04. oktober 13
  26. 26. portal = api.portal.get() contact = portal['about']['contact'] api.content.move( source=contact, target=portal, ) petek, 04. oktober 13
  27. 27. Workflow state? workflow = getToolByName( portal, 'portal_workflow' ) workflow.getInfoFor(obj, 'review_state') petek, 04. oktober 13
  28. 28. api.content.get_state( obj=portal['about'] ) api.content.transition( obj=portal['about'], transition='publish', ) petek, 04. oktober 13
  29. 29. It’s documented! petek, 04. oktober 13
  30. 30. It’s documented • Document first • Narrative documentation • Advanced usage documentation • Good code comments petek, 04. oktober 13
  31. 31. petek, 04. oktober 13
  32. 32. petek, 04. oktober 13
  33. 33. It’s documented • Document first • Narrative documentation • Advanced usage documentation • Good code comments petek, 04. oktober 13
  34. 34. petek, 04. oktober 13
  35. 35. It’s tested! petek, 04. oktober 13
  36. 36. It’s tested • ~99% test coverage • Narrative documentation included • Continuous Integration petek, 04. oktober 13
  37. 37. petek, 04. oktober 13
  38. 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. 39. • get() • get_navigation_root() • get_tool() • get_localized_time() • send_email() • show_message() • get_registry_record() api.portal petek, 04. oktober 13
  40. 40. api.content • create() • get() • delete() • copy() • move() • rename() • get_uuid() • get_view() • get_state() • transition() petek, 04. oktober 13
  41. 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. 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. 43. api.env • adopt_roles() • adopt_user() petek, 04. oktober 13
  44. 44. In the wild • tutorial.todoapp • 150k objects / +1000 users production site • hands up? petek, 04. oktober 13
  45. 45. Latest Additions • Various bug fixes • api.env.adopt_user() & api.env.adopt_roles() • Coding style guide! petek, 04. oktober 13
  46. 46. api.env.adopt_roles petek, 04. oktober 13
  47. 47. api.env.adopt_user petek, 04. oktober 13
  48. 48. The Style Guide (included in Plone 5 core) petek, 04. oktober 13
  49. 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. 50. Line Length • 80 chars • # noqa if you need to break it • configure your editor! petek, 04. oktober 13
  51. 51. Breaking Lines • 1. Break into next line with one additional indent block petek, 04. oktober 13
  52. 52. Breaking Lines • 2. If this still doesn’t fit the 80-char limit, break into multiple lines petek, 04. oktober 13
  53. 53. Docstrings petek, 04. oktober 13
  54. 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. 55. unittest2 • Deprecated: failUnlessEqual, failIfEqual, failUnlessAlmostEqual, failIfAlmostEqual, failUnless,failUnlessRaises and failIf petek, 04. oktober 13
  56. 56. unittest2 • assertGreater / assertLess / assertGreaterEqual / assertLessEqual • assertRegexpMatches(text, regexp) • assertIn(value, sequence) • assertIs(first, second) • assertIsNone petek, 04. oktober 13
  57. 57. unittest2 • assertIsInstance / assertNotIsInstance • assertDictContainsSubset(subset, full) • assertSequenceEqual(actual, expected) • assertItemsEqual(actual, expected) petek, 04. oktober 13
  58. 58. unittest2 petek, 04. oktober 13
  59. 59. unittest2 • assertMultiLineEqual • assertSetEqual • assertDictEqual • assertListEqual • assertTupleEqual petek, 04. oktober 13
  60. 60. unittest2 petek, 04. oktober 13
  61. 61. String Formatting • Prefer new-style format() • Use numbering to support Python 2.6 petek, 04. oktober 13
  62. 62. Imports petek, 04. oktober 13
  63. 63. Tracking Changes petek, 04. oktober 13
  64. 64. Versioning Scheme petek, 04. oktober 13
  65. 65. Commit Messages petek, 04. oktober 13
  66. 66. Many More • String quoting • Git workflow & branching model • Release process petek, 04. oktober 13
  67. 67. Bonus Slide: plone.dotfiles petek, 04. oktober 13
  68. 68. Coming up petek, 04. oktober 13
  69. 69. api.env • api.env.debug_mode() • api.env.test_mode() • api.env.plone_version() • api.env.zope_version() petek, 04. oktober 13
  70. 70. api.system • Run upgrades • Cleanup broken objects, utilities, interfaces ... • Mount things • Make sysadmins happy! petek, 04. oktober 13
  71. 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. 72. BONUS SLIDE! petek, 04. oktober 13
  73. 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. 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. 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. 76. Open Tasks • Permission checks decision: • apply them? • go around them? • let the user decide with “strict=True”? petek, 04. oktober 13
  77. 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. 78. Thanks! & See you at the sprint http://github.com/plone/plone.api petek, 04. oktober 13

×