easyvista-python-client 0.4.2__py3-none-any.whl → 0.4.3__py3-none-any.whl

easyvista_python_client/_version.py

@@ -5,4 +5,4 @@
 live only in ``__init__``.
 """
 
-__version__ = "0.4.2"
+__version__ = "0.4.3"

easyvista_python_client/content/__init__.py

@@ -13,6 +13,10 @@ stack left to report it otherwise (see ``docs/content.rst``).
 
 from __future__ import annotations
 
-from easyvista_python_client.content.conversion import EasyvistaContentConverter
+from easyvista_python_client.content.conversion import (
+    EasyvistaContentConverter,
+    Link,
+    RewriteLink,
+)
 
-__all__ = ["EasyvistaContentConverter"]
+__all__ = ["EasyvistaContentConverter", "Link", "RewriteLink"]

easyvista_python_client/content/conversion.py

@@ -59,9 +59,11 @@ import re
 import string
 import unicodedata
 from collections.abc import Callable, Iterator, Mapping, MutableMapping, Sequence
+from contextvars import ContextVar
+from dataclasses import dataclass
 from functools import cached_property
 from html import escape, unescape
-from typing import Any, cast
+from typing import Any, ClassVar, cast
 
 from easyvista_python_client.exceptions import EasyvistaContentError
 
@@ -396,6 +398,97 @@ def _title(title: str) -> str:
     return ' "' + re.sub(r'[\\"]', r"\\\g<0>", title) + '"' if title else ""
 
 
+#: How a memo embeds an image: EasyVista's editor stores a pasted image as an
+#: attachment of the request and writes ``<img src="@@EMBEDDED_IMAGE_PATH@@...">``
+#: with that attachment's ``DOCUMENT_ID``. Measured 2026-10-07 on one instance
+#: (tier 4): an image written that way through the API displays too, for an
+#: attachment pasted in the editor and for one uploaded with ``add_document``.
+EMBEDDED_IMAGE_PREFIX = "@@EMBEDDED_IMAGE_PATH@@"
+
+#: A ``DOCUMENT_ID``, as an embedded image's ``src`` carries one. Measured: 40 hex
+#: digits for an image pasted in the editor, an account number, ``_`` and 64 hex
+#: digits for a file uploaded through the API. The class is wider than both.
+_DOCUMENT_ID = re.compile(r"[A-Za-z0-9_.-]{1,128}")
+
+
+@dataclass(frozen=True, slots=True)
+class Link:
+    """A link or an image the reader meets, as a ``rewrite_link`` callback sees it.
+
+    Attributes
+    ----------
+    href : str
+        An ``<a>``'s ``href`` or an ``<img>``'s ``src``, character references
+        decoded.
+    text : str
+        An ``<a>``'s displayed text or an ``<img>``'s ``alt``, whitespace
+        collapsed.
+    title : str
+        The ``title``, or ``""``.
+    image : bool
+        ``True`` for an ``<img>``.
+    document_id : str or None
+        For an ``<img>`` embedding an attachment of the request
+        (:data:`EMBEDDED_IMAGE_PREFIX` and a ``DOCUMENT_ID``), that
+        ``DOCUMENT_ID``; ``None`` otherwise, and always for an ``<a>``.
+    enclosing_href : str or None
+        For an ``<img>`` inside a link, that link's ``href``; ``None``
+        otherwise. The image is read before the link around it.
+    """
+
+    href: str
+    text: str = ""
+    title: str = ""
+    image: bool = False
+    document_id: str | None = None
+    enclosing_href: str | None = None
+
+
+#: A ``rewrite_link`` callback: called with each link and image a read meets,
+#: outside code. ``None`` keeps what the reader writes without one. A ``str`` is
+#: written instead, as literal text. A :class:`Link` is written in the reader's
+#: own spelling: a link's ``href`` and ``title``, around the link's content as
+#: read; an image's ``href`` as its ``src``, ``text`` as its ``alt`` and
+#: ``title``. An empty ``href`` drops a link and keeps its content, and writes an
+#: image as its ``text``.
+RewriteLink = Callable[[Link], "Link | str | None"]
+
+_REWRITE: ContextVar[RewriteLink | None] = ContextVar("rewrite_link", default=None)
+"""The callback of the read in progress. A context variable rather than state
+on the shared converter: each thread and each task reads with its own."""
+
+
+class _CallbackRaised(Exception):
+    """What a ``rewrite_link`` callback raised, carried past the reader's fallbacks.
+
+    The reader answers a ``ValueError`` by reading the body as its text; a
+    callback's own ``ValueError`` must not pass for markdownify's and quietly
+    cost the body its formatting.
+    """
+
+    def __init__(self, error: Exception) -> None:
+        super().__init__(error)
+        self.error = error
+
+
+def _rewritten(link: Link) -> Link | str | None:
+    """Ask the read's callback about ``link``; ``None`` when there is none."""
+
+    rewrite = _REWRITE.get()
+    if rewrite is None:
+        return None
+    try:
+        answer: object = rewrite(link)  # typed as what it is, not what it should be
+    except Exception as exc:
+        raise _CallbackRaised(exc) from exc
+    if answer is None or isinstance(answer, (Link, str)):
+        return answer
+    error = TypeError(
+        f"rewrite_link returned {type(answer).__name__}; expected Link, str or None"
+    )
+    raise _CallbackRaised(error)
+
+
 class _Converter(MarkdownConverter):
     """``markdownify``, with what CommonMark and the reader's glue need on top.
 
@@ -553,15 +646,27 @@ class _Converter(MarkdownConverter):
         body, _, tail = rest.rpartition("```")
         return f"{head}{fence}{body}{fence}{tail}"
 
+    def _literal(self, text: str, parent_tags: set[str]) -> str:
+        """``text`` escaped as the reader escapes a text node: displayed as it is."""
+
+        return self.escape(" ".join(text.split()), parent_tags)
+
     def convert_a(self, el: Tag, text: str, parent_tags: set[str]) -> str:
         """A link; ``<url>`` when its text is its URL and reads back unchanged."""
 
+        if "_noformat" in parent_tags:
+            return text
         href = str(el.get("href") or "")
+        title = str(el.get("title") or "")
+        answer = _rewritten(Link(href, " ".join(el.get_text().split()), title))
+        if isinstance(answer, str):
+            return self._literal(answer, parent_tags)
+        if answer is not None:
+            href, title = answer.href, answer.title
         edges = _EDGES.fullmatch(text)
-        if "_noformat" in parent_tags or not href or edges is None or not edges[2]:
+        if not href or edges is None or not edges[2]:
             return text
         before, inner, after = edges.groups()
-        title = str(el.get("title") or "")
         if not title and el.get_text() == href and _AUTOLINK.fullmatch(href):
             return f"{before}<{href}>{after}"
         return f"{before}[{inner}]({_destination(href)}{_title(title)}){after}"
@@ -569,12 +674,38 @@ class _Converter(MarkdownConverter):
     def convert_img(self, el: Tag, text: str, parent_tags: set[str]) -> str:
         """An image, wherever it is: a cell or a heading holds one too."""
 
+        src = str(el.get("src") or "")
         alt = " ".join(str(el.get("alt") or "").split())
+        title = str(el.get("title") or "")
+        if "_noformat" not in parent_tags:
+            embedded = EasyvistaContentConverter.document_id_of(src)
+            around = el.find_parent("a")
+            answer = _rewritten(
+                Link(
+                    src,
+                    alt,
+                    title,
+                    image=True,
+                    document_id=embedded,
+                    enclosing_href=(
+                        None if around is None else str(around.get("href") or "")
+                    ),
+                )
+            )
+            if isinstance(answer, str):
+                return self._literal(answer, parent_tags)
+            if answer is not None and not answer.href:
+                return self._literal(answer.text, parent_tags)
+            if answer is not None:
+                src, alt, title = (
+                    answer.href,
+                    " ".join(answer.text.split()),
+                    answer.title,
+                )
         alt = str(self._inherited("escape")(alt, parent_tags))
         if alt.startswith("^") and "_noformat" not in parent_tags:
             alt = "\\" + alt  # cmark-gfm reads "![^" as "!" and a link
-        src = _destination(str(el.get("src") or ""))
-        return f"![{alt}]({src}{_title(str(el.get('title') or ''))})"
+        return f"![{alt}]({_destination(src)}{_title(title)})"
 
 
 class _Node(RenderTreeNode):
@@ -784,11 +915,41 @@ def _text_of(html: str) -> str:
     return "\n".join(line for line in lines if line)
 
 
+def _converted(content: str) -> str:
+    """Read memo HTML, falling back to its text where the conversion cannot."""
+
+    try:
+        try:
+            return html_to_markdown(content)
+        except (RecursionError, ValueError):  # ValueError: markdownify's
+            # int() of a colspan or start such as "²" or 5,000 digits
+            return html_to_markdown(_plain_text_html(_text_of(content)))
+        except ParserRejectedMarkup:
+            # html.parser gives up on a few malformed declarations; the
+            # body's words are still worth more than an exception.
+            text = unescape(_ANY_TAG.sub(" ", content))
+            return html_to_markdown(_plain_text_html(" ".join(text.split())))
+    except _CallbackRaised:
+        raise
+    except Exception as exc:
+        raise EasyvistaContentError(
+            "Could not convert EasyVista memo HTML to Markdown "
+            f"({type(exc).__name__}: {exc})."
+        ) from exc
+
+
 class EasyvistaContentConverter:
     """Convert content between EasyVista memo HTML and canonical Markdown."""
 
+    EMBEDDED_IMAGE_PREFIX: ClassVar[str] = EMBEDDED_IMAGE_PREFIX
+
     @staticmethod
-    def from_transport(value: object, *, plain_text_is_markdown: bool = False) -> str:
+    def from_transport(
+        value: object,
+        *,
+        plain_text_is_markdown: bool = False,
+        rewrite_link: RewriteLink | None = None,
+    ) -> str:
         """Convert one EasyVista memo value into Markdown.
 
         Parameters
@@ -806,6 +967,12 @@ class EasyvistaContentConverter:
             ``<kbd>`` is still Markdown, but Markdown that opens with an
             autolink or other angle-bracketed text and carries inline HTML
             further on is read as HTML, and loses that autolink.
+        rewrite_link : callable, optional
+            Called with a :class:`Link` for each link and image the read
+            meets outside code, an image before the link around it; its
+            answer decides what is written (:data:`RewriteLink`). Not called
+            for a value passed through as Markdown, nor for a body read as
+            its text. Without one, the read is what it always was.
 
         Returns
         -------
@@ -825,6 +992,10 @@ class EasyvistaContentConverter:
             limit, where no stack is left even to report the failure as
             ``EasyvistaContentError`` (``docs/content.rst`` gives the
             measured depths).
+        Exception
+            Whatever ``rewrite_link`` raised, unchanged; ``TypeError`` when it
+            answered something other than a :class:`Link`, a ``str`` or
+            ``None``.
         """
 
         content = str(value or "").strip()
@@ -840,22 +1011,65 @@ class EasyvistaContentConverter:
         # 3.11.14/3.12.12/3.13.6 rescans to the end for each (quadratic).
         head, end, tail = content.rpartition(">")
         content = head + end + tail.replace("<", "&lt;")
+        token = _REWRITE.set(rewrite_link)
         try:
-            try:
-                return html_to_markdown(content)
-            except (RecursionError, ValueError):  # ValueError: markdownify's
-                # int() of a colspan or start such as "²" or 5,000 digits
-                return html_to_markdown(_plain_text_html(_text_of(content)))
-            except ParserRejectedMarkup:
-                # html.parser gives up on a few malformed declarations; the
-                # body's words are still worth more than an exception.
-                text = unescape(_ANY_TAG.sub(" ", content))
-                return html_to_markdown(_plain_text_html(" ".join(text.split())))
-        except Exception as exc:
-            raise EasyvistaContentError(
-                "Could not convert EasyVista memo HTML to Markdown "
-                f"({type(exc).__name__}: {exc})."
-            ) from exc
+            return _converted(content)
+        except _CallbackRaised as raised:
+            callback_error = raised.error
+        finally:
+            _REWRITE.reset(token)
+        raise callback_error  # outside the handler: the callback's, as it raised it
+
+    @staticmethod
+    def document_id_of(src: str) -> str | None:
+        """Return the ``DOCUMENT_ID`` an embedded image's ``src`` names.
+
+        ``None`` unless ``src`` is exactly :data:`EMBEDDED_IMAGE_PREFIX`
+        followed by a ``DOCUMENT_ID`` -- how EasyVista's editor refers to an
+        image pasted into a memo, which it keeps as an attachment of the
+        request.
+        """
+
+        if not src.startswith(EMBEDDED_IMAGE_PREFIX):
+            return None
+        document_id = src[len(EMBEDDED_IMAGE_PREFIX) :]
+        return document_id if _DOCUMENT_ID.fullmatch(document_id) else None
+
+    @staticmethod
+    def document_image(document_id: str, *, alt: str = "") -> str:
+        """Return the Markdown of an image embedding one of the request's attachments.
+
+        :meth:`to_transport` renders it as EasyVista's editor writes a pasted
+        image, ``<img src="@@EMBEDDED_IMAGE_PATH@@<document_id>" alt="..." />``,
+        and :meth:`from_transport` reads that back as this same Markdown: it
+        is spelled by the reader itself. The memo displays the image once the
+        attachment is on the same request.
+
+        Parameters
+        ----------
+        document_id : str
+            The attachment's ``DOCUMENT_ID``, as ``list_documents`` gives it.
+        alt : str, optional
+            The image's alternative text.
+
+        Raises
+        ------
+        ValueError
+            ``document_id`` is not one: empty, or holding a character no
+            ``DOCUMENT_ID`` has.
+        """
+
+        if not _DOCUMENT_ID.fullmatch(document_id):
+            raise ValueError(f"not an EasyVista DOCUMENT_ID: {document_id!r}")
+        native = (
+            f'<p><img src="{EMBEDDED_IMAGE_PREFIX}{document_id}" '
+            f'alt="{escape(" ".join(alt.split()))}" /></p>'
+        )
+        token = _REWRITE.set(None)  # a callback in force for an enclosing read
+        try:
+            return html_to_markdown(native)
+        finally:
+            _REWRITE.reset(token)
 
     @staticmethod
     def to_transport(value: object) -> str:

{easyvista_python_client-0.4.2.dist-info → easyvista_python_client-0.4.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: easyvista-python-client
-Version: 0.4.2
+Version: 0.4.3
 Summary: Typed Python client for the EasyVista Service Manager REST API
 Project-URL: Homepage, https://github.com/baraline/easyvista_python_client
 Project-URL: Documentation, https://easyvista-python-client.readthedocs.io/en/latest/

{easyvista_python_client-0.4.2.dist-info → easyvista_python_client-0.4.3.dist-info}/RECORD

@@ -2,7 +2,7 @@ easyvista_python_client/__init__.py,sha256=AkPNxN1iaQhprPYShcqCEx03b0d4qi6b98MCF
 easyvista_python_client/_fields.py,sha256=L-9niigMP6vAMLR1rhY0KpmY0Zo_FeTkROr3dYd_Qwo,2164
 easyvista_python_client/_html.py,sha256=KftxdX4vHptQrOMqfWM-9I3g03UAA5YRmqwnLjI2Ir4,1276
 easyvista_python_client/_transport.py,sha256=AZItqLNOfgj1qTfC0ajxiKOPxXGnh7S0mGJE7VilfLU,3034
-easyvista_python_client/_version.py,sha256=Qs1bD7HLZeviaRaWtnZfFdMaFFMcmAU9-o4uKWhIj2E,290
+easyvista_python_client/_version.py,sha256=wQ7sg-msBHn48e4NjY2ZXTaUNRKk4_KX05NpEw71eNs,290
 easyvista_python_client/config.py,sha256=Zdzv2GB7Hma-z6RiR0820l4KPFn_EZxfmuQrS4RYlek,12361
 easyvista_python_client/context.py,sha256=_5PEjH4a2jM8Ks51YEes--CESt1vBXlK87y0s8UutHQ,13597
 easyvista_python_client/directory.py,sha256=BD44sgJgAAhcz2d0Eyqpv4fjdc9HCustI_izR4qwoyo,7820
@@ -24,8 +24,8 @@ easyvista_python_client/_sync/__init__.py,sha256=TKnndsi6v7S43so4X6fg_hZy3wg45Jk
 easyvista_python_client/_sync/_concurrency.py,sha256=zeCtzdrMQa9thzdV6A5sdP8Ojojgjkhbx6X8pH7qWGw,1750
 easyvista_python_client/_sync/_transport.py,sha256=JwEclG90LO9wrPxv1aEy8sQxHbeWVyyi61oEy4zsHx8,27537
 easyvista_python_client/_sync/client.py,sha256=I7H999YpssGhGozMo7Dxu4qkkfTMKzJjAHvR8fEyyC8,117586
-easyvista_python_client/content/__init__.py,sha256=Bqf40LdL00OyOfq0IqR5uBSEBL1QKvVwll8u4dQ0lW0,878
-easyvista_python_client/content/conversion.py,sha256=LFkNnKHJfsHEhcHwANYDMnKSX0Q9POan84lbxGiFj_M,35249
+easyvista_python_client/content/__init__.py,sha256=9_b5Dl9wnsoFuEmnBMfPn-jvypMydePVMe37PuY9zYA,937
+easyvista_python_client/content/conversion.py,sha256=NUzSUawBwBYkIoGTSTPX7__rCgGjJcZF8jQwGjVqSbU,43559
 easyvista_python_client/models/__init__.py,sha256=dCN1GPDWqu5zraEuGiCZaUGXyNQiK3yCuAC18Fh6NL4,47
 easyvista_python_client/models/action.py,sha256=m-R_n9S89yq3acjXsBM7FY05edW4jH97YIw5B-VG6zI,33405
 easyvista_python_client/models/asset.py,sha256=_cKeGOORSSLbqvXf_rQ2K00KM6K4DJdnqDvvhg7rhAg,2047
@@ -44,7 +44,7 @@ easyvista_python_client/resources/discovery.py,sha256=2XKV_sfP8Evlb_aDc4gi-aP-W3
 easyvista_python_client/resources/documents.py,sha256=FUfRDeAJu1qF9MvqLFwRtkxJvBC85SGEuoO85n_Qupk,6526
 easyvista_python_client/resources/employees.py,sha256=7X_hTRnk7T-GMNldDANmdnv2TgFZCfhIwgz7-PEDKaY,1790
 easyvista_python_client/resources/requests.py,sha256=qNksnO6RST6smHnT9eEkSbxR0iHXrW-ADkM3J_oQ4To,5380
-easyvista_python_client-0.4.2.dist-info/METADATA,sha256=jwB2EAUsFzBnTfCbdZJjiT9-dulWiPS3R-PhgABBTDk,13094
-easyvista_python_client-0.4.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-easyvista_python_client-0.4.2.dist-info/licenses/LICENSE,sha256=COAKFzPjsNCUJS82NnwBj20wPEHE34Dl8GzGZzaQWR0,1093
-easyvista_python_client-0.4.2.dist-info/RECORD,,
+easyvista_python_client-0.4.3.dist-info/METADATA,sha256=5aSLy5ONU6vdmMr2YwDCpZ9K7rG9wzIYdcLgxhtAQi8,13094
+easyvista_python_client-0.4.3.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+easyvista_python_client-0.4.3.dist-info/licenses/LICENSE,sha256=COAKFzPjsNCUJS82NnwBj20wPEHE34Dl8GzGZzaQWR0,1093
+easyvista_python_client-0.4.3.dist-info/RECORD,,