Your first script

Your first script#

In this tutorial, we will write a Python script that connects to a Plone site, creates a page, publishes it, and finds it again with a search. Along the way, you will meet the client, its managers, and the way plone-client answers with plain JSON.

You need uv and Docker.

Start a Plone site#

We will work against a throwaway Plone site running in Docker. Start it in its own terminal and leave it running.

docker run --rm -p 8080:8080 -e SITE=Plone -e TYPE=volto plone/plone-backend:6.1

Wait until the output shows Serving on http://0.0.0.0:8080. The site is now at http://localhost:8080/Plone, with the user admin and the password admin.

Create a project#

In another terminal, create a project and add plone-client to it.

uv init --bare first-script
cd first-script
uv add plone-client

Connect to the site#

Create a file named script.py with this content.

from plone_client import PloneClient

client = PloneClient("http://localhost:8080/Plone", username="admin", password="admin")
site = client.content.get("/")
print("Connected to", site["title"])

Run it.

uv run python script.py

You should see the title of the site.

Connected to Plone Site

client.content is a manager, one of many attributes of the client. Each manager groups the plone.restapi services for one subject, and each method returns the site’s JSON answer as Python dictionaries and lists.

Create a page#

Add these lines to the end of script.py.

from plone_client import blocks

page = client.content.create(
    "/",
    "Document",
    id="hello",
    title="Hello, Plone",
    description="My first page created with plone-client",
    **blocks.build(blocks.title(), blocks.description(), blocks.text("It works.")),
)
print("Created", page["@id"], "in state", page["review_state"])

Run the script again.

uv run python script.py

Connected to Plone Site
Created http://localhost:8080/Plone/hello in state private

Open http://localhost:8080/Plone/++api++/hello in your browser, logged in as admin, to see the page as the site stores it. Notice the blocks field: plone_client.blocks built the title, description, and text blocks a Volto page needs.

Publish it#

New pages are private. Add these lines to publish it.

client.workflow.transition(page["@id"], "publish")
print("Published", client.content.get(page["@id"])["review_state"])

The page already exists, so running the whole script again would fail when it tries to create it. Delete the page if it is there, then create it again.

if client.content.exists("/hello"):
    client.content.delete("/hello")

Put those lines just before the call to client.content.create, and run the script.

uv run python script.py

Connected to Plone Site
Created http://localhost:8080/Plone/hello in state private
Published published

Find it again#

Add a search at the end of the script.

for item in client.search.iter(portal_type="Document", review_state="published"):
    print("Found", item["title"])

Run the script once more.

uv run python script.py

Connected to Plone Site
Created http://localhost:8080/Plone/hello in state private
Published published
Found Hello, Plone

search.iter goes through every page of results for you, however many there are.

The complete script#

from plone_client import PloneClient
from plone_client import blocks

client = PloneClient("http://localhost:8080/Plone", username="admin", password="admin")
site = client.content.get("/")
print("Connected to", site["title"])

if client.content.exists("/hello"):
    client.content.delete("/hello")
page = client.content.create(
    "/",
    "Document",
    id="hello",
    title="Hello, Plone",
    description="My first page created with plone-client",
    **blocks.build(blocks.title(), blocks.description(), blocks.text("It works.")),
)
print("Created", page["@id"], "in state", page["review_state"])

client.workflow.transition(page["@id"], "publish")
print("Published", client.content.get(page["@id"])["review_state"])

for item in client.search.iter(portal_type="Document", review_state="published"):
    print("Found", item["title"])

You have connected to a site, created a page with blocks, published it, and found it with a search. Stop the Plone site with Control-C in its terminal when you are done; nothing it stored is kept.

Next steps#

Contents