Ready for v0.4.0

Author: pwwang

README.md

@@ -126,18 +126,12 @@ Thanks goes to these awesome people/projects:
     # Since v0.1.3
     # We can ask varname to raise exceptions
     # if it fails to detect the variable name
-
-    from varname import VarnameRetrievingError
-    def get_name():
-        try:
-            # if raise_exc is False
-            # "var_<index>" will be returned
-            return varname(raise_exc=True)
-        except VarnameRetrieveingError:
-            return None
+    def get_name(raise_exc):
+        return varname(raise_exc=raise_exc)
 
     a = {}
-    a['b'] = get_name() # None
+    a['b'] = get_name(True) # VarnameRetrievingError
+    a['b'] = get_name(False) # None
     ```
 
 ### Value wrapper
@@ -189,7 +183,7 @@ class AwesomeClass:
         self.will = None
 
     def permit(self):
-        self.will = will()
+        self.will = will(raise_exc=False)
         if self.will == 'do':
             # let self handle do
             return self
@@ -239,13 +233,18 @@ b.append(1)
 a == b
 ```
 
-## Limitations
+## Reliability and limitations
 `python-varname` is all depending on `executing` package to look for the node.
-It does not work with any environment where `executing` is not able to detect the node.
+The node `executing` detects is ensured to be the correct one (see [this][19]).
+
+It partially works with environments where other AST magics apply, including
+`pytest`, `ipython`, `macropy`, `birdseye`, `reticulate` with `R`, etc. Neither
+`executing` nor `python-varname` is 100% working with those environments. Use
+it at your own risk.
+
 For example:
 
-- Environments where other AST magics apply. For example: `pytest`, `ipython`, `macropy`, or `birdseye`.
-  This will not work with `pytest`:
+- This will not work with `pytest`:
   ```python
   a = 1
   assert nameof(a) == 'a'
@@ -254,6 +253,13 @@ For example:
   name_a = nameof(a)
   assert name_a == 'a'
   ```
+
+- This will also typically fail with `ipython`:
+  ```python
+  a = 1
+  for _ in [0]:
+      print(nameof(a))
+  ```
 - `R` with `reticulate`.
 
 [1]: https://github.com/pwwang/python-varname
@@ -272,3 +278,4 @@ For example:
 [16]: https://pwwang.github.io/python-varname/CHANGELOG/
 [17]: https://img.shields.io/gitter/room/pwwang/python-varname?style=flat-square
 [18]: https://gitter.im/python-varname/community
+[19]: https://github.com/alexmojaki/executing#is-it-reliable

docs/CHANGELOG.md

@@ -32,3 +32,8 @@
 - Drop support for pytest, don't try to find node when executing fails
 - Remodel `will` for better logic
 - Support attributes in varname and nameof (#14)
+
+## v0.4.0
+- Change default of `raise_exc` to `True` for all related APIs
+- Deprecate `var_0`
+- Get rid of `VarnameRetrievingWarning`.

tests/test_varname.py

@@ -3,8 +3,6 @@
 
 import pytest
 from varname import (varname,
-                     VarnameRetrievingWarning,
-                     MultipleTargetAssignmentWarning,
                      VarnameRetrievingError,
                      Wrapper,
                      will,
@@ -212,18 +210,23 @@ def function():
 
 def test_raise():
 
-    def get_name():
-        return varname(raise_exc=True)
+    def get_name(raise_exc):
+        return varname(raise_exc=raise_exc)
 
     with pytest.raises(VarnameRetrievingError):
-        get_name()
+        get_name(True)
+
+    name = "0"
+    # we can't get it in such way.
+    name += str(get_name(False))
+    assert name == '0None'
 
 def test_multiple_targets():
 
     def function():
         return varname()
 
-    with pytest.warns(MultipleTargetAssignmentWarning):
+    with pytest.warns(UserWarning):
         y = x = function()
     assert y == x == 'y'
 
@@ -237,9 +240,9 @@ def function():
     assert xyz == 'z'
 
     x = 'a'
-    with pytest.warns(VarnameRetrievingWarning):
+    with pytest.raises(VarnameRetrievingError):
         x += function()
-    assert x == 'avar_0'
+    assert x == 'a'
 
     func = function
     x = func()
@@ -431,7 +434,7 @@ def __init__(self):
             self.will = None
 
         def permit(self, *_):
-            self.will = will()
+            self.will = will(raise_exc=False)
             if self.will == 'do':
                 # let self handle do
                 return self
@@ -488,9 +491,8 @@ def func(raise_exc):
     with pytest.raises(VarnameRetrievingError):
         a = func(True)
 
-    with pytest.warns(VarnameRetrievingWarning):
-        b = func(False)
-    assert b.startswith('var_')
+    b = func(False)
+    assert b is None
 
 
 def test_frame_fail_nameof(no_getframe):

varname.py

@@ -11,18 +11,10 @@
 
 __version__ = "0.3.0"
 
-VARNAME_INDEX = [-1]
-
-class MultipleTargetAssignmentWarning(Warning):
-    """When multiple-target assignment found, i.e. y = x = func()"""
-
-class VarnameRetrievingWarning(Warning):
-    """When varname retrieving failed for whatever reason"""
-
 class VarnameRetrievingError(Exception):
     """When failed to retrieve the varname"""
 
-def varname(caller: int = 1, raise_exc: bool = False) -> str:
+def varname(caller: int = 1, raise_exc: bool = True) -> str:
     """Get the variable name that assigned by function/class calls
 
     Args:
@@ -32,9 +24,7 @@ def varname(caller: int = 1, raise_exc: bool = False) -> str:
             to retrieve the name.
 
     Returns:
-        str|None: The variable name, or
-            `var_<index>` (will be deprecated in `v0.4.0`) if failed.
-            It returns `None` when `raise_exc` is `False` and
+        str|None: The variable name, or `None` when `raise_exc` is `False` and
             we failed to retrieve the variable name.
 
     Raises:
@@ -44,44 +34,34 @@ def varname(caller: int = 1, raise_exc: bool = False) -> str:
             is set to `True`.
 
     Warns:
-        MultipleTargetAssignmentWarning: When there are multiple target
+        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)
-        VarnameRetrievingWarning: When `var_0` and alike returned.
-            This will be deprecated in `v0.4.0`
     """
     node = _get_node(caller)
     if not node:
         if raise_exc:
             raise VarnameRetrievingError("Unable to retrieve the ast node.")
-        VARNAME_INDEX[0] += 1
-        warnings.warn(f"var_{VARNAME_INDEX[0]} used, "
-                      "which will be deprecated in v0.4.0",
-                      VarnameRetrievingWarning)
-        return f"var_{VARNAME_INDEX[0]}"
+        return None
 
     node = _lookfor_parent_assign(node)
     if not node:
         if raise_exc:
             raise VarnameRetrievingError(
                 'Failed to retrieve the variable name.'
             )
-        VARNAME_INDEX[0] += 1
-        warnings.warn(f"var_{VARNAME_INDEX[0]} used, "
-                      "which will be deprecated in v0.4.0",
-                      VarnameRetrievingWarning)
-        return f"var_{VARNAME_INDEX[0]}"
+        return None
 
     # Need to actually check that there's just one
     # give warnings if: a = b = func()
     if len(node.targets) > 1:
         warnings.warn("Multiple targets in assignment, variable name "
                       "on the very left will be used.",
-                      MultipleTargetAssignmentWarning)
+                      UserWarning)
     target = node.targets[0]
     return _node_name(target)
 
-def will(caller: int = 1, raise_exc: bool = False) -> str:
+def will(caller: int = 1, raise_exc: bool = True) -> str:
     """Detect the attribute name right immediately after a function call.
 
     Examples:
@@ -259,7 +239,7 @@ class Wrapper:
         value (any): The value this wrapper wraps
     """
 
-    def __init__(self, value: any, raise_exc: bool = False):
+    def __init__(self, value: any, raise_exc: bool = True):
         self.name: str = varname(raise_exc=raise_exc)
         self.value: any = value