diff --git a/enum_tools/autoenum.py b/enum_tools/autoenum.py index 6265122..331f31d 100644 --- a/enum_tools/autoenum.py +++ b/enum_tools/autoenum.py @@ -54,6 +54,7 @@ # stdlib from contextlib import suppress from enum import Enum +from textwrap import dedent from typing import Any, Dict, List, Optional, Tuple, get_type_hints # 3rd party @@ -239,6 +240,64 @@ def document_members(self, all_members: bool = False) -> None: description="Valid values are as follows:", ) + # Document member access + + if len(self.object): + + member = list(self.object)[0] + cls_name = self.object.__name__ + enum_length = len(self.object) + + if enum_length < 4: + list_line = f"list({cls_name})" + list_repr = repr(list(self.object)) + else: + list_line = f"list({cls_name})[:3]" + list_repr = repr(list(self.object)[:3]) + + body = f""" + + Members can be accessed by: + + + - attribute access: + + .. code-block:: python + + >>> {cls_name}.{member.name} + <{cls_name}.{member.name}: {member.value!r}> + + + - value lookup: + + .. code-block:: python + + >>> {cls_name}({member.value!r}) + <{cls_name}.{member.name}: {member.value!r}> + + + - name lookup: + + .. code-block:: python + + >>> {cls_name}[{member.name!r}] + <{cls_name}.{member.name}: {member.value!r}> + + + Enumerations can be iterated over, and know how many members they have: + + .. code-block:: python + + >>> len({cls_name}) + {enum_length!r} + >>> {list_line} + {list_repr} + + """ + + for line in dedent(body).expandtabs(4).splitlines(): + self.add_line(line, self.sourcename) + # Document everything else self.options.undoc_members = user_option_undoc_members # type: ignore diff --git a/enum_tools/demo.py b/enum_tools/demo.py index 3ca64da..5f978c3 100644 --- a/enum_tools/demo.py +++ b/enum_tools/demo.py @@ -14,9 +14,6 @@ @enum_tools.documentation.document_enum class People(IntEnum): - """ - An enumeration of people. - """ Bob = bob = 1 # noqa # doc: A person called Bob # doc: another doc # isort: ignore Alice = 2 # doc: A person called Alice @@ -54,9 +51,9 @@ class NoMethods(IntEnum): An enumeration of people without any methods. """ - Bob = bob = 1 # noqa # doc: A person called Bob # doc: another doc # isort: ignore - Alice = 2 # doc: A person called Alice - Carol = 3 # doc: A person called Carol + Bob = bob = "1" # noqa # doc: A person called Bob # doc: another doc # isort: ignore + Alice = "2" # doc: A person called Alice + Carol = "3" # doc: A person called Carol @enum_tools.documentation.document_enum diff --git a/tests/test_autoenum.py b/tests/test_autoenum.py index a63e0fa..b76ead8 100644 --- a/tests/test_autoenum.py +++ b/tests/test_autoenum.py @@ -19,6 +19,11 @@ NEW_ENUM_REPR = sys.version_info >= (3, 11) +xfail_311 = pytest.mark.xfail( + reason="Python 3.11 behaviour has not been finalised yet.", + condition=sys.version_info[:2] == (3, 11) and sys.version_info.releaselevel == "alpha" + ) + @pytest.mark.parametrize("obj", [ "abcdefg", @@ -82,6 +87,7 @@ def preprocess_soup(soup: BeautifulSoup): dt.replace_with(NavigableString(dt.get_text())) +@xfail_311 @pytest.mark.parametrize( "page", [ "index.html", @@ -180,6 +186,7 @@ def test_index(page: BeautifulSoup, html_regression: HTMLRegressionFixture): assert class_count == 2 +@xfail_311 @pytest.mark.parametrize( "page", [ "flag.html", @@ -265,6 +272,7 @@ def test_flag(page: BeautifulSoup, html_regression: HTMLRegressionFixture): assert class_count == 2 +@xfail_311 @pytest.mark.parametrize( "page", [ "no-member-doc.html", diff --git a/tests/test_documented_enum.py b/tests/test_documented_enum.py index 40ee5e3..8f80e79 100644 --- a/tests/test_documented_enum.py +++ b/tests/test_documented_enum.py @@ -52,6 +52,13 @@ def get_name(person: People = People.Bob) -> str: return "Unknown" +xfail_311 = pytest.mark.xfail( + reason="Python 3.11 behaviour has not been finalised yet.", + condition=sys.version_info[:2] == (3, 11) and sys.version_info.releaselevel == "alpha" + ) + + +@xfail_311 def test_people(): assert People.Bob == 1 @@ -139,6 +146,7 @@ def test_document_member_wrong_types(obj): enum_tools.document_member(obj) +@xfail_311 def test_document_enum_not_interactive(): interactive_last_value = enum_tools.documentation.INTERACTIVE diff --git a/tests/test_enums.py b/tests/test_enums.py index 2490e79..88100a9 100644 --- a/tests/test_enums.py +++ b/tests/test_enums.py @@ -26,6 +26,13 @@ class DramatisPersonae(StrEnum): Eve = "An eavesdropper" +xfail_311 = pytest.mark.xfail( + reason="Python 3.11 behaviour has not been finalised yet.", + condition=sys.version_info[:2] == (3, 11) and sys.version_info.releaselevel == "alpha" + ) + + +@xfail_311 def test_str_enum(): assert DramatisPersonae.Message == "a secret message" assert DramatisPersonae.Alice != "An eavesdropper" @@ -128,6 +135,7 @@ class FifthFailedStrEnum(StrEnum): two = b'2', "ascii", 9 +@xfail_311 def test_member_dir_enum(): class MyEnum(int, MemberDirEnum):