Fix #113: support server role aliases and improve validation error reporting

* Added an internal alias mapping to support strings like devel, dev, prod, p, stage, and s. 
* Implemented the _missing_ class method in the ServerRole enum.
* Added case-insensitive lookup logic to handle uppercase input (for example, PRODUCTION).

Signed-off-by: sushant-suse <[email protected]>

Author: sushant-suse

.github/workflows/ci.yml

@@ -228,4 +228,4 @@ jobs:
           source .venv/bin/activate
           pytest --cov=src -vv
         env:
-          PYTHONSTARTMETHOD: spawn
+          PYTHONSTARTMETHOD: spawn

changelog.d/113.feature.rst

@@ -0,0 +1,2 @@
+Implement a "smart" ``ServerRole`` enum that accepts case-insensitive or abbreviated aliases like ``p``, ``prod``, or ``PRODUCTION``. The new value ``devel`` is an alias for ``testing``.
+Refactor CLI error handling to display Pydantic validation failures in a clean, structured format.

src/docbuild/constants.py

@@ -20,15 +20,16 @@
 DEFAULT_DELIVERABLES = "*/@supported/en-us"
 """The default deliverables when no specific doctype is provided."""
 
-# SERVER_ROLES = (
-#     "production", "prod", "p",
-#     "testing", "test", "t",
-#     "staging", "stage", "s",
-# )
+# The primary, unique values of the Enum ('production', 'staging', 'testing')
 SERVER_ROLES = tuple(
-    [role.value for role in ServerRole]  # type: ignore[call-arg]
+    [role.value for role in ServerRole]
 )
-"""The different server roles, including long and short spelling."""
+"""The unique primary server role values."""
+
+# Every single valid name and alias defined in the Enum
+# ('PRODUCTION', 'PROD', 'P', 'production', 'prod', 'p', 'devel', etc.)
+SERVER_ROLES_ALIASES = tuple(ServerRole.__members__.keys())
+"""All valid server role names and aliases for validation and testing."""
 
 DEFAULT_LIFECYCLE = "supported"
 """The default lifecycle state for a docset."""

src/docbuild/models/serverroles.py

@@ -1,43 +1,58 @@
 """Server roles for the docbuild application."""
 
 from enum import StrEnum
-
-# from typing import Literal, Type
-# from pydantic import BaseModel, field_validator, Field
-# from ...constants import SERVER_ROLES
-#
-# ServerRole = StrEnum(
-#     "ServerRole",
-#     # Allow lowercase and uppercase names
-#     {name: name for name in SERVER_ROLES}
-#     | {name.upper(): name for name in SERVER_ROLES},
-# )
+from typing import Self
 
 
 class ServerRole(StrEnum):
-    """The server role."""
+    """The server role.
+
+    This Enum supports various aliases and case variations for each role.
+    """
 
-    # production
+    # Primary Members
     PRODUCTION = "production"
-    """Server is in production mode, serving live traffic."""
-    PROD = PRODUCTION
-    P = PRODUCTION
-    production = PRODUCTION
-    prod = PRODUCTION
-    p = PRODUCTION
-    # staging
     STAGING = "staging"
-    """Server is in staging mode, used for testing before production."""
-    STAGE = STAGING
-    S = STAGING
-    staging = STAGING
-    stage = STAGING
-    s = STAGING
-    # testing
     TESTING = "testing"
-    """Server is in testing mode, used for development and QA."""
-    TEST = TESTING
-    T = TESTING
-    testing = TESTING
-    test = TESTING
-    t = TESTING
+
+    # Aliases for PRODUCTION
+    PROD = "production"
+    P = "production"
+    prod = "production"
+    p = "production"
+
+    # Aliases for STAGING
+    STAGE = "staging"
+    S = "staging"
+    stage = "staging"
+    s = "staging"
+
+    # Aliases for TESTING
+    TEST = "testing"
+    T = "testing"
+    test = "testing"
+    t = "testing"
+    DEVEL = "testing"
+    devel = "testing"
+    DEV = "testing"
+    dev = "testing"
+
+    @classmethod
+    def _missing_(cls: type[Self], value: object) -> "ServerRole | None":
+        """Handle aliases and case-insensitive lookups using class members.
+
+        If the value passed isn't a valid value (for example, 'production'),
+        check if it matches one of the alias names (for example, 'p').
+        """
+        # Convert the input to a string to check against member keys
+        name = str(value)
+        member = cls.__members__.get(name)
+
+        if member is not None:
+            return member
+
+        # If no match is found, raise ValueError with all valid names/aliases
+        valid = ", ".join(cls.__members__.keys())
+        raise ValueError(
+            f"{name!r} is not a valid {cls.__name__}; valid names/aliases: {valid}"
+        )

tests/models/test_serverroles.py

@@ -1,6 +1,6 @@
 import pytest
 
-from docbuild.constants import SERVER_ROLES
+from docbuild.constants import SERVER_ROLES, SERVER_ROLES_ALIASES
 from docbuild.models.serverroles import ServerRole
 
 
@@ -9,9 +9,9 @@ def test_serverrole_with_call(role):
     assert ServerRole(role)
 
 
-@pytest.mark.parametrize("role", SERVER_ROLES)
+@pytest.mark.parametrize("role", SERVER_ROLES_ALIASES)
 def test_serverrole_with_predicate(role):
-    assert ServerRole[role]
+    assert ServerRole(role)
 
 
 @pytest.mark.parametrize("role", SERVER_ROLES)