Managers

find_by_uid(uid)[source]#

Catalog entry of the item with a UID.

Parameters:: uid (str) – The UID.
Returns:: The search result, with @id, @type and title.
Raises:: PloneNotFoundError – If no item has this UID.
Return type:: dict[str, Any]

resolve(ref)[source]#

Site path for a reference.

Plain paths and URLs are only normalized. uid:<UID> and resolveuid links are looked up in the catalog.

Parameters:: ref (str) – Path, URL, uid:<UID> or resolveuid link.
Returns:: The site path.
Raises:: PloneNotFoundError – If the UID is not found.
Return type:: str

exists(ref)[source]#

Say whether there is an item at a path.

Parameters:: ref (str) – Path or URL of the item.
Returns:: True if it exists.
Return type:: bool

children(ref='/', *, portal_type=None, metadata_fields=None, limit=None, b_size=100)[source]#

Items directly inside a folder, in the folder’s order.

Uses @search on the folder, so each item is a catalog entry rather than a full serialization.

Parameters:

ref (str) – Path or URL of the folder.
portal_type (str | Iterable[str] | None) – Only items of these types.
metadata_fields (str | Iterable[str] | None) – Extra catalog metadata to return (_all for every column).
limit (int | None) – Stop after this many items.
b_size (int) – Items fetched per request.

Returns:

Each item.

Return type:

create(parent, portal_type, data=None, **fields)[source]#

Create an item inside a folder.

Read the @id of the result rather than assuming it: Plone may change the id that was asked for.

Parameters:

parent (str) – Path or URL of the folder.
portal_type (str) – Content type, such as Document.
data (Mapping[str, Any] | None) – Field values; also id, and UID (needs the Manage portal permission).
fields (Any) – More field values, merged over data.

Returns:

The new item.

Raises:

PloneBadRequestError – If the id is in use, the type is not allowed in the folder, or a field is invalid.

Return type:

update(ref, data=None, *, lock_token=None, representation=True, **fields)[source]#

Change fields of an item (PATCH).

Parameters:

ref (str) – Path or URL of the item.
data (Mapping[str, Any] | None) – Field values.
lock_token (str | None) – Token of a lock held on the item.
representation (bool) – Ask the site to return the changed item.
fields (Any) – More field values, merged over data.

Returns:

The changed item, or None with representation=False.

Return type:

dict[str, Any] | None

delete(ref)[source]#

Delete an item.

Parameters:: ref (str) – Path or URL of the item.
Raises:: PloneBadRequestError – If link integrity forbids the deletion.
Return type:: None

copy(source, target)[source]#

Copy items into a folder.

Parameters:

source (str | Iterable[str]) – Path, URL or UID of an item, or several.
target (str) – Path or URL of the folder.

Returns:

One {"source", "target"} entry per item.

Return type:

move(source, target)[source]#

Move items into a folder.

Parameters:

source (str | Iterable[str]) – Path, URL or UID of an item, or several.
target (str) – Path or URL of the folder.

Returns:

One {"source", "target"} entry per item.

Return type:

order(folder, obj_id, delta, *, subset_ids=None)[source]#

Move an item within its folder.

Parameters:

folder (str) – Path or URL of the folder.
obj_id (str) – Id of the item to move.
delta (int | Literal['top', 'bottom']) – Positions to move (negative moves up), top or bottom.
subset_ids (Iterable[str] | None) – Ids of the items the client knows about, in their current order; the site refuses the change if they are out of date.

Return type:

None

sort(folder, on, order='ascending')[source]#

Sort the items of a folder by an index, once.

Parameters:

folder (str) – Path or URL of the folder.
on (str) – Catalog index to sort on, such as modified.
order (Literal['ascending', 'descending']) – ascending or descending.

Return type:

None

lock(ref, *, stealable=True, timeout=None)[source]#

Lock an item.

Parameters:

ref (str) – Path or URL of the item.
stealable (bool) – Let other users break the lock.
timeout (int | None) – Seconds the lock lasts.

Returns:

Lock information, with the token to send in updates.

Return type:

unlock(ref, *, force=False)[source]#

Remove the lock of an item.

Parameters:

ref (str) – Path or URL of the item.
force (bool) – Remove a lock held by another user.

Returns:

Lock information.

Return type:

refresh_lock(ref)[source]#

Extend the lock of an item.

Parameters:: ref (str) – Path or URL of the item.
Returns:: Lock information.
Return type:: dict[str, Any]

lock_info(ref)[source]#

Lock information of an item.

Parameters:: ref (str) – Path or URL of the item.
Returns:: locked, stealable and, when locked, the owner.
Return type:: dict[str, Any]

link_integrity(uids)[source]#

Items that link to the given items.

Check this before deleting content.

Parameters:: uids (str | Iterable[str]) – UID of an item, or several.
Returns:: One entry per item, with its breaches.
Return type:: list[dict[str, Any]]

Search: the @search catalog query and @querystring-search.

class plone_client.managers.search.SearchManager(client)[source]#

Bases: BaseManager

Catalog queries through @search.

Searching on a folder restricts the results to that folder, which works the same with and without virtual hosting. That is why path here is the folder to search in, not a path index query.

Parameters:: client (PloneClient)

search(path='/', *, query=None, portal_type=None, review_state=None, text=None, depth=None, sort_on=None, sort_order=None, metadata_fields=None, fullobjects=False, b_size=None, b_start=None, **indexes)[source]#

One page of results.

Parameters:

path (str) – Folder to search in; the site root by default.
query (Mapping[str, Any] | None) – Catalog query as a mapping, for index names that are not valid keyword arguments; nested options are flattened ({"created": {"query": "2026-01-01", "range": "min"}}).
portal_type (str | Iterable[str] | None) – Content types.
review_state (str | Iterable[str] | None) – Workflow states.
text (str | None) – Full-text search (SearchableText).
depth (int | None) – Levels below path: 0 is the folder itself, 1 its children.
sort_on (str | Iterable[str] | None) – Index to sort on; several sort on each in turn.
sort_order (str | None) – ascending or descending.
metadata_fields (str | Iterable[str] | None) – Extra catalog metadata in each result (_all for every column).
fullobjects (bool) – Return full serializations; much slower.
b_size (int | None) – Results per page (the site defaults to 25).
b_start (int | None) – Offset of the page.
indexes (Any) – Other catalog indexes, such as UID or Subject.

Returns:

items, items_total and batching.

Return type:

iter(path='/', *, query=None, portal_type=None, review_state=None, text=None, depth=None, sort_on=None, sort_order=None, metadata_fields=None, fullobjects=False, limit=None, b_size=100, **indexes)[source]#

Every result, fetching the pages as needed.

Takes the same arguments as search(), plus:

Parameters:

limit (int | None) – Stop after this many results.
b_size (int) – Results fetched per request.
path (str)
query (Mapping[str, Any] | None)
portal_type (str | Iterable[str] | None)
review_state (str | Iterable[str] | None)
text (str | None)
depth (int | None)
sort_on (str | Iterable[str] | None)
sort_order (str | None)
metadata_fields (str | Iterable[str] | None)
fullobjects (bool)
indexes (Any)

Returns:

Each result.

Return type:

count(path='/', *, query=None, portal_type=None, review_state=None, text=None, depth=None, **indexes)[source]#

Number of results of a search.

Returns:

items_total.

Parameters:

path (str)
query (Mapping[str, Any] | None)
portal_type (str | Iterable[str] | None)
review_state (str | Iterable[str] | None)
text (str | None)
depth (int | None)
indexes (Any)

Return type:

int

class plone_client.managers.search.QuerystringManager(client)[source]#

Bases: BaseManager

Collection-style queries through @querystring-search.

Parameters:: client (PloneClient)

config(path='/')[source]#

Indexes, operators and sort options the querystring accepts.

Parameters:: path (str) – Context of the query.
Returns:: indexes and sortable_indexes.
Return type:: dict[str, Any]

search(query, *, path='/', sort_on=None, sort_order=None, limit=None, b_size=None, b_start=None, metadata_fields=None, fullobjects=False)[source]#

Run a querystring query.

Parameters:

query (Iterable[Mapping[str, Any]]) – Criteria, each with i (index), o (operation) and v (value), as a Listing block stores them.
path (str) – Context of the query, for relative path criteria.
sort_on (str | None) – Index to sort on.
sort_order (str | None) – ascending or descending.
limit (int | None) – Maximum number of results.
b_size (int | None) – Results per page.
b_start (int | None) – Offset of the page.
metadata_fields (str | Iterable[str] | None) – Extra catalog metadata in each result.
fullobjects (bool) – Return full serializations.

Returns:

items, items_total and batching.

Return type:

Workflow, versions and working copies of items.

class plone_client.managers.workflow.WorkflowManager(client)[source]#

Bases: BaseManager

Workflow state and transitions (@workflow).

Parameters:: client (PloneClient)

get(ref)[source]#

Current state, history and available transitions of an item.

Parameters:: ref (str) – Path or URL of the item.
Returns:: state, history and transitions.
Return type:: dict[str, Any]

transition(ref, transition, *, comment=None, effective=None, expires=None, include_children=False)[source]#

Run a workflow transition.

Parameters:

ref (str) – Path or URL of the item.
transition (str) – Transition id, such as publish or retract.
comment (str | None) – Comment stored in the workflow history.
effective (str | None) – Publication date (ISO 8601).
expires (str | None) – Expiration date (ISO 8601).
include_children (bool) – Also run it on the items inside a folder.

Returns:

The new history entry, with review_state.

Raises:

PloneBadRequestError – If the transition is not available.

Return type:

class plone_client.managers.workflow.HistoryManager(client)[source]#

Bases: BaseManager

Versions and workflow history of an item (@history).

Parameters:: client (PloneClient)

list(ref)[source]#

History entries of an item, newest first.

Parameters:: ref (str) – Path or URL of the item.
Returns:: Versioning and workflow entries.
Return type:: list[dict[str, Any]]

get(ref, version)[source]#

An older version of an item.

Parameters:

ref (str) – Path or URL of the item.
version (int) – Version number, from list().

Returns:

The item as it was.

Return type:

revert(ref, version)[source]#

Revert an item to an older version.

Parameters:

ref (str) – Path or URL of the item.
version (int) – Version number, from list().

Returns:

A confirmation message.

Return type:

class plone_client.managers.workflow.WorkingCopyManager(client)[source]#

Bases: BaseManager

Working copies of published items (@workingcopy).

Needs plone.app.iterate installed on the site.

Parameters:: client (PloneClient)

get(ref)[source]#

Working copy of an item, or the baseline of a working copy.

Parameters:: ref (str) – Path or URL of the baseline or of the working copy.
Returns:: working_copy and working_copy_of.
Return type:: dict[str, Any]

create(ref)[source]#

Check out an item into a working copy.

Parameters:: ref (str) – Path or URL of the item.
Returns:: @id of the working copy.
Return type:: dict[str, Any]

check_in(ref)[source]#

Apply a working copy to its baseline and remove it.

Parameters:: ref (str) – Path or URL of the working copy or of the baseline.
Return type:: None

delete(ref)[source]#

Remove a working copy without applying it.

Parameters:: ref (str) – Path or URL of the working copy or of the baseline.
Return type:: None

Files and images: upload, replace and download.

plone_client.managers.files.TUS_CHUNK_SIZE = 4194304#: Chunk size for TUS uploads: 4 MiB.

plone_client.managers.files.file_data(source, *, filename=None, content_type=None)[source]#

Value of a file or image field, as plone.restapi reads it.

Parameters:

source (str | Path | bytes) – Path of the file, or its bytes.
filename (str | None) – File name; required when source is bytes.
content_type (str | None) – Content type; guessed from the file name if missing.

Returns:

data (base64), encoding, filename and content-type.

Return type:

dict[str, str]

class plone_client.managers.files.FilesManager(client)[source]#

Bases: BaseManager

Files and images stored in content items.

Parameters:: client (PloneClient)

upload(parent, source, *, portal_type=None, field=None, filename=None, content_type=None, **fields)[source]#

Create a File or Image from a file, in one request.

The file travels base64 encoded inside the JSON body, which is simple and works on every site; for large files use tus_upload().

Parameters:

parent (str) – Path or URL of the folder.
source (str | Path | bytes) – Path of the file, or its bytes.
portal_type (str | None) – Content type; Image for images and File for anything else by default.
field (str | None) – Field that holds the file; image for Image and file otherwise by default.
filename (str | None) – File name; required when source is bytes.
content_type (str | None) – Content type; guessed from the file name if missing.
fields (Any) – Other field values, such as id or title.

Returns:

The new item.

Return type:

replace(ref, source, *, field='file', filename=None, content_type=None)[source]#

Replace the file stored in a field of an item.

Parameters:

ref (str) – Path or URL of the item.
source (str | Path | bytes) – Path of the file, or its bytes.
field (str) – Field that holds the file (image for images).
filename (str | None) – File name; required when source is bytes.
content_type (str | None) – Content type; guessed from the file name if missing.

Return type:

None

download(ref, *, field='file')[source]#

Contents of a file field (@@download).

Parameters:

ref (str) – Path or URL of the item.
field (str) – Field that holds the file (image for images).

Returns:

The file contents.

Return type:

bytes

image_scale(ref, *, field='image', scale='preview')[source]#

Contents of an image scale (@@images).

Parameters:

ref (str) – Path or URL of the item.
field (str) – Field that holds the image.
scale (str) – Scale name, such as thumb, preview or large.

Returns:

The scaled image.

Return type:

bytes

tus_upload(parent, source, *, portal_type=None, field=None, filename=None, content_type=None, chunk_size=4194304)[source]#

Create an item from a large file, sent in chunks (@tus-upload).

Parameters:

parent (str) – Path or URL of the folder.
source (str | Path | bytes) – Path of the file, or its bytes.
portal_type (str | None) – Content type; Image for images and File for anything else by default.
field (str | None) – Field that holds the file; image for Image and file otherwise by default.
filename (str | None) – File name; required when source is bytes.
content_type (str | None) – Content type; guessed from the file name if missing.
chunk_size (int) – Bytes sent per request.

Returns:

URL of the new item.

Return type:

str

tus_replace(ref, source, *, field=None, filename=None, content_type=None, chunk_size=4194304)[source]#

Replace the file of an item with a large file (@tus-replace).

Parameters:

ref (str) – Path or URL of the item.
source (str | Path | bytes) – Path of the file, or its bytes.
field (str | None) – Field that holds the file.
filename (str | None) – File name; required when source is bytes.
content_type (str | None) – Content type; guessed from the file name if missing.
chunk_size (int) – Bytes sent per request.

Returns:

URL of the item.

Return type:

str

class plone_client.managers.navigation.NavigationManager(client)[source]#

Bases: BaseManager

Contextual information about an item.

Parameters:: client (PloneClient)

navigation(ref='/', *, depth=None)[source]#

Top navigation (@navigation).

Parameters:

ref (str) – Path or URL of the context.
depth (int | None) – Levels of the navigation tree to include.

Returns:

items of the navigation.

Return type:

breadcrumbs(ref)[source]#

Breadcrumbs of an item (@breadcrumbs).

Parameters:: ref (str) – Path or URL of the item.
Returns:: items from the navigation root to the item.
Return type:: dict[str, Any]

contextnavigation(ref, **params)[source]#

Navigation portlet of an item (@contextnavigation).

Parameters:

ref (str) – Path or URL of the item.
params (Any) – Portlet options, such as expand.contextnavigation.bottomLevel.

Returns:

The navigation tree.

Return type:

navroot(ref='/')[source]#

Navigation root of an item (@navroot).

On a multilingual site, this is the language root folder.

Parameters:: ref (str) – Path or URL of the item.
Returns:: navroot, the serialized root.
Return type:: dict[str, Any]

actions(ref='/', *, categories=None)[source]#

CMF actions available on an item (@actions).

Parameters:

ref (str) – Path or URL of the item.
categories (Iterable[str] | None) – Only these categories (object, user…).

Returns:

Actions by category.

Return type:

inherit(ref, behaviors)[source]#

Field values an item inherits from its parents (@inherit).

Parameters:

ref (str) – Path or URL of the item.
behaviors (str | Iterable[str]) – Behaviors to look up, such as plone.navigationroot.

Returns:

For each behavior, the closest item that has it and its data.

Return type:

Comments, translations, aliases and relations.

class plone_client.managers.discussion.CommentsManager(client)[source]#

Bases: BaseManager

Comments on an item (@comments).

Comments must be enabled on the site and on the content type.

Parameters:: client (PloneClient)

list(ref, *, limit=None)[source]#

Comments of an item.

Parameters:

ref (str) – Path or URL of the item.
limit (int | None) – Stop after this many comments.

Returns:

Each comment.

Return type:

create(ref, text, *, reply_to=None)[source]#

Add a comment, or a reply to a comment.

Parameters:

ref (str) – Path or URL of the item.
text (str) – Text of the comment.
reply_to (str | None) – Id of the comment to reply to.

Return type:

None

update(ref, comment_id, text)[source]#

Change the text of a comment.

Parameters:

ref (str) – Path or URL of the item.
comment_id (str) – Id of the comment.
text (str) – New text.

Return type:

None

delete(ref, comment_id)[source]#

Delete a comment.

Parameters:

ref (str) – Path or URL of the item.
comment_id (str) – Id of the comment.

Return type:

None

class plone_client.managers.discussion.TranslationsManager(client)[source]#

Bases: BaseManager

Translations of an item (@translations).

Needs plone.app.multilingual installed on the site.

Parameters:: client (PloneClient)

get(ref)[source]#

Translations linked to an item.

Parameters:: ref (str) – Path or URL of the item.
Returns:: items with the @id and language of each translation.
Return type:: dict[str, Any]

link(ref, translation)[source]#

Link an existing item as a translation.

Parameters:

ref (str) – Path or URL of the item.
translation (str) – Path, URL or UID of the translation.

Returns:

The linked translation.

Return type:

unlink(ref, language)[source]#

Remove the link to the translation in a language.

Parameters:

ref (str) – Path or URL of the item.
language (str) – Language code of the translation.

Return type:

None

locate(ref, language)[source]#

Where a translation into a language should be created.

Parameters:

ref (str) – Path or URL of the item.
language (str) – Language code of the new translation.

Returns:

@id of the folder for the translation.

Return type:

class plone_client.managers.discussion.AliasesManager(client)[source]#

Bases: BaseManager

URL aliases and redirections (@aliases).

Parameters:: client (PloneClient)

list(ref='/', **params)[source]#

Aliases of an item, or every redirection of the site.

Parameters:

ref (str) – Path or URL of the item; the site root lists them all.
params (Any) – Filters accepted on the site root, such as query, manual, start, end, b_size.

Returns:

items and items_total.

Return type:

create(ref, aliases)[source]#

Add aliases to an item.

Parameters:

ref (str) – Path or URL of the item.
aliases (str | Iterable[str]) – Old path, or several, that should redirect to the item.

Return type:

None

create_redirects(redirects)[source]#

Add redirections on the site root.

Parameters:: redirects (Iterable[Mapping[str, Any]]) – Entries with path (the old path), redirect-to (the target) and, optionally, datetime.
Return type:: None

delete(ref, aliases)[source]#

Remove aliases.

Parameters:

ref (str) – Path or URL of the item, or the site root.
aliases (str | Iterable[str]) – Alias path, or several.

Return type:

None

class plone_client.managers.discussion.RelationsManager(client)[source]#

Bases: BaseManager

Relations between items (@relations).

Parameters:: client (PloneClient)

stats()[source]#

Number of relations of each kind.

Returns:: stats and broken counts.
Return type:: dict[str, Any]

list(*, source=None, target=None, relation=None, query_source=None, query_target=None, only_broken=False, limit=None)[source]#

Relations matching a filter.

Parameters:

source (str | None) – Path or UID of the source item.
target (str | None) – Path or UID of the target item.
relation (str | None) – Relation name, such as relatedItems.
query_source (str | None) – Text the source title must match.
query_target (str | None) – Text the target title must match.
only_broken (bool) – Only relations whose target is gone.
limit (int | None) – Maximum number of relations returned.

Returns:

relations by name, with items and items_total.

Return type:

create(relations)[source]#

Create relations.

Parameters:: relations (Iterable[Mapping[str, str]]) – Entries with source, target (paths or UIDs) and relation.
Return type:: None

delete(relations=None, *, source=None, target=None, relation=None)[source]#

Delete relations, listed one by one or by filter.

Parameters:

relations (Iterable[Mapping[str, str]] | None) – Entries with source, target and relation.
source (str | None) – Delete every relation from this item.
target (str | None) – Delete every relation to this item.
relation (str | None) – Delete every relation with this name.

Return type:

None

rebuild(*, flush=False)[source]#

Rebuild the relation catalog.

Parameters:: flush (bool) – Empty the catalog first, which also refreshes intids.
Return type:: None

Users, groups, roles and sharing.

class plone_client.managers.users.UsersManager(client)[source]#

Bases: BaseManager

Site users (@users).

Parameters:: client (PloneClient)

list(*, query=None, search=None, groups=None, limit=None)[source]#

Users of the site.

Parameters:

query (str | None) – Text the user id must contain.
search (str | None) – Text to look for in the id, full name and email.
groups (Iterable[str] | None) – Only members of these groups.
limit (int | None) – Maximum number of users (the site defaults to 25).

Returns:

The users.

Return type:

get(user_id)[source]#

A user.

Parameters:: user_id (str) – Id of the user.
Returns:: The user, with roles and groups.
Return type:: dict[str, Any]

create(username, data=None, **fields)[source]#

Create a user.

Parameters:

username (str) – Login name.
data (Mapping[str, Any] | None) – Other fields: email, fullname, password, roles, groups, sendPasswordReset…
fields (Any) – More fields, merged over data.

Returns:

The new user.

Return type:

update(user_id, data=None, **fields)[source]#

Change a user.

Parameters:

user_id (str) – Id of the user.
data (Mapping[str, Any] | None) – Fields to change; roles maps role names to True/False.
fields (Any) – More fields, merged over data.

Return type:

None

delete(user_id, *, delete_memberareas=True, delete_localroles=True)[source]#

Delete a user.

Parameters:

user_id (str) – Id of the user.
delete_memberareas (bool) – Also delete the user’s member folder.
delete_localroles (bool) – Also remove the user’s local roles.

Return type:

None

reset_password(user_id)[source]#

Send the user an email to reset the password.

Parameters:: user_id (str) – Id of the user.
Return type:: None

update_password(user_id, new_password, *, old_password=None)[source]#

Set a new password.

Managers set any user’s password without the old one; users change their own by giving it.

Parameters:

user_id (str) – Id of the user.
new_password (str) – The new password.
old_password (str | None) – The current password.

Return type:

None

schema(*, registration=False)[source]#

JSON schema of the user fields (@userschema).

Parameters:: registration (bool) – Schema of the registration form instead.
Returns:: The schema.
Return type:: dict[str, Any]

portrait(user_id=None)[source]#

Portrait image of a user (@portrait).

Parameters:: user_id (str | None) – Id of the user; the current user when missing.
Returns:: The image.
Return type:: bytes

class plone_client.managers.users.GroupsManager(client)[source]#

Bases: BaseManager

Site groups (@groups).

Parameters:: client (PloneClient)

list(*, query=None, limit=None)[source]#

Groups of the site.

Parameters:

query (str | None) – Text the group id must contain.
limit (int | None) – Maximum number of groups.

Returns:

The groups.

Return type:

get(group_id)[source]#

A group, with its members.

Parameters:: group_id (str) – Id of the group.
Returns:: The group.
Return type:: dict[str, Any]

create(groupname, data=None, **fields)[source]#

Create a group.

Parameters:

groupname (str) – Id of the group.
data (Mapping[str, Any] | None) – Other fields: title, description, email, roles, groups, users.
fields (Any) – More fields, merged over data.

Returns:

The new group.

Return type:

update(group_id, data=None, **fields)[source]#

Change a group.

Parameters:

group_id (str) – Id of the group.
data (Mapping[str, Any] | None) – Fields to change; users maps user ids to True (add) or False (remove).
fields (Any) – More fields, merged over data.

Return type:

None

delete(group_id)[source]#

Delete a group.

Parameters:: group_id (str) – Id of the group.
Return type:: None

add_members(group_id, user_ids)[source]#

Add users to a group.

Parameters:

group_id (str) – Id of the group.
user_ids (str | Iterable[str]) – Id of a user, or several.

Return type:

None

remove_members(group_id, user_ids)[source]#

Remove users from a group.

Parameters:

group_id (str) – Id of the group.
user_ids (str | Iterable[str]) – Id of a user, or several.

Return type:

None

class plone_client.managers.users.SharingManager(client)[source]#

Bases: BaseManager

Local roles (@sharing), principals and roles.

Parameters:: client (PloneClient)

get(ref, *, search=None, include_titles=False)[source]#

Local roles of an item.

Parameters:

ref (str) – Path or URL of the item.
search (str | None) – Also list users and groups matching this text.
include_titles (bool) – Add role titles to the answer.

Returns:

entries, inherit and available_roles.

Return type:

update(ref, entries, *, inherit=None)[source]#

Change local roles of an item.

Parameters:

ref (str) – Path or URL of the item.
entries (Iterable[Mapping[str, Any]]) – Entries with id, type (user or group) and roles, a mapping of role names to True/False.
inherit (bool | None) – Inherit local roles from the parent.

Return type:

None

principals(search)[source]#

Users and groups matching a text (@principals).

Parameters:: search (str) – Text to look for.
Returns:: users and groups.
Return type:: dict[str, Any]

roles()[source]#

Roles defined on the site (@roles).

Returns:: The roles, with id and title.
Return type:: list[dict[str, Any]]

Content types, their schemas, and vocabularies.

plone_client.managers.types.TypeIds#

A list of type ids; list itself is shadowed by the managers’ method.

alias of list[str]

class plone_client.managers.types.TypesManager(client)[source]#

Bases: BaseManager

Content types and their JSON schemas (@types).

Parameters:: client (PloneClient)

list(ref='/')[source]#

Content types, with whether they can be added in a folder.

Parameters:: ref (str) – Path or URL of the folder.
Returns:: @id, title, addable and immediately_addable of each type.
Return type:: list[dict[str, Any]]

addable(ref='/')[source]#

Ids of the content types that can be added in a folder.

Parameters:: ref (str) – Path or URL of the folder.
Returns:: Type ids, such as Document.
Return type:: list[str]

get(portal_type, *, ref='/')[source]#

JSON schema of a content type.

Parameters:

portal_type (str) – Type id, such as Document.
ref (str) – Context, which affects some vocabularies in the schema.

Returns:

properties, required, fieldsets…

Return type:

get_field(portal_type, name)[source]#

Schema of one field or fieldset of a content type.

Parameters:

portal_type (str) – Type id.
name (str) – Field or fieldset name.

Returns:

Its schema.

Return type:

create_field(portal_type, data)[source]#

Add a field (or, with fieldset data, a fieldset) to a type.

Only for types whose schema is stored in the site, not in code.

Parameters:

portal_type (str) – Type id.
data (Mapping[str, Any]) – factory, title, description, required…

Returns:

The new field.

Return type:

update(portal_type, data, *, name=None)[source]#

Change a type’s schema, or one of its fields or fieldsets.

Parameters:

portal_type (str) – Type id.
data (Mapping[str, Any]) – Changes to apply.
name (str | None) – Field or fieldset name; the whole schema when missing.

Return type:

None

replace(portal_type, schema)[source]#

Replace a type’s schema.

Parameters:

portal_type (str) – Type id.
schema (Mapping[str, Any]) – The full schema.

Return type:

None

delete_field(portal_type, name)[source]#

Remove a field or fieldset from a type.

Parameters:

portal_type (str) – Type id.
name (str) – Field or fieldset name.

Return type:

None

class plone_client.managers.types.VocabulariesManager(client)[source]#

Bases: BaseManager

Vocabularies and field sources.

Parameters:: client (PloneClient)

list(ref='/')[source]#

Named vocabularies registered on the site.

Parameters:: ref (str) – Context of the vocabularies.
Returns:: @id and title of each one.
Return type:: list[dict[str, Any]]

get(name, *, ref='/', title=None, token=None, sort_on=None, sort_order=None, b_size=None, b_start=None)[source]#

Terms of a vocabulary, a page at a time.

Parameters:

name (str) – Vocabulary name, such as plone.app.vocabularies.Keywords.
ref (str) – Context of the vocabulary.
title (str | None) – Only terms whose title contains this text.
token (str | Iterable[str] | None) – Only the term with this token, or with these tokens.
sort_on (str | None) – token or title.
sort_order (str | None) – ascending or descending.
b_size (int | None) – Terms per page; -1 returns them all.
b_start (int | None) – Offset of the page.

Returns:

items (token and title) and items_total.

Return type:

iter(name, *, ref='/', title=None)[source]#

Every term of a vocabulary.

Parameters:

name (str) – Vocabulary name.
ref (str) – Context of the vocabulary.
title (str | None) – Only terms whose title contains this text.

Returns:

Each term.

Return type:

source(ref, field)[source]#

Terms of the source of a field (@sources).

Parameters:

ref (str) – Path or URL of an item with the field.
field (str) – Field name.

Returns:

items and items_total.

Return type:

querysource(ref, field, query)[source]#

Terms of a query source matching a text (@querysources).

Parameters:

ref (str) – Path or URL of an item with the field.
field (str) – Field name.
query (str) – Text to search for.

Returns:

items and items_total.

Return type:

Block types: the blocks a Volto site offers, with their docs and schemas.

The list of blocks only exists in the frontend, so it comes from the @blocks-schema service of the Volto server, not from plone.restapi. Sites whose Volto does not have that service yet, clients that talk to the backend directly, and anonymous clients get the documentation of Volto’s core blocks that ships with plone-client instead, marked with "source": "builtin" and a warning that says why.

plone_client.managers.block_types.CORE_BLOCKS: dict[str, tuple[str, bool | str]] = {'description': ('Description', False), 'detachedSlate': ('Detached Slate', True), 'gridBlock': ('Grid', False), 'html': ('HTML', False), 'image': ('Image', False), 'listing': ('Listing', False), 'maps': ('Maps', False), 'search': ('Search', False), 'slate': ('Text', False), 'teaser': ('Teaser', False), 'title': ('Title', 'context'), 'toc': ('Table of Contents', False), 'video': ('Video', False)}#: Title and restricted of Volto’s core blocks, from its configuration. "context" means the block chooser decides per content item.

plone_client.managers.block_types.PLACEHOLDERS: dict[str, dict[str, str]] = {'gridBlock': {'allowedBlocks': '`image`, `listing`, `slate` and `teaser`', 'maxLength': '4'}}#: Values of the placeholders in the core docs, from Volto’s configuration.

exception plone_client.managers.block_types.BlocksSchemaUnavailable(reason)[source]#

Bases: Exception

The site has no @blocks-schema service that the client can use.

Parameters:: reason (str) – Why, for the warning of the builtin answer.
Return type:: None

plone_client.managers.block_types.core_docs(block_id)[source]#

Documentation of a core block, as shipped with plone-client.

Parameters:: block_id (str) – Block id, such as slate.
Returns:: The Markdown, without its frontmatter and with its placeholders filled in.
Raises:: KeyError – If the block is not a core block.
Return type:: str

plone_client.managers.block_types.summary(docs)[source]#

First paragraph of a block’s documentation.

Parameters:: docs (str) – The Markdown.
Returns:: The paragraph, on one line.
Return type:: str

plone_client.managers.block_types.builtin_list(reason)[source]#

The core blocks, in the shape of GET @blocks-schema.

Parameters:: reason (str) – Why the site’s own list is not used.
Returns:: items, items_total, source and warning.
Return type:: dict[str, Any]

plone_client.managers.block_types.builtin_block(block_id, reason)[source]#

One core block, in the shape of GET @blocks-schema/<id>.

Parameters:

block_id (str) – Block id.
reason (str) – Why the site’s own description is not used.

Returns:

id, title, docs (no schema: only the site knows it), source and warning.

Raises:

KeyError – If the block is not a core block.

Return type:

plone_client.managers.block_types.builtin_markdown(data)[source]#

Markdown for a builtin answer, like the service’s text/markdown.

Parameters:: data (dict[str, Any]) – A builtin list or block.
Returns:: The Markdown.
Return type:: str

class plone_client.managers.block_types.BlockTypesManager(client)[source]#

Bases: BaseManager

The blocks a Volto site offers (@blocks-schema of the Volto server).

Requests go to the client’s frontend_url with a Bearer token, which the client gets from @login when it uses basic authentication.

Parameters:: client (PloneClient)

list(ref=None)[source]#

The blocks of the site, with their title and summary.

Parameters:: ref (str | None) – A content item; only the blocks that editors can add to it are listed (their restricted is evaluated for it).
Returns:: items (id, title, description, maybe restricted), items_total and source: site, or builtin with a warning when the site cannot tell.
Return type:: dict[str, Any]

get(block_id, ref=None)[source]#

One block: its documentation, data schema and variations.

Parameters:

block_id (str) – Block id, such as teaser.
ref (str | None) – A content item; restricted is evaluated for it.

Returns:

id, title, docs, schema, variations and source; builtin answers have no schema.

Raises:

PloneNotFoundError – If there is no such block.

Return type:

markdown(block_id=None, ref=None)[source]#

The list of blocks, or one block, as Markdown.

Easier for a language model to read than the JSON schema.

Parameters:

block_id (str | None) – Block id; without it, the list.
ref (str | None) – A content item, as in list().

Returns:

The Markdown.

Raises:

PloneNotFoundError – If there is no such block.

Return type:

str

Site configuration and maintenance.

class plone_client.managers.site.RegistryManager(client)[source]#

Bases: BaseManager

Configuration registry (@registry).

Parameters:: client (PloneClient)

get(key)[source]#

Value of a registry record.

Parameters:: key (str) – Record name, such as plone.site_title.
Returns:: The value.
Return type:: Any

list(query=None)[source]#

Registry records.

Parameters:: query (str | None) – Only records whose name contains this text.
Returns:: Each record, with name, value and schema.
Return type:: Iterator[dict[str, Any]]

update(values)[source]#

Change registry records.

Parameters:: values (Mapping[str, Any]) – New values by record name.
Return type:: None

set(key, value)[source]#

Change one registry record.

Parameters:

key (str) – Record name.
value (Any) – New value.

Return type:

None

class plone_client.managers.site.ControlpanelsManager(client)[source]#

Bases: BaseManager

Control panels (@controlpanels).

Parameters:: client (PloneClient)

list()[source]#

Control panels of the site.

Returns:: @id, title and group of each panel.
Return type:: list[dict[str, Any]]

get(panel, item=None)[source]#

A control panel, or an item inside it.

Parameters:

panel (str) – Panel id, such as editing or dexterity-types.
item (str | None) – Item id, such as a content type in dexterity-types.

Returns:

Its schema and data.

Return type:

update(panel, data, *, item=None)[source]#

Change settings of a control panel, or of an item inside it.

Parameters:

panel (str) – Panel id.
data (Mapping[str, Any]) – New values.
item (str | None) – Item id.

Return type:

None

create(panel, data)[source]#

Add an item to a control panel, such as a content type.

Parameters:

panel (str) – Panel id, such as dexterity-types.
data (Mapping[str, Any]) – Data of the new item.

Returns:

The new item.

Return type:

delete(panel, item)[source]#

Remove an item from a control panel.

Parameters:

panel (str) – Panel id.
item (str) – Item id.

Return type:

None

class plone_client.managers.site.AddonsManager(client)[source]#

Bases: BaseManager

Add-ons (@addons).

Parameters:: client (PloneClient)

list()[source]#

Add-ons available on the site.

Returns:: items, each with is_installed and upgrade_info.
Return type:: dict[str, Any]

get(addon)[source]#

One add-on.

Parameters:: addon (str) – Add-on id, such as plone.app.multilingual.
Returns:: The add-on.
Return type:: dict[str, Any]

install(addon)[source]#

Install an add-on.

Parameters:: addon (str) – Add-on id.
Returns:: The add-ons, after the change.
Return type:: dict[str, Any]

uninstall(addon)[source]#

Uninstall an add-on.

Parameters:: addon (str) – Add-on id.
Returns:: The add-ons, after the change.
Return type:: dict[str, Any]

upgrade(addon)[source]#

Run the pending upgrade steps of an add-on.

Parameters:: addon (str) – Add-on id.
Returns:: The add-ons, after the change.
Return type:: dict[str, Any]

install_profile(addon, profile)[source]#

Import a GenericSetup profile of an add-on.

Parameters:

addon (str) – Add-on id.
profile (str) – Profile name, such as default.

Returns:

The add-ons, after the change.

Return type: