"""High-level operations: tasks that take several requests, in the right order.
Each operation gets a task right on any Plone 6 site, Volto sites included,
where doing it request by request means knowing the content model: a News
Item has no ``image`` field there, and its lead image is a relation to an
Image stored inside it.
Every operation returns an :class:`OperationResult` that lists what it
created or changed and every request it sent. With a ``dry_run`` client,
nothing is sent: the result shows the planned requests, with the paths the
new items would most likely get. A read-only client refuses the first
change. When a request fails part way, the operation raises
:class:`~plone_client.exceptions.PloneOperationError`, whose ``result`` lists
what was already done, so the caller can clean up or resume.
Example::
from plone_client import PloneClient
from plone_client import operations
with PloneClient.from_profile("blog") as site:
result = operations.create_with_files(
site,
"/news",
"News Item",
["lead.jpg", "photo-2.jpg"],
title="Our new office",
publish="publish",
)
print(result.item["@id"])
"""
from . import blocks
from .exceptions import PloneAPIError
from .exceptions import PloneClientError
from .exceptions import PloneOperationError
from .managers.files import file_data
from collections.abc import Callable
from collections.abc import Iterable
from collections.abc import Iterator
from collections.abc import Mapping
from contextlib import contextmanager
from dataclasses import dataclass
from dataclasses import field
from pathlib import Path
from typing import Any
from typing import Literal
from typing import TYPE_CHECKING
import copy
import mimetypes
import re
import unicodedata
if TYPE_CHECKING:
from .client import PloneClient
#: Keys kept from an item in a result.
ITEM_KEYS = ("@id", "@type", "UID", "id", "title", "review_state")
#: Extensions of the files that :func:`upload_tree` can turn into pages.
PAGE_FORMATS: dict[str, blocks.SourceFormat] = {
".md": "markdown",
".markdown": "markdown",
".html": "html",
".htm": "html",
}
#: Files that hold the content of their folder's page in :func:`upload_tree`.
INDEX_NAMES = ("index.md", "README.md", "index.html")
LeadImage = int | Literal["first"] | None
[docs]
@dataclass
class OperationResult:
"""What an operation did.
:param operation: Name of the operation.
:param dry_run: Whether the requests that change the site were skipped.
:param item: The main item, for operations that create one.
:param created: Items created, in order; ``source`` names the local file
or folder they came from, and ``planned`` marks a path guessed in a
dry run.
:param changed: Items changed, with what changed.
:param requests: Every request sent or skipped: ``method``, ``url``,
``status`` and, when skipped, ``dry_run``.
:param error: Type and message of the error that stopped the operation.
"""
operation: str
dry_run: bool
item: dict[str, Any] | None = None
created: list[dict[str, Any]] = field(default_factory=list)
changed: list[dict[str, Any]] = field(default_factory=list)
requests: list[dict[str, Any]] = field(default_factory=list)
error: dict[str, Any] | None = None
[docs]
def to_dict(self) -> dict[str, Any]:
"""The result as JSON-ready data.
:returns: Every field; ``item`` and ``error`` only when set.
"""
data: dict[str, Any] = {"operation": self.operation, "dry_run": self.dry_run}
if self.item is not None:
data["item"] = self.item
data.update(created=self.created, changed=self.changed, requests=self.requests)
if self.error is not None:
data["error"] = self.error
return data
@contextmanager
def _operation(client: "PloneClient", name: str) -> Iterator[OperationResult]:
"""Run an operation: record its requests and report a failure part way.
:param client: The client.
:param name: Name of the operation.
:returns: The result, filled in by the operation.
:raises PloneOperationError: If a request fails.
"""
result = OperationResult(operation=name, dry_run=client.dry_run)
with client.recording() as requests:
result.requests = requests
try:
yield result
except PloneClientError as error:
result.error = {"type": error.__class__.__name__, "message": str(error)}
if isinstance(error, PloneAPIError):
result.error = error.to_dict()
raise PloneOperationError(f"{name} stopped: {error}", result) from error
def _summary(item: Mapping[str, Any], **extra: Any) -> dict[str, Any]:
"""Short form of an item for a result.
:param item: A serialized item.
:param extra: Keys to add.
:returns: The keys in :data:`ITEM_KEYS`, and ``extra``.
"""
return {**{key: item[key] for key in ITEM_KEYS if key in item}, **extra}
[docs]
def slug(text: str) -> str:
"""A likely id for a title, close to what Plone generates.
Only used to name items in a dry run, before Plone picks the real id.
:param text: The title or file name.
:returns: Lower case ASCII words joined by ``-``; dots of file names kept.
"""
text = unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode()
text = re.sub(r"[^\w.]+", "-", text.lower()).strip("-.")
return text or "item"
def _created(
client: "PloneClient",
answer: Mapping[str, Any],
parent: str,
data: Mapping[str, Any],
**extra: Any,
) -> dict[str, Any]:
"""Entry for a new item; a planned one in a dry run.
:param client: The client.
:param answer: What the site answered, or the dry run log entry.
:param parent: Site path of the folder.
:param data: Field values sent, for the planned id.
:param extra: Keys to add, such as ``source``.
:returns: The entry; its ``@id`` is the item's URL.
"""
if not client.dry_run:
return _summary(answer, **extra)
item_id = data.get("id") or slug(str(data.get("title") or "item"))
url = client.site_url(f"{parent.rstrip('/')}/{item_id}")
entry = {
"@id": url,
"@type": data.get("@type"),
"id": item_id,
"title": data.get("title"),
"planned": True,
**extra,
}
if "warning" in answer:
entry["warning"] = answer["warning"]
return entry
def _check_files(paths: Iterable[str | Path]) -> list[Path]:
"""Local files, checked before anything is sent.
:param paths: Paths of the files.
:returns: The paths.
:raises ValueError: If a path is not a file.
"""
files = [Path(path).expanduser() for path in paths]
missing = [str(path) for path in files if not path.is_file()]
if missing:
raise ValueError(f"Not a file: {', '.join(missing)}")
return files
def _is_image(path: Path) -> bool:
"""Say whether a file is an image, from its name.
:param path: The file.
:returns: ``True`` for ``image/*`` content types.
"""
return (mimetypes.guess_type(path.name)[0] or "").startswith("image/")
def _pick_lead(files: list[Path], lead_image: LeadImage) -> Path | None:
"""The file to use as lead image.
:param files: The files.
:param lead_image: Index in ``files``, ``"first"`` for the first image,
or ``None``.
:returns: The file, or ``None``.
:raises ValueError: If the index is out of range or not an image.
"""
if lead_image is None:
return None
if lead_image == "first":
return next((path for path in files if _is_image(path)), None)
try:
lead = files[lead_image]
except IndexError:
raise ValueError(f"lead_image {lead_image} is not one of the files") from None
if not _is_image(lead):
raise ValueError(f"{lead.name} is not an image")
return lead
def _default_blocks(
schema: Mapping[str, Any], data: Mapping[str, Any]
) -> dict[str, Any]:
"""Title and description blocks, for types with blocks.
:param schema: ``properties`` of the type's schema.
:param data: Field values given.
:returns: ``blocks`` and ``blocks_layout``, or nothing when the type has
no blocks or blocks are given.
"""
if "blocks" not in schema or "blocks" in data:
return {}
return blocks.build(blocks.title(), blocks.description())
def _lead_target(
portal_type: str,
schema: Mapping[str, Any],
lead: Path | None,
lead_image: LeadImage,
) -> tuple[Path | None, bool]:
"""Where the lead image goes, given the type's schema.
:param portal_type: Content type, for the error message.
:param schema: ``properties`` of the type's schema.
:param lead: The lead image file, or ``None``.
:param lead_image: The ``lead_image`` the caller asked for.
:returns: The lead image file (``None`` when there is none), and whether
it goes in the ``image`` field rather than an Image inside the item.
:raises ValueError: If the type has no lead image and ``lead_image`` named
an image explicitly.
"""
if lead is None:
return None, False
if "image" in schema:
return lead, True
if "preview_image_link" in schema:
return lead, False
if lead_image != "first":
raise ValueError(f"{portal_type} has no lead image field")
return None, False
def _attach_files(
client: "PloneClient",
result: OperationResult,
item: Mapping[str, Any],
item_path: str,
paths: list[Path],
lead: Path | None,
in_field: bool,
) -> None:
"""Upload files as items inside a new item, and set its lead image.
:param client: The client.
:param result: The result to fill in.
:param item: The new item, as recorded in the result.
:param item_path: Site path of the new item.
:param paths: Files to upload, in order.
:param lead: The lead image file, or ``None``.
:param in_field: Whether the lead image is already in the ``image`` field,
so it is not uploaded again.
"""
lead_entry: dict[str, Any] | None = None
for path in paths:
if in_field and path == lead:
continue
uploaded = client.files.upload(item_path, path)
entry = _created(
client,
uploaded,
item_path,
{
"@type": "Image" if _is_image(path) else "File",
"title": path.name,
},
source=str(path),
)
result.created.append(entry)
if path == lead:
lead_entry = entry
if lead_entry is not None:
target = lead_entry.get("UID") or lead_entry["@id"]
client.content.update(
item_path, preview_image_link=target, representation=False
)
result.changed.append({
"@id": item["@id"],
"fields": {"preview_image_link": lead_entry["@id"]},
})
[docs]
def create_with_files(
client: "PloneClient",
parent: str,
portal_type: str,
files: Iterable[str | Path],
*,
data: Mapping[str, Any] | None = None,
lead_image: LeadImage = "first",
publish: str | None = None,
**fields: Any,
) -> OperationResult:
"""Create an item, upload files and images inside it, and set its lead image.
The lead image goes where the type keeps it: in the ``image`` field when
the type has one (the file is then not uploaded again), or otherwise as
an Image inside the item that ``preview_image_link`` points to, which
is how News Items work on Volto sites. Files are uploaded as ``Image``
or ``File`` items, in order. Types with blocks get title and
description blocks unless blocks are given. ``blocks`` may be a list of
blocks, in order, as :func:`~plone_client.blocks.prepare` takes it.
The item must be folderish to hold the files: on Volto sites, Documents
and News Items are.
:param client: The client.
:param parent: Path or URL of the folder.
:param portal_type: Content type, such as ``News Item``.
:param files: Paths of the files to upload inside the item.
:param data: Field values of the item.
:param lead_image: Index of the lead image in ``files``, ``"first"``
for the first image (skipped when the type has no lead image), or
``None`` for no lead image.
:param publish: Workflow transition to run at the end, such as
``publish``.
:param fields: More field values, merged over ``data``.
:returns: The result; ``item`` is the new item.
:raises ValueError: If a file is missing, the lead image is not an
image or cannot be stored by the type, or a block has no ``@type``.
Nothing is changed then.
:raises PloneOperationError: If a request fails.
"""
paths = _check_files(files)
lead = _pick_lead(paths, lead_image)
values = blocks.prepare({**(data or {}), **fields})
with _operation(client, "create_with_files") as result:
parent_path = client.content.resolve(parent)
schema = client.types.get(portal_type).get("properties", {})
body = dict(values)
body.update(_default_blocks(schema, body))
lead, in_field = _lead_target(portal_type, schema, lead, lead_image)
if in_field and lead is not None:
body["image"] = file_data(lead)
answer = client.content.create(parent_path, portal_type, body)
item = _created(client, answer, parent_path, {"@type": portal_type, **body})
result.item = item
result.created.append(item)
item_path = client.path(item["@id"])
_attach_files(client, result, item, item_path, paths, lead, in_field)
if publish:
client.workflow.transition(item_path, publish)
result.changed.append({"@id": item["@id"], "transition": publish})
if not client.dry_run:
result.item = _summary(client.content.get(item_path, include_items=False))
return result
H1_MARKDOWN_RE = re.compile(r"\A\s*#[ \t]+(?P<title>[^\n]+?)[ \t#]*(?:\n|\Z)")
H1_HTML_RE = re.compile(r"\A\s*<h1[^>]*>(?P<title>.*?)</h1>", re.IGNORECASE | re.DOTALL)
TAG_RE = re.compile(r"<[^>]+>")
[docs]
def split_title(source: str, source_format: blocks.SourceFormat) -> tuple[str, str]:
"""Take a leading level 1 heading out of Markdown or HTML.
:param source: The Markdown or HTML.
:param source_format: ``markdown`` or ``html``.
:returns: The heading text (empty when there is none) and the rest.
"""
pattern = H1_MARKDOWN_RE if source_format == "markdown" else H1_HTML_RE
match = pattern.match(source)
if not match:
return "", source
title = " ".join(TAG_RE.sub("", match["title"]).split())
return title, source[match.end() :].lstrip("\n")
[docs]
def page_data(
source: str,
source_format: blocks.SourceFormat = "markdown",
*,
title: str | None = None,
description: str | None = None,
default_title: str = "",
blocks_setting: blocks.BlocksSetting | None = None,
) -> dict[str, Any]:
"""Field values of a page made from Markdown or HTML.
The page gets a title block, a description block and the converted
content. Without a title, the leading level 1 heading is the title, and
is not repeated in the content.
:param source: The Markdown or HTML.
:param source_format: ``markdown`` or ``html``.
:param title: Title of the page.
:param description: Description of the page.
:param default_title: Title when there is neither ``title`` nor a
leading heading, such as the name of the file.
:param blocks_setting: Which block types the content becomes; see
:func:`~plone_client.blocks.convert`.
:returns: ``title``, maybe ``description``, ``blocks`` and
``blocks_layout``.
:raises ValueError: If there is no title, or ``blocks_setting`` is
invalid.
:raises PloneConfigurationError: If ``collective.html2blocks`` is missing.
"""
if not title:
title, source = split_title(source, source_format)
title = title or default_title
if not title:
raise ValueError("A title is needed: pass one, or start with a # heading")
data: dict[str, Any] = {"title": title}
if description:
data["description"] = description
data.update(
blocks.convert(
source,
source_format,
before=[blocks.title(), blocks.description()],
blocks=blocks_setting,
)
)
return data
def _blocks_setting(
client: "PloneClient", setting: blocks.BlocksSetting | None
) -> dict[str, Any]:
"""The setting of a conversion: the site's, with the call's over it.
:param client: The client, whose ``blocks`` is the site's setting.
:param setting: The setting of the call.
:returns: The merged setting, validated.
:raises ValueError: If it is invalid.
"""
return blocks.validate_setting(blocks.merge_settings(client.blocks, setting))
[docs]
def create_page(
client: "PloneClient",
parent: str,
source: str,
*,
source_format: blocks.SourceFormat = "markdown",
portal_type: str = "Document",
title: str | None = None,
description: str | None = None,
data: Mapping[str, Any] | None = None,
files: Iterable[str | Path] = (),
lead_image: LeadImage = "first",
publish: str | None = None,
blocks_setting: blocks.BlocksSetting | None = None,
) -> OperationResult:
"""Create a page from Markdown or HTML, converted to blocks.
See :func:`page_data` for how the page is built. Needs the ``markdown``
extra (Python 3.12 or later). Files are uploaded inside the page as in
:func:`create_with_files`, and the lead image is set the same way. The
block types come from the client's ``blocks``, with ``blocks_setting``
merged over it block type by block type.
:param client: The client.
:param parent: Path or URL of the folder.
:param source: The Markdown or HTML text.
:param source_format: ``markdown`` or ``html``.
:param portal_type: Content type; it must have blocks.
:param title: Title; the leading ``#`` heading by default.
:param description: Description.
:param data: More field values, such as ``id`` or ``subjects``.
:param files: Paths of the files to upload inside the page.
:param lead_image: Index of the lead image in ``files``, ``"first"``
for the first image (skipped when the type has no lead image), or
``None`` for no lead image.
:param publish: Workflow transition to run at the end.
:param blocks_setting: Which block types the content becomes; see
:func:`~plone_client.blocks.convert`.
:returns: The result; ``item`` is the new page.
:raises ValueError: If there is no title, a file is missing, the lead
image is not an image or cannot be stored by the type, or the blocks
setting is invalid. Nothing is sent then.
:raises PloneConfigurationError: If ``collective.html2blocks`` is missing.
:raises PloneOperationError: If a request fails.
"""
paths = _check_files(files)
lead = _pick_lead(paths, lead_image)
body = {
**(data or {}),
**page_data(
source,
source_format,
title=title,
description=description,
blocks_setting=_blocks_setting(client, blocks_setting),
),
}
with _operation(client, "create_page") as result:
parent_path = client.content.resolve(parent)
schema = {}
if lead is not None:
schema = client.types.get(portal_type).get("properties", {})
lead, in_field = _lead_target(portal_type, schema, lead, lead_image)
if in_field and lead is not None:
body["image"] = file_data(lead)
answer = client.content.create(parent_path, portal_type, body)
item = _created(client, answer, parent_path, {"@type": portal_type, **body})
result.item = item
result.created.append(item)
_attach_files(
client, result, item, client.path(item["@id"]), paths, lead, in_field
)
if publish:
client.workflow.transition(client.path(item["@id"]), publish)
result.changed.append({"@id": item["@id"], "transition": publish})
if not client.dry_run:
result.item = _summary(
client.content.get(item["@id"], include_items=False)
)
return result
def _folder_body(
directory: Path,
convert_pages: bool,
include_hidden: bool,
blocks_setting: Mapping[str, Any],
) -> tuple[dict[str, Any], Path | None]:
"""Field values of the page made for a folder.
:param directory: The folder.
:param convert_pages: Use its index file, if any, as content.
:param include_hidden: Whether hidden files are uploaded.
:param blocks_setting: Which block types the content becomes.
:returns: The values, and the index file used.
"""
if convert_pages:
for name in INDEX_NAMES:
index = directory / name
if index.is_file() and (include_hidden or not name.startswith(".")):
body = page_data(
index.read_text(),
PAGE_FORMATS[index.suffix.lower()],
default_title=directory.name,
blocks_setting=blocks_setting,
)
return {"id": slug(directory.name), **body}, index
return {
"id": slug(directory.name),
"title": directory.name,
**blocks.build(blocks.title(), blocks.description()),
}, None
[docs]
def upload_tree(
client: "PloneClient",
source: str | Path,
parent: str,
*,
folder_type: str = "Document",
convert_pages: bool = False,
include_hidden: bool = False,
publish: str | None = None,
blocks_setting: blocks.BlocksSetting | None = None,
) -> OperationResult:
"""Upload the contents of a local folder, keeping its structure.
Folders become folderish pages (``Document`` by default, which is
folderish on Volto sites), images become ``Image`` items, and other files
``File`` items. The contents of ``source`` go inside ``parent``, which
must exist, as with ``rsync source/ parent``.
With ``convert_pages``, Markdown and HTML files become pages (see
:func:`page_data`), and a folder's ``index.md``, ``README.md`` or
``index.html`` becomes the content of the folder's own page. This needs
the ``markdown`` extra. The block types come from the client's
``blocks``, with ``blocks_setting`` merged over it.
:param client: The client.
:param source: Local folder.
:param parent: Path or URL of the folder in the site.
:param folder_type: Content type for folders.
:param convert_pages: Turn Markdown and HTML files into pages.
:param include_hidden: Also upload files and folders whose name starts
with a dot.
:param publish: Workflow transition to run on each new page, such as
``publish``; files and images follow their folder.
:param blocks_setting: Which block types pages become; see
:func:`~plone_client.blocks.convert`.
:returns: The result; each created entry names its local ``source``.
:raises ValueError: If ``source`` is not a folder, or, with
``convert_pages``, the blocks setting is invalid. Nothing is sent then.
:raises PloneOperationError: If a request fails.
"""
root = Path(source).expanduser()
if not root.is_dir():
raise ValueError(f"Not a folder: {root}")
setting = _blocks_setting(client, blocks_setting) if convert_pages else {}
with _operation(client, "upload_tree") as result:
parent_path = client.content.resolve(parent)
client.content.get(parent_path, include_items=False) # it must exist
_upload_folder(
client,
result,
root,
parent_path,
folder_type=folder_type,
convert_pages=convert_pages,
include_hidden=include_hidden,
publish=publish,
skip=None,
blocks_setting=setting,
)
return result
def _upload_folder(
client: "PloneClient",
result: OperationResult,
directory: Path,
parent: str,
*,
folder_type: str,
convert_pages: bool,
include_hidden: bool,
publish: str | None,
skip: Path | None,
blocks_setting: Mapping[str, Any],
) -> None:
"""Upload the entries of a local folder into a folder of the site.
:param client: The client.
:param result: The result to fill in.
:param directory: Local folder.
:param parent: Site path of the folder.
:param folder_type: Content type for folders.
:param convert_pages: Turn Markdown and HTML files into pages.
:param include_hidden: Upload hidden entries.
:param publish: Transition for new pages.
:param skip: Index file already used for the folder's page.
:param blocks_setting: Which block types pages become, validated.
"""
entries = sorted(directory.iterdir(), key=lambda path: path.name.lower())
for path in entries:
if path == skip or (path.name.startswith(".") and not include_hidden):
continue
if path.is_dir():
body, index = _folder_body(
path, convert_pages, include_hidden, blocks_setting
)
answer = client.content.create(parent, folder_type, body)
entry = _created(
client, answer, parent, {"@type": folder_type, **body}, source=str(path)
)
result.created.append(entry)
folder = client.path(entry["@id"])
if publish:
client.workflow.transition(folder, publish)
_upload_folder(
client,
result,
path,
folder,
folder_type=folder_type,
convert_pages=convert_pages,
include_hidden=include_hidden,
publish=publish,
skip=index,
blocks_setting=blocks_setting,
)
elif convert_pages and path.suffix.lower() in PAGE_FORMATS:
body = {
"id": slug(path.stem),
**page_data(
path.read_text(),
PAGE_FORMATS[path.suffix.lower()],
default_title=path.stem,
blocks_setting=blocks_setting,
),
}
answer = client.content.create(parent, "Document", body)
entry = _created(
client, answer, parent, {"@type": "Document", **body}, source=str(path)
)
result.created.append(entry)
if publish:
client.workflow.transition(client.path(entry["@id"]), publish)
elif path.is_file():
answer = client.files.upload(parent, path)
data = {"@type": "Image" if _is_image(path) else "File", "title": path.name}
result.created.append(
_created(client, answer, parent, data, source=str(path))
)
def _transfer(
client: "PloneClient",
name: str,
sources: str | Iterable[str],
target: str,
) -> OperationResult:
"""Copy or move items, and report where each one went.
:param client: The client.
:param name: ``copy`` or ``move``.
:param sources: Items to copy or move.
:param target: Folder to copy or move into.
:returns: The result.
"""
refs = [sources] if isinstance(sources, str) else list(sources)
with _operation(client, name) as result:
target_path = client.content.resolve(target)
folder = client.content.get(target_path, include_items=False)
if folder.get("is_folderish") is False:
raise ValueError(f"{target_path} is not a folder")
paths = [client.content.resolve(ref) for ref in refs]
counts = {path: client.search.count(path) for path in paths}
method = client.content.move if name == "move" else client.content.copy
answer = method(paths, target_path)
if client.dry_run:
pairs = [
(path, f"{target_path.rstrip('/')}/{path.rsplit('/', 1)[-1]}")
for path in paths
]
else:
pairs = [
(client.path(entry["source"]), client.path(entry["target"]))
for entry in answer
]
for source_path, target_item in pairs:
entry: dict[str, Any] = {
"source": client.site_url(source_path),
"@id": client.site_url(target_item),
"items": counts.get(source_path),
}
if client.dry_run:
entry["planned"] = True
else:
entry["items_after"] = client.search.count(target_item)
(result.changed if name == "move" else result.created).append(entry)
return result
[docs]
def copy_items(
client: "PloneClient", sources: str | Iterable[str], target: str
) -> OperationResult:
"""Copy items, folders with their contents, into a folder.
Plone may rename a copy whose id is taken (``copy_of_news``), so read
the ``@id`` of each created entry.
:param client: The client.
:param sources: Path, URL or UID reference of an item, or several.
:param target: Path or URL of the folder.
:returns: The result; each created entry has the ``source``, the new
``@id``, and the number of ``items`` (the item and everything inside
it) before and, unless in a dry run, after the copy.
:raises PloneOperationError: If a request fails.
"""
return _transfer(client, "copy", sources, target)
[docs]
def move_items(
client: "PloneClient", sources: str | Iterable[str], target: str
) -> OperationResult:
"""Move items, folders with their contents, into a folder.
:param client: The client.
:param sources: Path, URL or UID reference of an item, or several.
:param target: Path or URL of the folder.
:returns: The result; each changed entry has the old ``source``, the
new ``@id`` and the number of ``items`` before and after the move.
:raises PloneOperationError: If a request fails.
"""
return _transfer(client, "move", sources, target)
BlockEdit = Callable[[dict[str, Any]], dict[str, Any]]
def _edit_blocks(
client: "PloneClient", ref: str, name: str, edit: BlockEdit
) -> OperationResult:
"""Read the blocks of an item, change them, and save them in one request.
The change runs on a copy and may raise ``ValueError`` to refuse it;
nothing is sent then. The layout is tidied with
:func:`~plone_client.blocks.tidy` before saving. The blocks are read and
written back without a lock, so a change made by someone else in between
is lost.
:param client: The client.
:param ref: Path or URL of the item.
:param name: Name of the operation.
:param edit: Changes ``blocks`` and ``blocks_layout`` in place, and
returns what changed, for the result.
:returns: The result; ``item`` has an outline of the saved blocks.
:raises ValueError: If the item has no blocks, or the change is refused.
:raises PloneOperationError: If a request fails.
"""
with _operation(client, name) as result:
path = client.content.resolve(ref)
item = client.content.get(path, include_items=False)
if not isinstance(item.get("blocks"), dict):
raise ValueError(f"{path} has no blocks")
data = {
"blocks": copy.deepcopy(item["blocks"]),
"blocks_layout": copy.deepcopy(item.get("blocks_layout") or {}),
}
details = edit(data)
data = blocks.tidy(data["blocks"], data["blocks_layout"])
client.content.update(path, data, representation=False)
result.changed.append({"@id": item["@id"], **details})
result.item = _summary(
item, blocks=blocks.outline(data["blocks"], data["blocks_layout"])
)
return result
def _holder(data: dict[str, Any], block_id: str) -> dict[str, Any]:
"""What holds a block, with a layout to change.
:param data: ``blocks`` and ``blocks_layout`` of an item.
:param block_id: Id of the block.
:returns: The item data or the container block that holds it.
:raises ValueError: If there is no such block.
"""
holder = blocks.locate(data, block_id)
if holder is None:
raise ValueError(f"No block {block_id!r} in the item")
layout = holder.setdefault("blocks_layout", {})
layout.setdefault("items", list(holder["blocks"]))
return holder
[docs]
def add_blocks(
client: "PloneClient",
ref: str,
items: Iterable[Mapping[str, Any]],
*,
after: str | None = None,
position: int | None = None,
) -> OperationResult:
"""Add blocks to an item, keeping the blocks it has.
The blocks are normalized with :func:`~plone_client.blocks.normalize`,
so a container may list the blocks inside it. They go after the block
``after``, in the same container as it, or at ``position`` among the item's own
blocks, or at the end.
:param client: The client.
:param ref: Path or URL of the item.
:param items: The blocks, in order, each with an ``@type``.
:param after: Id of the block to add them after.
:param position: Index in the item's layout; ``0`` is the top.
:returns: The result; its changed entry lists the ``added`` ids.
:raises ValueError: If a block has no ``@type``, both ``after`` and
``position`` are given, ``after`` names no block, or ``position`` is
outside the layout. Nothing is changed then.
:raises PloneOperationError: If a request fails.
"""
if after is not None and position is not None:
raise ValueError("Give either after or position, not both")
built = blocks.build(*(blocks.normalize(item) for item in items))
if not built["blocks"]:
raise ValueError("No blocks to add")
ids = built["blocks_layout"]["items"]
def edit(data: dict[str, Any]) -> dict[str, Any]:
holder = _holder(data, after) if after is not None else data
order = holder.setdefault("blocks_layout", {}).setdefault(
"items", list(holder["blocks"])
)
if after is not None:
index = order.index(after) + 1 if after in order else len(order)
elif position is not None:
if not 0 <= position <= len(order):
raise ValueError(
f"position must be between 0 and {len(order)}, not {position}"
)
index = position
else:
index = len(order)
holder["blocks"].update(built["blocks"])
order[index:index] = ids
return {"added": ids}
return _edit_blocks(client, ref, "add_blocks", edit)
[docs]
def update_block(
client: "PloneClient",
ref: str,
block_id: str,
data: Mapping[str, Any],
*,
replace: bool = False,
) -> OperationResult:
"""Change the data of one block, at any depth.
:param client: The client.
:param ref: Path or URL of the item.
:param block_id: Id of the block.
:param data: Values to merge into the block, or, with ``replace``, its
new data. The ``@type`` is kept unless ``data`` has one.
:param replace: Replace the block's data instead of merging into it.
:returns: The result; its changed entry lists the ``updated`` id.
:raises ValueError: If there is no such block. Nothing is changed then.
:raises PloneOperationError: If a request fails.
"""
def edit(found: dict[str, Any]) -> dict[str, Any]:
holder = _holder(found, block_id)
old = holder["blocks"][block_id]
base = {"@type": old.get("@type")} if replace else old
holder["blocks"][block_id] = blocks.normalize({**base, **data})
return {"updated": [block_id]}
return _edit_blocks(client, ref, "update_block", edit)
[docs]
def remove_blocks(
client: "PloneClient", ref: str, block_ids: str | Iterable[str]
) -> OperationResult:
"""Remove blocks from an item, at any depth, with the blocks inside them.
:param client: The client.
:param ref: Path or URL of the item.
:param block_ids: Id of a block, or several.
:returns: The result; its changed entry lists the ``removed`` ids.
:raises ValueError: If a block is not found. Nothing is changed then.
:raises PloneOperationError: If a request fails.
"""
ids = [block_ids] if isinstance(block_ids, str) else list(block_ids)
def edit(data: dict[str, Any]) -> dict[str, Any]:
for block_id in ids:
holder = _holder(data, block_id)
del holder["blocks"][block_id]
order = holder["blocks_layout"]["items"]
if block_id in order:
order.remove(block_id)
return {"removed": ids}
return _edit_blocks(client, ref, "remove_blocks", edit)
#: Blocks that show fields of the item, kept by :func:`set_blocks`.
FIELD_BLOCKS = ("title", "description")
[docs]
def set_blocks(
client: "PloneClient", ref: str, items: Iterable[Mapping[str, Any]]
) -> OperationResult:
"""Replace all the blocks of an item.
The item's title and description blocks are kept at the top unless the
new blocks have blocks of those types, so the page keeps showing its
title.
:param client: The client.
:param ref: Path or URL of the item.
:param items: The new blocks, in order, each with an ``@type``; see
:func:`~plone_client.blocks.normalize`.
:returns: The result; its changed entry lists the ``added`` ids and the
``removed`` ones.
:raises ValueError: If a block has no ``@type``. Nothing is changed then.
:raises PloneOperationError: If a request fails.
"""
built = blocks.build(*(blocks.normalize(item) for item in items))
given = {block["@type"] for block in built["blocks"].values()}
def edit(data: dict[str, Any]) -> dict[str, Any]:
old = blocks.tidy(data["blocks"], data["blocks_layout"])
kept = [
block_id
for block_id in old["blocks_layout"]["items"]
if data["blocks"][block_id].get("@type") in FIELD_BLOCKS
and data["blocks"][block_id].get("@type") not in given
]
removed = [block_id for block_id in data["blocks"] if block_id not in kept]
data["blocks"] = {
**{block_id: data["blocks"][block_id] for block_id in kept},
**built["blocks"],
}
data["blocks_layout"]["items"] = kept + built["blocks_layout"]["items"]
return {"added": built["blocks_layout"]["items"], "removed": removed}
return _edit_blocks(client, ref, "set_blocks", edit)