fix nested class howto

Author: bckohan

doc/source/conf.py

@@ -41,7 +41,8 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
-    'sphinx.ext.intersphinx'
+    'sphinx.ext.intersphinx',
+    "sphinx_tabs.tabs"
 ]
 
 # Add any paths that contain templates here, relative to this directory.

doc/source/howto.rst

@@ -207,22 +207,28 @@ are supported on flags. Boundary specifiers must be supplied as named arguments:
 Use Nested Classes as Enums
 ---------------------------
 
-.. note::
-
-    In python <3.13, nested classes behave normally on enums that inherit from
-    :py:class:`~enum_properties.EnumProperties` and that specify at least one
-    property. In python 3.13 this behavior will remain unchanged in
-    enum-properties and normal :class:`enum.Enum` classes will adopt it.
+You can use nested classes as enumeration values. The tricky part is keeping them from becoming
+values themselves.
 
 On enums that inherit from :class:`enum.Enum` in python < 3.13 nested classes become
 enumeration values because types may be values and a quirk of Python makes it
 difficult to determine if a type on a class is declared as a nested class
 during __new__. For enums with properties we can distinguish declared classes
 because values must be tuples.
 
-Using :py:class:`~enum_properties.EnumProperties` this is possible:
+Note that on 3.13 and above you must use the nonmember/member decorators. Also note that
+the position of ``label`` is important.
+
+.. tabs::
+
+    .. tab:: <3.13
+
+        .. literalinclude:: ../../tests/examples/howto_nested_classes.py
+
+    .. tab:: >=3.11 (required >=3.13)
+
+        .. literalinclude:: ../../tests/examples/howto_nested_classes_313.py
 
-.. literalinclude:: ../../tests/examples/howto_nested_classes.py
 
 What about dataclass Enums?
 ---------------------------

pyproject.toml

@@ -67,6 +67,7 @@ docs = [
     "readme-renderer[md]>=43.0",
     "sphinx>=7.1.2",
     "sphinx-autobuild>=2021.3.14",
+    "sphinx-tabs>=3.4.7",
 ]
 
 

tests/examples/howto_nested_classes.py

@@ -20,10 +20,10 @@ class Type3:
 
 
 # only the expected values become enumeration values
-assert MyEnum.Type1 == MyEnum.VALUE1.value
-assert MyEnum.Type2 == MyEnum.VALUE2.value
-assert MyEnum.Type3 == MyEnum.VALUE3.value
-assert len(MyEnum) == 3
+assert MyEnum.Type1 == MyEnum.VALUE1
+assert MyEnum.Type2 == MyEnum.VALUE2
+assert MyEnum.Type3 == MyEnum.VALUE3
+assert len(MyEnum) == 3, len(MyEnum)
 
 # nested classes behave as expected
 assert MyEnum.Type1().__class__ is MyEnum.Type1

tests/examples/howto_nested_classes_313.py

@@ -0,0 +1,35 @@
+from enum_properties import EnumProperties
+from enum import nonmember, member
+
+
+class MyEnum(EnumProperties):
+
+    @nonmember
+    class Type1:
+        pass
+
+    @nonmember
+    class Type2:
+        pass
+
+    @nonmember
+    class Type3:
+        pass
+
+    label: str
+
+    VALUE1 = member(Type1), 'label1'
+    VALUE2 = member(Type2), 'label2'
+    VALUE3 = member(Type3), 'label3'
+
+
+# only the expected values become enumeration values
+assert MyEnum.Type1 == MyEnum.VALUE1
+assert MyEnum.Type2 == MyEnum.VALUE2
+assert MyEnum.Type3 == MyEnum.VALUE3
+assert len(MyEnum) == 3, len(MyEnum)
+
+# nested classes behave as expected
+assert MyEnum.Type1().__class__ is MyEnum.Type1
+assert MyEnum.Type2().__class__ is MyEnum.Type2
+assert MyEnum.Type3().__class__ is MyEnum.Type3

tests/examples/test_examples.py

@@ -91,7 +91,15 @@ def test_howto_flag_boundaries():
         from tests.examples import howto_flag_boundaries
 
 
+@pytest.mark.skipif(sys.version_info < (3, 11), reason="requires Python 3.11 or higher")
 def test_howto_nested_classes():
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", DeprecationWarning)
+        from tests.examples import howto_nested_classes_313
+
+
+@pytest.mark.skipif(sys.version_info >= (3, 13), reason="requires Python < 3.13")
+def test_howto_nested_classes_313():
     with warnings.catch_warnings():
         warnings.simplefilter("ignore", DeprecationWarning)
         from tests.examples import howto_nested_classes