0.6.4 (#50)

* Add ImproperUseError to distinguish node retrieving error from improper varname use #49

* 0.6.4

* Update CHANGELOG

Author: pwwang

.pylintrc

@@ -157,7 +157,8 @@ disable=print-statement,
         too-many-locals,
         not-callable,
         unsubscriptable-object,
-        unused-arguments
+        unused-arguments,
+        fixme
 
 # Enable the message, report, category or checker with the given id(s). You can
 # either give multiple identifier separated by comma (,) or put this option
@@ -306,12 +307,20 @@ function-naming-style=snake_case
 #function-rgx=
 
 # Good variable names which should always be accepted, separated by a comma.
-good-names=i,
+good-names=a,
+           b,
+           c,
+           i,
            j,
            k,
+           n,
            x,
            y,
            z,
+           fn,
+           df,
+           pd,
+           sd,
            np,
            gc,
            nn,
@@ -327,6 +336,7 @@ good-names=i,
            tf,
            on,
            op,
+           wt,
            Run,
            _
 
@@ -457,7 +467,7 @@ indent-string='    '
 max-line-length=80
 
 # Maximum number of lines in a module.
-max-module-lines=1000
+max-module-lines=1500
 
 # List of optional constructs for which whitespace checking is disabled. `dict-
 # separator` is used to allow tabulation in dicts, etc.: {1  : 1,\n222: 2}.

README.rst

@@ -155,11 +155,6 @@ Retrieving the variable names using ``varname(...)``
 
        func = asyncio.run(function()) # func == 'func'
 
-       # you can switch it off by:
-       # config.ignore_stdlib = False
-       # then you have to specify the library yourself:
-       # varname(ignore=[asyncio])
-
 * 
   Retrieving name of a class instance
 

docs/CHANGELOG.md

@@ -1,3 +1,6 @@
+## v0.6.4
+- Add ImproperUseError to distinguish node retrieving error from improper varname use #49
+
 ## v0.6.3
 - Fix standard library ignoring ignores 3rd-party libraries under site-packages/
 - Allow pathlib.Path object to be used in ignore items

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.masonry.api"
 
 [tool.poetry]
 name = "varname"
-version = "0.6.3"
+version = "0.6.4"
 description = "Dark magics about variable names in python."
 authors = [ "pwwang <pwwang@pwwang.com>",]
 license = "MIT"

setup.py

@@ -24,7 +24,7 @@
 setup(
     long_description=readme,
     name='varname',
-    version='0.6.3',
+    version='0.6.4',
     description='Dark magics about variable names in python.',
     python_requires='==3.*,>=3.6.0',
     project_urls={"homepage": "https://github.com/pwwang/python-varname",

tests/test_varname.py

@@ -7,7 +7,7 @@
 from executing import Source
 from varname import *
 from varname.helpers import *
-from varname.utils import get_node
+from varname.utils import ImproperUseError, get_node
 
 
 from .conftest import run_async, module_from_source
@@ -93,11 +93,11 @@ def test_single_var_lhs_required():
     def function():
         return varname()
 
-    with pytest.raises(VarnameRetrievingError,
+    with pytest.raises(ImproperUseError,
                        match='Expect a single variable on left-hand side'):
         x, y = function()
 
-    with pytest.raises(VarnameRetrievingError):
+    with pytest.raises(ImproperUseError):
         x, y = function(), function()
 
 def test_multi_vars_lhs():
@@ -122,7 +122,7 @@ def function():
 
     # Not all LHS are variables
     with pytest.raises(
-        VarnameRetrievingError,
+        ImproperUseError,
         match='Can only get name of a variable or attribute, not Starred'
     ):
         a, *b = function()

varname/__init__.py

@@ -3,11 +3,12 @@
 from .utils import (
     config,
     VarnameRetrievingError,
+    ImproperUseError,
     QualnameNonUniqueError,
     NonVariableArgumentError,
     MultiTargetAssignmentWarning,
     MaybeDecoratedFunctionWarning
 )
 from .core import varname, nameof, will, argname
 
-__version__ = "0.6.3"
+__version__ = "0.6.4"

varname/core.py

@@ -15,6 +15,7 @@
     get_function_called_argname,
     parse_argname_subscript,
     VarnameRetrievingError,
+    ImproperUseError,
     NonVariableArgumentError,
     MultiTargetAssignmentWarning
 )
@@ -62,9 +63,12 @@ class instantiation.
             If `True`, this function returns a tuple of the variable names,
             even there is only one variable on LHS.
             If `False`, and multiple variables on LHS, a
-            `VarnameRetrievingError` will be raised.
+            `ImproperUseError` will be raised.
         raise_exc: Whether we should raise an exception if failed
-            to retrieve the name.
+            to retrieve the ast node.
+            Note that set this to `False` will not supress the exception when
+            the use of `varname` is improper (i.e. multiple variables on
+            LHS with `multi_vars` is `False`). See `Raises/ImproperUseError`.
 
     Returns:
         The variable name, or `None` when `raise_exc` is `False` and
@@ -78,6 +82,11 @@ class instantiation.
             when we are unable to retrieve the variable name and `raise_exc`
             is set to `True`.
 
+        ImproperUseError: When the use of `varname()` is improper. For example:
+            - When LHS is not an `ast.Name` or `ast.Attribute` node or not a
+                list/tuple of them
+            - When there are multiple variables on LHS but `multi_vars` is False
+
         UserWarning: When there are multiple target
             in the assign node. (e.g: `a = b = func()`, in such a case,
             `b == 'a'`, may not be the case you want)
@@ -118,7 +127,7 @@ class instantiation.
         return names
 
     if len(names) > 1:
-        raise VarnameRetrievingError(
+        raise ImproperUseError(
             f"Expect a single variable on left-hand side, got {len(names)}."
         )
 

varname/utils.py

@@ -59,13 +59,27 @@ class NonVariableArgumentError(Exception):
     """When vars_only is True but try to retrieve name of
     a non-variable argument"""
 
+class ImproperUseError(VarnameRetrievingError):
+    """When varname() is improperly used"""
+    def __init__(self, message: str) -> None:
+        message = (
+            f"{message}\n\n"
+            "(Warning: `ImproperUseError` is a subclass of "
+            "`VarnameRetrievingError` for now for backward compatibility, "
+            "so you can still use `VarnameRetrievingError` to catch it. "
+            "But it will be independent of `VarnameRetrievingError` "
+            "in the future.)"
+        )
+        super().__init__(message)
+
 class MaybeDecoratedFunctionWarning(Warning):
     """When a suspecious decorated function used as ignore function directly"""
 
 class MultiTargetAssignmentWarning(Warning):
     """When varname tries to retrieve variable name in
     a multi-target assignment"""
 
+
 @lru_cache()
 def cached_getmodule(codeobj: CodeType):
     """Cached version of inspect.getmodule"""
@@ -125,7 +139,7 @@ def lookfor_parent_assign(node: ast.AST) -> Optional[ast.Assign]:
 def node_name(node: ast.AST) -> Optional[Union[str, Tuple[Union[str, tuple]]]]:
     """Get the node node name.
 
-    Raises VarnameRetrievingError when failed
+    Raises ImproperUseError when failed
     """
     if isinstance(node, ast.Name):
         return node.id
@@ -134,7 +148,7 @@ def node_name(node: ast.AST) -> Optional[Union[str, Tuple[Union[str, tuple]]]]:
     if isinstance(node, (ast.List, ast.Tuple)):
         return tuple(node_name(elem) for elem in node.elts)
 
-    raise VarnameRetrievingError(
+    raise ImproperUseError(
         f"Can only get name of a variable or attribute, "
         f"not {ast.dump(node)}"
     )