0.6.0 (#39)

* Init 0.6.0 in changelog

* Close #36

* Fix #35

* Close #34

* Fix linting

* Open ignore to Wrapper and register.

* Update README and Changelog

* Fix typo in README

* Allow ignore to work with modules when source code is not retrievable.

* Allow functions in ignore

* Refactor to separate ignore functionality.

* Rename varname/varname.py to varname/core.py

* Update config files

* Allow regex for qualname matching in ignore

* Ignore standard libraries by default.

* Warn when a potential decorated function used directly as an ignore element

* Warn when a suspicious decorated function used as ignore element directly

* Use fnmatch instead of re for qualname matching for ignore; Check realpath instead of raw for module filename check for ignore.

* Split IgnoreModule

* Update docs.

* Split IgnoreQualname

* Update docs.

* Try adding python3.9 in CI

* Update pylintrc

* Apply suggestions from code review

Co-authored-by: Alex Hall <alex.mojaki@gmail.com>

* Take suggestions by Alex in the PR.

* Take suggestions by Alex in the PR.

* Add __varname_ignore_id__ to the module of module-qname ignore pair.

* Take suggestions by Alex in the PR.

* Submit README.rst, converted by dephell

* Fix a typo in test

* Change argument module to modname for utils.check_qualname_by_source

* Add lru_cache to check_qualname_by_source

* Initiate the playground

* Finish playground

* Add qualname uniqueness check for IgnoreFilenameQualname

* Uniform __repr__ and simplify subclass_init for IgnoreElem subclasses

* Update varname/ignore.py

Co-authored-by: Alex Hall <alex.mojaki@gmail.com>

* Update varname/ignore.py

Co-authored-by: Alex Hall <alex.mojaki@gmail.com>

Co-authored-by: Alex Hall <alex.mojaki@gmail.com>

Author: pwwang

.github/workflows/build.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.6, 3.7, 3.8, 3.9]
 
     steps:
       - uses: actions/checkout@v2
@@ -23,7 +23,7 @@ jobs:
           python -m pip install poetry
           poetry install -v
       - name: Run pylint
-        run: pylint varname.py
+        run: pylint varname
       - name: Test with pytest
         run: poetry run pytest tests/ --junitxml=junit/test-results-${{ matrix.python-version }}.xml
       - name: Upload pytest test results

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
     rev: v2.4.4
     hooks:
     -   id: pylint
-        files: ^varname.py$
+        files: ^varname/.+$
         pass_filenames: false
         types: [python]
         args: [varname]
@@ -46,4 +46,4 @@ repos:
         language: system
         args: [tests/]
         pass_filenames: false
-        files: ^tests/.+$|^varname.py$
+        files: ^tests/.+$|^varname/.+$

.pylintrc

@@ -155,7 +155,8 @@ disable=print-statement,
         too-many-arguments,
         too-many-return-statements,
         too-many-locals,
-        not-callable
+        not-callable,
+        unsubscriptable-object
 
 # 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

.tagitrc

@@ -12,7 +12,7 @@ checksource = py:False
 checktoml = py:False
 
 ; The source file or the package name.
-versource = varname.py
+versource = varname
 
 ; The toml file, typically pyproject.toml.
 vertoml = ./pyproject.toml

README.md

@@ -6,21 +6,26 @@
 
 Dark magics about variable names in python
 
-[Change Log][16] | [API][15]
+[Change Log][16] | [API][15] | [Playground][11]
 
 ## Installation
 ```shell
-pip install varname
+pip install -U varname
 ```
 
 ## Features
 
-- Fetching variable names from inside the function/class call using `varname`
-- Fetching variable names directly using `nameof`
-- A value wrapper to store the variable name that a value is assigned to using `Wrapper`
-- Detecting next immediate attribute name using `will`
-- Injecting `__varname__` to classes
-- A `debug` function to print variables with their names and values.
+- Core 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`
+
+- Other helper APIs (built based on core features):
+
+  - A value wrapper to store the variable name that a value is assigned to, using `Wrapper`
+  - A decorator to register `__varname__` to functions/classes, using `register`
+  - A `debug` function to print variables with their names and values
 
 ## Credits
 
@@ -47,9 +52,10 @@ Special thanks to [@HanyuuLu][2] to give up the name `varname` in pypi for this
 
 ## Usage
 
-### Retrieving the variable names from inside a function call/class instantiation
+### Retrieving the variable names using `varname(...)`
+
+- From inside a function
 
-- From inside a function call
     ```python
     from varname import varname
     def function():
@@ -58,45 +64,40 @@ Special thanks to [@HanyuuLu][2] to give up the name `varname` in pypi for this
     func = function()  # func == 'func'
     ```
 
--  `varname` calls being buried deeply
-
+    When there are intermediate frames:
     ```python
-    def function():
-        # I know that at which frame this will be called
-        return varname(3)
-        # with v0.5.6+ now you can also specify a list of intermediate
-        # calls to be ignored in counting:
-        # module = sys.modules[__name__]
-        # return varname(ignore=[(module, 'function1'), (module, 'function2)])
-
-    def function1():
+    def wrapped():
         return function()
 
-    def function2():
-        return function1()
+    def function():
+        # retrieve the variable name at the 2nd frame from this one
+        return varname(frame=2)
 
-    func = function2()  # func == 'func'
+    func = wrapped() # func == 'func'
     ```
 
-- `varname` in type annotation or async context
+    Or use `ignore` to ignore the wrapped frame:
     ```python
-    import typing
-    class Foo:
-        def __init__(self):
-            self.id = varname(ignore=[typing])
+    def wrapped():
+        return function()
+
+    def function():
+        return varname(ignore=wrapped)
 
-    foo: Foo = Foo() # foo.id == 'foo'
+    func = wrapped() # func == 'func'
     ```
 
+    Calls from standard libraries are ignored by default:
     ```python
     import asyncio
-    async def func():
-        return varname(ignore=[asyncio])
 
-    x = asyncio.run(func()) # x == 'x'
+    async def function():
+        return varname()
+
+    func = asyncio.run(function()) # func == 'func'
     ```
 
-- Retrieving instance name of a class
+- Retrieving name of a class instance
 
     ```python
     class Foo:
@@ -109,17 +110,15 @@ Special thanks to [@HanyuuLu][2] to give up the name `varname` in pypi for this
             copied.id = varname() # assign id to whatever variable name
             return copied
 
-    k = Foo()   # k.id == 'k'
-    # see also register __varname__ to classes
+    foo = Foo()   # foo.id == 'foo'
 
-    k2 = k.copy() # k2.id == 'k2'
+    foo2 = foo.copy() # foo2.id == 'foo2'
     ```
 
 - Multiple variables on Left-hand side
 
     ```python
     # since v0.5.4
-
     def func():
         return varname(multi_vars=True)
 
@@ -134,14 +133,17 @@ Special thanks to [@HanyuuLu][2] to give up the name `varname` in pypi for this
 - Some unusual use
 
     ```python
+    def function():
+        return varname()
+
     func = [function()]    # func == ['func']
 
     func = [function(), function()] # func == ['func', 'func']
 
     func = function(), function()   # func = ('func', 'func')
 
     func = func1 = function()  # func == func1 == 'func'
-    # a warning will be printed
+    # a warning will be shown
     # since you may not want func1 to be 'func'
 
     x = func(y = func())  # x == 'x'
@@ -167,26 +169,44 @@ Special thanks to [@HanyuuLu][2] to give up the name `varname` in pypi for this
     a['b'] = get_name(False) # None
     ```
 
-### Value wrapper
+### The decorator way to register `__varname__` to functions/classes
 
-```python
-from varname import Wrapper
+- Registering `__varname__` to functions
 
-foo = Wrapper(True)
-# foo.name == 'foo'
-# foo.value == True
-bar = Wrapper(False)
-# bar.name == 'bar'
-# bar.value == False
+    ```python
+    from varname.helpers import register
 
-def values_to_dict(*args):
-    return {val.name: val.value for val in args}
+    @register
+    def function():
+        return __varname__
 
-mydict = values_to_dict(foo, bar)
-# {'foo': True, 'bar': False}
-```
+    func = function() # func == 'func'
+    ```
+
+    ```python
+    # arguments also allowed (frame, ignore and raise_exc)
+    @register(frame=2)
+    def function():
+        return __varname__
+
+    def wrapped():
+        return function()
+
+    func = wrapped() # func == 'func'
+    ```
+
+- Registering `__varname__` as a class property
+
+    ```python
+    @register
+    class Foo:
+        ...
+
+    foo = Foo()
+    # foo.__varname__ == 'foo'
+    ```
 
-### Getting variable names directly
+### Getting variable names directly using `nameof`
 
 ```python
 from varname import varname, nameof
@@ -236,25 +256,29 @@ awesome.permit() # AttributeError: Should do something with AwesomeClass object
 awesome.permit().do() == 'I am doing!'
 ```
 
-### Register `__varname__` to classes
+### Value wrapper
 
 ```python
-from varname import register
-
-@register
-class Dict(dict):
-    pass
-
-a = Dict(a=1)
-b = Dict(b=2)
-a.__varname__ == 'a'
-b.__varname__ == 'b'
-a.update(b)
-a == {'a':1, 'b':2}
+from varname.helpers import Wrapper
+
+foo = Wrapper(True)
+# foo.name == 'foo'
+# foo.value == True
+bar = Wrapper(False)
+# bar.name == 'bar'
+# bar.value == False
+
+def values_to_dict(*args):
+    return {val.name: val.value for val in args}
+
+mydict = values_to_dict(foo, bar)
+# {'foo': True, 'bar': False}
 ```
 
 ### Debugging with `debug`
 ```python
+from varname.helpers import debug
+
 a = 'value'
 b = object()
 debug(a) # DEBUG: a='value'
@@ -300,6 +324,7 @@ For example:
 [8]: https://img.shields.io/pypi/pyversions/varname?style=flat-square
 [9]: https://img.shields.io/github/workflow/status/pwwang/python-varname/Build%20Docs?label=docs&style=flat-square
 [10]: https://img.shields.io/github/workflow/status/pwwang/python-varname/Build%20and%20Deploy?style=flat-square
+[11]: https://mybinder.org/v2/gh/pwwang/python-varname/dev?filepath=playground%2Fplayground.ipynb
 [12]: https://img.shields.io/codacy/grade/ed851ff47b194e3e9389b2a44d6f21da?style=flat-square
 [13]: https://app.codacy.com/manual/pwwang/python-varname/dashboard
 [14]: https://img.shields.io/codacy/coverage/ed851ff47b194e3e9389b2a44d6f21da?style=flat-square