plone.api: plone development best practices revealed

plone.apiPlone development best practices revealed

@nzupan

petek, 04. oktober 13

Everybody stand up please!


self.context


• 2006

• Student workshop

• Plone 2.5

• Life was good!


eestec.net

• Online since 2009

• Switched to Plone 3 during development

• +2500 users

• Several events per month


+2500Electrical

Engineering Students


no. of new contributors:


no. of new contributors:

2


eestec.net

• Online since 2009

• ***Switched to Plone 3 during development***

• +2500 users

• Several events per month


Plone 3Impossible to: - train - write docs for - stay productive - keep devs happy


Plone 4?


From where to import that thing?


Many ways to get the Site root: which

is correct?


Copy/move objects?

target.manage_pasteObjects( source.manage_cutObjects(source_id))


Workflow state?workflow = getToolByName(portal,'portal_workflow'

)workflow.getInfoFor(obj, 'review_state')


plone.api


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?


Inspiration

• PEP20• PEP8• Pareto Principle• SQLAlchemy• Requests


From where to import that thing?


from plone import api


Many ways to get the Site root: which

is correct?


api.portal.get()


Copy/move objects?

target.manage_pasteObjects( source.manage_cutObjects(source_id))


portal = api.portal.get()contact = portal['about']['contact']

api.content.move( source=contact, target=portal,)


Workflow state?workflow = getToolByName(portal,'portal_workflow'

)workflow.getInfoFor(obj, 'review_state')


api.content.get_state(obj=portal['about']

)

api.content.transition(obj=portal['about'], transition='publish',

)


It’s documented!


It’s documented

• Document first• Narrative documentation• Advanced usage documentation• Good code comments


It’s tested!


It’s tested

• ~99% test coverage• Narrative documentation included• Continuous Integration


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

• get()• get_navigation_root()• get_tool()• get_localized_time()• send_email()• show_message()• get_registry_record()

api.portal


api.content

• create()• get()• delete()• copy()• move()• rename()

• get_uuid()• get_view()• get_state()• transition()


api.user

• create()• get()• get_users()• get_current()• delete()

• is_anonymous()• get_roles()• get_permissions()• grant_roles()• revoke_roles()


api.group

• create()• get()• get_groups()• delete()

• add_user()• remove_user()• get_roles()• get_permissions()• grant_roles()• revoke_roles()


api.env

• adopt_roles() • adopt_user()


In the wild

• tutorial.todoapp• 150k objects / +1000 users production

site• hands up?


Latest Additions

• Various bug fixes• api.env.adopt_user() & api.env.adopt_roles()• Coding style guide!


api.env.adopt_roles


api.env.adopt_user


The Style Guide(included in Plone 5 core)


The Style Guide

• PEP 8• PEP 257• Rope project• Google Style Guide• Pylons Coding Style• Tim Pope on Git commit messages


Line Length

• 80 chars• # noqa if you need to break it• configure your editor!


Breaking Lines

• 1. Break into next line with one additional indent block


Breaking Lines

• 2. If this still doesn’t fit the 80-char limit, break into multiple lines


Docstrings


unittest2

• http://www.voidspace.org.uk/python/articles/unittest2.shtml

• fail* -> use assert* instead

• assertEquals -> assertEqual is the one true way


http://www.voidspace.org.uk/python/articles/unittest2.shtml

http://www.voidspace.org.uk/python/articles/unittest2.shtml

unittest2

• Deprecated:

failUnlessEqual, failIfEqual, failUnlessAlmostEqual, failIfAlmostEqual, failUnless,failUnlessRaises and failIf


unittest2

• assertGreater / assertLess / assertGreaterEqual / assertLessEqual

• assertRegexpMatches(text, regexp)

• assertIn(value, sequence)

• assertIs(first, second)

• assertIsNone


unittest2

• assertIsInstance / assertNotIsInstance

• assertDictContainsSubset(subset, full)

• assertSequenceEqual(actual, expected)

• assertItemsEqual(actual, expected)


unittest2


unittest2

• assertMultiLineEqual

• assertSetEqual

• assertDictEqual

• assertListEqual

• assertTupleEqual


unittest2


String Formatting

• Prefer new-style format()• Use numbering to support Python 2.6


Imports


Tracking Changes


Versioning Scheme


Commit Messages


Many More

• String quoting• Git workflow & branching model• Release process


Bonus Slide: plone.dotfiles


Coming up


api.env

• api.env.debug_mode()

• api.env.test_mode()

• api.env.plone_version()

• api.env.zope_version()


api.system

• Run upgrades

• Cleanup broken objects, utilities, interfaces ...

• Mount things

• Make sysadmins happy!


JSON WebServices

• Probably packaged as plone.jsonapi

• One-to-one mapping to plone.api methods

• @@jsonapi view

• Standardized JavaScript writing!


BONUS SLIDE!


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!


Open Tasks

• Deprecate plone.api on RTD

• Sphinx warnings should break the build

• plone.recipe.codeanalysis

• Coveralls.io

• Various bugs

• Proof-reading documentation


Open Tasks

• Changelog decision:

• CHANGES.rst or docs/CHANGES.rst

• “CHANGELOG” or “Changelog” or “CHANGES” or “Changes” for heading


Open Tasks

• Permission checks decision:

• apply them?

• go around them?

• let the user decide with “strict=True”?


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?


Thanks!&

See you at the sprint

http://github.com/plone/plone.api


https://github.com/plone/plone.api/wiki

https://github.com/plone/plone.api/wiki

plone.api: plone development best practices revealed

Technology