Pump to 0.3.0 (#21)

* Cleanup and add changelog

* Add docs

* Fix API style

* Update build.yml

* Update build.yml

* Update build.yml

* Update build.yml

* Update mkdocs.yml

* Give up github pages, use rtd instead.

* Update requirements for mkdocs

* Add compiled API

* Update mkdocs config

* Don't buid docs automatically for now.

* Update README

* Update README.md

* 0.3.0

Author: pwwang

.github/workflows/build.yml

@@ -19,11 +19,20 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install poetry
           pip install pylint
+          pip install poetry
           poetry install -v
       - name: Run pylint
         run: pylint varname.py
+      # - name: Update docs
+      #   run: |
+      #     pip install mkdocs
+      #     pip install mkdocs-material
+      #     pip install mkapi
+      #     pip install pymdown-extensions
+      #     cd docs; ln -s ../README.md index.md; ln -s ../logo.png; cd -
+      #     mkdocs gh-deploy
+      #   if: success() && matrix.python-version == 3.8 && github.event_name == 'push'
       - name: Test with pytest
         run: poetry run pytest tests/ --junitxml=junit/test-results-${{ matrix.python-version }}.xml
       - name: Upload pytest test results
@@ -40,6 +49,5 @@ jobs:
           project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
           coverage-reports: .coverage.xml
       - name: Publish to PyPI
-        if: success() && matrix.python-version == 3.8 && github.event_name == 'push' && startsWith(github.ref, 'refs/tags') 
+        if: success() && matrix.python-version == 3.8 && github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
         run: poetry publish --build -u ${{ secrets.pypi_user }} -p ${{ secrets.pypi_password }}
-    

.gitignore

@@ -105,3 +105,6 @@ poetry.lock
 
 # backup files
 *.bak
+
+docs/index.md
+docs/logo.png

README.md

@@ -1,36 +1,38 @@
 ![python-varname][7]
 
-[![Pypi][3]][4] [![Github][5]][6] [![PythonVers][8]][4] [![Travis building][10]][11] [![Codacy][12]][13] [![Codacy coverage][14]][13]
+[![Pypi][3]][4] [![Github][5]][6] [![PythonVers][8]][4] [![Travis building][10]][11] [![Codacy][12]][13] [![Codacy coverage][14]][13] [![Chat on gitter][17]][18]
 
 Dark magics about variable names in python
 
+[Change Log][16] | [API][15]
+
 ## Installation
 ```shell
 pip install python-varname
 ```
 
 ## Features
 
-- 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`)
+- 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`
+- Shortcut for `collections.namedtuple`
+- Injecting `__varname__` to objects
 
 ## Credits
 
 Thanks goes to these awesome people/projects:
 
 <table>
   <tr>
-    <td align="center">
+    <td align="center" style="min-width: 75px">
       <a href="https://github.com/alexmojaki">
         <img src="https://avatars0.githubusercontent.com/u/3627481?s=400&v=4" width="50px;" alt=""/>
         <br /><sub><b>@alexmojaki</b></sub>
       </a>
     </td>
-    <td align="center">
+    <td align="center" style="min-width: 75px">
       <a href="https://github.com/alexmojaki/executing">
         <img src="https://via.placeholder.com/50?text=executing" width="50px;" alt=""/>
         <br /><sub><b>executing</b></sub>
@@ -54,6 +56,7 @@ Thanks goes to these awesome people/projects:
     ```
 
 -  `varname` calls being buried deeply
+
     ```python
     def function():
         # I know that at which stack this will be called
@@ -70,6 +73,7 @@ Thanks goes to these awesome people/projects:
     ```
 
 - Retrieving instance name of a class
+
     ```python
     class Klass:
         def __init__(self):
@@ -87,6 +91,7 @@ Thanks goes to these awesome people/projects:
     ```
 
 - Some unusual use
+
     ```python
     func = [function()]
     # func == ['func']
@@ -114,6 +119,10 @@ Thanks goes to these awesome people/projects:
     func = function2()
     # func == 'func'
 
+    a = lambda: 0
+    a.b = function()
+    # a.b == 'b'
+
     # Since v0.1.3
     # We can ask varname to raise exceptions
     # if it fails to detect the variable name
@@ -127,7 +136,8 @@ Thanks goes to these awesome people/projects:
         except VarnameRetrieveingError:
             return None
 
-    a.b = get_name() # None
+    a = {}
+    a['b'] = get_name() # None
     ```
 
 ### Value wrapper
@@ -230,18 +240,21 @@ 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 (caller's depth)
-- Not working with `reticulate` from `R` since it cuts stacks to the most recent one.
-- ~~`nameof` cannot be used in statements in `pytest`~~ (supported in `v0.2.0`)
-  ```diff
-  -a = 1
-  +assert nameof(a) == 'a'
-  -# Retrieving failure.
-  -# The right way:
-  -aname = nameof(a)
-  -assert aname == 'a'
+`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.
+For example:
+
+- Environments where other AST magics apply. For example: `pytest`, `ipython`, `macropy`, or `birdseye`.
+  This will not work with `pytest`:
+  ```python
+  a = 1
+  assert nameof(a) == 'a'
+
+  # do this instead
+  name_a = nameof(a)
+  assert name_a == 'a'
   ```
+- `R` with `reticulate`.
 
 [1]: https://github.com/pwwang/python-varname
 [3]: https://img.shields.io/pypi/v/python-varname?style=flat-square
@@ -255,3 +268,7 @@ a == b
 [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
+[15]: https://pwwang.github.io/python-varname/api/varname/
+[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

README.rst

@@ -1,6 +1,3 @@
-.. role:: raw-html-m2r(raw)
-   :format: html
-
 
 
 .. image:: logo.png
@@ -32,10 +29,16 @@
 .. image:: https://img.shields.io/codacy/coverage/ed851ff47b194e3e9389b2a44d6f21da?style=flat-square
    :target: https://img.shields.io/codacy/coverage/ed851ff47b194e3e9389b2a44d6f21da?style=flat-square
    :alt: Codacy coverage
- <https://app.codacy.com/manual/pwwang/python-varname/dashboard>`_
+ <https://app.codacy.com/manual/pwwang/python-varname/dashboard>`_ `
+.. image:: https://img.shields.io/gitter/room/pwwang/python-varname?style=flat-square
+   :target: https://img.shields.io/gitter/room/pwwang/python-varname?style=flat-square
+   :alt: Chat on gitter
+ <https://gitter.im/python-varname/community>`_
 
 Dark magics about variable names in python
 
+`Change Log <https://pwwang.github.io/python-varname/CHANGELOG/>`_ | `API <https://pwwang.github.io/python-varname/api/varname/>`_
+
 Installation
 ------------
 
@@ -47,12 +50,38 @@ Features
 --------
 
 
-* 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``\ )
+* 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``
+* Shortcut for ``collections.namedtuple``
+* Injecting ``__varname__`` to objects
+
+Credits
+-------
+
+Thanks goes to these awesome people/projects:
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+       <td align="center" style="min-width: 75px">
+         <a href="https://github.com/alexmojaki">
+           <img src="https://avatars0.githubusercontent.com/u/3627481?s=400&v=4" width="50px;" alt=""/>
+           <br /><sub><b>@alexmojaki</b></sub>
+         </a>
+       </td>
+       <td align="center" style="min-width: 75px">
+         <a href="https://github.com/alexmojaki/executing">
+           <img src="https://via.placeholder.com/50?text=executing" width="50px;" alt=""/>
+           <br /><sub><b>executing</b></sub>
+         </a>
+       </td>
+     </tr>
+   </table>
+
 
 Usage
 -----
@@ -141,6 +170,10 @@ Retrieving the variable names from inside a function call/class instantiation
        func = function2()
        # func == 'func'
 
+       a = lambda: 0
+       a.b = function()
+       # a.b == 'b'
+
        # Since v0.1.3
        # We can ask varname to raise exceptions
        # if it fails to detect the variable name
@@ -154,7 +187,8 @@ Retrieving the variable names from inside a function call/class instantiation
            except VarnameRetrieveingError:
                return None
 
-       a.b = get_name() # None
+       a = {}
+       a['b'] = get_name() # None
 
 Value wrapper
 ^^^^^^^^^^^^^
@@ -265,16 +299,22 @@ Injecting ``__varname__``
 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.
+For example:
+
+
+* 
+  Environments where other AST magics apply. For example: ``pytest``\ , ``ipython``\ , ``macropy``\ , or ``birdseye``.
+  This will not work with ``pytest``\ :
+
+  .. code-block:: python
+
+     a = 1
+     assert nameof(a) == 'a'
 
-* Working in ``ipython REPL`` but not in standard ``python console``
-* You have to know at which stack the function/class will be called (caller's depth)
-* Not working with ``reticulate`` from ``R`` since it cuts stacks to the most recent one.
-* :raw-html-m2r:`<del>\ ``nameof`` cannot be used in statements in ``pytest``\ </del>` (supported in ``v0.2.0``\ )
-  .. code-block:: diff
+     # do this instead
+     name_a = nameof(a)
+     assert name_a == 'a'
 
-     -a = 1
-     +assert nameof(a) == 'a'
-     -# Retrieving failure.
-     -# The right way:
-     -aname = nameof(a)
-     -assert aname == 'a'
+* ``R`` with ``reticulate``.

docs/CHANGELOG.md

@@ -0,0 +1,34 @@
+## v0.1.0
+- Implement `varname` function
+
+## v0.1.1
+- Add a value wrapper `Wrapper` class
+
+## v0.1.2
+- Add function `nameof`
+
+## v0.1.3
+- Add arugment `raise_exc` for `varname` to raise an exception instead of returning `var_<index>`
+
+## v0.1.4
+- Add `will` to detect next immediate attribute name
+
+## v0.1.5
+- Fix `will` from a property call
+
+## v0.1.6
+- Fit situations when frames cannot be fetched
+- Add shortcut for `namedtuple`
+
+## v0.1.7
+- Add `inject` function
+
+## v0.2.0
+- Fix #5 and fit nameof in more cases
+
+## v0.3.0
+- Use sys._getframe instead of inspect.stack for efficiency (#9)
+- Add alternative way of testing bytecode nameof (#10)
+- 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)

docs/api.css

@@ -0,0 +1,10 @@
+
+.mkapi-docstring{
+    line-height: 1;
+}
+.mkapi-node pre {
+    line-height: 1.5;
+}
+.mkapi-node * {
+    font-size: .65rem !important;
+}

docs/requirements.txt

@@ -0,0 +1,3 @@
+mkdocs-material
+pymdown-extensions
+mkapi

mkdocs.yml

@@ -0,0 +1,19 @@
+site_name: python-varname
+theme:
+    name: 'material'
+plugins:
+  - search
+  - mkapi
+extra_css:
+  - api.css
+markdown_extensions:
+    - markdown.extensions.admonition
+    - pymdownx.superfences:
+        preserve_tabs: true
+    - toc:
+        baselevel: 2
+nav:
+    - "": mkapi/api/varname
+    - index.md
+    - API: api/varname.md
+    - 'Change Log': CHANGELOG.md

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.masonry.api"
 
 [tool.poetry]
 name = "python-varname"
-version = "0.2.0"
+version = "0.3.0"
 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.2.0',
+    version='0.3.0',
     description='Retrieving variable names of function or class calls.',
     python_requires='==3.*,>=3.6.0',
     project_urls={