0.7.3 (#61)

* Get richer information for ImproperUseError: #60 * Add VarnameException and VarnameWarning as root for all varname-defined exceptions and warnings. * Add mypy check pre-commit * Add mypy check to CI

Author: pwwang

.github/workflows/build.yml

@@ -25,9 +25,12 @@ jobs:
  run: |
  python -m pip install --upgrade pip
  python -m pip install pylint=='2.8.*'
+ python -m pip install mypy
  python -m pip install poetry
  poetry config virtualenvs.create false
  poetry install -v
+ - name: Run mypy check
+ run: mypy -p varname
  - name: Run pylint
  run: pylint varname
  - name: Test with pytest

.pre-commit-config.yaml

@@ -40,6 +40,14 @@ repos:
  language: system
  files: pyproject.toml
  pass_filenames: false
+ - id: mypycheck
+ name: Type checking by mypy
+ entry: mypy
+ language: system
+ files: ^pipda/.+$
+ pass_filenames: false
+ types: [python]
+ args: [-p, varname]
  - id: pytest
  name: Run pytest
  entry: pytest

varname/core.py

@@ -15,6 +15,7 @@
  get_argument_sources,
  get_function_called_argname,
  parse_argname_subscript,
+ rich_exc_message,
  ArgSourceType,
  VarnameRetrievingError,
  ImproperUseError,
@@ -104,13 +105,13 @@ class instantiation.
 
  # Skip one more frame, as it is supposed to be called
  # inside another function
- node = get_node(frame + 1, ignore, raise_exc=raise_exc)
- if not node:
+ refnode = get_node(frame + 1, ignore, raise_exc=raise_exc)
+ if not refnode:
  if raise_exc:
  raise VarnameRetrievingError("Unable to retrieve the ast node.")
  return None
 
- node = lookfor_parent_assign(node, strict=strict)
+ node = lookfor_parent_assign(refnode, strict=strict)
  if not node:
  if strict and not strict_given:
  warnings.warn(
@@ -134,7 +135,7 @@ class instantiation.
  msg = "Expression is not the direct RHS of an assignment."
  else:
  msg = "Expression is not part of an assignment."
- raise ImproperUseError(msg)
+ raise ImproperUseError(rich_exc_message(msg, refnode))
  return None
 
  if isinstance(node, ast.Assign):
@@ -161,7 +162,11 @@ class instantiation.
 
  if len(names) > 1:
  raise ImproperUseError(
- f"Expect a single variable on left-hand side, got {len(names)}."
+ rich_exc_message(
+ "Expect a single variable on left-hand side, "
+ f"got {len(names)}.",
+ refnode,
+ )
  )
 
  return names[0]
@@ -539,8 +544,12 @@ def argname2(
  If False, `asttokens` is required to retrieve the source.
 
  Returns:
- Scalar string if
+ The argument source when no more_args passed, otherwise a tuple of
+ argument sources
 
+ Raises:
+ VarnameRetrievingError: When the ast node where the function is called
+ cannot be retrieved
  """
  ignore_list = IgnoreList.create(
  ignore,
@@ -579,7 +588,7 @@ def argname2(
  vars_only=vars_only,
  pos_only=False,
  )
- except Exception as err: # pragma: no cover
+ except Exception as err:  # pragma: no cover
  # find a test case?
  raise VarnameRetrievingError(
  "Have you specified the right `frame`?"

varname/helpers.py

@@ -184,7 +184,7 @@ def debug(
  values = (var, *more_vars)
  name_and_values = [
  f"{var_name}{sep}{value!r}" if repr else f"{var_name}{sep}{value}"
- for var_name, value in zip(var_names, values) # type: ignore
+ for var_name, value in zip(var_names, values)  # type: ignore
  ]
 
  if merge:

varname/ignore.py

@@ -41,6 +41,7 @@
  debug_ignore_frame,
 )
 
+
 class IgnoreElem(ABC):
  """An element of the ignore list"""
 
@@ -66,7 +67,7 @@ def subclass_init(
 
  # save it for __repr__
  cls.attrs = attrs
- cls.__init__ = subclass_init # type: ignore
+ cls.__init__ = subclass_init  # type: ignore
 
  def _post_init(self) -> None:
  """Setups after __init__"""
@@ -127,7 +128,7 @@ def _post_init(self) -> None:
  # pylint: disable=attribute-defined-outside-init
 
  # Path object will turn into str here
- self.dirname = path.realpath(self.dirname) # type: str
+ self.dirname = path.realpath(self.dirname)  # type: str
 
  if not self.dirname.endswith(path.sep):
  self.dirname = f"{self.dirname}{path.sep}"
@@ -264,23 +265,23 @@ def create_ignore_elem(ignore_elem: IgnoreElemType) -> IgnoreElem:
  return (
  IgnoreDirname(ignore_elem) # type: ignore
  if path.isdir(ignore_elem)
- else IgnoreFilename(ignore_elem) # type: ignore
+ else IgnoreFilename(ignore_elem)  # type: ignore
  )
  if hasattr(ignore_elem, "__code__"):
- return IgnoreFunction(ignore_elem) # type: ignore
+ return IgnoreFunction(ignore_elem)  # type: ignore
  if not isinstance(ignore_elem, tuple) or len(ignore_elem) != 2:
  raise ValueError(f"Unexpected ignore item: {ignore_elem!r}")
  # is tuple and len == 2
  if hasattr(ignore_elem[0], "__code__") and isinstance(ignore_elem[1], int):
- return IgnoreDecorated(*ignore_elem) # type: ignore
+ return IgnoreDecorated(*ignore_elem)  # type: ignore
  # otherwise, the second element should be qualname
  if not isinstance(ignore_elem[1], str):
  raise ValueError(f"Unexpected ignore item: {ignore_elem!r}")
 
  if isinstance(ignore_elem[0], ModuleType):
- return IgnoreModuleQualname(*ignore_elem) # type: ignore
+ return IgnoreModuleQualname(*ignore_elem)  # type: ignore
  if isinstance(ignore_elem[0], (Path, str)):
- return IgnoreFilenameQualname(*ignore_elem) # type: ignore
+ return IgnoreFilenameQualname(*ignore_elem)  # type: ignore
  if ignore_elem[0] is None:
  return IgnoreOnlyQualname(*ignore_elem)
 
@@ -316,24 +317,22 @@ def create(
  ignore = [ignore]
 
  ignore_list = [
- IgnoreStdlib( # type: ignore
+ IgnoreStdlib(  # type: ignore
  sysconfig.get_python_lib(standard_lib=True)
  )
- ] # type: List[IgnoreElem]
+ ]  # type: List[IgnoreElem]
  if ignore_varname:
  ignore_list.append(create_ignore_elem(sys.modules[__package__]))
  if ignore_lambda:
  ignore_list.append(create_ignore_elem((None, "*<lambda>")))
  for ignore_elem in ignore:
  ignore_list.append(create_ignore_elem(ignore_elem))
 
- return cls(ignore_list) # type: ignore
+ return cls(ignore_list)  # type: ignore
 
  def __init__(self, ignore_list: List[IgnoreElemType]) -> None:
  self.ignore_list = ignore_list
- debug_ignore_frame(
- '>>> IgnoreList initiated <<<'
- )
+ debug_ignore_frame(">>> IgnoreList initiated <<<")
 
  def nextframe_to_check(
  self, frame_no: int, frameinfos: List[inspect.FrameInfo]
@@ -352,7 +351,7 @@ def nextframe_to_check(
  A number for Next `N`th frame to check. 0 if no frame matched.
  """
  for ignore_elem in self.ignore_list:
- matched = ignore_elem.match(frame_no, frameinfos) # type: ignore
+ matched = ignore_elem.match(frame_no, frameinfos)  # type: ignore
  if matched and isinstance(ignore_elem, IgnoreDecorated):
  debug_ignore_frame(
  f"Ignored by {ignore_elem!r}", frameinfos[frame_no]
@@ -406,4 +405,4 @@ def get_frame(self, frame_no: int) -> FrameType:
 
  raise VarnameRetrievingError from exc
 
- return None # pragma: no cover
+ return None  # pragma: no cover

varname/utils.py

@@ -44,10 +44,10 @@
 
 if sys.version_info >= (3, 8):
  ASSIGN_TYPES = (ast.Assign, ast.AnnAssign, ast.NamedExpr)
- AssignType = Union[ASSIGN_TYPES]
-else: # pragma: no cover
+ AssignType = Union[ASSIGN_TYPES] # type: ignore
+else:  # pragma: no cover
  ASSIGN_TYPES = (ast.Assign, ast.AnnAssign)
- AssignType = Union[ASSIGN_TYPES]
+ AssignType = Union[ASSIGN_TYPES] # type: ignore
 
 MODULE_IGNORE_ID_NAME = "__varname_ignore_id__"
 
@@ -62,29 +62,37 @@ class config: # pylint: disable=invalid-name
  debug = False
 
 
-class VarnameRetrievingError(Exception):
+class VarnameException(Exception):
+ """Root exception for all varname exceptions"""
+
+
+class VarnameRetrievingError(VarnameException):
  """When failed to retrieve the varname"""
 
 
-class QualnameNonUniqueError(Exception):
+class QualnameNonUniqueError(VarnameException):
  """When a qualified name is used as an ignore element but references to
  multiple objects in a module"""
 
 
-class NonVariableArgumentError(Exception):
+class NonVariableArgumentError(VarnameException):
  """When vars_only is True but try to retrieve name of
  a non-variable argument"""
 
 
-class ImproperUseError(Exception):
+class ImproperUseError(VarnameException):
  """When varname() is improperly used"""
 
 
-class MaybeDecoratedFunctionWarning(Warning):
+class VarnameWarning(Warning):
+ """Root warning for all varname warnings"""
+
+
+class MaybeDecoratedFunctionWarning(VarnameWarning):
  """When a suspecious decorated function used as ignore function directly"""
 
 
-class MultiTargetAssignmentWarning(Warning):
+class MultiTargetAssignmentWarning(VarnameWarning):
  """When varname tries to retrieve variable name in
  a multi-target assignment"""
 
@@ -120,13 +128,14 @@ def get_node(
  return get_node_by_frame(frameobj, raise_exc)
 
 
-def get_node_by_frame(
- frame: FrameType, raise_exc: bool = True
-) -> ast.AST:
+def get_node_by_frame(frame: FrameType, raise_exc: bool = True) -> ast.AST:
  """Get the node by frame, raise errors if possible"""
  exect = Source.executing(frame)
 
  if exect.node:
+ # attach the frame for better exception message
+ # (ie. where ImproperUseError happens)
+ exect.node.__frame__ = frame
  return exect.node
 
  if exect.source.text and exect.source.tree and raise_exc:
@@ -257,10 +266,7 @@ def check_qualname_by_source(
  )
 
 
-def debug_ignore_frame(
- msg: str,
- frameinfo: inspect.FrameInfo = None
-) -> None:
+def debug_ignore_frame(msg: str, frameinfo: inspect.FrameInfo = None) -> None:
  """Print the debug message for a given frame info object
 
  Args:
@@ -415,9 +421,9 @@ def parse_argname_subscript(node: ast.Subscript):
  if not isinstance(name, ast.Name):
  raise ValueError(f"Expect {ast.dump(name)} to be a variable.")
 
- subscript = node.slice # type: ast.AST
+ subscript = node.slice  # type: ast.AST
  if isinstance(subscript, ast.Index):
- subscript = subscript.value # pragma: no cover
+ subscript = subscript.value  # pragma: no cover
  if not isinstance(subscript, (ast.Str, ast.Num, ast.Constant)):
  raise ValueError(f"Expect {ast.dump(subscript)} to be a constant.")
 
@@ -428,3 +434,40 @@ def parse_argname_subscript(node: ast.Subscript):
  subscript = getattr(subscript, "s", subscript) # ast.Str
 
  return name.id, subscript
+
+
+def rich_exc_message(msg: str, node: ast.AST) -> str:
+ """Attach the source code from the node to message to
+ get a rich message for exceptions
+
+ If package 'rich' is not install or 'node.__frame__' doesn't exist, fall
+ to plain message (with basic information), otherwise show a better message
+ with full information
+ """
+ frame = node.__frame__ # type: FrameType
+ lineno = node.lineno # type: int
+ col_offset = node.col_offset # type: int
+ filename = frame.f_code.co_filename # type: str
+ lines, startlineno = inspect.getsourcelines(frame)
+ line_range = (startlineno + 1, startlineno + len(lines) + 1)
+ if startlineno == 0:
+ # wired shift
+ lineno -= 1 # pragma: no cover
+
+ linenos = tuple(map(str, range(*line_range))) # type: Tuple[str, ...]
+ lineno_width = max(map(len, linenos)) # type: int
+ hiline = lineno - startlineno # type: int
+ codes = [] # type: List[str]
+ for i, lno in enumerate(linenos):
+ lno = lno.ljust(lineno_width)
+ if i == hiline:
+ codes.append(f" > | {lno} {lines[i]}")
+ codes.append(f" | {' ' * (lineno_width + col_offset + 2)}^\n")
+ else:
+ codes.append(f" | {lno} {lines[i]}")
+
+ return (
+ f"{msg}\n\n"
+ f" {filename}:{lineno+1}:{col_offset+1}\n"
+ f"{''.join(codes)}\n"
+ )