Preview changes and protect a site#

This guide shows you how to see what a script or command would change before it changes anything, and how to make a client unable to change a site at all.

The examples run against the Compose site; see Run a Plone site for testing. Point the command line and your scripts at it.

export PLONE_CLIENT_URL=http://localhost:8080/Plone
export PLONE_CLIENT_USERNAME=admin
export PLONE_CLIENT_PASSWORD=admin

Choose between a dry run and read-only#

Dry run

Read-only

In Python

dry_run=True

read_only=True

On the command line

-n, anywhere on the line

--read-only, before the command

In a profile

Not available.

--read-only when you add it.

Reads

Sent.

Sent.

Changes

Skipped, and printed.

Refused.

What a command reports

The request it would send, with exit code 0.

An error, with exit code 7.

What a script gets

The record of the request, in place of the answer.

PloneReadOnlyError

Use it to

See what would happen.

Make sure that nothing can happen.

With both, read-only wins: -n on a read-only profile is refused with exit code 7, so a read-only site cannot preview a change.

A dry run shows the request, not the site’s answer to it, so a request that looks fine can still fail in the real run. For new and changed items, the dry run checks what it can, says so in warning, and still exits with code 0:

  • a new item of a type that the folder cannot add;

  • blocks that are not a mapping of block IDs, a block without @type, or a blocks_layout that does not list them;

  • fields of a new item that its type does not have, which the site would ignore.

Added in version 1.0.0a4: The warning of a dry run on a type that the folder refuses.

Added in version 1.0.0a5: The warning of a dry run on blocks, and on fields the type does not have.

The same change, with each switch:

plone-client -n update /news/release-party --title "Party in Brasília"
{
  "dry_run": true,
  "method": "PATCH",
  "url": "http://localhost:8080/Plone/++api++/news/release-party",
  "json": {
    "title": "Party in Brasília"
  }
}
plone-client --read-only update /news/release-party --title "Party in Brasília"
{
  "error": {
    "type": "PloneReadOnlyError",
    "message": "PATCH /news/release-party refused: the client is read-only"
  }
}

Preview the changes of a script#

Create the client with dry_run=True. Reads still go to the site, so the script behaves as usual, but each changing request is recorded in client.dry_run_log instead of being sent.

from plone_client import PloneClient

client = PloneClient.from_env(dry_run=True)
client.content.update("/news/release-party", title="Party in Brasília")

for request in client.dry_run_log:
    print(request["method"], request["url"], request.get("json"))
python preview.py
PATCH http://localhost:8080/Plone/++api++/news/release-party {'title': 'Party in Brasília'}

Each skipped call returns the record of the request instead of the site’s answer. A create therefore returns no @id; stop before any step that needs one.

A common pattern is to plan by default and change the site only when asked.

client = PloneClient.from_env(dry_run=not args.apply)

Preview the changes of a command#

Pass -n anywhere on the command line. The command prints the requests it would send, and sends none of them.

plone-client -n delete /news/release-party
plone-client update /news/release-party --description "Join us" -n
{
  "deleted": [
    "/news/release-party"
  ],
  "dry_run": true
}
{
  "dry_run": true,
  "method": "PATCH",
  "url": "http://localhost:8080/Plone/++api++/news/release-party",
  "json": {
    "description": "Join us"
  }
}

With -n, destructive commands do not ask for confirmation.

Refuse every change#

Create the client with read_only=True. Any request that could change the site raises PloneReadOnlyError before it is sent.

from plone_client import PloneClient
from plone_client.exceptions import PloneReadOnlyError

client = PloneClient.from_env(read_only=True)
try:
    client.content.delete("/news/release-party")
except PloneReadOnlyError as error:
    print(error)
python refuse.py
DELETE /news/release-party refused: the client is read-only

On the command line, pass --read-only before the command, or create the profile with --read-only so it always refuses changes.

plone-client --read-only -p production ls /news
plone-client profile add production --url https://example.org --username editor --read-only

Searches through @querystring-search and logins still work, because those services answer a POST without changing anything.