Refactor LifecycleFlag to help editors (#54)

Dynamically created class didn't work well with VSCode and
attribute access.

* Use a real class
* Remove `BaseLifecycleFlag`. It's not needed anymore
* Use `auto()` to get integer value
* Use only "unknown" in lowercase to avoid problems with iterating
  over the class

Author: tomschr

changelog.d/53.refactor.rst

@@ -0,0 +1,3 @@
+Refactor :class:`~docbuild.models.lifecycle.LifecycleFlag`.
+Dynamically created class didn't work well with VSCode and
+attribute access.

src/docbuild/config/xml/list.py

@@ -39,7 +39,7 @@ def list_all_deliverables(
             if '*' not in dt.docset:
                 xpath += '[' + ' or '.join([f'@setid={d!r}' for d in dt.docset]) + ']'
 
-            if LifecycleFlag.UNKNOWN != dt.lifecycle:  # type: ignore
+            if LifecycleFlag.unknown != dt.lifecycle:  # type: ignore
                 xpath += (
                     '['
                     + ' or '.join([f'@lifecycle={lc.name!r}' for lc in dt.lifecycle])

src/docbuild/constants.py

@@ -3,6 +3,7 @@
 from pathlib import Path
 import re
 
+from .models.lifecycle import LifecycleFlag
 from .models.serverroles import ServerRole
 
 APP_NAME = 'docbuild'
@@ -24,14 +25,20 @@
 #     "testing", "test", "t",
 #     "staging", "stage", "s",
 # )
-SERVER_ROLES = tuple([role.value for role in ServerRole])
+SERVER_ROLES = tuple(
+    [role.value for role in ServerRole]  # type: ignore[call-arg]
+)
 """The different server roles, including long and short spelling."""
 
 DEFAULT_LIFECYCLE = 'supported'
 """The default lifecycle state for a docset."""
 
-ALLOWED_LIFECYCLES = ('supported', 'beta', 'hidden', 'unsupported')
-"""The available lifecycle states for a docset."""
+ALLOWED_LIFECYCLES: tuple[str] = tuple(
+    lc.name
+    for lc in LifecycleFlag
+)
+# ('supported', 'beta', 'hidden', 'unsupported')
+"""The available lifecycle states for a docset (without 'unknown')."""
 
 
 # All product acronyms and their names
@@ -141,7 +148,7 @@
 # --- State and Logging Constants (Refactored) ---
 
 BASE_STATE_DIR = Path.home() / '.local' / 'state' / APP_NAME
-"""The directory where application state, logs, and locks are stored, 
+"""The directory where application state, logs, and locks are stored,
 per XDG Base Directory Specification."""
 
 GITLOGGER_NAME = "docbuild.git"

src/docbuild/models/doctype.py

@@ -7,7 +7,7 @@
 from pydantic import BaseModel, Field, field_validator
 
 from .language import LanguageCode
-from .lifecycle import BaseLifecycleFlag, LifecycleFlag
+from .lifecycle import LifecycleFlag
 from .product import Product
 
 
@@ -185,7 +185,7 @@ def coerce_docset(cls, value: str | list[str]) -> list[str]:
 
     @field_validator('lifecycle', mode='before')
     @classmethod
-    def coerce_lifecycle(cls, value: str | LifecycleFlag) -> BaseLifecycleFlag:
+    def coerce_lifecycle(cls, value: str | LifecycleFlag) -> LifecycleFlag:
         """Convert a string into a LifecycleFlag."""
         # value = "" if value is None else value
         if isinstance(value, str):
@@ -261,7 +261,7 @@ def xpath(self) -> str:
             [
                 f'@lifecycle={lc.name!r}'
                 for lc in self.lifecycle
-                if lc != LifecycleFlag.UNKNOWN
+                if lc != LifecycleFlag.unknown
             ]
         )
         if lifecycle:

src/docbuild/models/lifecycle.py

@@ -1,44 +1,67 @@
 """Lifecycle model for docbuild."""
 
-from enum import Flag
+from enum import Flag, auto
 import re
+from typing import ClassVar, Self
 
-from ..constants import ALLOWED_LIFECYCLES
 
-_SEPARATOR = re.compile(r'[|,]')
+class LifecycleFlag(Flag):
+    """LifecycleFlag represents the lifecycle of a product."""
 
+    # Order is important here
+    unknown = 0
+    # UNKNOWN = 0
+    """Unknown lifecycle state."""
 
-class BaseLifecycleFlag(Flag):
-    """Base class for LifecycleFlag."""
+    supported = auto()
+    """Supported lifecycle state."""
+
+    beta = auto()
+    """Beta lifecycle state."""
+
+    hidden = auto()
+    """Hidden lifecycle state."""
+
+    unsupported = auto()
+    """Unsupported lifecycle state."""
+
+    # NOTE: Putting a compiled regex (or other helper) as a class
+    # variable on an Enum/Flag is error-prone:
+    # the Enum metaclass treats class attributes specially and may
+    # convert them into members or otherwise interfere.
+    #
+    # Solution: This class variable will be attached after class creation.
+    # _SEPARATOR = re.compile(r'[|,]')  # Static class variable
 
     @classmethod
-    def from_str(cls, value: str) -> 'BaseLifecycleFlag':
+    def from_str(cls: 'LifecycleFlag', value: str) -> 'LifecycleFlag':
         """Convert a string to a LifecycleFlag object.
 
         The string accepts the values 'supported', 'beta', 'hidden',
         'unsupported', or a combination of them separated by a comma or pipe.
-        Addtionally, the class knows the values "UNKNOWN" and "unknown".
-        An empty string, "", is equivalent to "UNKNOWN".
+        Addtionally, the class knows the values "unknown".
+        An empty string, "", is equivalent to "unknown".
 
         Examples:
         >>> LifecycleFlag.from_str("supported")
         <LifecycleFlag.supported: 2>
-        >>> LifecycleFlag.from_str("supported|beta")
+        >>> LifecycleFlag.from_str("supported,beta")
         <LifecycleFlag.supported|beta: 6>
         >>> LifecycleFlag.from_str("beta,supported|beta")
         <LifecycleFlag.supported|beta: 6>
         >>> LifecycleFlag.from_str("")
         <LifecycleFlag.unknown: 0>
 
         """
+        separator = cls._SEPARATOR  # will exist after we attach it
         try:
             flag = cls(0)  # Start with an empty flag
-            parts = [v.strip() for v in _SEPARATOR.split(value) if v.strip()]
+            parts = [v.strip() for v in separator.split(value) if v.strip()]
             if not parts:
                 return cls(0)
 
             for part_name in parts:
-                flag |= cls[part_name]
+                flag |= cls.__members__[part_name]
 
             return flag
 
@@ -48,12 +71,12 @@ def from_str(cls, value: str) -> 'BaseLifecycleFlag':
                 f'Invalid lifecycle name: {err.args[0]!r}. Allowed values: {allowed}',
             ) from err
 
-    def __contains__(self, other: str | Flag) -> bool:
+    def __contains__(self: Self, other: str | Flag) -> bool:
         """Return True if self has at least one of same flags set as other.
 
-        >>> "supported" in Lifecycle.beta
+        >>> "supported" in LifecycleFlag.beta
         False
-        >>> "supported|beta" in Lifecycle.beta
+        >>> "supported|beta" in LifecycleFlag.beta
         True
         """
         if isinstance(other, str):
@@ -68,13 +91,5 @@ def __contains__(self, other: str | Flag) -> bool:
         return (self & item_flag) == item_flag
 
 
-# Lifecycle is implemented as a Flag as different states can be combined
-# An additional "unknown" state could be used if the state is unknown or not yet
-# retrieved.
-# TODO: Should we allow weird combination like "supported|unsupported"
-LifecycleFlag = BaseLifecycleFlag(
-    'LifecycleFlag',
-    {'unknown': 0, 'UNKNOWN': 0}
-    | {item: (2 << index) for index, item in enumerate(ALLOWED_LIFECYCLES, 0)},
-)
-"""LifecycleFlag represents the lifecycle of a product."""
+# attach after class creation so EnumMeta doesn't touch it
+LifecycleFlag._SEPARATOR: ClassVar[re.Pattern] = re.compile(r'[|,]')

tests/models/test_lifecycle.py

@@ -22,7 +22,7 @@ def test_unknown_lifecycle():
 
 def test_lifecycle_flag_from_str_with_empty_string():
     instance = LifecycleFlag.from_str('')
-    assert instance == LifecycleFlag.UNKNOWN
+    assert instance == LifecycleFlag.unknown
     assert instance.name == 'unknown'
     assert instance.value == 0