Git Product home page Git Product logo

enum_tools's Introduction

Enum Tools

Tools to expand Python's enum module.

Docs Documentation Build Status Docs Check Status
Tests Linux Test Status Windows Test Status macOS Test Status Coverage
PyPI PyPI - Package Version PyPI - Supported Python Versions PyPI - Supported Implementations PyPI - Wheel
Anaconda Conda - Package Version Conda - Platform
Activity GitHub last commit Maintenance PyPI - Downloads
QA CodeFactor Grade Flake8 Status mypy status
Other License GitHub top language Requirements Status

This library provides the following:

  1. enum_tools.autoenum – A Sphinx extension to document Enums better than autoclass can currently.
  2. @enum_tools.documentation.document_enum – A decorator to add docstrings to Enum members from a comment at the end of the line.
  3. enum_tools.custom_enums – Additional Enum classes with different functionality.

Installation

enum_tools can be installed from PyPI or Anaconda.

To install with pip:

$ python -m pip install enum_tools

To install with conda:

$ conda install -c conda-forge enum_tools

Further Reading

  1. https://docs.python.org/3/library/enum.html
  2. Is it possible to define a class constant inside an Enum?
  3. Enums with Attributes
  4. When should I subclass EnumMeta instead of Enum?

enum_tools's People

Contributors

1kastner avatar adamtheturtle avatar domdfcoding avatar pre-commit-ci[bot] avatar pvragov avatar repo-helper[bot] avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar

Forkers

zevaryx pvragov mls-tuhh 1kastner brandon-leapyear lgtm-migrator adamtheturtle

enum_tools's Issues

0.9.0.post1: pytest is failing

I'm packaging your module as an rpm package so I'm using the typical PEP517 based build, install and test cycle used on building packages from non-root account.

  • python3 -sBm build -w --no-isolation
  • because I'm calling build with --no-isolation I'm using during all processes only locally installed modules
  • install .whl file in </install/prefix>
  • run pytest with PYTHONPATH pointing to sitearch and sitelib inside </install/prefix>

On first looks looks like `enum_tools needs to be adapoed for latest sphix.
Here is pytest output:

+ PYTHONPATH=/home/tkloczko/rpmbuild/BUILDROOT/python-enum-tools-0.9.0.post1-2.fc35.x86_64/usr/lib64/python3.8/site-packages:/home/tkloczko/rpmbuild/BUILDROOT/python-enum-tools-0.9.0.post1-2.fc35.x86_64/usr/lib/python3.8/site-packages
+ /usr/bin/pytest -ra
=========================================================================== test session starts ============================================================================
platform linux -- Python 3.8.14, pytest-7.1.3, pluggy-1.0.0
Test session started at 10:09:12
rootdir: /home/tkloczko/rpmbuild/BUILD/enum_tools-0.9.0.post1, configfile: tox.ini
plugins: datadir-1.3.1, regressions-2.4.1, timeout-2.1.0
timeout: 300.0s
timeout method: signal
timeout func_only: False
collected 69 items

tests/test_autoenum.py .........FFF                                                                                                                                  [ 17%]
tests/test_documented_enum.py ..............................                                                                                                         [ 60%]
tests/test_enums.py ........                                                                                                                                         [ 72%]
tests/test_utils.py ...................                                                                                                                              [100%]

================================================================================= FAILURES =================================================================================
__________________________________________________________________________ test_index[index.html] __________________________________________________________________________

page = <!DOCTYPE html>
<html lang="en"><head>
    <meta charset="utf-8"/>
    <meta content="width=device-width, initial-scal...
        </div>
      </div>

      <div class="clearer"></div>
    </div>






</body></html>
html_regression = <sphinx_toolbox.testing.HTMLRegressionFixture object at 0x7ff5773d0430>

    @pytest.mark.parametrize(
                "page", [
                                "index.html",
                                ], indirect=True
                )
    def test_index(page: BeautifulSoup, html_regression: HTMLRegressionFixture):
        # Make sure the page title is what you expect
        title = page.find("h1").contents[0].strip()
        assert "autoenum Demo" == title

        preprocess_soup(page)

>       html_regression.check(page, jinja2=True)
E    AssertionError: FILES DIFFER:
E    /tmp/pytest-of-tkloczko/pytest-48/test_index_index_html_0/test_autoenum_/test_index_index_html_.html
E    /tmp/pytest-of-tkloczko/pytest-48/test_index_index_html_0/test_autoenum_/test_index_index_html_.obtained.html
E    HTML DIFF: /tmp/pytest-of-tkloczko/pytest-48/test_index_index_html_0/test_autoenum_/test_index_index_html_.obtained.diff.html
E    ---
E    +++
E    @@ -1,8 +1,9 @@
E     <!DOCTYPE html>
E    -<html>
E    +<html lang="en">
E      <head>
E       <meta charset="utf-8"/>
E       <meta content="width=device-width, initial-scale=1.0" name="viewport"/>
E    +  <meta content="Docutils 0.18.1: http://docutils.sourceforge.net/" name="generator"/>
E       <title>
E        autoenum Demo — Python  documentation
E       </title>
E    @@ -11,6 +12,8 @@
E       <script src="_static/jquery.js">
E       </script>
E       <script src="_static/underscore.js">
E    +  </script>
E    +  <script src="_static/_sphinx_javascript_frameworks_compat.js">
E       </script>
E       <script src="_static/doctools.js">
E       </script>
E    @@ -21,12 +24,12 @@
E        <div class="documentwrapper">
E         <div class="bodywrapper">
E          <div class="body" role="main">
E    -      <div class="section" id="module-enum_tools.demo">
E    +      <section id="module-enum_tools.demo">
E            <span id="autoenum-demo">
E            </span>
E            <h1>
E             autoenum Demo
E    -        <a class="headerlink" href="#module-enum_tools.demo" title="Permalink to this headline">
E    +        <a class="headerlink" href="#module-enum_tools.demo" title="Permalink to this heading">
E              ¶
E             </a>
E            </h1>
E    @@ -63,6 +66,9 @@
E              <dl class="field-list simple">
E               <dt class="field-odd">
E                Member Type
E    +           <span class="colon">
E    +            :
E    +           </span>
E               </dt>
E               <dd class="field-odd">
E                <p>
E    @@ -241,6 +247,9 @@
E              <dl class="field-list simple">
E               <dt class="field-odd">
E                Member Type
E    +           <span class="colon">
E    +            :
E    +           </span>
E               </dt>
E               <dd class="field-odd">
E                <p>
E    @@ -330,7 +339,7 @@
E              </code>
E             </a>
E            </p>
E    -      </div>
E    +      </section>
E          </div>
E         </div>
E        </div>

tests/test_autoenum.py:97: AssertionError
------------------------------------------------------------------------- Captured stdout teardown -------------------------------------------------------------------------
# testroot: root
# builder: html
# srcdir: /tmp/pytest-of-tkloczko/pytest-48/root
# outdir: /tmp/pytest-of-tkloczko/pytest-48/root/_build/html
# status:
Running Sphinx v5.1.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded.

The HTML pages are in ../../../../../tmp/pytest-of-tkloczko/pytest-48/root/_build/html.

# warning:

___________________________________________________________________________ test_flag[flag.html] ___________________________________________________________________________

page = <!DOCTYPE html>
<html lang="en"><head>
    <meta charset="utf-8"/>
    <meta content="width=device-width, initial-scal...
        </div>
      </div>

      <div class="clearer"></div>
    </div>






</body></html>
html_regression = <sphinx_toolbox.testing.HTMLRegressionFixture object at 0x7ff577162340>

    @pytest.mark.parametrize(
                "page", [
                                "flag.html",
                                ], indirect=True
                )
    def test_flag(page: BeautifulSoup, html_regression: HTMLRegressionFixture):
        # Make sure the page title is what you expect
        title = page.find("h1").contents[0].strip()
        assert "autoenum Demo - Flag" == title

        preprocess_soup(page)

>       html_regression.check(page, jinja2=True)
E    AssertionError: FILES DIFFER:
E    /tmp/pytest-of-tkloczko/pytest-48/test_flag_flag_html_0/test_autoenum_/test_flag_flag_html_.html
E    /tmp/pytest-of-tkloczko/pytest-48/test_flag_flag_html_0/test_autoenum_/test_flag_flag_html_.obtained.html
E    HTML DIFF: /tmp/pytest-of-tkloczko/pytest-48/test_flag_flag_html_0/test_autoenum_/test_flag_flag_html_.obtained.diff.html
E    ---
E    +++
E    @@ -1,8 +1,9 @@
E     <!DOCTYPE html>
E    -<html>
E    +<html lang="en">
E      <head>
E       <meta charset="utf-8"/>
E       <meta content="width=device-width, initial-scale=1.0" name="viewport"/>
E    +  <meta content="Docutils 0.18.1: http://docutils.sourceforge.net/" name="generator"/>
E       <title>
E        autoenum Demo - Flag — Python  documentation
E       </title>
E    @@ -11,6 +12,8 @@
E       <script src="_static/jquery.js">
E       </script>
E       <script src="_static/underscore.js">
E    +  </script>
E    +  <script src="_static/_sphinx_javascript_frameworks_compat.js">
E       </script>
E       <script src="_static/doctools.js">
E       </script>
E    @@ -21,10 +24,10 @@
E        <div class="documentwrapper">
E         <div class="bodywrapper">
E          <div class="body" role="main">
E    -      <div class="section" id="autoenum-demo-flag">
E    +      <section id="autoenum-demo-flag">
E            <h1>
E             autoenum Demo - Flag
E    -        <a class="headerlink" href="#autoenum-demo-flag" title="Permalink to this headline">
E    +        <a class="headerlink" href="#autoenum-demo-flag" title="Permalink to this heading">
E              ¶
E             </a>
E            </h1>
E    @@ -61,6 +64,9 @@
E              <dl class="field-list simple">
E               <dt class="field-odd">
E                Member Type
E    +           <span class="colon">
E    +            :
E    +           </span>
E               </dt>
E               <dd class="field-odd">
E                <p>
E    @@ -193,6 +199,9 @@
E              <dl class="field-list simple">
E               <dt class="field-odd">
E                Member Type
E    +           <span class="colon">
E    +            :
E    +           </span>
E               </dt>
E               <dd class="field-odd">
E                <p>
E    @@ -290,7 +299,7 @@
E              </dl>
E             </dd>
E            </dl>
E    -      </div>
E    +      </section>
E          </div>
E         </div>
E        </div>

tests/test_autoenum.py:195: AssertionError
------------------------------------------------------------------------- Captured stdout teardown -------------------------------------------------------------------------
# testroot: root
# builder: html
# srcdir: /tmp/pytest-of-tkloczko/pytest-48/root
# outdir: /tmp/pytest-of-tkloczko/pytest-48/root/_build/html
# status:
Running Sphinx v5.1.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded.

The HTML pages are in ../../../../../tmp/pytest-of-tkloczko/pytest-48/root/_build/html.

# warning:

__________________________________________________________________ test_no_member_doc[no-member-doc.html] __________________________________________________________________

page = <!DOCTYPE html>
<html lang="en"><head>
    <meta charset="utf-8"/>
    <meta content="width=device-width, initial-scal...
        </div>
      </div>

      <div class="clearer"></div>
    </div>






</body></html>
html_regression = <sphinx_toolbox.testing.HTMLRegressionFixture object at 0x7ff5770e71c0>

    @pytest.mark.parametrize(
                "page", [
                                "no-member-doc.html",
                                ], indirect=True
                )
    def test_no_member_doc(page: BeautifulSoup, html_regression: HTMLRegressionFixture):
        # Make sure the page title is what you expect
        title = page.find("h1").contents[0].strip()
        assert "autoenum Demo - Members without docstrings" == title

        preprocess_soup(page)

>       html_regression.check(page, jinja2=True)
E    AssertionError: FILES DIFFER:
E    /tmp/pytest-of-tkloczko/pytest-48/test_no_member_doc_no_member_d0/test_autoenum_/test_no_member_doc_no_member_doc_html_.html
E    /tmp/pytest-of-tkloczko/pytest-48/test_no_member_doc_no_member_d0/test_autoenum_/test_no_member_doc_no_member_doc_html_.obtained.html
E    HTML DIFF: /tmp/pytest-of-tkloczko/pytest-48/test_no_member_doc_no_member_d0/test_autoenum_/test_no_member_doc_no_member_doc_html_.obtained.diff.html
E    ---
E    +++
E    @@ -1,8 +1,9 @@
E     <!DOCTYPE html>
E    -<html>
E    +<html lang="en">
E      <head>
E       <meta charset="utf-8"/>
E       <meta content="width=device-width, initial-scale=1.0" name="viewport"/>
E    +  <meta content="Docutils 0.18.1: http://docutils.sourceforge.net/" name="generator"/>
E       <title>
E        autoenum Demo - Members without docstrings — Python  documentation
E       </title>
E    @@ -11,6 +12,8 @@
E       <script src="_static/jquery.js">
E       </script>
E       <script src="_static/underscore.js">
E    +  </script>
E    +  <script src="_static/_sphinx_javascript_frameworks_compat.js">
E       </script>
E       <script src="_static/doctools.js">
E       </script>
E    @@ -21,10 +24,10 @@
E        <div class="documentwrapper">
E         <div class="bodywrapper">
E          <div class="body" role="main">
E    -      <div class="section" id="autoenum-demo-members-without-docstrings">
E    +      <section id="autoenum-demo-members-without-docstrings">
E            <h1>
E             autoenum Demo - Members without docstrings
E    -        <a class="headerlink" href="#autoenum-demo-members-without-docstrings" title="Permalink to this headline">
E    +        <a class="headerlink" href="#autoenum-demo-members-without-docstrings" title="Permalink to this heading">
E              ¶
E             </a>
E            </h1>
E    @@ -61,6 +64,9 @@
E              <dl class="field-list simple">
E               <dt class="field-odd">
E                Member Type
E    +           <span class="colon">
E    +            :
E    +           </span>
E               </dt>
E               <dd class="field-odd">
E                <p>
E    @@ -127,7 +133,7 @@
E              </code>
E             </a>
E            </p>
E    -      </div>
E    +      </section>
E          </div>
E         </div>
E        </div>

tests/test_autoenum.py:280: AssertionError
------------------------------------------------------------------------- Captured stdout teardown -------------------------------------------------------------------------
# testroot: root
# builder: html
# srcdir: /tmp/pytest-of-tkloczko/pytest-48/root
# outdir: /tmp/pytest-of-tkloczko/pytest-48/root/_build/html
# status:
Running Sphinx v5.1.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded.

The HTML pages are in ../../../../../tmp/pytest-of-tkloczko/pytest-48/root/_build/html.

# warning:

=========================================================================== slowest 25 durations ===========================================================================
0.40s call     tests/test_autoenum.py::test
0.14s setup    tests/test_autoenum.py::test
0.05s setup    tests/test_autoenum.py::test_index[index.html]
0.04s setup    tests/test_autoenum.py::test_flag[flag.html]
0.04s call     tests/test_autoenum.py::test_index[index.html]
0.04s setup    tests/test_autoenum.py::test_no_member_doc[no-member-doc.html]
0.03s call     tests/test_autoenum.py::test_flag[flag.html]
0.02s call     tests/test_autoenum.py::test_no_member_doc[no-member-doc.html]

(17 durations < 0.005s hidden.  Use -vv to show these durations.)
========================================================================= short test summary info ==========================================================================
FAILED tests/test_autoenum.py::test_index[index.html] - AssertionError: FILES DIFFER:
FAILED tests/test_autoenum.py::test_flag[flag.html] - AssertionError: FILES DIFFER:
FAILED tests/test_autoenum.py::test_no_member_doc[no-member-doc.html] - AssertionError: FILES DIFFER:
======================================================================= 3 failed, 66 passed in 1.13s =======================================================================

Here is list of installed modules in build env

Package                       Version
----------------------------- -----------------
alabaster                     0.7.12
apeye                         1.2.0
appdirs                       1.4.4
attrs                         22.1.0
autodocsumm                   0.2.9
Babel                         2.10.2
beautifulsoup4                4.11.1
Brlapi                        0.8.3
build                         0.8.0
CacheControl                  0.12.11
cffi                          1.15.1
charset-normalizer            2.1.0
click                         8.1.3
codespell                     2.1.0
coincidence                   0.6.2
consolekit                    1.4.1
cryptography                  36.0.2
cssselect                     1.1.0
cssutils                      2.6.0
default-values                0.5.1
deprecation                   2.1.0
deprecation-alias             0.3.1
dict2css                      0.3.0
dist-meta                     0.5.0
distro                        1.7.0
dnspython                     2.2.1
docutils                      0.18.1
dom_toml                      0.6.0
domdf-python-tools            3.3.0
extras                        1.0.0
extras-require                0.4.3
fixtures                      4.0.0
gpg                           1.17.1-unknown
handy-archives                0.1.2
html-section                  0.2.0.post1
html5lib                      1.1
idna                          3.4
imagesize                     1.4.1
importlib-metadata            4.12.0
iniconfig                     1.1.1
Jinja2                        3.1.1
libcomps                      0.1.19
lockfile                      0.12.2
louis                         3.23.0
lxml                          4.9.1
Markdown                      3.4.1
MarkupSafe                    2.1.1
mistletoe                     0.9.0
msgpack                       1.0.4
natsort                       8.0.2
numpy                         1.23.1
packaging                     21.3
pbr                           5.9.0
pep517                        0.12.0
pip                           22.2.2
platformdirs                  2.5.2
pluggy                        1.0.0
ply                           3.11
py                            1.11.0
pyasn1                        0.4.8
pychoosealicense              2022.7.25
pycparser                     2.21
Pygments                      2.13.0
PyGObject                     3.42.2
pyparsing                     3.0.9
pypi-json                     0.3.0
pyproject-parser              0.5.0
pytest                        7.1.3
pytest-datadir                1.3.1
pytest-regressions            2.4.1
pytest-timeout                2.1.0
python-dateutil               2.8.2
python-frontmatter            1.0.0
pytz                          2022.1
PyYAML                        6.0
requests                      2.28.1
rpm                           4.17.0
ruamel.yaml                   0.17.21
ruamel.yaml.clib              0.2.6
scour                         0.38.2
seed-intersphinx-mapping      1.1.0
setuptools                    65.3.0
shippinglabel                 1.4.1
six                           1.16.0
snowballstemmer               2.2.0
soupsieve                     2.3.2.post1
Sphinx                        5.1.1
sphinx-autodoc-typehints      1.19.2
sphinx-copybutton             0.5.0
sphinx-debuginfo              0.2.2
sphinx-jinja2-compat          0.2.0
sphinx-licenseinfo            0.3.1
sphinx-notfound-page          0.8
sphinx-prompt                 1.4.0
sphinx-pyproject              0.1.0
sphinx-tabs                   3.4.1
sphinx-toolbox                3.2.0
sphinxcontrib-applehelp       1.0.2.dev20220730
sphinxcontrib-devhelp         1.0.2.dev20220730
sphinxcontrib-htmlhelp        2.0.0
sphinxcontrib-jsmath          1.0.1.dev20220730
sphinxcontrib-qthelp          1.0.3.dev20220730
sphinxcontrib-serializinghtml 1.1.5
sphinxemoji                   0.2.0
tabulate                      0.8.10
testtools                     2.5.0
toctree-plus                  0.6.0
toml                          0.10.2
tomli                         2.0.1
typing_extensions             4.3.0
urllib3                       1.26.12
webencodings                  0.5.1
wheel                         0.37.1
whey                          0.0.23
zipp                          3.8.1

Publish enum_tools at conda-forge?

I would like to use enum_tools for a conda package which I plan to publish at conda-forge. One of my dependencies is your module. As you already made enum_tools available at your own conda channel, would you mind adding conda-forge as an additional channel?

The general issue is that with our own personal channels, we will end up with a long chain of additional channels. Now it is conda-build -c conda-forge -c domdfcoding my-recipe for me when building my package on my own channel. But the next person who depends on my work would need to add my personal channel as well, making this chain longer and longer. This is not good practice. Some interesting background knowledge is available at https://github.com/conda-forge/staged-recipes#6-do-all-of-my-packages-dependencies-have-to-be-in-conda-forge-already.

Quick side note: This is only necessary because I need enum_tools for the user installation (otherwise the decorators would not be defined). If it was only a dependency for the development installation (as layed out in #50), this step could be skipped.

Alternative: A possible workaround would be to define my own wrapper for your library, checking whether it is installed and if it is not available, just make the decorators a no-op. This is by far not my favorite solution.

Use of deprecated API

Description

Use of deprecated API

Exception occurred:
  File "/Users/az02065/Projects/Alton/python-extsemver/.venv/lib/python3.10/site-packages/enum_tools/autoenum.py", line 165, in _start_generate
    documenter.directive.filename_set.add(documenter.analyzer.srcname)
AttributeError: 'DocumenterBridge' object has no attribute 'filename_set'

sphinx.ext.autodoc.directive.DocumenterBridge.filename_set has been removed in sphinx 6

See https://github.com/sphinx-doc/sphinx/blob/bb74aec2b6aa1179868d83134013450c9ff9d4d6/doc/extdev/deprecated.rst#L274

Styling lost with Jupyter-book using autoenum

Hi!
Writing some documentation using jupyter-book, I decided to use this package for better looking api documention. (using sphinx ext.autodoc). However, some styling was lost when using autoenum. The same applies for other packages like sphinx-toolbox (providing other types like namedtuples), and pydantic models with autodoc_pydantic. However, authors of autodoc_pydantic was able to fix this by using sphinx events to add missing css classes. I.e "py enum" does not render ok, but "py class enum" does.

Please see JB for the issue, and autodoc_pydantic . Would you be willing to implement such a fix? Currently I do a post documentation build step, where I add class to all html elements with "py enum".

Support per-enum-value comments

Description

sphinx-autodoc supports the use of #: comments to document class attributes (ref). It would be great to have the same support in enum_tools

e.g.

class MyEnum(Enum):
    #: This is an A value
    A = auto()

    #: This is another value
    B = auto()

Version

  • Operating System:
  • Python:
  • enum_tools:

Other Additional Information:

Exception occurred: File "[...]/enum_tools/autoenum.py", line 324, in import_object // self._datadescriptor = False // AttributeError: can't set attribute

Description

The docs stopped building without a change in the code files.

Steps to Reproduce

I am not sure why the error showed up in https://github.com/1kastner/conflowgen/runs/4546078790?check_suite_focus=true but did work in https://github.com/1kastner/conflowgen/actions/runs/1580338713 because since then no code has changed. Only static files have been added since then.

Actual result:

Run cd ./docs/ && make html SPHINXOPTS="-W --keep-going"
Running Sphinx v4.3.1
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 4 source files that are out of date
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [ 25%] api

Exception occurred:
  File "/home/runner/.local/lib/python3.9/site-packages/enum_tools/autoenum.py", line 324, in import_object
    self._datadescriptor = False
AttributeError: can't set attribute
The full traceback has been saved in /tmp/sphinx-err-e_37qs4r.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [Makefile:20: html] Error 2

Expected result:

The docs build just like before

Reproduces how often:

Always as a GitHub action but never locally.

Version

  • Operating System: Ubuntu
  • Python: 3.9
  • enum_tools: newest (fresh install for each CI pipeline)

Installation source

PyPI

Request for short clarification on design principles

Description

Other modules, such as https://github.com/agronholm/sphinx-autodoc-typehints, also extend the options of the sphinx documentation. However, they do not use decorators in the code. Instead, they listen to sphinx events. This way, only the people who build the docs need to have the module installed. When using the decorator approach like in this module, each user needs to install it just to run the code. Furthermore, the decorators are invoked every time the the module is imported, even if it is only used programmatically and no documentation is required. What were the reasons that led to this decorator-based module design? A small explanation in the Readme would be very great! Thank you very much for the clarification.

After update - cannot import name 'RequestsURL' from 'apeye.url'

Description

I had a working setup, and then I was re-recreating the whole virtual environment for an unrelated reason. Out of the sudden the following error popped up:

PS XXX\docs> .\make.bat html
Running Sphinx v4.4.0
Extension error:
Could not import extension enum_tools.autoenum (exception: cannot import name 'RequestsURL' from 'apeye.url' (VENV_DIR\lib\site-packages\apeye\url.py))

This error message creates the imporession that enum_tools is the culprit here which I believe in fact it isn't.

Steps to Reproduce

A simple import suffices.

PS XXX> python
Python 3.8.12 | packaged by conda-forge | (default, Oct 12 2021, 21:22:46) [MSC v.1916 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import apeye
>>> print(apeye.__version__)
1.1.0
>>> import enum_tools
>>> print(enum_tools.__version__)
0.8.0
>>> from enum_tools import autoenum
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "VENV_DIR\lib\site-packages\enum_tools\autoenum.py", line 77, in <module>
    from sphinx_toolbox.more_autodoc.typehints import format_annotation  # nodep
  File "VENV_DIR\lib\site-packages\sphinx_toolbox\__init__.py", line 36, in <module>
    from sphinx_toolbox import (
  File "VENV_DIR\lib\site-packages\sphinx_toolbox\assets.py", line 111, in <module>
    from sphinx_toolbox.utils import SphinxExtMetadata
  File "VENV_DIR\lib\site-packages\sphinx_toolbox\utils.py", line 40, in <module>
    from apeye.url import RequestsURL
ImportError: cannot import name 'RequestsURL' from 'apeye.url' (VENV_DIR\lib\site-packages\apeye\url.py)
>>>

The traceback indicates that the sphinx toolbox uses an outdated version of apeye and thus this error appears. Maybe the error message in the initial output could be even clearer to better guide the user?

Installation source

I installed everything via pip

enum_tools.documentation doesn't work

Trying to use DocumentedEnum or document_enum, I'm unable to get anything working. It seems like unless INTERACTIVE is set to True, they don't do anything. And indeed, the tests manually turn this on.

enum_tools/tests/test_documented_enum.py

Line 14 in 94b16a6

enum_tools.documentation.INTERACTIVE = True

Why is it implemented this way? Running python setup.py build_sphinx doesn't set INTERACTIVE to true. At the very least, should the line above be included in the documentation on how to use the library?

option to only show enum member's value for autoenum

Description

To make my docs look cleaner, I'd like an option to show just the repr of the enum member's value instead of the repr of the enum member for autoenum.

I.e.: repr(enum.member.value) not repr(enum.member)

Current behaviour:
image

Requested behaviour:
image

Version

  • Operating System: Linux
  • Python: 3.9
  • enum_tools: 0.6.4

Other Additional Information:

Issue with sphinx 4.3.x

Hello everyone,

enum_tools version: 0.6.5

After updating Sphinx version from 4.2.0 to 4.3.1, I encounter this issue:

# Sphinx version: 4.3.1
# Python version: 3.9.9 (CPython)
# Docutils version: 0.16 release
# Jinja2 version: 3.0.3
# Last messages:
#   building [mo]: targets for 0 po files that are out of date
#   building [html]: targets for 5 source files that are out of date
#   updating environment:
#   [new config]
#   5 added, 0 changed, 0 removed
#   reading sources... [ 20%] configuration
#   reading sources... [ 40%] examples
#   reading sources... [ 60%] index
#   reading sources... [ 80%] install
#   reading sources... [100%] modules
# Loaded extensions:
#   sphinx.ext.mathjax (4.3.1) from /home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/ext/mathjax.py
#   sphinxcontrib.applehelp (1.0.2) from /home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinxcontrib/applehelp/__init__.py
#   sphinxcontrib.devhelp (1.0.2) from /home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinxcontrib/devhelp/__init__.py
#   sphinxcontrib.htmlhelp (2.0.0) from /home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinxcontrib/htmlhelp/__init__.py
#   sphinxcontrib.serializinghtml (1.1.5) from /home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinxcontrib/serializinghtml/__init__.py
#   sphinxcontrib.qthelp (1.0.3) from /home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinxcontrib/qthelp/__init__.py
#   alabaster (0.7.12) from /home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/alabaster/__init__.py
#   sphinx.ext.autodoc.preserve_defaults (1.0) from /home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/ext/autodoc/preserve_defaults.py
#   sphinx.ext.autodoc.type_comment (4.3.1) from /home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/ext/autodoc/type_comment.py
#   sphinx.ext.autodoc (4.3.1) from /home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/ext/autodoc/__init__.py
#   sphinx.ext.doctest (4.3.1) from /home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/ext/doctest.py
#   sphinx.ext.graphviz (4.3.1) from /home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/ext/graphviz.py
#   enum_tools.autoenum (0.6.5) from /home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/enum_tools/autoenum.py
Traceback (most recent call last):
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/cmd/build.py", line 280, in build_main
    app.build(args.force_all, filenames)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/application.py", line 344, in build
    self.builder.build_update()
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 294, in build_update
    self.build(to_build,
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 308, in build
    updated_docnames = set(self.read())
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 415, in read
    self._read_serial(docnames)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 436, in _read_serial
    self.read_doc(docname)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/builders/__init__.py", line 476, in read_doc
    doctree = read_doc(self.app, self.env, self.env.doc2path(docname))
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/io.py", line 189, in read_doc
    pub.publish()
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/core.py", line 217, in publish
    self.document = self.reader.read(self.source, self.parser,
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/io.py", line 109, in read
    self.parse()
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/readers/__init__.py", line 77, in parse
    self.parser.parse(self.input, document)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/parsers.py", line 101, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 170, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/statemachine.py", line 241, in run
    context, next_state, result = self.check_line(
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/statemachine.py", line 459, in check_line
    return method(match, context, next_state)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 2769, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 327, in section
    self.new_subsection(title, lineno, messages)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection
    newabsoffset = self.nested_parse(
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 196, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/statemachine.py", line 241, in run
    context, next_state, result = self.check_line(
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/statemachine.py", line 459, in check_line
    return method(match, context, next_state)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 2769, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 327, in section
    self.new_subsection(title, lineno, messages)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection
    newabsoffset = self.nested_parse(
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 196, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/statemachine.py", line 241, in run
    context, next_state, result = self.check_line(
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/statemachine.py", line 459, in check_line
    return method(match, context, next_state)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 2769, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 327, in section
    self.new_subsection(title, lineno, messages)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection
    newabsoffset = self.nested_parse(
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 196, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/statemachine.py", line 241, in run
    context, next_state, result = self.check_line(
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/statemachine.py", line 459, in check_line
    return method(match, context, next_state)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 2342, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 2354, in explicit_construct
    return method(self, expmatch)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 2096, in directive
    return self.run_directive(
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/docutils/parsers/rst/states.py", line 2146, in run_directive
    result = directive_instance.run()
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/ext/autodoc/directive.py", line 162, in run
    documenter.generate(more_content=self.content)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/ext/autodoc/__init__.py", line 984, in generate
    self.document_members(all_members)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx/ext/autodoc/__init__.py", line 860, in document_members
    documenter.generate(
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/enum_tools/autoenum.py", line 278, in generate
    self.document_members(all_members)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/enum_tools/autoenum.py", line 139, in document_members
    self._do_document_members(
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/enum_tools/autoenum.py", line 224, in _do_document_members
    documenter.generate(
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/enum_tools/autoenum.py", line 344, in generate
    ret = begin_generate(self, real_modname, check_module)
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/sphinx_toolbox/utils.py", line 394, in begin_generate
    if not documenter.import_object():
  File "/home/gilles/innova/dev/python-client/.tox/docs/lib/python3.9/site-packages/enum_tools/autoenum.py", line 324, in import_object
    self._datadescriptor = False
AttributeError: can't set attribute

With same version of enum_tools (0.6.5), I got this error with sphinx 4.3.0 and 4.3.1 but not with 4.2.0

Missing dependency “sphinx_toolbox”

Description

Your package metadata doesn’t say that sphinx_toolbox is a dependency.

Steps to Reproduce

Install package and add the autoenum extensison

extensions = [
    ...
    'enum_tools.autoenum',
    ...
]

Actual result:

Extension error:
  Could not import extension enum_tools.autoenum (exception: No module named 'sphinx_toolbox')

Expected result:

Works

Reproduces how often:

Easily reproduced

Version

  • Operating System: Arch Linux
  • Python: 3.9
  • enum_tools: 0.6.4

Installation source

PyPI/pip

sphinx autoenum does not work with Sphinx 7.2+: UnboundLocalError: cannot access local variable 'membername' where it is not associated with a value

Description

sphinx autoenum does not work with Sphinx 7.2+.

We get:

updating environment: [new config] 1 added, 0 changed, 0 removed
/Users/adam/.virtualenvs/enum_example/lib/python3.11/site-packages/enum_tools/autoenum.py:226: RemovedInSphinx80Warning: The tuple interface of ObjectMember is deprecated. Use (obj.__name__, obj.object) instead.
  if member[0] not in self.object.__members__.keys():

Exception occurred:
  File "/Users/adam/.virtualenvs/enum_example/lib/python3.11/site-packages/sphinx/ext/autodoc/__init__.py", line 779, in filter_members
    self.name, membername, member, exc, type='autodoc')
               ^^^^^^^^^^
UnboundLocalError: cannot access local variable 'membername' where it is not associated with a value
The full traceback has been saved in /var/folders/kd/d94l0l2j6vs_5f52qthyrtj80000gn/T/sphinx-err-040l0gvj.log, if you want to report the issue to the developers.

Steps to Reproduce

pip install the following:

enum-tools==0.10.0

# This will cause a failure.
# Change this to 7.1.2 or lower to avoid the error.
sphinx==7.2.2

Create the following files:

conf.py :

extensions = ['sphinx.ext.autodoc', 'enum_tools.autoenum']

index.rst :

.. autoenum:: enum_tools.demo.People
    :members:

Run:

sphinx-build -M html . build

Actual result:

updating environment: [new config] 1 added, 0 changed, 0 removed
/Users/adam/.virtualenvs/enum_example/lib/python3.11/site-packages/enum_tools/autoenum.py:226: RemovedInSphinx80Warning: The tuple interface of ObjectMember is deprecated. Use (obj.__name__, obj.object) instead.
  if member[0] not in self.object.__members__.keys():

Exception occurred:
  File "/Users/adam/.virtualenvs/enum_example/lib/python3.11/site-packages/sphinx/ext/autodoc/__init__.py", line 779, in filter_members
    self.name, membername, member, exc, type='autodoc')
               ^^^^^^^^^^
UnboundLocalError: cannot access local variable 'membername' where it is not associated with a value
The full traceback has been saved in /var/folders/kd/d94l0l2j6vs_5f52qthyrtj80000gn/T/sphinx-err-040l0gvj.log, if you want to report the issue to the developers.

Expected result:

No error.

Reproduces how often:

Easily reproduced.

Version

  • Operating System: macOS
  • Python: 3.11.4
  • enum_tools: 0.10.0

Installation source

pip

License confusion

The project's metadata specifies LGPLv3+ as its license. However, most source files specify GPLv3+:

enum_tools/enum_tools/custom_enums.py

Lines 10 to 13 in 872d39d

# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3 of the License, or
# (at your option) any later version.

Create multi-line enum member documentation

Description

I would like to do something like this:

@enum_tools.documentation.document_enum
class Test(enum.Enum):
    """
    xxx
    """

    a= 20  # doc: some text
    b= 40  # doc: some more text....
               # doc: and an additional line still referring to b

The naive version did not work for me but is there a way to do it?

Conda install: missing `filelock` when running Sphinx doctests

Description

While attempting to use enum_tools.autoenum via conda installation, doctests fail due to a missing import.

Error message:

Extension error:  
    Could not import extension enum_tools.autoenum (exception: 
    NOTE: In order to use the FileCache you must have 
    filelock installed. You can install it via pip:  
      pip install cachecontrol[filecache]  
    )

Steps to Reproduce

We encountered this issue when adding enum_tools.autoenum to our documentation on Pyomo. The steps below assume you have cloned Pyomo and installed its deps via conda. You can see a real-life log of all steps in our GitHub actions workflows.

conda install enum_tools
make -C doc/OnlineDocs doctest -d

Actual result:

Error message:

Extension error:  
    Could not import extension enum_tools.autoenum (exception: 
    NOTE: In order to use the FileCache you must have 
    filelock installed. You can install it via pip:  
      pip install cachecontrol[filecache]  
    )

Expected result:

Doctests can run without having to also manually installing filelock.

Reproduces how often:

Always unless you manually run conda install filelock in addition to conda install enum_tools

Version

  • Operating System: Windows
  • Python: (All versions tested - 3.8 through 3.12)
  • enum_tools: 0.11.0

Installation source

Anaconda/conda

Other Additional Information:

See this commit for code that will produce failure message: https://github.com/mrmundt/pyomo/tree/23bdbf7b76f674b5d437a3136387e28a84844086
See this commit for workaround implementing filelock: mrmundt/pyomo@d405bcb

ImportError: cannot import name '_power_of_two' from 'enum'

Description

Adding enum_tools.autoenum to Sphinx on Python 3.10 causes the following error:

ImportError: cannot import name '_power_of_two' from 'enum'

Steps to Reproduce

  1. Install Python 3.10
  2. Run make html with enum_tools.autoenum installed

Actual result:

ImportError: cannot import name '_power_of_two' from 'enum'

Expected result:

Better enum autodocs

Reproduces how often:

Easily reproduced

Version

  • Operating System: Windows 11 22471.1000
  • Python: 3.10.0
  • enum_tools: 0.6.4

Installation source

PyPi

Other Additional Information:

A solution would be to replace enum_tools/custom_enums.py#L50 with the Python main branch implementation

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.