"""Content: read, create, update, delete, copy, move, order and lock items."""
from ..exceptions import PloneClientError
from ..exceptions import PloneNotFoundError
from ..utils import uid_from_ref
from .base import BaseManager
from collections.abc import Iterable
from collections.abc import Iterator
from collections.abc import Mapping
from typing import Any
from typing import Literal
#: Keys a new item takes that are not fields of its type.
ALWAYS_ACCEPTED = frozenset({"id", "UID"})
[docs]
def blocks_warning(data: Mapping[str, Any]) -> str | None:
"""Say why the site would refuse the blocks of an item.
The site wants ``blocks`` as a mapping of block ids, each block with an
``@type``, and ``blocks_layout.items`` listing those ids in order;
:func:`~plone_client.blocks.build` and
:func:`~plone_client.blocks.prepare` make both.
:param data: Field values of the item.
:returns: The warning, or ``None`` if there are no blocks or they are
well formed.
"""
found = data.get("blocks")
if found is None:
return None
if not isinstance(found, Mapping):
return (
"The site would refuse this: blocks must be a mapping of block ids, "
"with their order in blocks_layout; make both with "
"plone_client.blocks.build or plone_client.blocks.prepare."
)
untyped = sorted(
key
for key, block in found.items()
if not isinstance(block, Mapping) or not block.get("@type")
)
if untyped:
return (
f"The site would refuse this: blocks without @type: {', '.join(untyped)}."
)
layout = data.get("blocks_layout")
items = layout.get("items") if isinstance(layout, Mapping) else None
if not isinstance(items, list) or set(items) != set(found):
return (
"Volto would not show these blocks as they are: blocks_layout.items "
"must list the ids in blocks, in order."
)
return None
def _add_warnings(answer: dict[str, Any], warnings: Iterable[str | None]) -> None:
"""Put the warnings of a dry run into its record, as one ``warning``.
:param answer: The record of the request.
:param warnings: Warnings; ``None`` stands for none.
"""
found = [warning for warning in warnings if warning]
if found:
answer["warning"] = " ".join(found)
def _sources(refs: str | Iterable[str]) -> list[str]:
"""Normalize one or more references for ``@copy`` and ``@move``.
:param refs: A reference or several.
:returns: A list of references.
"""
return [refs] if isinstance(refs, str) else list(refs)
[docs]
class ContentManager(BaseManager):
"""Content items, through the content endpoints of ``plone.restapi``.
Every method takes the path of an item, or its URL as found in ``@id``.
"""
# ------------------------------------------------------------------
# Reading
# ------------------------------------------------------------------
[docs]
def get(
self,
ref: str = "/",
*,
expand: str | Iterable[str] | None = None,
fullobjects: bool = False,
include_items: bool | None = None,
version: str | int | None = None,
**params: Any,
) -> dict[str, Any]:
"""Serialization of an item.
:param ref: Path or URL of the item; also ``uid:<UID>``.
:param expand: Components to expand inline (``breadcrumbs``,
``navigation``, ``translations``…).
:param fullobjects: Serialize the contained items in full.
:param include_items: ``False`` leaves the contained items out.
:param version: Version of the item to return, from ``@history``.
:param params: Other query parameters.
:returns: The item.
"""
if not isinstance(expand, str) and expand is not None:
expand = ",".join(expand)
query: dict[str, Any] = {
"expand": expand or None,
"fullobjects": 1 if fullobjects else None,
"include_items": include_items,
"version": version,
**params,
}
return self._client.get(self.resolve(ref), **query)
[docs]
def find_by_uid(self, uid: str) -> dict[str, Any]:
"""Catalog entry of the item with a UID.
:param uid: The UID.
:returns: The search result, with ``@id``, ``@type`` and ``title``.
:raises PloneNotFoundError: If no item has this UID.
"""
found = self._client.get("/@search", UID=uid)
if not found.get("items"):
raise PloneNotFoundError(
f"No item with UID {uid}",
status_code=404,
error_type="NotFound",
method="GET",
url=self._client.api_url("/@search"),
)
return found["items"][0]
[docs]
def resolve(self, ref: str) -> str:
"""Site path for a reference.
Plain paths and URLs are only normalized. ``uid:<UID>`` and
``resolveuid`` links are looked up in the catalog.
:param ref: Path, URL, ``uid:<UID>`` or ``resolveuid`` link.
:returns: The site path.
:raises PloneNotFoundError: If the UID is not found.
"""
uid = uid_from_ref(ref)
if uid:
return self._client.path(self.find_by_uid(uid)["@id"])
return self._client.path(ref)
[docs]
def exists(self, ref: str) -> bool:
"""Say whether there is an item at a path.
:param ref: Path or URL of the item.
:returns: ``True`` if it exists.
"""
return self._client.exists(ref)
[docs]
def children(
self,
ref: str = "/",
*,
portal_type: str | Iterable[str] | None = None,
metadata_fields: str | Iterable[str] | None = None,
limit: int | None = None,
b_size: int = 100,
) -> Iterator[dict[str, Any]]:
"""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.
:param ref: Path or URL of the folder.
:param portal_type: Only items of these types.
:param metadata_fields: Extra catalog metadata to return
(``_all`` for every column).
:param limit: Stop after this many items.
:param b_size: Items fetched per request.
:returns: Each item.
"""
params = {
"path.depth": 1,
"sort_on": "getObjPositionInParent",
"portal_type": portal_type,
"metadata_fields": metadata_fields,
"b_size": b_size,
}
return self._client.iter_items(
self._service(ref, "@search"), params, limit=limit
)
# ------------------------------------------------------------------
# Changing
# ------------------------------------------------------------------
[docs]
def create(
self,
parent: str,
portal_type: str,
data: Mapping[str, Any] | None = None,
**fields: Any,
) -> dict[str, Any]:
"""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.
:param parent: Path or URL of the folder.
:param portal_type: Content type, such as ``Document``.
:param data: Field values; also ``id``, and ``UID`` (needs the
*Manage portal* permission).
:param fields: More field values, merged over ``data``.
:returns: The new item. In a dry run, the record of the request, with
a ``warning`` if the site would refuse the type in the folder,
refuse the blocks, or ignore fields the type does not have.
:raises PloneBadRequestError: If the id is in use, or a field is invalid.
:raises PloneForbiddenError: If the type is not allowed in the folder.
"""
path = self.resolve(parent)
payload = {"@type": portal_type, **(data or {}), **fields}
answer = self._client.post(path, payload)
if self._client.dry_run:
warnings = [
self._type_warning(path, portal_type),
blocks_warning(payload),
self._fields_warning(portal_type, payload),
]
_add_warnings(answer, warnings)
return answer
def _type_warning(self, path: str, portal_type: str) -> str | None:
"""Say why a dry run's new item would be refused.
A dry run sends nothing, so nothing else asks the site about the type.
A folder that does not exist yet, such as one planned by the same dry
run, cannot be asked, and gets no warning.
:param path: Path of the folder.
:param portal_type: Content type.
:returns: The warning, or ``None`` if the type can be added or the
site cannot say.
"""
try:
addable = self._client.types.addable(path)
except PloneClientError:
return None
if portal_type in addable:
return None
return (
f"The site would refuse this: {portal_type} cannot be added in "
f"{path}. It can add: {', '.join(addable) or 'nothing'}."
)
def _fields_warning(
self, portal_type: str, payload: Mapping[str, Any]
) -> str | None:
"""Say which fields of a dry run's new item the site would ignore.
:param portal_type: Content type.
:param payload: Field values.
:returns: The warning, or ``None`` if every field exists or the site
cannot say.
"""
try:
schema = self._client.types.get(portal_type).get("properties", {})
except PloneClientError:
return None
unknown = sorted(
key
for key in payload
if key not in schema
and key not in ALWAYS_ACCEPTED
and not key.startswith("@")
)
if not unknown or not schema:
return None
return (
f"The site would ignore fields that {portal_type} does not have: "
f"{', '.join(unknown)}."
)
[docs]
def update(
self,
ref: str,
data: Mapping[str, Any] | None = None,
*,
lock_token: str | None = None,
representation: bool = True,
**fields: Any,
) -> dict[str, Any] | None:
"""Change fields of an item (``PATCH``).
:param ref: Path or URL of the item.
:param data: Field values.
:param lock_token: Token of a lock held on the item.
:param representation: Ask the site to return the changed item.
:param fields: More field values, merged over ``data``.
:returns: The changed item, or ``None`` with ``representation=False``.
In a dry run, the record of the request, with a ``warning`` if
the site would refuse the blocks.
"""
headers = {}
if representation:
headers["Prefer"] = "return=representation"
if lock_token:
headers["Lock-Token"] = lock_token
payload = {**(data or {}), **fields}
answer = self._client.patch(self.resolve(ref), payload, headers=headers)
if self._client.dry_run and isinstance(answer, dict):
_add_warnings(answer, [blocks_warning(payload)])
return answer
[docs]
def delete(self, ref: str) -> None:
"""Delete an item.
:param ref: Path or URL of the item.
:raises PloneBadRequestError: If link integrity forbids the deletion.
"""
self._client.delete(self.resolve(ref))
[docs]
def copy(self, source: str | Iterable[str], target: str) -> list[dict[str, Any]]:
"""Copy items into a folder.
:param source: Path, URL or UID of an item, or several.
:param target: Path or URL of the folder.
:returns: One ``{"source", "target"}`` entry per item.
"""
return self._client.post(
self._service(target, "@copy"), {"source": _sources(source)}
)
[docs]
def move(self, source: str | Iterable[str], target: str) -> list[dict[str, Any]]:
"""Move items into a folder.
:param source: Path, URL or UID of an item, or several.
:param target: Path or URL of the folder.
:returns: One ``{"source", "target"}`` entry per item.
"""
return self._client.post(
self._service(target, "@move"), {"source": _sources(source)}
)
[docs]
def order(
self,
folder: str,
obj_id: str,
delta: int | Literal["top", "bottom"],
*,
subset_ids: Iterable[str] | None = None,
) -> None:
"""Move an item within its folder.
:param folder: Path or URL of the folder.
:param obj_id: Id of the item to move.
:param delta: Positions to move (negative moves up), ``top`` or
``bottom``.
:param subset_ids: Ids of the items the client knows about, in their
current order; the site refuses the change if they are out of date.
"""
ordering: dict[str, Any] = {"obj_id": obj_id, "delta": delta}
if subset_ids is not None:
ordering["subset_ids"] = list(subset_ids)
self._client.patch(self.resolve(folder), {"ordering": ordering})
[docs]
def sort(
self,
folder: str,
on: str,
order: Literal["ascending", "descending"] = "ascending",
) -> None:
"""Sort the items of a folder by an index, once.
:param folder: Path or URL of the folder.
:param on: Catalog index to sort on, such as ``modified``.
:param order: ``ascending`` or ``descending``.
"""
self._client.patch(self.resolve(folder), {"sort": {"on": on, "order": order}})
# ------------------------------------------------------------------
# Locking
# ------------------------------------------------------------------
[docs]
def lock(
self, ref: str, *, stealable: bool = True, timeout: int | None = None
) -> dict[str, Any]:
"""Lock an item.
:param ref: Path or URL of the item.
:param stealable: Let other users break the lock.
:param timeout: Seconds the lock lasts.
:returns: Lock information, with the ``token`` to send in updates.
"""
data: dict[str, Any] = {"stealable": stealable}
if timeout is not None:
data["timeout"] = timeout
return self._client.post(self._service(ref, "@lock"), data)
[docs]
def unlock(self, ref: str, *, force: bool = False) -> dict[str, Any]:
"""Remove the lock of an item.
:param ref: Path or URL of the item.
:param force: Remove a lock held by another user.
:returns: Lock information.
"""
data = {"force": True} if force else None
return self._client.delete(self._service(ref, "@lock"), data)
[docs]
def refresh_lock(self, ref: str) -> dict[str, Any]:
"""Extend the lock of an item.
:param ref: Path or URL of the item.
:returns: Lock information.
"""
return self._client.patch(self._service(ref, "@lock"))
[docs]
def lock_info(self, ref: str) -> dict[str, Any]:
"""Lock information of an item.
:param ref: Path or URL of the item.
:returns: ``locked``, ``stealable`` and, when locked, the owner.
"""
return self._client.get(self._service(ref, "@lock"))
# ------------------------------------------------------------------
# Link integrity
# ------------------------------------------------------------------
[docs]
def link_integrity(self, uids: str | Iterable[str]) -> list[dict[str, Any]]:
"""Items that link to the given items.
Check this before deleting content.
:param uids: UID of an item, or several.
:returns: One entry per item, with its ``breaches``.
"""
return self._client.get("/@linkintegrity", uids=_sources(uids))