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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -610,6 +610,99 @@ class AsyncEasyvistaClient:
610
610
  )
611
611
  return parse(await self._transport.send(spec.allowing(allow_workflow_effect)))
612
612
 
613
+ async def suspend_ticket(
614
+ self,
615
+ rfc_number: str,
616
+ *,
617
+ allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect],
618
+ comment: str | None = None,
619
+ done_by_id: int | None = None,
620
+ ) -> Request:
621
+ """Suspend a ticket -- the vendor's suspend request.
622
+
623
+ Sends ``PUT requests/{rfc}`` with a ``suspended`` body, as the vendor
624
+ documents it:
625
+ https://docs.easyvista.com/docs/rest-api-suspend-an-incident-request.md
626
+ (tier 1, re-read 2026-11-10). The page documents two optional
627
+ parameters, ``comment`` and ``done_by_id`` (an employee id), and no
628
+ target status. Both are left out of the body when ``None``. A ticket
629
+ that is already suspended is refused by the server (400, "The request
630
+ is already suspended. Operation aborted.").
631
+
632
+ Measured 2026-11-04 to 2026-11-10 on one instance (tier 4, may not
633
+ generalise): the ticket moved to the instance's suspended status and
634
+ one already-ended suspension action carrying the comment was added;
635
+ the workflow step stayed open. A status key sent in the body was
636
+ ignored (measured 2026-11-04). The request takes no status, and the
637
+ package has no status setter.
638
+
639
+ ``allow_workflow_effect`` is **required**: nothing documents what a
640
+ suspend does to the workflow, so the write is named
641
+ ``WorkflowEffect.UNKNOWN`` and refused with
642
+ :class:`~easyvista_python_client.EasyvistaWorkflowEffectRefused`
643
+ before any request is made unless the call allows it. The allowed
644
+ request is sent once, never retried. The return value is parsed like
645
+ :meth:`close_ticket`'s: the vendor answers 201 with an ``HREF`` only, so
646
+ re-read with :meth:`get_ticket` to see the status::
647
+
648
+ client.suspend_ticket(
649
+ rfc,
650
+ allow_workflow_effect=WorkflowEffect.UNKNOWN,
651
+ comment="Waiting for the requester",
652
+ )
653
+ """
654
+ spec, parse = requests_res.build_suspend_ticket(
655
+ rfc_number,
656
+ comment=comment,
657
+ done_by_id=done_by_id,
658
+ context=self._validation_context,
659
+ )
660
+ return parse(await self._transport.send(spec.allowing(allow_workflow_effect)))
661
+
662
+ async def restart_ticket(
663
+ self,
664
+ rfc_number: str,
665
+ *,
666
+ allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect],
667
+ comment: str | None = None,
668
+ done_by_id: int | None = None,
669
+ ) -> Request:
670
+ """Restart a suspended ticket -- the vendor's restart request.
671
+
672
+ Sends ``PUT requests/{rfc}`` with a ``restarted`` body, as the vendor
673
+ documents it:
674
+ https://docs.easyvista.com/docs/rest-api-reopen-an-incident-request.md
675
+ (tier 1, re-read 2026-11-10). The page documents two optional
676
+ parameters, ``comment`` and ``done_by_id`` (an employee id), and no
677
+ target status; its example marks ``comment`` as required while its
678
+ table lists it as optional, so this method leaves it out of the body
679
+ when ``None``. On a ticket that is not suspended the server answers
680
+ 400 with "The request is not suspended. Operation aborted.".
681
+
682
+ Measured 2026-11-04 to 2026-11-10 on one instance (tier 4, may not
683
+ generalise): the request added one end-of-suspension action and, in
684
+ the tested case, returned the ticket to the status it was suspended
685
+ from; a restart on a ticket that was not suspended was refused with
686
+ the documented message, as HTTP 590 rather than the documented 400.
687
+ A status key sent in the body was ignored
688
+ (measured 2026-11-04). The request takes no status, and the package
689
+ has no status setter.
690
+
691
+ ``allow_workflow_effect`` is **required** and is
692
+ ``WorkflowEffect.UNKNOWN``, as for :meth:`suspend_ticket`: refused
693
+ before any request unless allowed, and sent once, never retried. The
694
+ return value is parsed like :meth:`close_ticket`'s (an ``HREF`` only)::
695
+
696
+ client.restart_ticket(rfc, allow_workflow_effect=WorkflowEffect.UNKNOWN)
697
+ """
698
+ spec, parse = requests_res.build_restart_ticket(
699
+ rfc_number,
700
+ comment=comment,
701
+ done_by_id=done_by_id,
702
+ context=self._validation_context,
703
+ )
704
+ return parse(await self._transport.send(spec.allowing(allow_workflow_effect)))
705
+
613
706
  # --- actions -------------------------------------------------------------
614
707
  async def create_action(
615
708
  self,
@@ -947,14 +1040,20 @@ class AsyncEasyvistaClient:
947
1040
  the **first ticket only** the step was recorded as a type-20 action
948
1041
  with ``WORKFLOW_ID`` set; its ``WORKFLOW_ID`` was unchanged,
949
1042
  ``DONE_BY_ID`` stayed empty, and no ticket field changed.
950
- **The ticket's own ``OWNING_GROUP_ID`` does not follow the action's
951
- group** -- it stayed 57 on the first ticket, the only one read for it,
952
- so reassigning a step is not reassigning the ticket. The lower-case
953
- key ``group_id`` was the one sent; the upper-case spelling was never
954
- needed. The person (``done_by_id``) was **not measured**: the same
955
- body shape is sent, but nothing here shows what the instance does
956
- with it. Whether the UI wizard's notifications fire is not observable
957
- from the API.
1043
+ The ticket's own ``OWNING_GROUP_ID`` was read at the time on one
1044
+ ticket only and had not moved; that reading was taken too soon.
1045
+ Measured 2026-11-04 to 2026-11-10 on one instance (several tickets,
1046
+ may not generalise): the ticket's ``OWNING_GROUP_ID`` follows the
1047
+ step's new group after a delay of a few seconds to about two minutes,
1048
+ consistent with a server-side job (inferred, not observed), and
1049
+ ``LAST_UPDATE`` moves with it. What still holds: the status does not
1050
+ move, the step is not started and no action row is added. Also
1051
+ measured 2026-11-04 on one ticket: after ``done_by_id`` was written on
1052
+ the step, the ticket's ``OWNER_ID`` followed about 1 min 45 s later.
1053
+ The lower-case key ``group_id`` was the one sent; the upper-case
1054
+ spelling was never needed. The person's effect on the step was not
1055
+ measured beyond that one ``OWNER_ID`` observation. Whether the UI
1056
+ wizard's notifications fire is not observable from the API.
958
1057
 
959
1058
  Not refused by the workflow guard: the group and the person are data
960
1059
  the workflow reads, not workflow state. Re-read with :meth:`get_action`
@@ -610,6 +610,99 @@ class EasyvistaClient:
610
610
  )
611
611
  return parse(self._transport.send(spec.allowing(allow_workflow_effect)))
612
612
 
613
+ def suspend_ticket(
614
+ self,
615
+ rfc_number: str,
616
+ *,
617
+ allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect],
618
+ comment: str | None = None,
619
+ done_by_id: int | None = None,
620
+ ) -> Request:
621
+ """Suspend a ticket -- the vendor's suspend request.
622
+
623
+ Sends ``PUT requests/{rfc}`` with a ``suspended`` body, as the vendor
624
+ documents it:
625
+ https://docs.easyvista.com/docs/rest-api-suspend-an-incident-request.md
626
+ (tier 1, re-read 2026-11-10). The page documents two optional
627
+ parameters, ``comment`` and ``done_by_id`` (an employee id), and no
628
+ target status. Both are left out of the body when ``None``. A ticket
629
+ that is already suspended is refused by the server (400, "The request
630
+ is already suspended. Operation aborted.").
631
+
632
+ Measured 2026-11-04 to 2026-11-10 on one instance (tier 4, may not
633
+ generalise): the ticket moved to the instance's suspended status and
634
+ one already-ended suspension action carrying the comment was added;
635
+ the workflow step stayed open. A status key sent in the body was
636
+ ignored (measured 2026-11-04). The request takes no status, and the
637
+ package has no status setter.
638
+
639
+ ``allow_workflow_effect`` is **required**: nothing documents what a
640
+ suspend does to the workflow, so the write is named
641
+ ``WorkflowEffect.UNKNOWN`` and refused with
642
+ :class:`~easyvista_python_client.EasyvistaWorkflowEffectRefused`
643
+ before any request is made unless the call allows it. The allowed
644
+ request is sent once, never retried. The return value is parsed like
645
+ :meth:`close_ticket`'s: the vendor answers 201 with an ``HREF`` only, so
646
+ re-read with :meth:`get_ticket` to see the status::
647
+
648
+ client.suspend_ticket(
649
+ rfc,
650
+ allow_workflow_effect=WorkflowEffect.UNKNOWN,
651
+ comment="Waiting for the requester",
652
+ )
653
+ """
654
+ spec, parse = requests_res.build_suspend_ticket(
655
+ rfc_number,
656
+ comment=comment,
657
+ done_by_id=done_by_id,
658
+ context=self._validation_context,
659
+ )
660
+ return parse(self._transport.send(spec.allowing(allow_workflow_effect)))
661
+
662
+ def restart_ticket(
663
+ self,
664
+ rfc_number: str,
665
+ *,
666
+ allow_workflow_effect: WorkflowEffect | Iterable[WorkflowEffect],
667
+ comment: str | None = None,
668
+ done_by_id: int | None = None,
669
+ ) -> Request:
670
+ """Restart a suspended ticket -- the vendor's restart request.
671
+
672
+ Sends ``PUT requests/{rfc}`` with a ``restarted`` body, as the vendor
673
+ documents it:
674
+ https://docs.easyvista.com/docs/rest-api-reopen-an-incident-request.md
675
+ (tier 1, re-read 2026-11-10). The page documents two optional
676
+ parameters, ``comment`` and ``done_by_id`` (an employee id), and no
677
+ target status; its example marks ``comment`` as required while its
678
+ table lists it as optional, so this method leaves it out of the body
679
+ when ``None``. On a ticket that is not suspended the server answers
680
+ 400 with "The request is not suspended. Operation aborted.".
681
+
682
+ Measured 2026-11-04 to 2026-11-10 on one instance (tier 4, may not
683
+ generalise): the request added one end-of-suspension action and, in
684
+ the tested case, returned the ticket to the status it was suspended
685
+ from; a restart on a ticket that was not suspended was refused with
686
+ the documented message, as HTTP 590 rather than the documented 400.
687
+ A status key sent in the body was ignored
688
+ (measured 2026-11-04). The request takes no status, and the package
689
+ has no status setter.
690
+
691
+ ``allow_workflow_effect`` is **required** and is
692
+ ``WorkflowEffect.UNKNOWN``, as for :meth:`suspend_ticket`: refused
693
+ before any request unless allowed, and sent once, never retried. The
694
+ return value is parsed like :meth:`close_ticket`'s (an ``HREF`` only)::
695
+
696
+ client.restart_ticket(rfc, allow_workflow_effect=WorkflowEffect.UNKNOWN)
697
+ """
698
+ spec, parse = requests_res.build_restart_ticket(
699
+ rfc_number,
700
+ comment=comment,
701
+ done_by_id=done_by_id,
702
+ context=self._validation_context,
703
+ )
704
+ return parse(self._transport.send(spec.allowing(allow_workflow_effect)))
705
+
613
706
  # --- actions -------------------------------------------------------------
614
707
  def create_action(
615
708
  self,
@@ -947,14 +1040,20 @@ class EasyvistaClient:
947
1040
  the **first ticket only** the step was recorded as a type-20 action
948
1041
  with ``WORKFLOW_ID`` set; its ``WORKFLOW_ID`` was unchanged,
949
1042
  ``DONE_BY_ID`` stayed empty, and no ticket field changed.
950
- **The ticket's own ``OWNING_GROUP_ID`` does not follow the action's
951
- group** -- it stayed 57 on the first ticket, the only one read for it,
952
- so reassigning a step is not reassigning the ticket. The lower-case
953
- key ``group_id`` was the one sent; the upper-case spelling was never
954
- needed. The person (``done_by_id``) was **not measured**: the same
955
- body shape is sent, but nothing here shows what the instance does
956
- with it. Whether the UI wizard's notifications fire is not observable
957
- from the API.
1043
+ The ticket's own ``OWNING_GROUP_ID`` was read at the time on one
1044
+ ticket only and had not moved; that reading was taken too soon.
1045
+ Measured 2026-11-04 to 2026-11-10 on one instance (several tickets,
1046
+ may not generalise): the ticket's ``OWNING_GROUP_ID`` follows the
1047
+ step's new group after a delay of a few seconds to about two minutes,
1048
+ consistent with a server-side job (inferred, not observed), and
1049
+ ``LAST_UPDATE`` moves with it. What still holds: the status does not
1050
+ move, the step is not started and no action row is added. Also
1051
+ measured 2026-11-04 on one ticket: after ``done_by_id`` was written on
1052
+ the step, the ticket's ``OWNER_ID`` followed about 1 min 45 s later.
1053
+ The lower-case key ``group_id`` was the one sent; the upper-case
1054
+ spelling was never needed. The person's effect on the step was not
1055
+ measured beyond that one ``OWNER_ID`` observation. Whether the UI
1056
+ wizard's notifications fire is not observable from the API.
958
1057
 
959
1058
  Not refused by the workflow guard: the group and the person are data
960
1059
  the workflow reads, not workflow state. Re-read with :meth:`get_action`
@@ -5,4 +5,4 @@
5
5
  live only in ``__init__``.
6
6
  """
7
7
 
8
- __version__ = "0.4.2"
8
+ __version__ = "0.5.0"
@@ -13,6 +13,10 @@ stack left to report it otherwise (see ``docs/content.rst``).
13
13
 
14
14
  from __future__ import annotations
15
15
 
16
- from easyvista_python_client.content.conversion import EasyvistaContentConverter
16
+ from easyvista_python_client.content.conversion import (
17
+ EasyvistaContentConverter,
18
+ Link,
19
+ RewriteLink,
20
+ )
17
21
 
18
- __all__ = ["EasyvistaContentConverter"]
22
+ __all__ = ["EasyvistaContentConverter", "Link", "RewriteLink"]
@@ -59,9 +59,11 @@ import re
59
59
  import string
60
60
  import unicodedata
61
61
  from collections.abc import Callable, Iterator, Mapping, MutableMapping, Sequence
62
+ from contextvars import ContextVar
63
+ from dataclasses import dataclass
62
64
  from functools import cached_property
63
65
  from html import escape, unescape
64
- from typing import Any, cast
66
+ from typing import Any, ClassVar, cast
65
67
 
66
68
  from easyvista_python_client.exceptions import EasyvistaContentError
67
69
 
@@ -396,6 +398,97 @@ def _title(title: str) -> str:
396
398
  return ' "' + re.sub(r'[\\"]', r"\\\g<0>", title) + '"' if title else ""
397
399
 
398
400
 
401
+ #: How a memo embeds an image: EasyVista's editor stores a pasted image as an
402
+ #: attachment of the request and writes ``<img src="@@EMBEDDED_IMAGE_PATH@@...">``
403
+ #: with that attachment's ``DOCUMENT_ID``. Measured 2026-10-07 on one instance
404
+ #: (tier 4): an image written that way through the API displays too, for an
405
+ #: attachment pasted in the editor and for one uploaded with ``add_document``.
406
+ EMBEDDED_IMAGE_PREFIX = "@@EMBEDDED_IMAGE_PATH@@"
407
+
408
+ #: A ``DOCUMENT_ID``, as an embedded image's ``src`` carries one. Measured: 40 hex
409
+ #: digits for an image pasted in the editor, an account number, ``_`` and 64 hex
410
+ #: digits for a file uploaded through the API. The class is wider than both.
411
+ _DOCUMENT_ID = re.compile(r"[A-Za-z0-9_.-]{1,128}")
412
+
413
+
414
+ @dataclass(frozen=True, slots=True)
415
+ class Link:
416
+ """A link or an image the reader meets, as a ``rewrite_link`` callback sees it.
417
+
418
+ Attributes
419
+ ----------
420
+ href : str
421
+ An ``<a>``'s ``href`` or an ``<img>``'s ``src``, character references
422
+ decoded.
423
+ text : str
424
+ An ``<a>``'s displayed text or an ``<img>``'s ``alt``, whitespace
425
+ collapsed.
426
+ title : str
427
+ The ``title``, or ``""``.
428
+ image : bool
429
+ ``True`` for an ``<img>``.
430
+ document_id : str or None
431
+ For an ``<img>`` embedding an attachment of the request
432
+ (:data:`EMBEDDED_IMAGE_PREFIX` and a ``DOCUMENT_ID``), that
433
+ ``DOCUMENT_ID``; ``None`` otherwise, and always for an ``<a>``.
434
+ enclosing_href : str or None
435
+ For an ``<img>`` inside a link, that link's ``href``; ``None``
436
+ otherwise. The image is read before the link around it.
437
+ """
438
+
439
+ href: str
440
+ text: str = ""
441
+ title: str = ""
442
+ image: bool = False
443
+ document_id: str | None = None
444
+ enclosing_href: str | None = None
445
+
446
+
447
+ #: A ``rewrite_link`` callback: called with each link and image a read meets,
448
+ #: outside code. ``None`` keeps what the reader writes without one. A ``str`` is
449
+ #: written instead, as literal text. A :class:`Link` is written in the reader's
450
+ #: own spelling: a link's ``href`` and ``title``, around the link's content as
451
+ #: read; an image's ``href`` as its ``src``, ``text`` as its ``alt`` and
452
+ #: ``title``. An empty ``href`` drops a link and keeps its content, and writes an
453
+ #: image as its ``text``.
454
+ RewriteLink = Callable[[Link], "Link | str | None"]
455
+
456
+ _REWRITE: ContextVar[RewriteLink | None] = ContextVar("rewrite_link", default=None)
457
+ """The callback of the read in progress. A context variable rather than state
458
+ on the shared converter: each thread and each task reads with its own."""
459
+
460
+
461
+ class _CallbackRaised(Exception):
462
+ """What a ``rewrite_link`` callback raised, carried past the reader's fallbacks.
463
+
464
+ The reader answers a ``ValueError`` by reading the body as its text; a
465
+ callback's own ``ValueError`` must not pass for markdownify's and quietly
466
+ cost the body its formatting.
467
+ """
468
+
469
+ def __init__(self, error: Exception) -> None:
470
+ super().__init__(error)
471
+ self.error = error
472
+
473
+
474
+ def _rewritten(link: Link) -> Link | str | None:
475
+ """Ask the read's callback about ``link``; ``None`` when there is none."""
476
+
477
+ rewrite = _REWRITE.get()
478
+ if rewrite is None:
479
+ return None
480
+ try:
481
+ answer: object = rewrite(link) # typed as what it is, not what it should be
482
+ except Exception as exc:
483
+ raise _CallbackRaised(exc) from exc
484
+ if answer is None or isinstance(answer, (Link, str)):
485
+ return answer
486
+ error = TypeError(
487
+ f"rewrite_link returned {type(answer).__name__}; expected Link, str or None"
488
+ )
489
+ raise _CallbackRaised(error)
490
+
491
+
399
492
  class _Converter(MarkdownConverter):
400
493
  """``markdownify``, with what CommonMark and the reader's glue need on top.
401
494
 
@@ -553,15 +646,27 @@ class _Converter(MarkdownConverter):
553
646
  body, _, tail = rest.rpartition("```")
554
647
  return f"{head}{fence}{body}{fence}{tail}"
555
648
 
649
+ def _literal(self, text: str, parent_tags: set[str]) -> str:
650
+ """``text`` escaped as the reader escapes a text node: displayed as it is."""
651
+
652
+ return self.escape(" ".join(text.split()), parent_tags)
653
+
556
654
  def convert_a(self, el: Tag, text: str, parent_tags: set[str]) -> str:
557
655
  """A link; ``<url>`` when its text is its URL and reads back unchanged."""
558
656
 
657
+ if "_noformat" in parent_tags:
658
+ return text
559
659
  href = str(el.get("href") or "")
660
+ title = str(el.get("title") or "")
661
+ answer = _rewritten(Link(href, " ".join(el.get_text().split()), title))
662
+ if isinstance(answer, str):
663
+ return self._literal(answer, parent_tags)
664
+ if answer is not None:
665
+ href, title = answer.href, answer.title
560
666
  edges = _EDGES.fullmatch(text)
561
- if "_noformat" in parent_tags or not href or edges is None or not edges[2]:
667
+ if not href or edges is None or not edges[2]:
562
668
  return text
563
669
  before, inner, after = edges.groups()
564
- title = str(el.get("title") or "")
565
670
  if not title and el.get_text() == href and _AUTOLINK.fullmatch(href):
566
671
  return f"{before}<{href}>{after}"
567
672
  return f"{before}[{inner}]({_destination(href)}{_title(title)}){after}"
@@ -569,12 +674,38 @@ class _Converter(MarkdownConverter):
569
674
  def convert_img(self, el: Tag, text: str, parent_tags: set[str]) -> str:
570
675
  """An image, wherever it is: a cell or a heading holds one too."""
571
676
 
677
+ src = str(el.get("src") or "")
572
678
  alt = " ".join(str(el.get("alt") or "").split())
679
+ title = str(el.get("title") or "")
680
+ if "_noformat" not in parent_tags:
681
+ embedded = EasyvistaContentConverter.document_id_of(src)
682
+ around = el.find_parent("a")
683
+ answer = _rewritten(
684
+ Link(
685
+ src,
686
+ alt,
687
+ title,
688
+ image=True,
689
+ document_id=embedded,
690
+ enclosing_href=(
691
+ None if around is None else str(around.get("href") or "")
692
+ ),
693
+ )
694
+ )
695
+ if isinstance(answer, str):
696
+ return self._literal(answer, parent_tags)
697
+ if answer is not None and not answer.href:
698
+ return self._literal(answer.text, parent_tags)
699
+ if answer is not None:
700
+ src, alt, title = (
701
+ answer.href,
702
+ " ".join(answer.text.split()),
703
+ answer.title,
704
+ )
573
705
  alt = str(self._inherited("escape")(alt, parent_tags))
574
706
  if alt.startswith("^") and "_noformat" not in parent_tags:
575
707
  alt = "\\" + alt # cmark-gfm reads "![^" as "!" and a link
576
- src = _destination(str(el.get("src") or ""))
577
- return f"![{alt}]({src}{_title(str(el.get('title') or ''))})"
708
+ return f"![{alt}]({_destination(src)}{_title(title)})"
578
709
 
579
710
 
580
711
  class _Node(RenderTreeNode):
@@ -784,11 +915,41 @@ def _text_of(html: str) -> str:
784
915
  return "\n".join(line for line in lines if line)
785
916
 
786
917
 
918
+ def _converted(content: str) -> str:
919
+ """Read memo HTML, falling back to its text where the conversion cannot."""
920
+
921
+ try:
922
+ try:
923
+ return html_to_markdown(content)
924
+ except (RecursionError, ValueError): # ValueError: markdownify's
925
+ # int() of a colspan or start such as "²" or 5,000 digits
926
+ return html_to_markdown(_plain_text_html(_text_of(content)))
927
+ except ParserRejectedMarkup:
928
+ # html.parser gives up on a few malformed declarations; the
929
+ # body's words are still worth more than an exception.
930
+ text = unescape(_ANY_TAG.sub(" ", content))
931
+ return html_to_markdown(_plain_text_html(" ".join(text.split())))
932
+ except _CallbackRaised:
933
+ raise
934
+ except Exception as exc:
935
+ raise EasyvistaContentError(
936
+ "Could not convert EasyVista memo HTML to Markdown "
937
+ f"({type(exc).__name__}: {exc})."
938
+ ) from exc
939
+
940
+
787
941
  class EasyvistaContentConverter:
788
942
  """Convert content between EasyVista memo HTML and canonical Markdown."""
789
943
 
944
+ EMBEDDED_IMAGE_PREFIX: ClassVar[str] = EMBEDDED_IMAGE_PREFIX
945
+
790
946
  @staticmethod
791
- def from_transport(value: object, *, plain_text_is_markdown: bool = False) -> str:
947
+ def from_transport(
948
+ value: object,
949
+ *,
950
+ plain_text_is_markdown: bool = False,
951
+ rewrite_link: RewriteLink | None = None,
952
+ ) -> str:
792
953
  """Convert one EasyVista memo value into Markdown.
793
954
 
794
955
  Parameters
@@ -806,6 +967,12 @@ class EasyvistaContentConverter:
806
967
  ``<kbd>`` is still Markdown, but Markdown that opens with an
807
968
  autolink or other angle-bracketed text and carries inline HTML
808
969
  further on is read as HTML, and loses that autolink.
970
+ rewrite_link : callable, optional
971
+ Called with a :class:`Link` for each link and image the read
972
+ meets outside code, an image before the link around it; its
973
+ answer decides what is written (:data:`RewriteLink`). Not called
974
+ for a value passed through as Markdown, nor for a body read as
975
+ its text. Without one, the read is what it always was.
809
976
 
810
977
  Returns
811
978
  -------
@@ -825,6 +992,10 @@ class EasyvistaContentConverter:
825
992
  limit, where no stack is left even to report the failure as
826
993
  ``EasyvistaContentError`` (``docs/content.rst`` gives the
827
994
  measured depths).
995
+ Exception
996
+ Whatever ``rewrite_link`` raised, unchanged; ``TypeError`` when it
997
+ answered something other than a :class:`Link`, a ``str`` or
998
+ ``None``.
828
999
  """
829
1000
 
830
1001
  content = str(value or "").strip()
@@ -840,22 +1011,65 @@ class EasyvistaContentConverter:
840
1011
  # 3.11.14/3.12.12/3.13.6 rescans to the end for each (quadratic).
841
1012
  head, end, tail = content.rpartition(">")
842
1013
  content = head + end + tail.replace("<", "&lt;")
1014
+ token = _REWRITE.set(rewrite_link)
843
1015
  try:
844
- try:
845
- return html_to_markdown(content)
846
- except (RecursionError, ValueError): # ValueError: markdownify's
847
- # int() of a colspan or start such as "²" or 5,000 digits
848
- return html_to_markdown(_plain_text_html(_text_of(content)))
849
- except ParserRejectedMarkup:
850
- # html.parser gives up on a few malformed declarations; the
851
- # body's words are still worth more than an exception.
852
- text = unescape(_ANY_TAG.sub(" ", content))
853
- return html_to_markdown(_plain_text_html(" ".join(text.split())))
854
- except Exception as exc:
855
- raise EasyvistaContentError(
856
- "Could not convert EasyVista memo HTML to Markdown "
857
- f"({type(exc).__name__}: {exc})."
858
- ) from exc
1016
+ return _converted(content)
1017
+ except _CallbackRaised as raised:
1018
+ callback_error = raised.error
1019
+ finally:
1020
+ _REWRITE.reset(token)
1021
+ raise callback_error # outside the handler: the callback's, as it raised it
1022
+
1023
+ @staticmethod
1024
+ def document_id_of(src: str) -> str | None:
1025
+ """Return the ``DOCUMENT_ID`` an embedded image's ``src`` names.
1026
+
1027
+ ``None`` unless ``src`` is exactly :data:`EMBEDDED_IMAGE_PREFIX`
1028
+ followed by a ``DOCUMENT_ID`` -- how EasyVista's editor refers to an
1029
+ image pasted into a memo, which it keeps as an attachment of the
1030
+ request.
1031
+ """
1032
+
1033
+ if not src.startswith(EMBEDDED_IMAGE_PREFIX):
1034
+ return None
1035
+ document_id = src[len(EMBEDDED_IMAGE_PREFIX) :]
1036
+ return document_id if _DOCUMENT_ID.fullmatch(document_id) else None
1037
+
1038
+ @staticmethod
1039
+ def document_image(document_id: str, *, alt: str = "") -> str:
1040
+ """Return the Markdown of an image embedding one of the request's attachments.
1041
+
1042
+ :meth:`to_transport` renders it as EasyVista's editor writes a pasted
1043
+ image, ``<img src="@@EMBEDDED_IMAGE_PATH@@<document_id>" alt="..." />``,
1044
+ and :meth:`from_transport` reads that back as this same Markdown: it
1045
+ is spelled by the reader itself. The memo displays the image once the
1046
+ attachment is on the same request.
1047
+
1048
+ Parameters
1049
+ ----------
1050
+ document_id : str
1051
+ The attachment's ``DOCUMENT_ID``, as ``list_documents`` gives it.
1052
+ alt : str, optional
1053
+ The image's alternative text.
1054
+
1055
+ Raises
1056
+ ------
1057
+ ValueError
1058
+ ``document_id`` is not one: empty, or holding a character no
1059
+ ``DOCUMENT_ID`` has.
1060
+ """
1061
+
1062
+ if not _DOCUMENT_ID.fullmatch(document_id):
1063
+ raise ValueError(f"not an EasyVista DOCUMENT_ID: {document_id!r}")
1064
+ native = (
1065
+ f'<p><img src="{EMBEDDED_IMAGE_PREFIX}{document_id}" '
1066
+ f'alt="{escape(" ".join(alt.split()))}" /></p>'
1067
+ )
1068
+ token = _REWRITE.set(None) # a callback in force for an enclosing read
1069
+ try:
1070
+ return html_to_markdown(native)
1071
+ finally:
1072
+ _REWRITE.reset(token)
859
1073
 
860
1074
  @staticmethod
861
1075
  def to_transport(value: object) -> str:
@@ -140,3 +140,71 @@ def build_close_ticket(
140
140
  )
141
141
 
142
142
  return spec, parse
143
+
144
+
145
+ def _build_state_request(
146
+ wrapper: str,
147
+ rfc_number: str,
148
+ *,
149
+ comment: str | None,
150
+ done_by_id: int | None,
151
+ context: dict[str, Any] | None,
152
+ ) -> tuple[RequestSpec, Callable[[Any], Request]]:
153
+ body: dict[str, Any] = {}
154
+ if comment is not None:
155
+ body["comment"] = comment
156
+ if done_by_id is not None:
157
+ body["done_by_id"] = done_by_id
158
+ spec = RequestSpec("PUT", f"requests/{rfc_number}", json={wrapper: body})
159
+
160
+ def parse(data: Any) -> Request:
161
+ records = extract_records(data, REQUESTS.envelope_key)
162
+ return Request.model_validate(
163
+ records[0] if records else data, context=context
164
+ )
165
+
166
+ return spec, parse
167
+
168
+
169
+ def build_suspend_ticket(
170
+ rfc_number: str,
171
+ *,
172
+ comment: str | None = None,
173
+ done_by_id: int | None = None,
174
+ context: dict[str, Any] | None = None,
175
+ ) -> tuple[RequestSpec, Callable[[Any], Request]]:
176
+ """Build the ``{"suspended": {...}}`` PUT spec -- the vendor's suspend request.
177
+
178
+ https://docs.easyvista.com/docs/rest-api-suspend-an-incident-request.md
179
+ (tier 1): ``comment`` and ``done_by_id`` are the page's two optional
180
+ parameters, and both are left out of the body when ``None``.
181
+ """
182
+ return _build_state_request(
183
+ "suspended",
184
+ rfc_number,
185
+ comment=comment,
186
+ done_by_id=done_by_id,
187
+ context=context,
188
+ )
189
+
190
+
191
+ def build_restart_ticket(
192
+ rfc_number: str,
193
+ *,
194
+ comment: str | None = None,
195
+ done_by_id: int | None = None,
196
+ context: dict[str, Any] | None = None,
197
+ ) -> tuple[RequestSpec, Callable[[Any], Request]]:
198
+ """Build the ``{"restarted": {...}}`` PUT spec -- the vendor's restart request.
199
+
200
+ https://docs.easyvista.com/docs/rest-api-reopen-an-incident-request.md
201
+ (tier 1): ``comment`` and ``done_by_id`` are the page's two optional
202
+ parameters, and both are left out of the body when ``None``.
203
+ """
204
+ return _build_state_request(
205
+ "restarted",
206
+ rfc_number,
207
+ comment=comment,
208
+ done_by_id=done_by_id,
209
+ context=context,
210
+ )
@@ -35,7 +35,8 @@ site allowed it explicitly, with ``allow_workflow_effect=``.
35
35
  ``end_action``, ``suspended``, ``restarted`` -- as a top-level body key, in any
36
36
  casing, on any path. (2) On ticket and action routes, the columns that hold or
37
37
  select workflow state: a status, a catalog (which selects the workflow), the
38
- workflow, stage and step links, and on an existing action its end date, type,
38
+ workflow, stage and step links, and on an existing action its end date, the
39
+ statuses it sets (``status_id_on_terminate``, ``status_id_on_create``), type,
39
40
  parent or ticket (creating an action or a task names a narrower set, below).
40
41
  (3) Ticket sub-routes that are workflow commands rather than records, and
41
42
  ``requests/without-workflow`` and the deletion of a ticket. (4) A write to
@@ -114,11 +115,17 @@ _REQUEST_COLUMNS = frozenset(
114
115
  )
115
116
 
116
117
  #: Columns on ``actions/{id}`` that end, re-type, re-parent or move an action.
118
+ #: ``status_id_on_create``: workflow state. Measured 2026-11-09 and 2026-11-10
119
+ #: on one instance (tier 4, may not generalise): a write to it on an existing
120
+ #: action changed where the ticket's status went. Not in the create sets
121
+ #: below: on create the server overwrites it with the current status
122
+ #: (measured 2026-11-05).
117
123
  _ACTION_COLUMNS = frozenset(
118
124
  {
119
125
  "end_date_ut",
120
126
  "end_date",
121
127
  "status_id_on_terminate",
128
+ "status_id_on_create",
122
129
  "workflow_id",
123
130
  "stage_id",
124
131
  "process_step_id",
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: easyvista-python-client
3
- Version: 0.4.2
3
+ Version: 0.5.0
4
4
  Summary: Typed Python client for the EasyVista Service Manager REST API
5
5
  Project-URL: Homepage, https://github.com/baraline/easyvista_python_client
6
6
  Project-URL: Documentation, https://easyvista-python-client.readthedocs.io/en/latest/
@@ -2,7 +2,7 @@ easyvista_python_client/__init__.py,sha256=AkPNxN1iaQhprPYShcqCEx03b0d4qi6b98MCF
2
2
  easyvista_python_client/_fields.py,sha256=L-9niigMP6vAMLR1rhY0KpmY0Zo_FeTkROr3dYd_Qwo,2164
3
3
  easyvista_python_client/_html.py,sha256=KftxdX4vHptQrOMqfWM-9I3g03UAA5YRmqwnLjI2Ir4,1276
4
4
  easyvista_python_client/_transport.py,sha256=AZItqLNOfgj1qTfC0ajxiKOPxXGnh7S0mGJE7VilfLU,3034
5
- easyvista_python_client/_version.py,sha256=Qs1bD7HLZeviaRaWtnZfFdMaFFMcmAU9-o4uKWhIj2E,290
5
+ easyvista_python_client/_version.py,sha256=RMzNOTVK_EwDd1dZx5Zysi4DGWCqvJzH7Ax6KVA_jSA,290
6
6
  easyvista_python_client/config.py,sha256=Zdzv2GB7Hma-z6RiR0820l4KPFn_EZxfmuQrS4RYlek,12361
7
7
  easyvista_python_client/context.py,sha256=_5PEjH4a2jM8Ks51YEes--CESt1vBXlK87y0s8UutHQ,13597
8
8
  easyvista_python_client/directory.py,sha256=BD44sgJgAAhcz2d0Eyqpv4fjdc9HCustI_izR4qwoyo,7820
@@ -15,17 +15,17 @@ easyvista_python_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hS
15
15
  easyvista_python_client/references.py,sha256=o20WGeUjYqyP0AqdUkyHW-uTWg1soCwMGJDgIkz8J-A,14697
16
16
  easyvista_python_client/reporting.py,sha256=n_GgMG5UJlfRPgaVkMc30S_V6BvNVs2OjOk4HOAahnU,6817
17
17
  easyvista_python_client/timestamps.py,sha256=RAoBupaACjYAoNjTzLNq35fJDRYqw8ZX3Y9UN_6pQKA,6334
18
- easyvista_python_client/workflow.py,sha256=s3nXNnncNSw644eyRCUh9h3WrTBGJpUxpXKgCpxpqtQ,14415
18
+ easyvista_python_client/workflow.py,sha256=67775JdqTd4sbTRhiaDrx8TALI4Bsp4iY0AQ5GMPcGk,14847
19
19
  easyvista_python_client/_async/__init__.py,sha256=pg5E76VOB1ruJNVpqzatRm9TJBdPhAcDhsmBKlcRotc,612
20
20
  easyvista_python_client/_async/_concurrency.py,sha256=5Ce9LZKRkGgT_AVSE93IeU2gl-Z3Jq84YxWK3EL-FMM,3826
21
21
  easyvista_python_client/_async/_transport.py,sha256=oAvbrzlHFmotfo2w1k8JUqdybNUFEZzr2VxznwxxQXQ,27757
22
- easyvista_python_client/_async/client.py,sha256=MYbUOeUmFlW8-3Nd0xU748dRId1Mf4OhhSgosnqaOV8,118510
22
+ easyvista_python_client/_async/client.py,sha256=STMl_IK4bJ2RLWBOLXUTTaGomPt9jVCCCvjQ4i7Z7ac,123445
23
23
  easyvista_python_client/_sync/__init__.py,sha256=TKnndsi6v7S43so4X6fg_hZy3wg45Jk40pYCQ2FkgR0,601
24
24
  easyvista_python_client/_sync/_concurrency.py,sha256=zeCtzdrMQa9thzdV6A5sdP8Ojojgjkhbx6X8pH7qWGw,1750
25
25
  easyvista_python_client/_sync/_transport.py,sha256=JwEclG90LO9wrPxv1aEy8sQxHbeWVyyi61oEy4zsHx8,27537
26
- easyvista_python_client/_sync/client.py,sha256=I7H999YpssGhGozMo7Dxu4qkkfTMKzJjAHvR8fEyyC8,117586
27
- easyvista_python_client/content/__init__.py,sha256=Bqf40LdL00OyOfq0IqR5uBSEBL1QKvVwll8u4dQ0lW0,878
28
- easyvista_python_client/content/conversion.py,sha256=LFkNnKHJfsHEhcHwANYDMnKSX0Q9POan84lbxGiFj_M,35249
26
+ easyvista_python_client/_sync/client.py,sha256=BQGN9Em-oPZN8a34qjAAcyaSlP18o9dzXpswqc7n3Ps,122497
27
+ easyvista_python_client/content/__init__.py,sha256=9_b5Dl9wnsoFuEmnBMfPn-jvypMydePVMe37PuY9zYA,937
28
+ easyvista_python_client/content/conversion.py,sha256=NUzSUawBwBYkIoGTSTPX7__rCgGjJcZF8jQwGjVqSbU,43559
29
29
  easyvista_python_client/models/__init__.py,sha256=dCN1GPDWqu5zraEuGiCZaUGXyNQiK3yCuAC18Fh6NL4,47
30
30
  easyvista_python_client/models/action.py,sha256=m-R_n9S89yq3acjXsBM7FY05edW4jH97YIw5B-VG6zI,33405
31
31
  easyvista_python_client/models/asset.py,sha256=_cKeGOORSSLbqvXf_rQ2K00KM6K4DJdnqDvvhg7rhAg,2047
@@ -43,8 +43,8 @@ easyvista_python_client/resources/descriptor.py,sha256=mQt173Nolz2svALqtbQvk-I-5
43
43
  easyvista_python_client/resources/discovery.py,sha256=2XKV_sfP8Evlb_aDc4gi-aP-W3dNHqTn6rJnvp4dur0,2961
44
44
  easyvista_python_client/resources/documents.py,sha256=FUfRDeAJu1qF9MvqLFwRtkxJvBC85SGEuoO85n_Qupk,6526
45
45
  easyvista_python_client/resources/employees.py,sha256=7X_hTRnk7T-GMNldDANmdnv2TgFZCfhIwgz7-PEDKaY,1790
46
- easyvista_python_client/resources/requests.py,sha256=qNksnO6RST6smHnT9eEkSbxR0iHXrW-ADkM3J_oQ4To,5380
47
- easyvista_python_client-0.4.2.dist-info/METADATA,sha256=jwB2EAUsFzBnTfCbdZJjiT9-dulWiPS3R-PhgABBTDk,13094
48
- easyvista_python_client-0.4.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
49
- easyvista_python_client-0.4.2.dist-info/licenses/LICENSE,sha256=COAKFzPjsNCUJS82NnwBj20wPEHE34Dl8GzGZzaQWR0,1093
50
- easyvista_python_client-0.4.2.dist-info/RECORD,,
46
+ easyvista_python_client/resources/requests.py,sha256=dPQ1FeHIemzujblCbAtcuJjBkwDQPmWdGDursn6jNfA,7439
47
+ easyvista_python_client-0.5.0.dist-info/METADATA,sha256=s5G962OLAmtPhkPhSM7JUz-B9uhkV-p-TbzC9MfRVBg,13094
48
+ easyvista_python_client-0.5.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
49
+ easyvista_python_client-0.5.0.dist-info/licenses/LICENSE,sha256=COAKFzPjsNCUJS82NnwBj20wPEHE34Dl8GzGZzaQWR0,1093
50
+ easyvista_python_client-0.5.0.dist-info/RECORD,,
@@ -1,4 +1,4 @@
1
1
  Wheel-Version: 1.0
2
- Generator: hatchling 1.32.4
2
+ Generator: hatchling 1.33.0
3
3
  Root-Is-Purelib: true
4
4
  Tag: py3-none-any