docs(const): document the get overrides instead of hiding them (#1921)

pcapkit/const/ftp/command.py

@@ -559,7 +559,7 @@ def register_alias(cls, value: 'str', name: 'str') -> 'Command':
 
     @classmethod
     def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Command':
-        """Backport support for original codes.
+        """Resolve ``key`` to a member, matching the command code case-insensitively.
 
         A non-:class:`str` ``key`` is delegated to
         :meth:`~pcapkit.corekit.enum.EnumLookup.get`, as
@@ -584,14 +584,19 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Command':
                 matches no member name. ``None``, the default, uses ``key``
                 itself.
 
+        Returns:
+            The member named ``key`` upper-cased. On a miss, an unregistered
+            member with that name and the value ``default`` (or ``key``),
+            which is not added to the lookup tables, so ``get`` never registers
+            a command (:issue:`860`).
+
         Raises:
             EnumValueError: If ``key`` is not a :class:`str`. This reaches the
                 caller from the base's non-``str`` branch, where
                 :meth:`_validate_value` refuses it before ``cls(key)`` could
                 reach :meth:`_missing_`. A :exc:`ValueError`, so an
                 ``except ValueError`` caller is unaffected.
 
-        :meta private:
         """
         if not isinstance(key, str):
             # NOTE: unreachable only by the ``str`` annotation, which a caller

pcapkit/const/http/method.py

@@ -210,7 +210,7 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> 'Method':
 
     @classmethod
     def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Method':
-        """Backport support for original codes.
+        """Resolve ``key`` to a member, matching the method token case-sensitively.
 
         Delegates to :meth:`~pcapkit.corekit.enum.EnumLookup.get` for the
         lookup itself, so ``key`` is checked against member values as well
@@ -246,18 +246,23 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Method':
                 matches neither a name nor a value. ``None``, the
                 default, uses ``key`` itself.
 
+        Returns:
+            The member whose name or value is ``key``. On a miss, an
+            unregistered member named ``key`` upper-cased, with the value
+            ``default`` (or ``key``), which is not added to the lookup tables,
+            so ``get`` never registers a method (:issue:`860`).
+
         Raises:
             ValueError: If ``key`` is not a :class:`str`. This reaches the
                 caller from the base's non-``str`` branch, where
                 :meth:`_validate_value` refuses it before ``cls(key)`` could
                 reach ``_missing_``, and is **not** caught by
-                the ``except KeyError`` fallback below -- only a failed
-                *name* lookup is. Raising is the intended behaviour for
+                the miss fallback described under *Returns* -- only a failed
+                lookup is. Raising is the intended behaviour for
                 ``get(b'GET')`` as well: a member whose name and
                 value were both the :class:`bytes` object is not a thing
                 this registry should hand back.
 
-        :meta private:
         """
         try:
             return super().get(key)

pcapkit/const/pcapng/option_type.py

@@ -335,14 +335,27 @@ def register_alias(cls, value: 'int', name: 'str') -> 'OptionType':
 
     @staticmethod
     def get(key: 'int | str', default: 'int' = -1, *, namespace: 'str' = 'opt') -> 'OptionType':
-        """Backport support for original codes.
+        """Resolve ``key`` to a member, by option code or by name.
+
+        An :class:`int` ``key`` is an option code, looked up in ``namespace``
+        overlaid on ``opt``, so a code the namespace assigns itself wins over
+        the generic one. A :class:`str` ``key`` is matched case-sensitively
+        against member names, then against member values.
 
         Args:
-            key: Key to get enum item.
-            default: Default value if not found.
-            namespace: Namespace of the enum item.
+            key: Option code, member name or member value to look up.
+            default: Option code of the unregistered member built when a
+                :class:`str` ``key`` matches nothing. Unused for an
+                :class:`int` ``key``.
+            namespace: Namespace to resolve an :class:`int` ``key`` in.
+
+        Returns:
+            The matching member. On a miss, an unregistered member, which is
+            not added to the lookup tables, so ``get`` never registers an
+            option (:issue:`860`). For an option code, in range or not, it is
+            named ``{namespace}_unknown``; for a string, it is named ``key``
+            and carries the option code ``default``.
 
-        :meta private:
         """
         if isinstance(key, int):
             temp_ns = OptionType.__members_ns__.get('opt', {}).copy()

pcapkit/const/reg/apptype/apptype.py

@@ -88,7 +88,7 @@ class TransportProtocol(EnumLookup, IntEnum):
 
     @classmethod
     def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtocol':
-        """Backport support for original codes.
+        """Resolve ``key`` to a member, matching a name case-insensitively.
 
         Delegates to :meth:`~pcapkit.corekit.enum.EnumLookup.get` for GitHub
         issue :issue:`877`'s re-parenting, but keeps this override rather than dropping
@@ -161,7 +161,6 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco
             EnumValueError: If ``key`` is a value no member carries and there
                 is no usable ``default``. A :exc:`ValueError`, from the base.
 
-        :meta private:
         """
         if isinstance(key, str):
             return super().get(key.lower(), default)
@@ -2607,7 +2606,7 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[
     @classmethod
     def get(cls, key: 'int', *,  # type: ignore[override] # pylint: disable=arguments-differ
             proto: 'TransportProtocol | str | int' = TransportProtocol.undefined) -> 'AppType':
-        """Backport support for original codes.
+        """Resolve port ``key`` to the member for its canonical service.
 
         Args:
             key: Port number to look up.
@@ -2628,7 +2627,12 @@ def get(cls, key: 'int', *,  # type: ignore[override] # pylint: disable=argument
             to some ports -- ``80`` carries ``http``, ``www`` and ``www-http`` --
             and names no precedence among them, so :data:`__canonical__` supplies
             the one the rest of the world answers with. The others remain real,
-            named members and are reached through :meth:`get_all`.
+            named members and are reached through :meth:`get_all`. A port
+            with no row of its own resolves to an unregistered member that is
+            not added to the registry (:issue:`860`). Its name is the label of
+            the IANA span holding the port, whatever that label is --
+            ``reserved``, ``unassigned``, or a service name such as ``swx`` --
+            or ``unknown`` when no span holds it.
 
         Raises:
             ValueError: If called on a class that holds no members, i.e. on
@@ -2645,7 +2649,6 @@ def get(cls, key: 'int', *,  # type: ignore[override] # pylint: disable=argument
                 them, not simply for being composite -- see
                 :meth:`_dispatch`.
 
-        :meta private:
         """
         owner = cls._dispatch(key, proto)
 

pcapkit/vendor/ftp/command.py

@@ -393,7 +393,7 @@ def register_alias(cls, value: 'str', name: 'str') -> '{NAME}':
 
     @classmethod
     def get(cls, key: 'str', default: 'Optional[str]' = None) -> '{NAME}':
-        """Backport support for original codes.
+        """Resolve ``key`` to a member, matching the command code case-insensitively.
 
         A non-:class:`str` ``key`` is delegated to
         :meth:`~pcapkit.corekit.enum.EnumLookup.get`, as
@@ -418,14 +418,19 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> '{NAME}':
                 matches no member name. ``None``, the default, uses ``key``
                 itself.
 
+        Returns:
+            The member named ``key`` upper-cased. On a miss, an unregistered
+            member with that name and the value ``default`` (or ``key``),
+            which is not added to the lookup tables, so ``get`` never registers
+            a command (:issue:`860`).
+
         Raises:
             EnumValueError: If ``key`` is not a :class:`str`. This reaches the
                 caller from the base's non-``str`` branch, where
                 :meth:`_validate_value` refuses it before ``cls(key)`` could
                 reach :meth:`_missing_`. A :exc:`ValueError`, so an
                 ``except ValueError`` caller is unaffected.
 
-        :meta private:
         """
         if not isinstance(key, str):
             # NOTE: unreachable only by the ``str`` annotation, which a caller

pcapkit/vendor/http/method.py

@@ -115,7 +115,7 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> '{NAME}':
 
     @classmethod
     def get(cls, key: 'str', default: 'Optional[str]' = None) -> '{NAME}':
-        """Backport support for original codes.
+        """Resolve ``key`` to a member, matching the method token case-sensitively.
 
         Delegates to :meth:`~pcapkit.corekit.enum.EnumLookup.get` for the
         lookup itself, so ``key`` is checked against member values as well
@@ -151,18 +151,23 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> '{NAME}':
                 matches neither a name nor a value. ``None``, the
                 default, uses ``key`` itself.
 
+        Returns:
+            The member whose name or value is ``key``. On a miss, an
+            unregistered member named ``key`` upper-cased, with the value
+            ``default`` (or ``key``), which is not added to the lookup tables,
+            so ``get`` never registers a method (:issue:`860`).
+
         Raises:
             ValueError: If ``key`` is not a :class:`str`. This reaches the
                 caller from the base's non-``str`` branch, where
                 :meth:`_validate_value` refuses it before ``cls(key)`` could
                 reach ``_missing_``, and is **not** caught by
-                the ``except KeyError`` fallback below -- only a failed
-                *name* lookup is. Raising is the intended behaviour for
+                the miss fallback described under *Returns* -- only a failed
+                lookup is. Raising is the intended behaviour for
                 ``get(b'GET')`` as well: a member whose name and
                 value were both the :class:`bytes` object is not a thing
                 this registry should hand back.
 
-        :meta private:
         """
         try:
             return super().get(key)

pcapkit/vendor/pcapng/option_type.py

@@ -245,14 +245,27 @@ def register_alias(cls, value: 'int', name: 'str') -> '{NAME}':
 
     @staticmethod
     def get(key: 'int | str', default: 'int' = -1, *, namespace: 'str' = 'opt') -> '{NAME}':
-        """Backport support for original codes.
+        """Resolve ``key`` to a member, by option code or by name.
+
+        An :class:`int` ``key`` is an option code, looked up in ``namespace``
+        overlaid on ``opt``, so a code the namespace assigns itself wins over
+        the generic one. A :class:`str` ``key`` is matched case-sensitively
+        against member names, then against member values.
 
         Args:
-            key: Key to get enum item.
-            default: Default value if not found.
-            namespace: Namespace of the enum item.
+            key: Option code, member name or member value to look up.
+            default: Option code of the unregistered member built when a
+                :class:`str` ``key`` matches nothing. Unused for an
+                :class:`int` ``key``.
+            namespace: Namespace to resolve an :class:`int` ``key`` in.
+
+        Returns:
+            The matching member. On a miss, an unregistered member, which is
+            not added to the lookup tables, so ``get`` never registers an
+            option (:issue:`860`). For an option code, in range or not, it is
+            named ``{{namespace}}_unknown``; for a string, it is named ``key``
+            and carries the option code ``default``.
 
-        :meta private:
         """
         if isinstance(key, int):
             temp_ns = {NAME}.__members_ns__.get('opt', {{}}).copy()

pcapkit/vendor/reg/apptype/apptype.py

@@ -180,7 +180,7 @@ class TransportProtocol(EnumLookup, IntEnum):
 
     @classmethod
     def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtocol':
-        """Backport support for original codes.
+        """Resolve ``key`` to a member, matching a name case-insensitively.
 
         Delegates to :meth:`~pcapkit.corekit.enum.EnumLookup.get` for GitHub
         issue :issue:`877`'s re-parenting, but keeps this override rather than dropping
@@ -253,7 +253,6 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco
             EnumValueError: If ``key`` is a value no member carries and there
                 is no usable ``default``. A :exc:`ValueError`, from the base.
 
-        :meta private:
         """
         if isinstance(key, str):
             return super().get(key.lower(), default)
@@ -561,7 +560,7 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[
     @classmethod
     def get(cls, key: 'int', *,  # type: ignore[override] # pylint: disable=arguments-differ
             proto: 'TransportProtocol | str | int' = TransportProtocol.undefined) -> '{NAME}':
-        """Backport support for original codes.
+        """Resolve port ``key`` to the member for its canonical service.
 
         Args:
             key: Port number to look up.
@@ -582,7 +581,12 @@ def get(cls, key: 'int', *,  # type: ignore[override] # pylint: disable=argument
             to some ports -- ``80`` carries ``http``, ``www`` and ``www-http`` --
             and names no precedence among them, so :data:`__canonical__` supplies
             the one the rest of the world answers with. The others remain real,
-            named members and are reached through :meth:`get_all`.
+            named members and are reached through :meth:`get_all`. A port
+            with no row of its own resolves to an unregistered member that is
+            not added to the registry (:issue:`860`). Its name is the label of
+            the IANA span holding the port, whatever that label is --
+            ``reserved``, ``unassigned``, or a service name such as ``swx`` --
+            or ``unknown`` when no span holds it.
 
         Raises:
             ValueError: If called on a class that holds no members, i.e. on
@@ -599,7 +603,6 @@ def get(cls, key: 'int', *,  # type: ignore[override] # pylint: disable=argument
                 them, not simply for being composite -- see
                 :meth:`_dispatch`.
 
-        :meta private:
         """
         owner = cls._dispatch(key, proto)