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