GitHub-only

WARNING: If you are reading this on GitHub, DON’T! Read the documentation at docs.plone.org so you have working references and proper formatting.

Environment

Switch roles inside a block

To temporarily override the list of available roles, use api.env.adopt_roles(). This is especially useful in unit tests.

from plone import api
from AccessControl import Unauthorized

portal = api.portal.get()
with api.env.adopt_roles(['Anonymous']):
    self.assertRaises(
       Unauthorized,
       lambda: portal.restrictedTraverse("manage_propertiesForm")
    )

with api.env.adopt_roles(['Manager', 'Member']):
    portal.restrictedTraverse("manage_propertiesForm")

Switch user inside a block

To temporarily override the currently active user, use api.env.adopt_user().

from plone import api

portal = api.portal.get()

# Create a new user.
api.user.create(
    username="doc_owner",
    roles=('Member', 'Manager',),
    email="new_owner@example.com",
)

# Become that user and create a document.
with api.env.adopt_user(username="doc_owner"):
    api.content.create(
        container=portal,
        type='Document',
        id='new_owned_doc',
    )

self.assertEqual(
    portal.new_owned_doc.getOwner().getId(),
    "doc_owner",
)

Debug mode

To know if your Zope instance is running in debug mode, use api.env.debug_mode().

from plone import api

in_debug_mode = api.env.debug_mode()
if in_debug_mode:
    print('Zope is in debug mode')

Test mode

To know if your Plone instance is running in a test runner, use api.env.test_mode().

from plone import api

in_test_mode = api.env.test_mode()
if in_test_mode:
    pass  # do something

Read-Only mode

To know if your Zope / Plone instance is running on a read-only ZODB connection use api.env.read_only_mode().

Use-Case: If you run a ZRS or RelStorage cluster with active replication where all replicas are read-only be default. You could check if your instance is connected to a read only ZODB or a writeable ZODB. Therefore you could adjust the UI to prevent create, delete or update pages are shown.

from plone import api

is_read_only = api.env.read_only_mode()
if is_read_only:
    pass  # do something

Plone version

To know which version of Plone you are using, use api.env.plone_version().

from plone import api

plone_version = api.env.plone_version()
if plone_version < '4.1':
    pass  # do something

Zope version

To know which version of Zope 2 you are using, use api.env.zope_version().

from plone import api

zope_version = api.env.zope_version()
if zope_version >= '2.13':
    pass  # do something

Further reading

For more information on possible flags and usage options please see the full plone.api.env specification.