plone-client 1.0.0a1__py3-none-any.whl

plone_client/__init__.py

@@ -0,0 +1,51 @@
+"""plone-client: a Python library and command line client for Plone sites.
+
+Example::
+
+    from plone_client import PloneClient
+
+    with PloneClient.from_profile("blog") as site:
+        page = site.content.get("/about")
+        site.workflow.transition("/about", "publish")
+"""
+
+from .auth import JWTAuth
+from .auth import TokenAuth
+from .client import PloneClient
+from .exceptions import PloneAPIError
+from .exceptions import PloneAuthenticationError
+from .exceptions import PloneBadRequestError
+from .exceptions import PloneClientError
+from .exceptions import PloneConfigurationError
+from .exceptions import PloneConflictError
+from .exceptions import PloneConnectionError
+from .exceptions import PloneForbiddenError
+from .exceptions import PloneNotFoundError
+from .exceptions import PloneOperationError
+from .exceptions import PloneReadOnlyError
+from .exceptions import PloneServerError
+from .exceptions import PloneTimeoutError
+from .managers.files import file_data
+
+
+__version__ = "1.0.0a1"
+
+__all__ = [
+    "JWTAuth",
+    "PloneAPIError",
+    "PloneAuthenticationError",
+    "PloneBadRequestError",
+    "PloneClient",
+    "PloneClientError",
+    "PloneConfigurationError",
+    "PloneConflictError",
+    "PloneConnectionError",
+    "PloneForbiddenError",
+    "PloneNotFoundError",
+    "PloneOperationError",
+    "PloneReadOnlyError",
+    "PloneServerError",
+    "PloneTimeoutError",
+    "TokenAuth",
+    "file_data",
+]

plone_client/auth.py

@@ -0,0 +1,120 @@
+"""Authentication strategies for :class:`~plone_client.PloneClient`.
+
+Three ways to authenticate against ``plone.restapi`` are supported:
+
+* HTTP basic authentication (:class:`httpx.BasicAuth`), the simplest option
+  and the default when a username and password are given;
+* a JWT obtained from ``@login`` (:class:`JWTAuth`), which logs in again
+  when the token expires;
+* a token issued beforehand (:class:`TokenAuth`).
+
+Any other :class:`httpx.Auth` can be passed to the client as well.
+"""
+
+from .exceptions import error_from_response
+from collections.abc import Generator
+from typing import Literal
+
+import httpx
+
+
+AuthMethod = Literal["basic", "jwt"]
+
+
+class TokenAuth(httpx.Auth):
+    """Send a token issued beforehand as ``Authorization: Bearer``.
+
+    :param token: The JWT.
+    """
+
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        request.headers["Authorization"] = f"Bearer {self.token}"
+        yield request
+
+
+class JWTAuth(httpx.Auth):
+    """Log in with ``POST @login`` and send the JWT it returns.
+
+    The login happens on the first request. When the site answers ``401``,
+    the token is assumed to be expired: the flow logs in again and repeats
+    the request once.
+
+    :param username: Login name.
+    :param password: Password.
+    :param login_url: Absolute URL of the site's ``@login`` service.
+    """
+
+    requires_response_body = True
+
+    def __init__(self, username: str, password: str, login_url: str) -> None:
+        self.username = username
+        self.password = password
+        self.login_url = login_url
+        self.token = ""
+
+    def _login(self) -> Generator[httpx.Request, httpx.Response, None]:
+        """Ask the site for a new token.
+
+        :raises PloneAuthenticationError: If the site refuses the credentials.
+        """
+        response = yield httpx.Request(
+            "POST",
+            self.login_url,
+            json={"login": self.username, "password": self.password},
+            headers={"Accept": "application/json"},
+        )
+        if response.status_code != 200:
+            raise error_from_response(response)
+        self.token = response.json().get("token", "")
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        if not self.token:
+            yield from self._login()
+        request.headers["Authorization"] = f"Bearer {self.token}"
+        response = yield request
+        if response.status_code == 401:
+            yield from self._login()
+            request.headers["Authorization"] = f"Bearer {self.token}"
+            yield request
+
+
+def build_auth(
+    *,
+    username: str = "",
+    password: str = "",
+    token: str = "",
+    method: AuthMethod = "basic",
+    login_url: str = "",
+) -> httpx.Auth | None:
+    """Pick the authentication for a set of credentials.
+
+    A token wins over a username and password. Without any credential the
+    client is anonymous.
+
+    :param username: Login name.
+    :param password: Password.
+    :param token: JWT issued beforehand.
+    :param method: ``basic`` or ``jwt``, used with a username and password.
+    :param login_url: Absolute URL of ``@login``, needed by ``jwt``.
+    :returns: The authentication, or ``None`` for anonymous access.
+    :raises ValueError: If the method is unknown or only half of the
+        username/password pair is given.
+    """
+    if token:
+        return TokenAuth(token)
+    if not (username or password):
+        return None
+    if not (username and password):
+        raise ValueError("Both a username and a password are needed")
+    if method == "basic":
+        return httpx.BasicAuth(username, password)
+    if method == "jwt":
+        return JWTAuth(username, password, login_url)
+    raise ValueError(f"Unknown authentication method: {method!r}")

plone_client/block_docs/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Plone Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plone_client/block_docs/description.md

@@ -0,0 +1,13 @@
+---
+block: description
+---
+
+Shows the description (summary) of the content item.
+
+The block stores no data of its own: the text it shows is the content item's `description` field, so change that field to change the description.
+
+### Example
+
+```json
+{ "@type": "description" }
+```

plone_client/block_docs/detachedSlate.md

@@ -0,0 +1,5 @@
+---
+block: detachedSlate
+---
+
+A text block that is not split into new blocks when you press Enter, for use inside other blocks. Its data has the same format as the text block (`slate`).

plone_client/block_docs/gridBlock.md

@@ -0,0 +1,38 @@
+---
+block: gridBlock
+---
+
+Places blocks side by side in columns, for example several teasers in a row. It holds up to {{maxLength}} blocks.
+
+The grid contains its own blocks, in the same format as a page: `blocks` maps block IDs to block data, and `blocks_layout.items` lists those IDs in display order. Every ID must appear in both. The allowed blocks are {{allowedBlocks}}.
+
+The grid controls the layout of its blocks, so alignment and size settings of the blocks inside it are not used.
+
+### Fields
+
+- `blocks`: object of child blocks keyed by a unique ID (normally a UUID).
+- `blocks_layout`: `{ "items": [...] }` with the child IDs in order.
+
+### Example
+
+```json
+{
+  "@type": "gridBlock",
+  "blocks": {
+    "3f1a6c2e-0d8b-4a8e-9c55-1b2f7e9d4a01": {
+      "@type": "teaser",
+      "href": [{ "@id": "/news/article-one", "title": "Article one" }]
+    },
+    "8b7d0e4f-5c2a-4e61-a3f9-6d0c2b8e1f72": {
+      "@type": "teaser",
+      "href": [{ "@id": "/news/article-two", "title": "Article two" }]
+    }
+  },
+  "blocks_layout": {
+    "items": [
+      "3f1a6c2e-0d8b-4a8e-9c55-1b2f7e9d4a01",
+      "8b7d0e4f-5c2a-4e61-a3f9-6d0c2b8e1f72"
+    ]
+  }
+}
+```

plone_client/block_docs/html.md

@@ -0,0 +1,20 @@
+---
+block: html
+---
+
+Renders raw HTML markup as it is.
+
+Only use it for trusted markup that can't be built with other blocks: the HTML is not sanitized.
+
+### Fields
+
+- `html`: the HTML markup.
+
+### Example
+
+```json
+{
+  "@type": "html",
+  "html": "<p>Custom <strong>HTML</strong> content.</p>"
+}
+```

plone_client/block_docs/image.md

@@ -0,0 +1,30 @@
+---
+block: image
+---
+
+Shows a single image, either an Image content item from the site or an external image, with optional alt text, link, alignment and size.
+
+For an image from the site, set `url` to the path of the Image content item (for example `/my-folder/my-image`) or to its full URL, and set `image_field` to `image`. Both forms are stored as a UID-based path. Don't use an `@@images` scale URL.
+
+For an external image, set `url` to the full image URL and leave out `image_field`.
+
+Inside a container block such as the grid, the container controls the layout, so `align` and `size` are not used there.
+
+### Fields
+
+- `url`: path or URL of the image.
+- `image_field`: the image field of the content item, normally `image`. Only for images from the site.
+- `alt`: alternative text for screen readers.
+- `href`: optional link target.
+- `align`, `size`: alignment and size on the page.
+
+### Example
+
+```json
+{
+  "@type": "image",
+  "url": "/images/team-photo",
+  "image_field": "image",
+  "alt": "The team at the 2025 conference"
+}
+```

plone_client/block_docs/listing.md

@@ -0,0 +1,45 @@
+---
+block: listing
+---
+
+Shows a list of content items that match a catalog query, such as the latest news or upcoming events. The list updates as content is added. To link to specific items chosen by hand, use teasers instead.
+
+The query is stored in `querystring`. The criteria that a site supports depend on its configuration, so get the available indexes and operations from the `@querystring` endpoint of the Plone REST API.
+
+### Fields
+
+- `querystring`: an object with:
+  - `query`: list of criteria, each `{ "i": index, "o": operation, "v": value }`. Operations are full names, such as `plone.app.querystring.operation.selection.any`.
+  - `sort_on`, `sort_order` (`ascending` or `descending`): optional sorting. For descending order, also set `sort_order_boolean` to `true`.
+  - `b_size` (items per page) and `limit` (maximum number of items): optional, given as strings, for example `"10"`.
+- `variation`: how the items are shown. See the block's variations for the available ones.
+- `headline`, `headlineTag`: optional heading above the list.
+
+### Example
+
+```json
+{
+  "@type": "listing",
+  "headline": "Latest news",
+  "headlineTag": "h2",
+  "variation": "summary",
+  "querystring": {
+    "query": [
+      {
+        "i": "portal_type",
+        "o": "plone.app.querystring.operation.selection.any",
+        "v": ["News Item"]
+      },
+      {
+        "i": "path",
+        "o": "plone.app.querystring.operation.string.absolutePath",
+        "v": "/news"
+      }
+    ],
+    "sort_on": "effective",
+    "sort_order": "descending",
+    "sort_order_boolean": true,
+    "b_size": "6"
+  }
+}
+```

plone_client/block_docs/maps.md

@@ -0,0 +1,18 @@
+---
+block: maps
+---
+
+Embeds an interactive map from a map service.
+
+### Fields
+
+- `url`: the embed URL of the map. For Google Maps, use the URL from *Share > Embed a map*, which starts with `https://www.google.com/maps/embed`.
+
+### Example
+
+```json
+{
+  "@type": "maps",
+  "url": "https://www.google.com/maps/embed?pb=..."
+}
+```

plone_client/block_docs/search.md

@@ -0,0 +1,43 @@
+---
+block: search
+---
+
+Shows a list of content items that visitors can search, sort and filter with facets. Unlike the listing block, results change as the visitor interacts with the block.
+
+The base query in `query` has the same shape as the listing block's `querystring`: an object that contains a `query` list of criteria, not the list itself. It filters the results before the visitor's own search is applied. Use `{ "query": [] }` to start from all content. The criteria that a site supports depend on its configuration, so get the available indexes and operations from the `@querystring` endpoint of the Plone REST API.
+
+### Fields
+
+- `query`: the base query, with `query` (list of `{ "i", "o", "v" }` criteria), and optional `sort_on`, `sort_order`, `b_size` and `limit`. `b_size` and `limit` are strings, for example `"10"`.
+- `showSearchInput`, `showSortOn`, `showTotalResults`: booleans that show the search field, the sort menu and the result count.
+- `facets`: list of facets, each `{ "title", "field", "type" }`, where `field` is a catalog index and `type` is one of the facet widgets configured for the block (Volto ships `selectFacet`, `checkboxFacet`, `daterangeFacet` and `toggleFacet`). Optional `hidden` and `advanced` booleans.
+- `variation`: where the facets are placed. See the block's variations for the available ones.
+- `headline`: optional heading.
+
+### Example
+
+```json
+{
+  "@type": "search",
+  "headline": "News",
+  "query": {
+    "query": [
+      {
+        "i": "portal_type",
+        "o": "plone.app.querystring.operation.selection.any",
+        "v": ["News Item"]
+      }
+    ],
+    "sort_on": "effective",
+    "sort_order": "descending",
+    "b_size": "10"
+  },
+  "showSearchInput": true,
+  "showSortOn": true,
+  "showTotalResults": true,
+  "facets": [
+    { "title": "Topic", "field": "Subject", "type": "checkboxFacet" }
+  ],
+  "variation": "facetsRightSide"
+}
+```

plone_client/block_docs/slate.md

@@ -0,0 +1,81 @@
+---
+block: slate
+---
+
+Holds rich text: a paragraph, a heading, a list or a quote, with inline formatting and links. It is the most common block on a page.
+
+Each text block normally holds one paragraph, heading, list or quote. For several paragraphs, add one text block per paragraph, as the editor does when you press Enter.
+
+The text is stored twice:
+
+- `value`: the rich text, as a list of Slate nodes.
+- `plaintext`: the same text without formatting. It is what the site indexes for search and what decides whether the block is empty, so keep it in sync with `value`.
+
+### The `value` format
+
+`value` is a list with one element (sometimes more). An element is `{ "type": ..., "children": [...] }`, and the innermost children are text nodes, `{ "text": "..." }`. Every element has at least one child, even if it's `{ "text": "" }`.
+
+- Block-level types: `p` (paragraph), `h2`, `h3`, `h4` (headings; the page title is the `h1`), `ul` and `ol` (lists, whose children are `li` elements), and `blockquote`.
+- Inline formatting is not a property of text nodes. It is an element that wraps them: `strong`, `em`, `u`, `del`, `sub`, `sup` and `code`.
+- Links are `{ "type": "link", "data": { "url": ... }, "children": [...] }`. For content from the site, use its path, for example `/news/annual-report`; it is stored as a UID-based link. For an external link, use the full URL.
+
+### Fields
+
+- `value`: the rich text, as described above.
+- `plaintext`: the text of `value` without formatting.
+- `override_toc`, `level`, `entry_text`: optional. Replace this block's entry in a table of contents block.
+
+### Examples
+
+A heading:
+
+```json
+{
+  "@type": "slate",
+  "value": [{ "type": "h2", "children": [{ "text": "Our services" }] }],
+  "plaintext": "Our services"
+}
+```
+
+A paragraph with bold text and a link:
+
+```json
+{
+  "@type": "slate",
+  "value": [
+    {
+      "type": "p",
+      "children": [
+        { "text": "Read the " },
+        { "type": "strong", "children": [{ "text": "annual report" }] },
+        { "text": " on the " },
+        {
+          "type": "link",
+          "data": { "url": "/news/annual-report" },
+          "children": [{ "text": "news page" }]
+        },
+        { "text": "." }
+      ]
+    }
+  ],
+  "plaintext": "Read the annual report on the news page."
+}
+```
+
+A bulleted list:
+
+```json
+{
+  "@type": "slate",
+  "value": [
+    {
+      "type": "ul",
+      "children": [
+        { "type": "li", "children": [{ "text": "First item" }] },
+        { "type": "li", "children": [{ "text": "Second item" }] }
+      ]
+    }
+  ],
+  "plaintext": "First item Second item"
+}
+```

plone_client/block_docs/teaser.md

@@ -0,0 +1,25 @@
+---
+block: teaser
+---
+
+Shows a card that links to one content item, with its title, description and image. Use it for highlights chosen by hand. To show items that match a query, use a listing block instead.
+
+Usually only `href` is needed: the teaser reads the title, description and image from the target item, and follows it when that item changes. Set `overwrite` to `true` to replace them with your own values; the teaser then no longer follows changes to the target.
+
+### Fields
+
+- `href`: a list with one item, `[{ "@id": path or URL, "title": title }]`. Use a path for content from the site, or a full URL for an external link.
+- `overwrite`: use the teaser's own `title`, `description` and `preview_image` instead of the target's.
+- `preview_image`: only with `overwrite`. A list with one item, `[{ "@id": path, "image_field": "image" }]`; leave out `image_field` for an external image.
+- `styles.align`: `left`, `right` or `center`. Not used inside a grid, where the grid controls the layout.
+
+### Example
+
+```json
+{
+  "@type": "teaser",
+  "href": [
+    { "@id": "/news/annual-report-2025", "title": "Annual Report 2025" }
+  ]
+}
+```

plone_client/block_docs/title.md

@@ -0,0 +1,13 @@
+---
+block: title
+---
+
+Shows the title of the content item. It is part of the default layout of new pages, and a page normally has exactly one.
+
+The block stores no data of its own: the text it shows is the content item's `title` field, so change that field to change the title.
+
+### Example
+
+```json
+{ "@type": "title" }
+```

plone_client/block_docs/toc.md

@@ -0,0 +1,13 @@
+---
+block: toc
+---
+
+Shows a table of contents built from the headings on the page, so readers can jump to a section.
+
+It reads the headings of the page's text blocks when it renders, so it needs no content of its own. Its settings (title, heading levels, ordered list) are optional.
+
+### Example
+
+```json
+{ "@type": "toc" }
+```

plone_client/block_docs/video.md

@@ -0,0 +1,15 @@
+---
+block: video
+---
+
+Embeds a video from YouTube, Vimeo, PeerTube, or a direct link to a video file.
+
+### Fields
+
+- `url`: the video URL as you would share it, for example a YouTube watch or share link.
+
+### Example
+
+```json
+{ "@type": "video", "url": "https://youtu.be/n837R4emhns" }
+```