:py:mod:`exception_guidance`
============================

.. py:module:: conda._private.exception_guidance

.. autoapi-nested-parse::

   Structured error guidance for user-facing error messages.

   ``ErrorGuidance`` can be attached to ``conda.CondaError`` via the ``guidance`` keyword
   so that terminal and `--json` output share the same logical cause / hint structure.



Classes
-------

.. autoapisummary::

   conda._private.exception_guidance.GuidanceHintTypedDict
   conda._private.exception_guidance.GuidanceHint
   conda._private.exception_guidance.ErrorGuidance




.. py:class:: GuidanceHintTypedDict

   Bases: :py:obj:`TypedDict`


   dict() -> new empty dictionary
   dict(mapping) -> new dictionary initialized from a mapping object's
       (key, value) pairs
   dict(iterable) -> new dictionary initialized as if via:
       d = {}
       for k, v in iterable:
           d[k] = v
   dict(**kwargs) -> new dictionary initialized with the name=value pairs
       in the keyword argument list.  For example:  dict(one=1, two=2)

   Initialize self.  See help(type(self)) for accurate signature.


   .. py:attribute:: text
      :type:  str


   .. py:attribute:: hint_code
      :type:  str


.. py:class:: GuidanceHint

   A single actionable hint with a stable ``hint_code``.


   .. py:attribute:: text
      :type:  str

      Human-readable description of the action to take.


   .. py:attribute:: hint_code
      :type:  str

      Stable machine-readable identifier. Use snake_case.


.. py:class:: ErrorGuidance

   Structured guidance for solution-oriented error messages.

   When attached to a ``CondaError``, the display layer renders the cause
   and hints alongside the exception's ``message``.


   .. py:attribute:: summary
      :type:  str | None
      :value: None


      Optional headline overriding ``message`` for user-facing output.


   .. py:attribute:: cause
      :type:  str | None
      :value: None


      Explanation of what went wrong, distinct from the raw error text.


   .. py:attribute:: hints
      :type:  tuple[GuidanceHint, ...]
      :value: ()


      Ordered list of actionable next steps. Rendered in order.


   .. py:method:: __post_init__() -> None


   .. py:property:: hint_codes
      :type: tuple[str, ...]


      Hint codes extracted from ``hints`` for JSON serialization.


   .. py:method:: __json__() -> dict[str, object]

      Serialize for ``CondaError.dump_map``.



   .. py:method:: from_hints(hints: collections.abc.Iterable[GuidanceHint]) -> ErrorGuidance | None
      :classmethod:


      Create guidance from hints, deduplicating by ``hint_code``.



   .. py:method:: with_hints(hints: collections.abc.Iterable[GuidanceHint]) -> ErrorGuidance

      Return this guidance with additional hints appended.

      Existing hints keep priority when ``hint_code`` values collide.



   .. py:method:: coerce(value: Any) -> ErrorGuidance | None
      :classmethod:


      Coerce *value* to ``ErrorGuidance`` or ``None``.

      :param value: ``None`` returns ``None``, ``ErrorGuidance`` passes
                    through, a ``dict`` is coerced (empty ``dict`` returns
                    ``None``).

      :returns: ``None`` or an ``ErrorGuidance`` instance.



   .. py:method:: format(exception: conda.CondaError) -> str

      Format this guidance for terminal output.

      :param exception: ``str(exception)`` is used as the headline unless
                        ``summary`` is set.

      :returns: Formatted string including the exception class name, cause,
                and actionable hints.