easyvista-python-client 0.4.2__tar.gz → 0.5.0__tar.gz

{easyvista_python_client-0.4.2 → easyvista_python_client-0.5.0}/CHANGELOG.md

@@ -15,6 +15,75 @@ is the error. Tags carry no `v` prefix.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-11-10
+
+Two more of the vendor's ticket requests, and a guard that names one more
+column. Neither new method takes a status: the package still has no status
+setter.
+
+### Added
+
+- **`suspend_ticket(rfc_number, *, allow_workflow_effect, comment=None,
+  done_by_id=None)`** and **`restart_ticket(...)`** (same signature), the
+  vendor's suspend and restart requests
+  ([suspend](https://docs.easyvista.com/docs/rest-api-suspend-an-incident-request.md),
+  [restart](https://docs.easyvista.com/docs/rest-api-reopen-an-incident-request.md)):
+  `PUT requests/{rfc_number}` with a `suspended` / `restarted` object. The guard
+  already named both bodies `WorkflowEffect.UNKNOWN`, so
+  `allow_workflow_effect` is a required keyword and the call is refused before
+  any request unless it includes `UNKNOWN`; an allowed request is sent once,
+  never retried. `comment` and `done_by_id` are left out of the body when
+  `None`. The return value is parsed as `close_ticket`'s is.
+
+### Changed
+
+- **BREAKING:** the workflow guard now names `STATUS_ID_ON_CREATE` on an
+  existing action (`update_action`, or `PUT actions/{id}` through `send`), as
+  it does `STATUS_ID_ON_TERMINATE`. A write that passed before is refused
+  without `allow_workflow_effect=WorkflowEffect.UNKNOWN`. Measured 2026-11-09
+  and 2026-11-10 on one instance (tier 4, may not generalise): a write to it
+  on an existing action changed where the ticket's status went. Creating an
+  action or a task is unchanged: the server overwrites the column on create.
+
+### Fixed
+
+- **The `reassign_action` documentation about `OWNING_GROUP_ID`.** It said the
+  ticket's owning group does not follow a reassigned step. Measured 2026-11-04
+  to 2026-11-10 on one instance (several tickets, may not generalise): it
+  follows after a few seconds to about two minutes (consistent with a
+  server-side job; inferred, not observed), and `LAST_UPDATE` moves with it;
+  the first reading was taken too soon. The status still does not move, the
+  step is not started and no action row is added.
+
+## [0.4.3] - 2026-10-08
+
+A patch release of the content reader: a caller can recognise the images a
+memo embeds and decide, link by link, what a read writes. Without the new
+argument a read is unchanged, byte for byte; writing is unchanged, and so is
+everything outside `easyvista_python_client.content`.
+
+### Added
+
+- **`from_transport(..., rewrite_link=callback)`.** The callback is called with
+  a `Link` for each link and image the read meets outside code -- an image
+  before the link around it, with that link's `enclosing_href` -- and its
+  answer is written: `None` keeps the reader's output, a `str` is written as
+  literal text, a `Link` replaces the target (an empty `href` drops a link and
+  keeps its content, or writes an image as its text). The callback is held in
+  a context variable, so concurrent reads each use their own. What it raises
+  reaches the caller unchanged; a `ValueError` is not taken for markdownify's
+  and answered with the text fallback.
+- **`Link` and `RewriteLink`**, exported from `easyvista_python_client.content`.
+- **`EasyvistaContentConverter.document_id_of(src)`** returns the
+  `DOCUMENT_ID` of an embedded image's `src`
+  (`@@EMBEDDED_IMAGE_PATH@@<DOCUMENT_ID>`, how EasyVista's editor embeds a
+  pasted image), and **`document_image(document_id, alt=...)`** the Markdown
+  of one, spelled as the reader spells it. A `Link` for such an image carries
+  its `document_id`. Measured on one instance on 2026-10-07: an image written
+  that way through the API displays, for an attachment pasted in the editor
+  and for one uploaded with `add_document`.
+- `EasyvistaContentConverter.EMBEDDED_IMAGE_PREFIX`.
+
 ## [0.4.2] - 2026-10-07
 
 A patch release of the content writer: a link written into a memo opens in a
@@ -1661,7 +1730,9 @@ Initial public release.
   status/error code, with non-retryable validation errors (HTTP 590, code 2013).
 - `py.typed` marker — the package ships inline type information.
 
-[Unreleased]: https://github.com/baraline/easyvista_python_client/compare/0.4.2...HEAD
+[Unreleased]: https://github.com/baraline/easyvista_python_client/compare/0.5.0...HEAD
+[0.5.0]: https://github.com/baraline/easyvista_python_client/compare/0.4.3...0.5.0
+[0.4.3]: https://github.com/baraline/easyvista_python_client/compare/0.4.2...0.4.3
 [0.4.2]: https://github.com/baraline/easyvista_python_client/compare/0.4.1...0.4.2
 [0.4.1]: https://github.com/baraline/easyvista_python_client/compare/0.4.0...0.4.1
 [0.4.0]: https://github.com/baraline/easyvista_python_client/compare/0.3.0...0.4.0

{easyvista_python_client-0.4.2 → easyvista_python_client-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: easyvista-python-client
-Version: 0.4.2
+Version: 0.5.0
 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 → easyvista_python_client-0.5.0}/docs/content.rst

@@ -234,6 +234,60 @@ reported as
 :class:`~easyvista_python_client.exceptions.EasyvistaContentError`. A block
 quote nested 100,000 levels deep rendered without one (measured 2026-10-02).
 
+Embedded images, and rewriting links as they are read
+-----------------------------------------------------
+
+EasyVista's editor keeps an image pasted into a memo as an attachment of the
+request, named like ``image_emb_001.png``, and embeds it as
+``<img src="@@EMBEDDED_IMAGE_PATH@@<DOCUMENT_ID>" />``. Without a callback the
+reader writes that as any other image, ``![](@@EMBEDDED_IMAGE_PATH@@...)``,
+which displays nowhere but in EasyVista. Three helpers let a caller do better.
+
+``EasyvistaContentConverter.document_id_of(src)`` returns the ``DOCUMENT_ID``
+an image's ``src`` embeds, or ``None``. ``document_image(document_id, alt=...)``
+returns the Markdown of such an image, spelled exactly as the reader spells
+it, so ``to_transport`` writes the editor's form and ``from_transport`` reads
+it back unchanged. **Tier 4** -- measured on one instance on 2026-10-07: an
+image written that way through the API displays, both for an attachment
+pasted in the editor and for one uploaded with ``add_document``. The memo
+displays it only while the attachment is on the same request.
+
+``from_transport(..., rewrite_link=callback)`` calls ``callback`` with a
+:class:`~easyvista_python_client.content.Link` for each link and each image it
+meets outside code, an image before the link around it. A ``Link`` carries the
+``href`` (an image's ``src``), the ``text`` (an image's ``alt``), the
+``title``, whether it is an ``image``, an embedded image's ``document_id``, and
+for an image inside a link that link's ``enclosing_href``. What the callback
+answers is written:
+
+* ``None``: what the reader writes without a callback;
+* a ``str``: that text, literally -- escaped as any text the memo displays, so
+  it cannot become markup;
+* a ``Link``: a link's ``href`` and ``title`` around the link's content as
+  read, or an image's ``href`` as its ``src``, ``text`` as its ``alt`` and
+  ``title``;
+* a ``Link`` with an empty ``href``: a link is dropped and its content kept, an
+  image is written as its ``text``.
+
+.. code-block:: python
+
+    from easyvista_python_client.content import EasyvistaContentConverter, Link
+
+    def name_attachments(link: Link) -> Link | str | None:
+        if link.document_id is not None:
+            return f"[attachment {link.document_id}]"
+        return None
+
+    EasyvistaContentConverter.from_transport(memo, rewrite_link=name_attachments)
+
+The callback is held for the duration of one read, per thread and per task,
+so concurrent reads each use their own, and a read inside a callback has its
+own too. What the callback raises reaches the caller unchanged -- a
+``ValueError`` included, which the reader would otherwise take for one of
+markdownify's and answer by reading the body as its text. An answer of any
+other type raises ``TypeError``. It is not called for a value passed through
+as Markdown (``plain_text_is_markdown=True``), nor for a body read as its text.
+
 It is not a sanitiser
 ---------------------
 

{easyvista_python_client-0.4.2 → easyvista_python_client-0.5.0}/docs/user_guide.rst

@@ -473,8 +473,9 @@ rule on your instance can run on any write.
 To escalate the open workflow step to another group without ending it, use
 :meth:`~easyvista_python_client.EasyvistaClient.reassign_action` (measured
 2026-10-02, one instance, so it may not generalise: the step stays open and the
-status does not move; the ticket's owning group, read on one ticket, did not
-follow).
+status does not move; measured 2026-11-04 to 2026-11-10, several tickets, the
+ticket's owning group follows the step's new group after a few seconds to about
+two minutes).
 
 Creating a ticket starts its workflow -- the vendor's create page lists "The
 workflow associated with the ticket is started." among what a create does (tier

{easyvista_python_client-0.4.2 → easyvista_python_client-0.5.0}/docs/vendor-api-reference.md

@@ -287,10 +287,16 @@ again five seconds later); the step **stayed open** (`END_DATE_UT` empty); the t
 status and `END_DATE_UT` **did not move**; the open actions were unchanged; and **no new
 action rows** appeared. On the **first ticket only** the step was recorded as a type-20
 action with `WORKFLOW_ID` set, its `WORKFLOW_ID` was unchanged, `DONE_BY_ID` stayed
-empty and no ticket field changed; and that is also the only ticket on which the
-ticket's own `OWNING_GROUP_ID` was read — it **stayed at the old group**, so the
-ticket's owning group did not follow the action's. Reassigning to a person
-(`done_by_id`) was **not measured**. Whether the UI wizard's notifications fire is not
+empty and no ticket field changed. The ticket's own `OWNING_GROUP_ID` was read on
+that ticket only, and had not moved; that reading was taken too soon. Measured
+2026-11-04 to 2026-11-10 on one instance (several tickets, may not generalise): the
+ticket's `OWNING_GROUP_ID` **follows the step's new group** after a delay of a few
+seconds to about two minutes (consistent with a server-side job; inferred, not
+observed), and `LAST_UPDATE` moves with it; the status still does not move, the step
+is not started and no action row is added. Also measured 2026-11-04 on one ticket:
+after `done_by_id` was written on the step, the ticket's `OWNER_ID` followed about
+1 min 45 s later. The person's effect on the step was not measured beyond that one
+`OWNER_ID` observation. Whether the UI wizard's notifications fire is not
 observable from the API.
 
 **Business rules can fire on any write** — "On Insert/On Update" of any record

{easyvista_python_client-0.4.2 → easyvista_python_client-0.5.0}/easyvista_python_client/_async/client.py

@@ -610,6 +610,99 @@ class AsyncEasyvistaClient:
         )
         return parse(await self._transport.send(spec.allowing(allow_workflow_effect)))
 
+    async def suspend_ticket(
+        self,
+        rfc_number: str,
+        *,
+        allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect],
+        comment: str | None = None,
+        done_by_id: int | None = None,
+    ) -> Request:
+        """Suspend a ticket -- the vendor's suspend request.
+
+        Sends ``PUT requests/{rfc}`` with a ``suspended`` body, as the vendor
+        documents it:
+        https://docs.easyvista.com/docs/rest-api-suspend-an-incident-request.md
+        (tier 1, re-read 2026-11-10). The page documents two optional
+        parameters, ``comment`` and ``done_by_id`` (an employee id), and no
+        target status. Both are left out of the body when ``None``. A ticket
+        that is already suspended is refused by the server (400, "The request
+        is already suspended. Operation aborted.").
+
+        Measured 2026-11-04 to 2026-11-10 on one instance (tier 4, may not
+        generalise): the ticket moved to the instance's suspended status and
+        one already-ended suspension action carrying the comment was added;
+        the workflow step stayed open. A status key sent in the body was
+        ignored (measured 2026-11-04). The request takes no status, and the
+        package has no status setter.
+
+        ``allow_workflow_effect`` is **required**: nothing documents what a
+        suspend does to the workflow, so the write is named
+        ``WorkflowEffect.UNKNOWN`` and refused with
+        :class:`~easyvista_python_client.EasyvistaWorkflowEffectRefused`
+        before any request is made unless the call allows it. The allowed
+        request is sent once, never retried. The return value is parsed like
+        :meth:`close_ticket`'s: the vendor answers 201 with an ``HREF`` only, so
+        re-read with :meth:`get_ticket` to see the status::
+
+            client.suspend_ticket(
+                rfc,
+                allow_workflow_effect=WorkflowEffect.UNKNOWN,
+                comment="Waiting for the requester",
+            )
+        """
+        spec, parse = requests_res.build_suspend_ticket(
+            rfc_number,
+            comment=comment,
+            done_by_id=done_by_id,
+            context=self._validation_context,
+        )
+        return parse(await self._transport.send(spec.allowing(allow_workflow_effect)))
+
+    async def restart_ticket(
+        self,
+        rfc_number: str,
+        *,
+        allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect],
+        comment: str | None = None,
+        done_by_id: int | None = None,
+    ) -> Request:
+        """Restart a suspended ticket -- the vendor's restart request.
+
+        Sends ``PUT requests/{rfc}`` with a ``restarted`` body, as the vendor
+        documents it:
+        https://docs.easyvista.com/docs/rest-api-reopen-an-incident-request.md
+        (tier 1, re-read 2026-11-10). The page documents two optional
+        parameters, ``comment`` and ``done_by_id`` (an employee id), and no
+        target status; its example marks ``comment`` as required while its
+        table lists it as optional, so this method leaves it out of the body
+        when ``None``. On a ticket that is not suspended the server answers
+        400 with "The request is not suspended. Operation aborted.".
+
+        Measured 2026-11-04 to 2026-11-10 on one instance (tier 4, may not
+        generalise): the request added one end-of-suspension action and, in
+        the tested case, returned the ticket to the status it was suspended
+        from; a restart on a ticket that was not suspended was refused with
+        the documented message, as HTTP 590 rather than the documented 400.
+        A status key sent in the body was ignored
+        (measured 2026-11-04). The request takes no status, and the package
+        has no status setter.
+
+        ``allow_workflow_effect`` is **required** and is
+        ``WorkflowEffect.UNKNOWN``, as for :meth:`suspend_ticket`: refused
+        before any request unless allowed, and sent once, never retried. The
+        return value is parsed like :meth:`close_ticket`'s (an ``HREF`` only)::
+
+            client.restart_ticket(rfc, allow_workflow_effect=WorkflowEffect.UNKNOWN)
+        """
+        spec, parse = requests_res.build_restart_ticket(
+            rfc_number,
+            comment=comment,
+            done_by_id=done_by_id,
+            context=self._validation_context,
+        )
+        return parse(await self._transport.send(spec.allowing(allow_workflow_effect)))
+
     # --- actions -------------------------------------------------------------
     async def create_action(
         self,
@@ -947,14 +1040,20 @@ class AsyncEasyvistaClient:
         the **first ticket only** the step was recorded as a type-20 action
         with ``WORKFLOW_ID`` set; its ``WORKFLOW_ID`` was unchanged,
         ``DONE_BY_ID`` stayed empty, and no ticket field changed.
-        **The ticket's own ``OWNING_GROUP_ID`` does not follow the action's
-        group** -- it stayed 57 on the first ticket, the only one read for it,
-        so reassigning a step is not reassigning the ticket. The lower-case
-        key ``group_id`` was the one sent; the upper-case spelling was never
-        needed. The person (``done_by_id``) was **not measured**: the same
-        body shape is sent, but nothing here shows what the instance does
-        with it. Whether the UI wizard's notifications fire is not observable
-        from the API.
+        The ticket's own ``OWNING_GROUP_ID`` was read at the time on one
+        ticket only and had not moved; that reading was taken too soon.
+        Measured 2026-11-04 to 2026-11-10 on one instance (several tickets,
+        may not generalise): the ticket's ``OWNING_GROUP_ID`` follows the
+        step's new group after a delay of a few seconds to about two minutes,
+        consistent with a server-side job (inferred, not observed), and
+        ``LAST_UPDATE`` moves with it. What still holds: the status does not
+        move, the step is not started and no action row is added. Also
+        measured 2026-11-04 on one ticket: after ``done_by_id`` was written on
+        the step, the ticket's ``OWNER_ID`` followed about 1 min 45 s later.
+        The lower-case key ``group_id`` was the one sent; the upper-case
+        spelling was never needed. The person's effect on the step was not
+        measured beyond that one ``OWNER_ID`` observation. Whether the UI
+        wizard's notifications fire is not observable from the API.
 
         Not refused by the workflow guard: the group and the person are data
         the workflow reads, not workflow state. Re-read with :meth:`get_action`

{easyvista_python_client-0.4.2 → easyvista_python_client-0.5.0}/easyvista_python_client/_sync/client.py

@@ -610,6 +610,99 @@ class EasyvistaClient:
         )
         return parse(self._transport.send(spec.allowing(allow_workflow_effect)))
 
+    def suspend_ticket(
+        self,
+        rfc_number: str,
+        *,
+        allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect],
+        comment: str | None = None,
+        done_by_id: int | None = None,
+    ) -> Request:
+        """Suspend a ticket -- the vendor's suspend request.
+
+        Sends ``PUT requests/{rfc}`` with a ``suspended`` body, as the vendor
+        documents it:
+        https://docs.easyvista.com/docs/rest-api-suspend-an-incident-request.md
+        (tier 1, re-read 2026-11-10). The page documents two optional
+        parameters, ``comment`` and ``done_by_id`` (an employee id), and no
+        target status. Both are left out of the body when ``None``. A ticket
+        that is already suspended is refused by the server (400, "The request
+        is already suspended. Operation aborted.").
+
+        Measured 2026-11-04 to 2026-11-10 on one instance (tier 4, may not
+        generalise): the ticket moved to the instance's suspended status and
+        one already-ended suspension action carrying the comment was added;
+        the workflow step stayed open. A status key sent in the body was
+        ignored (measured 2026-11-04). The request takes no status, and the
+        package has no status setter.
+
+        ``allow_workflow_effect`` is **required**: nothing documents what a
+        suspend does to the workflow, so the write is named
+        ``WorkflowEffect.UNKNOWN`` and refused with
+        :class:`~easyvista_python_client.EasyvistaWorkflowEffectRefused`
+        before any request is made unless the call allows it. The allowed
+        request is sent once, never retried. The return value is parsed like
+        :meth:`close_ticket`'s: the vendor answers 201 with an ``HREF`` only, so
+        re-read with :meth:`get_ticket` to see the status::
+
+            client.suspend_ticket(
+                rfc,
+                allow_workflow_effect=WorkflowEffect.UNKNOWN,
+                comment="Waiting for the requester",
+            )
+        """
+        spec, parse = requests_res.build_suspend_ticket(
+            rfc_number,
+            comment=comment,
+            done_by_id=done_by_id,
+            context=self._validation_context,
+        )
+        return parse(self._transport.send(spec.allowing(allow_workflow_effect)))
+
+    def restart_ticket(
+        self,
+        rfc_number: str,
+        *,
+        allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect],
+        comment: str | None = None,
+        done_by_id: int | None = None,
+    ) -> Request:
+        """Restart a suspended ticket -- the vendor's restart request.
+
+        Sends ``PUT requests/{rfc}`` with a ``restarted`` body, as the vendor
+        documents it:
+        https://docs.easyvista.com/docs/rest-api-reopen-an-incident-request.md
+        (tier 1, re-read 2026-11-10). The page documents two optional
+        parameters, ``comment`` and ``done_by_id`` (an employee id), and no
+        target status; its example marks ``comment`` as required while its
+        table lists it as optional, so this method leaves it out of the body
+        when ``None``. On a ticket that is not suspended the server answers
+        400 with "The request is not suspended. Operation aborted.".
+
+        Measured 2026-11-04 to 2026-11-10 on one instance (tier 4, may not
+        generalise): the request added one end-of-suspension action and, in
+        the tested case, returned the ticket to the status it was suspended
+        from; a restart on a ticket that was not suspended was refused with
+        the documented message, as HTTP 590 rather than the documented 400.
+        A status key sent in the body was ignored
+        (measured 2026-11-04). The request takes no status, and the package
+        has no status setter.
+
+        ``allow_workflow_effect`` is **required** and is
+        ``WorkflowEffect.UNKNOWN``, as for :meth:`suspend_ticket`: refused
+        before any request unless allowed, and sent once, never retried. The
+        return value is parsed like :meth:`close_ticket`'s (an ``HREF`` only)::
+
+            client.restart_ticket(rfc, allow_workflow_effect=WorkflowEffect.UNKNOWN)
+        """
+        spec, parse = requests_res.build_restart_ticket(
+            rfc_number,
+            comment=comment,
+            done_by_id=done_by_id,
+            context=self._validation_context,
+        )
+        return parse(self._transport.send(spec.allowing(allow_workflow_effect)))
+
     # --- actions -------------------------------------------------------------
     def create_action(
         self,
@@ -947,14 +1040,20 @@ class EasyvistaClient:
         the **first ticket only** the step was recorded as a type-20 action
         with ``WORKFLOW_ID`` set; its ``WORKFLOW_ID`` was unchanged,
         ``DONE_BY_ID`` stayed empty, and no ticket field changed.
-        **The ticket's own ``OWNING_GROUP_ID`` does not follow the action's
-        group** -- it stayed 57 on the first ticket, the only one read for it,
-        so reassigning a step is not reassigning the ticket. The lower-case
-        key ``group_id`` was the one sent; the upper-case spelling was never
-        needed. The person (``done_by_id``) was **not measured**: the same
-        body shape is sent, but nothing here shows what the instance does
-        with it. Whether the UI wizard's notifications fire is not observable
-        from the API.
+        The ticket's own ``OWNING_GROUP_ID`` was read at the time on one
+        ticket only and had not moved; that reading was taken too soon.
+        Measured 2026-11-04 to 2026-11-10 on one instance (several tickets,
+        may not generalise): the ticket's ``OWNING_GROUP_ID`` follows the
+        step's new group after a delay of a few seconds to about two minutes,
+        consistent with a server-side job (inferred, not observed), and
+        ``LAST_UPDATE`` moves with it. What still holds: the status does not
+        move, the step is not started and no action row is added. Also
+        measured 2026-11-04 on one ticket: after ``done_by_id`` was written on
+        the step, the ticket's ``OWNER_ID`` followed about 1 min 45 s later.
+        The lower-case key ``group_id`` was the one sent; the upper-case
+        spelling was never needed. The person's effect on the step was not
+        measured beyond that one ``OWNER_ID`` observation. Whether the UI
+        wizard's notifications fire is not observable from the API.
 
         Not refused by the workflow guard: the group and the person are data
         the workflow reads, not workflow state. Re-read with :meth:`get_action`

{easyvista_python_client-0.4.2 → easyvista_python_client-0.5.0}/easyvista_python_client/_version.py

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

{easyvista_python_client-0.4.2 → easyvista_python_client-0.5.0}/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"]