exception_guidance

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

GuidanceHintTypedDict	dict() -> new empty dictionary
GuidanceHint	A single actionable hint with a stable hint_code.
ErrorGuidance	Structured guidance for solution-oriented error messages.

class GuidanceHintTypedDict

Bases: 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.

text: str

hint_code: str

class GuidanceHint

A single actionable hint with a stable hint_code.

text: str

Human-readable description of the action to take.

hint_code: str

Stable machine-readable identifier. Use snake_case.

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.

summary: str | None = None

Optional headline overriding message for user-facing output.

cause: str | None = None

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

hints: tuple[GuidanceHint, Ellipsis] = ()

Ordered list of actionable next steps. Rendered in order.

__post_init__() → None

property hint_codes: tuple[str, Ellipsis]

Hint codes extracted from hints for JSON serialization.

__json__() → dict[str, object]

Serialize for CondaError.dump_map.

classmethod from_hints(hints: collections.abc.Iterable[GuidanceHint]) → ErrorGuidance | None

Create guidance from hints, deduplicating by hint_code.

with_hints(hints: collections.abc.Iterable[GuidanceHint]) → ErrorGuidance

Return this guidance with additional hints appended.

Existing hints keep priority when hint_code values collide.

classmethod coerce(value: Any) → ErrorGuidance | None

Coerce value to ErrorGuidance or None.

Parameters:

value -- None returns None, ErrorGuidance passes through, a dict is coerced (empty dict returns None).

Returns:

None or an ErrorGuidance instance.

format(exception: conda.CondaError) → str

Format this guidance for terminal output.

Parameters:

exception -- str(exception) is used as the headline unless summary is set.

Returns:

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