plone.api: plone development best practices revealed

plone.api
Plone 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

+2500
Electrical
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 3
Impossible 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 plone import api

api.portal.get()

portal = api.portal.get()
contact = portal['about']['contact']
api.content.move(
source=contact,
target=portal,
)

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

It’s documented!

It’s documented
• Document ﬁrst
• 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',
)

• 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 ﬁxes
• 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
• conﬁgure your editor!

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

Breaking Lines
• 2. If this still doesn’t ﬁt 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

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

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

Tracking Changes

Versioning Scheme

Commit Messages

Many More
• String quoting
• Git workﬂow & 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

plone.api: plone development best practices revealed

Recomendados

Recomendados

Más contenido relacionado

Último

Último (20)

Destacado

Destacado (20)

plone.api: plone development best practices revealed