Skip to main content
Help us improve Python packaging – donate today!

A Plone API.

Project Description



The plone.api is an elegant and simple API, built for humans wishing to develop with Plone.

It comes with cookbook-like documentation and 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 intention of this package is to provide clear API methods for Plone functionality which may be confusing or difficult to access. As the underlying code improves some API methods may be deprecated and the documentation here will be updated to show how to use the improved code (even if it means not using plone.api)

Some parts of the documentation do not use plone.api methods directly, but simply provide guidance on achieving a task using Plone’s internal API. For example, using the portal catalog (see ‘Find content objects’).

The intention is to cover 20% of the tasks any Plone developer does 80% of the time. By keeping everything in one place, the API stays introspectable and discoverable, important aspects of being Pythonic.


This package is stable and used in production, but from time to time changes will be made to the API. Additional api methods may be introduced in minor versions (1.1 -> 1.2). Backward-incompatible changes to the API will be restricted to major versions (1.x -> 2.x).


1.2.1 (2014-06-24)

  • Resolve issues with CHANGES.rst symlink that prevented 1.2.0 from being installed in some circumstances. [mattss]

1.2.0 (2014-06-24)

  • Enhance api.content.transition with the ability to transition from the current state to a given state without knowing the transition ‘path’ refs. #162 [adamcheasley]
  • Add api.env.plone_version() and api.env.zope_version() refs. #126. [hvelarde]
  • Stop UnicodeDecodeErrors being swallowed in api.content.create [mattss]
  • Catch AttributeError in api.content.get (raised if only part of the traversal path exists) [mattss]

1.1.0 (2013-10-12)

  • List supported Plone versions in [zupo]
  • Plone 4.0 and 4.1 are now tested under Python 2.6 on CI. [hvelarde]
  • Use Plone 4.3 on development by default (was 4.2). [hvelarde]

1.1.0-rc.1 (2013-10-10)

  • Fix README.rst so it renders correctly on PyPI. [zupo]
  • Use redirects. [zupo]
  • Add file. [hvelarde]

1.0.0-rc.3 (2013-10-09)

  • Packaging issues. [zupo]

1.0.0-rc.2 (2013-10-09)

  • Proof-read the docs, improved grammar and wording. [cewing]

  • Add plone.recipe.codeanalysis to our buildout. [flohcim]

  • Make all assertRaise() calls use the with keyword. [winstonf88]

  • Amend user.get method to accept a userid parameter, refs #112. [cewing, xiru, winstonf88]


    This change fixes a bug in the earlier implementation that could cause errors in some situations. This situation will only arise if the userid and username for a user are not the same. If membrane is being used for content- based user objects, or if email-as-login is enabled and a user has changed their email address this will be the case. In the previous implementation the username parameter was implicitly being treated as userid. The new implementation does not do so. If consumer code is relying on this bug and passing userid, and if that code uses the username parameter as a keyword parameter, then lookup will fail. In all other cases, there should be no difference.

  • Add api.env.debug_mode() and api.env.test_mode(), refs #125. [sdelcourt]

  • Move most of text from docs/index.rst to README.rst so its also visible on PyPI and GitHub. [zupo]

  • Deprecate plone.api on ReadTheDocs and redirect to, refs #130. [wormj, zupo]

  • Add a new make coverage command and add support for posting coverage to [zupo]

  • Make api.content.create() also print out the underlying error, refs #118. [winston88]

  • Fix api.content copy/move/rename functions to return the object after they change content, refs #115. [rodfersou]

  • Make Travis IRC notification message to be one-line instead of three-lines. [zupo]

  • More examples of good and bad code blocks in documentation, more information on how to write good docstrings. [zupo]

  • Prefer single quotes over double quotes in code style. [zupo]

  • New to stay in the land of zc.buildout 1.x. [zupo]

  • Package now includes a copy of the GPLv2 license as stated in the GNU General Public License documentation. [hvelarde]

  • Fixed copying folderish objects. [pingviini]

  • Fixed moving folderish objects. [pingviini]

1.0.0-rc.1 (2013-01-27)

  • Increase test coverage. [cillianderoiste, JessN, reinhardt, zupo]
  • Implementation of api.env.adopt_roles() context manager for temporarily switching roles inside a block. [RichyB]
  • Created api.env module for interacting with global environment. [RichyB]
  • Decorators for defining constraints on api methods. Depend on decorator package. [JessN]
  • Resolved #61: Improve api.portal.get(). [cillianderoiste]
  • Use plone.api methods in plone.api codebase. [zupo]
  • Switch to flake8 instead of pep8`+`pyflakes. [zupo]
  • Get the portal path with absolute_url_path. [cillianderoiste]
  • Travis build speed-ups. [zupo]
  • Support for Python 2.6. [RichyB, zupo]
  • Support for Plone 4.0. [adamcheasley]
  • Support for Plone 4.3. [cillianderoiste, zupo]
  • Spelling fixes. [adamtheturtle]
  • Make get_view and get_tool tests not have hardcoded list of all expected values. [RichyB, cillianderoiste]
  • Code Style Guide. [iElectric, cillianderoiste, marciomazza, RichyB, thet, zupo]
  • Depend on manuel in [zupo]
  • Documentation how to get/set member properties. [zupo]
  • Improvements to get_registry_record. [zupo]

0.1b1 (2012-10-23)

  • Contributors guide and style guide. [zupo]
  • Enforce PEP257 for docstrings. [zupo]
  • Fix get_navigation_root() to return object instead of path. [pbauer]
  • Implementation of get_permissions(), get_roles(), grant_roles() and revoke roles() for users and groups. [rudaporto, xiru]
  • Implementation of get_registry_record and set_registry_record. [pbauer]
  • Use Makefile to build the project, run tests, generate documentation, etc. [witsch]
  • Moving all ReadTheDocs dependencies into rtd_requirements.txt. [zupo]

0.1a2 (2012-09-03)

  • Updated release, adding new features, test coverage, cleanup & refactor. [hvelarde, avelino, ericof, jpgimenez, xiru, macagua, zupo]

0.1a1 (2012-07-13)

  • Initial release. [davisagli, fulv, iElectric, jcerjak, jonstahl, kcleong, mauritsvanrees, wamdam, witsch, zupo]


Copyright (C) 2012-2013 Plone Foundation

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Release history Release notifications

History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date (196.3 kB) Copy SHA256 hash SHA256 Source None Jun 24, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page