"""path_info.py
In many places, by default we exclude the files from this package,
thus restricting tracebacks to code written by the users.
If Friendly-traceback is used by some other program,
it might be desirable to exclude additional files.
"""
import os
import asttokens # Only use it to find site-packages
EXCLUDED_FILE_PATH = set()
EXCLUDED_DIR_NAMES = set()
SITE_PACKAGES = os.path.abspath(os.path.join(os.path.dirname(asttokens.__file__), ".."))
FRIENDLY = os.path.abspath(os.path.dirname(__file__))
TESTS = os.path.abspath(os.path.join(FRIENDLY, "..", "tests"))
def exclude_file_from_traceback(full_path):
"""Exclude a file from appearing in a traceback generated by
Friendly-traceback. Note that this does not apply to
the true Python traceback obtained using "debug_tb".
"""
if not os.path.isfile(full_path):
raise RuntimeError(
f"{full_path} is not a valid file path; it cannot be excluded."
)
# full_path could be a pathlib.Path instance
full_path = str(full_path)
EXCLUDED_FILE_PATH.add(full_path)
def exclude_directory_from_traceback(dir_name):
"""Exclude all files found in a given directory, including sub-directories,
from appearing in a traceback generated by Friendly.
Note that this does not apply to the true Python traceback
obtained using "debug_tb".
"""
if not os.path.isdir(dir_name):
raise RuntimeError(f"{dir_name} is not a directory; it cannot be excluded.")
# dir_name could be a pathlib.Path instance.
dir_name = str(dir_name)
# Suppose we have dir_name = "this/path" instead of "this/path/".
# Later, when we want to exclude a directory, we get the following file path:
# "this/path2/name.py". If we don't append the ending "/", we would exclude
# this file by error in is_excluded_file below.
if dir_name[-1] != os.path.sep:
dir_name += os.path.sep
EXCLUDED_DIR_NAMES.add(dir_name)
dirname = os.path.abspath(os.path.dirname(__file__))
exclude_directory_from_traceback(dirname)
def is_excluded_file(full_path):
"""Determines if the file belongs to the group that is excluded from tracebacks."""
if full_path.startswith("<frozen "):
return True
# full_path could be a pathlib.Path instance
full_path = str(full_path)
for dirs in EXCLUDED_DIR_NAMES:
if full_path.startswith(dirs):
return True
return full_path in EXCLUDED_FILE_PATH
def include_file_in_traceback(full_path):
"""Reverses the effect of ``exclude_file_from_traceback()`` so that
the file can potentially appear in later tracebacks generated
by Friendly-traceback.
A typical pattern might be something like::
import some_module
revert = not is_excluded_file(some_module.__file__)
if revert:
exclude_file_from_traceback(some_module.__file__)
try:
some_module.do_something(...)
except Exception:
friendly.explain_traceback()
finally:
if revert:
include_file_in_traceback(some_module.__file__)
"""
EXCLUDED_FILE_PATH.discard(full_path)
class PathUtil:
def __init__(self):
self.python = os.path.abspath(os.path.dirname(os.__file__))
self.home = os.path.expanduser("~")
def shorten_path(self, path): # pragma: no cover
if path is None: # can happen in some rare cases
return path
path = path.replace("'", "") # We might get passed a path repr
path = os.path.abspath(path)
path_lower = path.lower()
if "<SyntaxError>" in path: # with IDLE's latest hack
# see https://bugs.python.org/issue43476
path = "<SyntaxError>"
elif "<pyshell#" in path:
path = "<pyshell#" + path.split("<pyshell#")[1]
elif "<ipython-input-" in path:
parts = path.split("<ipython")
parts = parts[1].split("-")
path = "[" + parts[-2] + "]"
elif "<friendly-console:" in path:
path = "<friendly-console:" + path.split("<friendly-console:")[1]
elif path_lower.startswith(SITE_PACKAGES.lower()):
path = "LOCAL:" + path[len(SITE_PACKAGES) :]
elif path_lower.startswith(self.python.lower()):
path = "PYTHON_LIB:" + path[len(self.python) :]
elif path_lower.startswith(FRIENDLY.lower()):
path = "FRIENDLY:" + path[len(FRIENDLY) :]
elif path_lower.startswith(TESTS.lower()):
path = "TESTS:" + path[len(TESTS) :]
elif path_lower.startswith(self.home.lower()):
path = "HOME:" + path[len(self.home) :]
return path
path_utils = PathUtil()
[docs]def show_paths(): # pragma: no cover
"""To avoid displaying very long file paths to the user,
Friendly-traceback tries to shorten them using some easily
recognized synonyms. This function shows the path synonyms
currently used.
"""
print("HOME =", path_utils.home)
print("LOCAL =", SITE_PACKAGES)
print("PYTHON_LIB =", path_utils.python)
if FRIENDLY != SITE_PACKAGES:
print("FRIENDLY = ", FRIENDLY)