Explore alternative to required_members in rest_send

[mikewiebe]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment

Description

The @response_handler.setter in plugins/module_utils/rest/rest_send.py has code to check required members manually.

Explore alternatives to this like potentially using ABC instead of a protocol

Original Comment: https://github.com/CiscoDevNet/ansible-nd/pull/185/changes#r2898597385

New or Affected Module(s):

• All modules (infrastructure)

ND version and ND Platform

• V 4.2

Collection versions

• cisco.nd 1.4.0

References

• #0000

[allenrobel]

Portable implementation for Python versions <= 3.12

The Python 3.8 - 3.11 fallback could be removed once 3.12 is the collection's minimum supported Python version.

import inspect
import sys
from typing import Any, Protocol, runtime_checkable, get_type_hints


def get_protocol_members(protocol_cls: type) -> frozenset[str]:
    """
    Return the set of required member names from a Protocol class.

    Uses the native API on 3.12+, falls back to manual extraction on 3.8–3.11.
    """
    if sys.version_info >= (3, 12):
        # Native: available since 3.12
        import typing
        return typing.get_protocol_members(protocol_cls)

    # Fallback for 3.8–3.11: attributes declared in the Protocol's own namespace,
    # excluding dunder names and anything inherited from Protocol/object itself.
    excluded = {
        *dir(Protocol),
        "__abstractmethods__",
        "__annotations__",
        "__weakref__",
        "__dict__",
        "__doc__",
    }
    members: set[str] = set()

    for name in list(protocol_cls.__dict__) + list(get_type_hints(protocol_cls)):
        if name.startswith("__") and name.endswith("__"):
            continue
        if name not in excluded:
            members.add(name)

    return frozenset(members)


def validate_protocol(obj: Any, protocol_cls: type) -> list[str]:
    """
    Return a list of member names required by `protocol_cls` that are
    missing from `obj`, using getattr_static to avoid triggering descriptors.
    """
    return [
        member
        for member in get_protocol_members(protocol_cls)
        if not _has_member_static(obj, member)
    ]


def _has_member_static(obj: Any, member: str) -> bool:
    try:
        inspect.getattr_static(obj, member)
        return True
    except AttributeError:
        return False

Then the setter RestSend.response_handler becomes:

@response_handler.setter
def response_handler(self, value: ResponseHandlerProtocol):
    missing = validate_protocol(value, ResponseHandlerProtocol)
    if missing:
        raise TypeError(
            f"{self.class_name}.response_handler: value must implement "
            f"ResponseHandlerProtocol. Missing members: {missing}. "
            f"Got type {type(value).__name__}."
        )
    if not callable(getattr(value, "commit", None)):
        raise TypeError(
            f"{self.class_name}.response_handler: value.commit must be callable. "
            f"Got type {type(value).__name__}."
        )
    self._response_handler = value

Notes

• The dunder filter — The fallback skips dunder names intentionally. Protocols can declare dunder methods like __len__ or __iter__ as required members; if you need those, remove the startswith/endswith guard and handle the excluded set more carefully.
• The callable() check is still manual — get_protocol_members() only tells you what members are required, not how they're typed. Checking that commit is callable (vs. a plain attribute) is information only you have from reading the Protocol definition, so that part stays explicit.