0.1.7

Author: pwwang

README.rst

@@ -1,6 +1,9 @@
 
-python-varname
-==============
+
+.. image:: logo.png
+   :target: logo.png
+   :alt: python-varname
+
 
 `
 .. image:: https://img.shields.io/pypi/v/python-varname?style=flat-square
@@ -37,146 +40,121 @@ Installation
 
    pip install python-varname
 
-Usage
------
-
-Retrieving the variable name inside a function
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Features
+--------
 
-.. code-block:: python
 
-   from varname import varname
-   def function():
-       return varname()
+* Fetching variable names from inside the function/class call
+* Fetching variable names directly (added in ``v0.1.2``\ )
+* A value wrapper to store the variable name that a value is assigned to (added in ``v0.1.1``\ )
+* Detecting next immediate attribute name (added in ``v0.1.4``\ )
+* Shortcut for ``collections.namedtuple`` (added in ``v0.1.6``\ )
+* Injecting ``__varname__`` to objects (added in ``v0.1.7``\ )
 
-   func = function()
-   # func == 'func'
+Usage
+-----
 
-   # available calls to retrieve
-   func = function(
-       # ...
-   )
+Retrieving the variable names from inside a function call/class instantiation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-   func = \
-       function()
 
-   func = function \
-       ()
+* 
+  From insdie a function call
 
-   func = (function
-           ())
+  .. code-block:: python
 
-``varname`` calls being buried deeply
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+       from varname import varname
+       def function():
+           return varname()
 
-.. code-block:: python
+       func = function()
+       # func == 'func'
 
-   def function():
-       # I know that at which stack this will be called
-       return varname(caller=3)
+* 
+  ``varname`` calls being buried deeply
 
-   def function1():
-       return function()
+  .. code-block:: python
 
-   def function2():
-       return function1()
+      def function():
+          # I know that at which stack this will be called
+          return varname(caller=3)
 
-   func = function2()
-   # func == 'func'
+      def function1():
+          return function()
 
-Retrieving instance name of a class object
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+      def function2():
+          return function1()
 
-.. code-block:: python
+      func = function2()
+      # func == 'func'
 
-   class Klass:
-       def __init__(self):
-           self.id = varname()
-       def copy(self):
-           return varname()
+* 
+  Retrieving instance name of a class
 
-   k = Klass()
-   # k.id == 'k'
+  .. code-block:: python
 
-   k2 = k.copy()
-   # k2 == 'k2'
+       class Klass:
+           def __init__(self):
+               self.id = varname()
 
-``varname`` calls being buried deeply for classes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+           def copy(self):
+               # also able to fetch inside a member call
+               return varname()
 
-.. code-block:: python
+       k = Klass()
+       # k.id == 'k'
 
-   class Klass:
-       def __init__(self):
-           self.id = self.some_internal()
+       k2 = k.copy()
+       # k2 == 'k2'
 
-       def some_internal(self):
-           return varname(caller=2)
+* 
+  Some unusual use
 
-       def copy(self):
-           return self.copy_id()
+  .. code-block:: python
 
-       def copy_id(self):
-           return self.copy_id_internal()
+       func = [function()]
+       # func == ['func']
 
-       def copy_id_internal(self):
-           return varname(caller=3)
+       func = [function(), function()]
+       # func == ['func', 'func']
 
-   k = Klass()
-   # k.id == 'k'
+       func = function(), function()
+       # func = ('func', 'func')
 
-   k2 = k.copy()
-   # k2 == 'k2'
+       func = func1 = function()
+       # func == func1 == 'func'
+       # a warning will be printed
+       # since you may not want func1 to be 'func'
 
-Some unusual use
-----------------
+       x = func(y = func())
+       # x == 'x'
 
-.. code-block:: python
+       # get part of the name
+       func_abc = function()[-3:]
+       # func_abc == 'abc'
 
-   func = [function()]
-   # func == ['func']
+       # function alias supported now
+       function2 = function
+       func = function2()
+       # func == 'func'
 
-   func = [function(), function()]
-   # func == ['func', 'func']
+       # Since v0.1.3
+       # We can ask varname to raise exceptions
+       # if it fails to detect the variable name
 
-   func = function(), function()
-   # func = ('func', 'func')
+       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
 
-   func = func1 = function()
-   # func == func1 == 'func'
-   # a warning will be printed
+       a.b = get_name() # None
 
-   x = func(
-       y = func()
-   )
-   # x == 'x'
-
-   # get part of the name
-   func_abc = function()[-3:]
-   # func_abc == 'abc'
-
-   # function alias supported now
-   function2 = function
-   func = function2()
-   # func == 'func'
-
-   # 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
-
-   a.b = get_name() # None
-
-A value wrapper (added in v0.1.1)
----------------------------------
+Value wrapper
+^^^^^^^^^^^^^
 
 .. code-block:: python
 
@@ -195,8 +173,8 @@ A value wrapper (added in v0.1.1)
    mydict = values_to_dict(foo, bar)
    # {'foo': True, 'bar': False}
 
-Getting variable names directly (added in v0.1.2)
--------------------------------------------------
+Getting variable names directly
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: python
 
@@ -218,8 +196,8 @@ Getting variable names directly (added in v0.1.2)
    fname = nameof(f)
    # fname == 'f'
 
-Detecting next immediate attribute name (added in ``v0.1.4``\ )
------------------------------------------------------------------
+Detecting next immediate attribute name
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: python
 
@@ -241,12 +219,12 @@ Detecting next immediate attribute name (added in ``v0.1.4``\ )
            return 'I am doing!'
 
    awesome = AwesomeClass()
-   awesome.do() # AttributeError: Should do something with AwesomeClass object
-   awesome.permit() # AttributeError: You don't have permission to do
+   awesome.do() # AttributeError: You don't have permission to do
+   awesome.permit() # AttributeError: Should do something with AwesomeClass object
    awesome.permit().do() == 'I am doing!'
 
-Shortcut for ``collections.namedtuple`` (addedin ``v0.1.6``\ )
---------------------------------------------------------------------
+Shortcut for ``collections.namedtuple``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: python
 
@@ -258,13 +236,36 @@ Shortcut for ``collections.namedtuple`` (addedin ``v0.1.6``\ )
    from varname import namedtuple
    Name = namedtuple(['first', 'last'])
 
+Injecting ``__varname__``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+   from varname import inject
+
+   class MyList(list):
+       pass
+
+   a = inject(MyList())
+   b = inject(MyList())
+
+   a.__varname__ == 'a'
+   b.__varname__ == 'b'
+
+   a == b
+
+   # other methods not affected
+   a.append(1)
+   b.append(1)
+   a == b
+
 Limitations
 -----------
 
 
 * Working in ``ipython REPL`` but not in standard ``python console``
 * You have to know at which stack the function/class will be called
-* For performance, since inspection is involved, better cache the name
+* Not working with ``reticulate`` from ``R`` since it cuts stacks to the most recent one.
 * ``nameof`` cannot be used in statements in ``pytest``
   .. code-block::
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.masonry.api"
 
 [tool.poetry]
 name = "python-varname"
-version = "0.1.6"
+version = "0.1.7"
 description = "Retrieving variable names of function or class calls."
 authors = [ "pwwang <pwwang@pwwang.com>",]
 license = "MIT"

setup.py

@@ -21,7 +21,7 @@
 setup(
     long_description=readme,
     name='python-varname',
-    version='0.1.6',
+    version='0.1.7',
     description='Retrieving variable names of function or class calls.',
     python_requires='==3.*,>=3.6.0',
     project_urls={

varname.py

@@ -5,7 +5,7 @@
 from collections import namedtuple as standard_namedtuple
 import executing
 
-__version__ = "0.1.6"
+__version__ = "0.1.7"
 
 VARNAME_INDEX = [-1]