Add argname to retrieve argument names/sources passed to a function (#42)

* Add argname to get names/sources of arguments

* Update docs for argname

* Fix linting

* Fix tests

* Support individual access to positional and keyword arguments for argname

* Update docs

* Update changelog

* Add pure_eval to evalute the function that calls argname

* Take suggestions by Alex

Author: pwwang

README.md

@@ -20,6 +20,7 @@ pip install -U varname
   - Retrieving names of variables a function/class call is assigned to from inside it, using `varname`.
   - Retrieving variable names directly, using `nameof`
   - Detecting next immediate attribute name, using `will`
+  - Fetching argument names/sources passed to a function using `argname`
 
 - Other helper APIs (built based on core features):
 
@@ -256,6 +257,31 @@ awesome.permit() # AttributeError: Should do something with AwesomeClass object
 awesome.permit().do() == 'I am doing!'
 ```
 
+### Fetching argument names/sources using `argname`
+```python
+from varname import argname
+
+def func(a, b=1):
+    print(argname(a))
+
+x = y = z = 2
+func(x) # prints: x
+
+def func2(a, b=1):
+    print(argname(a, b))
+func2(y, b=x) # prints: ('y', 'x')
+
+# allow expressions
+def func3(a, b=1):
+    print(argname(a, b, vars_only=False))
+func3(x+y, y+x) # prints: ('x+y', 'y+x')
+
+# positional and keyword arguments
+def func4(*args, **kwargs):
+    print(argname(args[1], kwargs['c']))
+func4(y, x, c=z) # prints: ('x', 'z')
+```
+
 ### Value wrapper
 
 ```python

README.rst

@@ -63,6 +63,7 @@ Features
   * Retrieving names of variables a function/class call is assigned to from inside it, using ``varname``.
   * Retrieving variable names directly, using ``nameof``
   * Detecting next immediate attribute name, using ``will``
+  * Fetching argument names/sources passed to a function using ``argname``
 
 * 
   Other helper APIs (built based on core features):
@@ -323,6 +324,33 @@ Detecting next immediate attribute name
    awesome.permit() # AttributeError: Should do something with AwesomeClass object
    awesome.permit().do() == 'I am doing!'
 
+Fetching argument names/sources using ``argname``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+   from varname import argname
+
+   def func(a, b=1):
+       print(argname(a))
+
+   x = y = z = 2
+   func(x) # prints: x
+
+   def func2(a, b=1):
+       print(argname(a, b))
+   func2(y, b=x) # prints: ('y', 'x')
+
+   # allow expressions
+   def func3(a, b=1):
+       print(argname(a, b, vars_only=False))
+   func3(x+y, y+x) # prints: ('x+y', 'y+x')
+
+   # positional and keyword arguments
+   def func4(*args, **kwargs):
+       print(argname(args[1], kwargs['c']))
+   func4(y, x, c=z) # prints: ('x', 'z')
+
 Value wrapper
 ^^^^^^^^^^^^^
 

docs/CHANGELOG.md

@@ -1,3 +1,6 @@
+## v0.6.1
+- Add `argname` to retrieve argument names/sources passed to a function
+
 ## v0.6.0
 - Changed:
     - `Wrapper`, `register` and `debug` moved to `varname.helpers`