0
plone.api
Plone development best practices revealed
@nzupan
petek, 04. oktober 13
Everybody stand up please!
petek, 04. oktober 13
petek, 04. oktober 13
self.context
petek, 04. oktober 13
• 2006
• Student
workshop
• Plone 2.5
• Life was good!
petek, 04. oktober 13
eestec.net
• Online since 2009
• Switched to Plone 3 during development
• +2500 users
• Several events per month
petek, 04...
+2500
Electrical
Engineering
Students
petek, 04. oktober 13
no. of new
contributors:
petek, 04. oktober 13
no. of new
contributors:
2
petek, 04. oktober 13
eestec.net
• Online since 2009
• ***Switched to Plone 3 during development***
• +2500 users
• Several events per month
pet...
Plone 3
Impossible to:
- train
- write docs for
- stay productive
- keep devs happy
petek, 04. oktober 13
Plone 4?
petek, 04. oktober 13
From where to
import that thing?
petek, 04. oktober 13
Many ways to get
the Site root: which
is correct?
petek, 04. oktober 13
Copy/move objects?
target.manage_pasteObjects(
source.manage_cutObjects(source_id)
)
petek, 04. oktober 13
Workflow state?
workflow = getToolByName(
portal,
'portal_workflow'
)
workflow.getInfoFor(obj, 'review_state')
petek, 04. ...
petek, 04. oktober 13
plone.api
petek, 04. oktober 13
plone.api
• Started at Plone Konf Munich (2012)
• Alpha release at Belgian Beer Sprint
(2012)
• Beta release at Plone Conf...
Inspiration
• PEP20
• PEP8
• Pareto Principle
• SQLAlchemy
• Requests
petek, 04. oktober 13
From where to
import that thing?
petek, 04. oktober 13
from plone import api
petek, 04. oktober 13
Many ways to get
the Site root: which
is correct?
petek, 04. oktober 13
api.portal.get()
petek, 04. oktober 13
Copy/move objects?
target.manage_pasteObjects(
source.manage_cutObjects(source_id)
)
petek, 04. oktober 13
portal = api.portal.get()
contact = portal['about']['contact']
api.content.move(
source=contact,
target=portal,
)
petek, 0...
Workflow state?
workflow = getToolByName(
portal,
'portal_workflow'
)
workflow.getInfoFor(obj, 'review_state')
petek, 04. ...
api.content.get_state(
obj=portal['about']
)
api.content.transition(
obj=portal['about'],
transition='publish',
)
petek, 0...
It’s documented!
petek, 04. oktober 13
It’s documented
• Document first
• Narrative documentation
• Advanced usage documentation
• Good code comments
petek, 04. o...
petek, 04. oktober 13
petek, 04. oktober 13
It’s documented
• Document first
• Narrative documentation
• Advanced usage documentation
• Good code comments
petek, 04. o...
petek, 04. oktober 13
It’s tested!
petek, 04. oktober 13
It’s tested
• ~99% test coverage
• Narrative documentation included
• Continuous Integration
petek, 04. oktober 13
petek, 04. oktober 13
Import and Usage style
from plone import api
portal = api.portal.get()
user = api.user.create(username='bob')
api.content....
• get()
• get_navigation_root()
• get_tool()
• get_localized_time()
• send_email()
• show_message()
• get_registry_record(...
api.content
• create()
• get()
• delete()
• copy()
• move()
• rename()
• get_uuid()
• get_view()
• get_state()
• transitio...
api.user
• create()
• get()
• get_users()
• get_current()
• delete()
• is_anonymous()
• get_roles()
• get_permissions()
• ...
api.group
• create()
• get()
• get_groups()
• delete()
• add_user()
• remove_user()
• get_roles()
• get_permissions()
• gr...
api.env
• adopt_roles() • adopt_user()
petek, 04. oktober 13
In the wild
• tutorial.todoapp
• 150k objects / +1000 users production
site
• hands up?
petek, 04. oktober 13
Latest Additions
• Various bug fixes
• api.env.adopt_user() & api.env.adopt_roles()
• Coding style guide!
petek, 04. oktobe...
api.env.adopt_roles
petek, 04. oktober 13
api.env.adopt_user
petek, 04. oktober 13
The Style Guide
(included in Plone 5 core)
petek, 04. oktober 13
The Style Guide
• PEP 8
• PEP 257
• Rope project
• Google Style Guide
• Pylons Coding Style
• Tim Pope on Git commit messa...
Line Length
• 80 chars
• # noqa if you need to break it
• configure your editor!
petek, 04. oktober 13
Breaking Lines
• 1. Break into next line with one
additional indent block
petek, 04. oktober 13
Breaking Lines
• 2. If this still doesn’t fit the 80-char
limit, break into multiple lines
petek, 04. oktober 13
Docstrings
petek, 04. oktober 13
unittest2
• http://www.voidspace.org.uk/python/articles/unittest2.shtml
• fail* -> use assert* instead
• assertEquals -> a...
unittest2
• Deprecated:
failUnlessEqual, failIfEqual,
failUnlessAlmostEqual,
failIfAlmostEqual,
failUnless,failUnlessRaise...
unittest2
• assertGreater / assertLess /
assertGreaterEqual /
assertLessEqual
• assertRegexpMatches(text, regexp)
• assert...
unittest2
• assertIsInstance /
assertNotIsInstance
• assertDictContainsSubset(subset,
full)
• assertSequenceEqual(actual,
...
unittest2
petek, 04. oktober 13
unittest2
• assertMultiLineEqual
• assertSetEqual
• assertDictEqual
• assertListEqual
• assertTupleEqual
petek, 04. oktobe...
unittest2
petek, 04. oktober 13
String Formatting
• Prefer new-style format()
• Use numbering to support Python 2.6
petek, 04. oktober 13
Imports
petek, 04. oktober 13
Tracking Changes
petek, 04. oktober 13
Versioning Scheme
petek, 04. oktober 13
Commit Messages
petek, 04. oktober 13
Many More
• String quoting
• Git workflow & branching model
• Release process
petek, 04. oktober 13
Bonus Slide: plone.dotfiles
petek, 04. oktober 13
Coming up
petek, 04. oktober 13
api.env
• api.env.debug_mode()
• api.env.test_mode()
• api.env.plone_version()
• api.env.zope_version()
petek, 04. oktober...
api.system
• Run upgrades
• Cleanup broken objects, utilities, interfaces ...
• Mount things
• Make sysadmins happy!
petek...
JSON WebServices
• Probably packaged as plone.jsonapi
• One-to-one mapping to plone.api methods
• @@jsonapi view
• Standar...
BONUS SLIDE!
petek, 04. oktober 13
Post-Conference sprint
• Implement remaining plone.api methods
• Get the test coverage even higher!
• Native speakers’ lov...
Open Tasks
• Deprecate plone.api on RTD
• Sphinx warnings should break the build
• plone.recipe.codeanalysis
• Coveralls.i...
Open Tasks
• Changelog decision:
• CHANGES.rst or docs/CHANGES.rst
• “CHANGELOG” or “Changelog” or
“CHANGES” or “Changes” ...
Open Tasks
• Permission checks decision:
• apply them?
• go around them?
• let the user decide with “strict=True”?
petek, ...
Open Tasks
• THE BIG ONE: usage scope
• use in core? performance issues ...
• use in add-ons? might creep into core
• only...
Thanks!
&
See you at the sprint
http://github.com/plone/plone.api
petek, 04. oktober 13
Upcoming SlideShare
Loading in...5
×

plone.api: plone development best practices revealed

735

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
735
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
14
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

Transcript of "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
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×