158 lines
5.0 KiB
Python
158 lines
5.0 KiB
Python
# -*- coding: utf-8 -*-
|
|
# Copyright (c) 2019 Ansible Project
|
|
# Simplified BSD License (see licenses/simplified_bsd.txt or https://opensource.org/licenses/BSD-2-Clause)
|
|
|
|
from __future__ import annotations as _annotations
|
|
|
|
import typing as _t
|
|
|
|
from ansible.module_utils._internal import _traceback, _deprecator, _event_utils, _messages, _errors
|
|
from ansible.module_utils import _internal
|
|
|
|
|
|
def warn(
|
|
warning: str,
|
|
*,
|
|
help_text: str | None = None,
|
|
obj: object | None = None,
|
|
) -> None:
|
|
"""Record a warning to be returned with the module result."""
|
|
_skip_stackwalk = True
|
|
|
|
if _internal.is_controller:
|
|
_display = _internal.import_controller_module('ansible.utils.display').Display()
|
|
_display.warning(
|
|
msg=warning,
|
|
help_text=help_text,
|
|
obj=obj,
|
|
)
|
|
|
|
return
|
|
|
|
warning = _messages.WarningSummary(
|
|
event=_messages.Event(
|
|
msg=warning,
|
|
help_text=help_text,
|
|
formatted_traceback=_traceback.maybe_capture_traceback(warning, _traceback.TracebackEvent.WARNING),
|
|
),
|
|
)
|
|
|
|
_global_warnings[warning] = None
|
|
|
|
|
|
def error_as_warning(
|
|
msg: str | None,
|
|
exception: BaseException,
|
|
*,
|
|
help_text: str | None = None,
|
|
obj: object = None,
|
|
) -> None:
|
|
"""Display an exception as a warning."""
|
|
_skip_stackwalk = True
|
|
|
|
if _internal.is_controller:
|
|
_display = _internal.import_controller_module('ansible.utils.display').Display()
|
|
_display.error_as_warning(
|
|
msg=msg,
|
|
exception=exception,
|
|
help_text=help_text,
|
|
obj=obj,
|
|
)
|
|
|
|
return
|
|
|
|
event = _errors.EventFactory.from_exception(exception, _traceback.is_traceback_enabled(_traceback.TracebackEvent.WARNING))
|
|
|
|
warning = _messages.WarningSummary(
|
|
event=_messages.Event(
|
|
msg=msg,
|
|
help_text=help_text,
|
|
formatted_traceback=_traceback.maybe_capture_traceback(msg, _traceback.TracebackEvent.WARNING),
|
|
chain=_messages.EventChain(
|
|
msg_reason=_errors.MSG_REASON_DIRECT_CAUSE,
|
|
traceback_reason=_errors.TRACEBACK_REASON_EXCEPTION_DIRECT_WARNING,
|
|
event=event,
|
|
),
|
|
),
|
|
)
|
|
|
|
_global_warnings[warning] = None
|
|
|
|
|
|
def deprecate(
|
|
msg: str,
|
|
version: str | None = None,
|
|
date: str | None = None,
|
|
collection_name: str | None = None,
|
|
*,
|
|
deprecator: _messages.PluginInfo | None = None,
|
|
help_text: str | None = None,
|
|
obj: object | None = None,
|
|
) -> None:
|
|
"""
|
|
Record a deprecation warning.
|
|
The `obj` argument is only useful in a controller context; it is ignored for target-side callers.
|
|
Most callers do not need to provide `collection_name` or `deprecator` -- but provide only one if needed.
|
|
Specify `version` or `date`, but not both.
|
|
If `date` is a string, it must be in the form `YYYY-MM-DD`.
|
|
"""
|
|
_skip_stackwalk = True
|
|
|
|
deprecator = _deprecator.get_best_deprecator(deprecator=deprecator, collection_name=collection_name)
|
|
|
|
if _internal.is_controller:
|
|
_display = _internal.import_controller_module('ansible.utils.display').Display()
|
|
_display.deprecated(
|
|
msg=msg,
|
|
version=version,
|
|
date=date,
|
|
help_text=help_text,
|
|
obj=obj,
|
|
# skip passing collection_name; get_best_deprecator already accounted for it when present
|
|
deprecator=deprecator,
|
|
)
|
|
|
|
return
|
|
|
|
warning = _messages.DeprecationSummary(
|
|
event=_messages.Event(
|
|
msg=msg,
|
|
help_text=help_text,
|
|
formatted_traceback=_traceback.maybe_capture_traceback(msg, _traceback.TracebackEvent.DEPRECATED),
|
|
),
|
|
version=version,
|
|
date=date,
|
|
deprecator=deprecator,
|
|
)
|
|
|
|
_global_deprecations[warning] = None
|
|
|
|
|
|
def get_warning_messages() -> tuple[str, ...]:
|
|
"""Return a tuple of warning messages accumulated over this run."""
|
|
# DTFIX7: add future deprecation comment
|
|
return tuple(_event_utils.format_event_brief_message(item.event) for item in _global_warnings)
|
|
|
|
|
|
def get_deprecation_messages() -> tuple[dict[str, _t.Any], ...]:
|
|
"""Return a tuple of deprecation warning messages accumulated over this run."""
|
|
# DTFIX7: add future deprecation comment
|
|
return tuple(_event_utils.deprecation_as_dict(item) for item in _global_deprecations)
|
|
|
|
|
|
def get_warnings() -> list[_messages.WarningSummary]:
|
|
"""Return a list of warning messages accumulated over this run."""
|
|
return list(_global_warnings)
|
|
|
|
|
|
def get_deprecations() -> list[_messages.DeprecationSummary]:
|
|
"""Return a list of deprecations accumulated over this run."""
|
|
return list(_global_deprecations)
|
|
|
|
|
|
_global_warnings: dict[_messages.WarningSummary, object] = {}
|
|
"""Global, ordered, de-duplicated storage of accumulated warnings for the current module run."""
|
|
|
|
_global_deprecations: dict[_messages.DeprecationSummary, object] = {}
|
|
"""Global, ordered, de-duplicated storage of accumulated deprecations for the current module run."""
|