"""
This module includes functions that can be used in a friendly console
or in other **interactive** environments such as in a Jupyter notebook.
If you intend to use ``friendly_traceback`` in an interactive environment,
you should use ``friendly`` instead, as in::
from friendly.ipython import ...
# or
from friendly.jupyter import ...
# etc.
Since this documentation is generated automatically by Sphinx using
``friendly_traceback`` code, it will not contain all the relevant
functions specific to a given environment. To find out about what
functions are available in such environments, do the following::
prompt>> from friendly.X import Friendly
prompt>> Friendly
# The output will include the required information
"""
# NOTE: __all__ is defined at the very bottom of this file
import inspect
import sys
import types
from typing import Any, Callable, Dict, List, Optional, Type, Union
import friendly_traceback
from friendly_traceback import __version__, base_formatters, debug_helper
from friendly_traceback.config import session
from friendly_traceback.ft_gettext import current_lang
from friendly_traceback.functions_help import add_help_attribute
from friendly_traceback.info_generic import get_generic_explanation
from friendly_traceback.path_info import show_paths
from friendly_traceback.syntax_errors.source_info import Statement
from friendly_traceback.tb_data import TracebackData
from friendly_traceback.typing_info import InclusionChoice, Site
_ = current_lang.translate
def _nothing_to_show():
return _("Nothing to show: no exception recorded.")
[docs]def disable():
"""Disable friendly-traceback exception hook"""
if not session.installed:
info = {"suggest": _("Friendly-traceback is already disabled.") + "\n"}
explanation = session.formatter(info, include="hint")
session.write_err(explanation)
return
session.uninstall()
[docs]def enable():
"""Enable friendly-traceback exception hook"""
if session.installed:
info = {"suggest": _("Friendly-traceback is already enabled.") + "\n"}
explanation = session.formatter(info, include="hint")
session.write_err(explanation)
return
session.install()
[docs]def explain(index: int = -1, include: InclusionChoice = "explain") -> None:
"""Shows the previously recorded traceback info again,
with the option to specify different items to include.
For example, ``explain("why")`` is equivalent to ``why()``.
"""
old_include = friendly_traceback.get_include()
friendly_traceback.set_include(include)
session.show_traceback_info_again(index)
friendly_traceback.set_include(old_include)
[docs]def friendly_tb(index: int = -1) -> None:
"""Shows the simplified Python traceback,
which includes the hint/suggestion if available.
"""
explain(index, include="friendly_tb")
[docs]def hint(index: int = -1) -> None:
"""Shows hint/suggestion if available."""
explain(index, include="hint")
class History:
__name__ = "history"
def __call__(self):
"""Prints a list of recorded tracebacks and warning messages"""
if not session.recorded_tracebacks:
info = {"suggest": _nothing_to_show() + "\n"}
explanation = session.formatter(info, include="hint")
session.write_err(explanation)
return
session.rich_add_vspace = False # for friendly
for index, tb in enumerate(session.recorded_tracebacks):
if "message" in tb.info:
info = {"message": f"{index}. {tb.info['message']}"}
explanation = session.formatter(info, include="message")
session.write_err(explanation)
session.rich_add_vspace = True
def __repr__(self):
return (
_("Shows a list of recorded traceback messages.")
+ "\n"
+ _("You can also use `history.clear()` and `history.pop()`.")
)
def clear(self):
"""Removes all recorded tracebacks and warnings"""
session.recorded_tracebacks.clear()
def pop(self, index=-1):
"""Used to delete a particular item, with the last item removed by default"""
if not session.recorded_tracebacks:
info = {"suggest": _("Nothing to delete: no exception recorded.") + "\n"}
explanation = session.formatter(info, include="hint")
session.write_err(explanation)
return
try:
session.recorded_tracebacks.pop(index)
except IndexError:
info = {"suggest": _("There is no such history item.") + "\n"}
explanation = session.formatter(info, include="hint")
session.write_err(explanation)
history = History()
[docs]def python_tb(index: int = -1) -> None:
"""Shows the Python traceback, excluding files from friendly
itself.
"""
explain(index, include="python_tb")
[docs]def what(
exception_or_index: Union[
Type[BaseException], str, bytes, types.CodeType, int, None
] = None,
pre: bool = False,
) -> None:
"""If known, shows the generic explanation about a given exception.
If the ``pre`` argument is set to ``True``, the output is
formatted in a way that is suitable for inclusion in the
documentation.
"""
if exception_or_index is None:
explain(index=-1, include="what")
return
elif isinstance(exception_or_index, int):
explain(index=exception_or_index, include="what")
return
if inspect.isclass(exception_or_index) and issubclass(
exception_or_index, BaseException
):
result = get_generic_explanation(exception_or_index)
else:
try:
exc = eval(exception_or_index) # skipcq PYL-W0123
if inspect.isclass(exc) and issubclass(exc, BaseException):
result = get_generic_explanation(exc)
else:
result = _("{exception} is not an exception.").format(
exception=f"`{exception_or_index}`"
)
except Exception: # noqa
result = _("{exception} is not an exception.").format(
exception=f"`{exception_or_index}`"
)
if pre: # for documentation # pragma: no cover
lines = result.split("\n")
for line in lines:
session.write_err(f" {line}\n")
session.write_err("\n")
else:
info = {"generic": result}
explanation = session.formatter(info, include="what")
session.write_err(explanation)
[docs]def where(index: int = -1, more=False) -> None:
"""Shows the information about where the exception occurred"""
if more:
try:
info = session.recorded_tracebacks[index].info
except Exception:
explain(index, "where") # let the error bubble up
else:
if "detailed_tb" in info:
explain(index, "detailed_tb")
else:
explain(index, "where")
else:
explain(index, "where")
[docs]def why(index: int = -1) -> None:
"""Shows the likely cause of the exception."""
# If no cause is found, and the exception name is not accompanied by a
# message, as in "StopIteration:", we use the same info for
# the cause as we used for the generic information as per issue #66
try:
if index == -1:
info = session.recorded_tracebacks[-1].info
else:
info = session.recorded_tracebacks[index + 1].info
except IndexError:
info = {}
if (
("cause" not in info or not info["cause"])
and "message" in info
and len(info["message"].split(":")) > 1
and not info["message"].split(":")[1].strip() # empty message
):
explain(index, "what")
else:
explain(index, "why")
[docs]def www(site_or_index: Union[Site, int] = -1) -> None: # pragma: no cover
"""This uses the ``webbrowser`` module to open a tab (or window)
in the default browser, linking to a specific url
or opening the default email client.
* If the argument ``site_or_index`` is not specified,
and an exception or a warning has been raised,
an internet search will be done using
the exception message of the last exception or warning
as the search string.
* If the argument ``site_or_index`` is not specified,
and NO exception has been raised,
Friendly's documentation will open.
* If the argument ``site_or_index`` == "friendly",
Friendly's documentation will open.
* If the argument ``site_or_index`` == "python", Python's documentation site
will open with the currently used Python version.
* If the argument ``site_or_index`` == "bug",
the Issues page for Friendly on GitHub will open.
* If the argument ``site_or_index`` == "email",
the default email client should open with Friendly's
developer's address already filled in.
* If the argument ``site_or_index`` is an integer representing an item
in the recorded history, an internet search will be done using
the exception message of the corresponding item as the search string.
"""
import urllib.parse
import webbrowser
def open_browser(url):
try:
webbrowser.open_new_tab(url)
except Exception: # noqa
session.write_err(
_("The default web browser cannot be used for searching.")
)
return
urls: Dict[Site, str] = {
"friendly": "https://friendly-traceback.github.io/docs/index.html",
"python": f"https://docs.python.org/3.{sys.version_info.minor}/",
"bug": "https://github.com/friendly-traceback/friendly-traceback/issues/new",
"email": "mailto:andre.roberge@gmail.com",
}
invalid_args = _(
"Invalid argument for `www()`.\n"
"Valid arguments are integer values or one of `{sites}`.\n"
).format(sites=repr(urls.keys()))
if isinstance(site_or_index, int):
index = site_or_index
else:
try:
site = site_or_index.casefold()
except Exception: # noqa
session.write_err(invalid_args)
return
else:
if site not in urls:
session.write_err(invalid_args)
return
return open_browser(urls[site])
try:
info = (
session.recorded_tracebacks[index].info
if session.recorded_tracebacks
else {}
)
except IndexError:
session.write_err(_("Invalid index value."))
return
url = urls["friendly"]
if info:
message = info["message"].replace("'", "")
if " (" in message:
message = message.split("(")[0]
url = f"https://duckduckgo.com?q={urllib.parse.quote(message)}"
return open_browser(url)
[docs]def set_debug(flag: bool = True) -> None: # pragma: no cover
"""This sets the value of the debug flag for the current session."""
debug_helper.DEBUG = flag
debug_helper.SHOW_DEBUG_HELPER = flag
get_lang = friendly_traceback.get_lang
set_lang = friendly_traceback.set_lang
get_include = friendly_traceback.get_include
set_include = friendly_traceback.set_include
set_formatter = friendly_traceback.set_formatter
# ===== Debugging functions are not unit tested by choice =====
def _get_statement() -> Optional[Statement]: # pragma: no cover
"""This returns a 'Statement' instance obtained for SyntaxErrors and
subclasses. Such a Statement instance contains essentially all
the known information about the statement where the error occurred.
This is not intended for end-users but is useful in development.
"""
if not session.recorded_tracebacks:
print(_nothing_to_show())
return None
current_tb = session.recorded_tracebacks[-1]
if hasattr(current_tb, "tb_data"):
if isinstance(
session.recorded_tracebacks[-1].tb_data.exception_instance, SyntaxError
):
return session.recorded_tracebacks[-1].tb_data.statement
elif hasattr(current_tb, "problem_statement"):
return current_tb.problem_statement
print("No statement: likely not a SyntaxError nor a SyntaxWarning.")
return None
def _get_tb_data() -> Optional[TracebackData]: # pragma: no cover
"""This returns the TracebackData instance containing all the
information we have obtained.
This is not intended for end-users but is useful in development.
"""
if not session.recorded_tracebacks:
print(_nothing_to_show())
return None
current_tb = session.recorded_tracebacks[-1]
return current_tb.tb_data if hasattr(current_tb, "tb_data") else current_tb
def _get_info() -> list:
"""Debugging tool: returns the content of a traceback info."""
return session.recorded_tracebacks[-1].info if session.recorded_tracebacks else []
def _show_info() -> None: # pragma: no cover
"""Debugging tool: shows the complete content of traceback info.
Prints ``''`` for a given item if it is not present.
"""
info = session.recorded_tracebacks[-1].info if session.recorded_tracebacks else []
for item in base_formatters.items_in_order:
if item in info and info[item].strip():
print(f"{item}:")
for line in info[item].strip().split("\n"):
print(" ", line)
print()
else:
print(f"{item}: ''")
for item in info:
if item not in base_formatters.items_in_order:
print(f"{item}: {info[item]}")
helpers: Dict[str, Callable[..., None]] = {
"why": why,
"what": what,
"where": where,
"www": www,
"explain": explain,
"hint": hint,
"enable": enable,
"disable": disable,
"history": history,
"friendly_tb": friendly_tb,
"python_tb": python_tb,
"show_paths": show_paths,
"get_include": get_include,
"set_include": set_include,
"get_lang": get_lang,
"set_lang": set_lang,
"set_formatter": set_formatter,
"set_debug": set_debug,
}
add_help_attribute(helpers)
debug_helper_methods: Dict[str, Callable[..., Any]] = {
"_get_info": _get_info,
"_get_tb_data": _get_tb_data,
"_get_statement": _get_statement,
}
add_help_attribute(debug_helper_methods)
class FriendlyHelpers:
"""Helper class which can be used in a console as an alternative
to using the helper functions directly.
This can be helpful if one of the helper functions gets redefined.
It is usually instantiated using the name ``Friendly``.
For example, we can write ``Friendly.why()`` as equivalent to ``why()``.
"""
version = __version__
def __init__(self) -> None:
self.helpers = {}
def add_helper(self, function: Callable) -> None: # pragma: no cover
"""Adds a helper base on its name and the function it refers to."""
self.helpers[function.__name__] = function
setattr(self, function.__name__, function)
def remove_helper(self, name: str) -> None: # pragma: no cover
"""Removes a helper from the FriendlyHelpers object"""
if name in self.helpers:
del self.helpers[name]
delattr(self, name)
else:
message = f"Cannot remove {name}; it is not a known helper."
debug_helper.log(message)
def __dir__(self) -> List[str]: # pragma: no cover
"""Only include useful friendly methods."""
return sorted(list(self.helpers))
def __repr__(self) -> str: # pragma: no cover
"""Shows a brief description in the default language of what
each function/method does.
Debugging helper functions are only included if the DEBUG flag is set.
"""
basic_helpers = {}
_debug_helpers = {}
for name in self.helpers:
if name.startswith("_"):
_debug_helpers[name] = self.helpers[name]
else:
basic_helpers[name] = self.helpers[name]
# sort alphabetically, then by length name for nicer display
basic_helpers = sorted(list(basic_helpers))
basic_helpers = sorted(basic_helpers, key=len)
_debug_helpers = sorted(list(_debug_helpers))
_debug_helpers = sorted(_debug_helpers, key=len)
header = _(
"The following methods of the Friendly object should also "
"be available as functions."
)
parts = [self.true_repr() + "\n" + header + "\n\n"]
for name in basic_helpers:
parts.append(name + "(): ")
fn = self.helpers[name]
if hasattr(fn, "help"):
parts.append(fn.help() + "\n")
else:
print("Warning:", name, "has no help() method.")
if debug_helper.SHOW_DEBUG_HELPER:
more_header = "Debugging methods (English only)."
parts.append("\n" + more_header + "\n\n")
for name in _debug_helpers:
parts.append(name + "(): ")
fn = self.helpers[name]
if hasattr(fn, "help"):
parts.append(fn.help() + "\n")
else:
print("Warning:", name, "has no help() method.")
return "".join(parts)
def true_repr(self) -> str: # pragma: no cover
"""Method that can be called when a normal looking repr is needed."""
return "<class FriendlyHelpers>"
Friendly = FriendlyHelpers()
for helper_name in helpers:
Friendly.add_helper(helpers[helper_name])
for helper_name in debug_helper_methods:
Friendly.add_helper(debug_helper_methods[helper_name])
helpers["Friendly"] = Friendly
# We don't include the debug helpers in __all__ so that they do
# not show when doing dir() at a console; we only make them
# available as methods of the Friendly object.
__all__ = list(helpers.keys())