worktoy 1.0.1.dev0__tar.gz → 1.0.1.dev1__tar.gz

{worktoy-1.0.1.dev0 → worktoy-1.0.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: worktoy
-Version: 1.0.1.dev0
+Version: 1.0.1.dev1
 Summary: Declarative structure for Python that enforces types at runtime and enables true function overloading
 Author-email: Asger Jon Vistisen <asgerjon2@gmail.com>
 License: Apache-2.0
@@ -32,7 +32,7 @@ Dynamic: license-file
 [![PyPI version](https://img.shields.io/pypi/v/worktoy)](https://pypi.org/project/worktoy/)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-# worktoy v1.0.1-dev0 (development build)
+# worktoy v1.0.1-dev1 (development build)
 
 **worktoy** provides utilities for Python development focused on
 reducing boilerplate while improving type safety and readability. Each

{worktoy-1.0.1.dev0 → worktoy-1.0.1.dev1}/README.md

@@ -4,7 +4,7 @@
 [![PyPI version](https://img.shields.io/pypi/v/worktoy)](https://pypi.org/project/worktoy/)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-# worktoy v1.0.1-dev0 (development build)
+# worktoy v1.0.1-dev1 (development build)
 
 **worktoy** provides utilities for Python development focused on
 reducing boilerplate while improving type safety and readability. Each

{worktoy-1.0.1.dev0 → worktoy-1.0.1.dev1}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = 'setuptools.build_meta'
 
 [project]
 name = "worktoy"
-version = "1.0.1-dev0"
+version = "1.0.1-dev1"
 authors = [
     { name = "Asger Jon Vistisen", email = "asgerjon2@gmail.com" },
 ]

{worktoy-1.0.1.dev0 → worktoy-1.0.1.dev1}/src/worktoy/__init__.py

@@ -39,7 +39,7 @@ chain.
 #  Copyright (c) 2025-2026 Asger Jon Vistisen
 from __future__ import annotations
 
-__version__ = '1.0.1-dev0'
+__version__ = '1.0.1-dev1'
 
 from . import utilities
 from . import waitaminute

{worktoy-1.0.1.dev0 → worktoy-1.0.1.dev1}/src/worktoy/core/sentinels/_args.py

@@ -11,7 +11,7 @@ from typing import TYPE_CHECKING
 from . import SentinelMeta
 
 if TYPE_CHECKING:  # pragma: no cover
-  from typing import Self, Iterator, Optional
+  from typing import Any, Self, Iterator, Optional
 
 
 class _MetaARGS(SentinelMeta):
@@ -38,6 +38,11 @@ class ARGS(metaclass=_MetaARGS):
   """
   ARGS uses a Sentinel metaclass and provides a placeholder for a starred
   argument in an overload signature.
+
+  Each subscript builds a new instance, so two signatures written the same
+  way hold two distinct instances. Instances therefore compare and hash by
+  their inner type, which lets a variadic signature in a subclass be
+  recognized as equal to the one it overrides.
   """
 
   def __iter__(self) -> Iterator[Self]:
@@ -46,6 +51,25 @@ class ARGS(metaclass=_MetaARGS):
     """
     yield from (self,)
 
+  def __eq__(self, other: Any) -> bool:
+    if not isinstance(other, ARGS):
+      return NotImplemented
+    return True if self.__inner_type__ is other.__inner_type__ else False
+
+  def __hash__(self) -> int:
+    return hash((type(self).__name__, self.__inner_type__))
+
+  def __str__(self) -> str:
+    """
+    The rendering follows the subscript that created the instance, for
+    example 'ARGS[int]'.
+    """
+    innerType = self.__inner_type__
+    innerName = getattr(innerType, '__name__', None) or str(innerType)
+    return '%s[%s]' % (type(self).__name__, innerName)
+
+  __repr__ = __str__
+
   @classmethod
   def __class_getitem__(cls, type_: type) -> Self:
     """

{worktoy-1.0.1.dev0 → worktoy-1.0.1.dev1}/src/worktoy/desc/_attri_box.py

@@ -148,7 +148,11 @@ class AttriBox(BaseDescriptor[T]):
   --------------------
   Reading the field returns the stored 'T' instance, building the
   deferred default on first read. Reading a deleted field raises
-  'MissingVariable'. Assigning a value:
+  'MissingVariable'. The field always holds an instance of 'T', though
+  not necessarily of exactly 'T': a 'bool' assigned to an
+  'AttriBox[int]' stays a 'bool'. A field type whose constructor returns
+  something other than an instance of it is refused with
+  'TypeException'. Assigning a value:
 
   - a value already of type 'T' is stored unchanged;
   - otherwise a lossless 'typeCast(T, value)' is tried with no
@@ -192,6 +196,20 @@ class AttriBox(BaseDescriptor[T]):
   constructor taking an argument raises 'TypeException' here, chained
   from the 'TypeError' that 'object.__init__' raises, rather than
   silently handing back the owner.
+
+  Each instance stores the value of a field under the private name that
+  'Object.getPrivateName' derives from the field name, followed by the
+  lower-case name of the box class and '_field_object__', so an
+  'AttriBox' named 'fooBar' stores at
+  '__foo_bar__attribox_field_object__'. The double underscore inside
+  keeps the storage apart from dunders Python uses and from private
+  class attributes such as '__foo_bar__'. Names that differ only in how
+  their words are joined or capitalised derive the same private name,
+  though: 'fooBar' and 'foo_bar' both store at
+  '__foo_bar__attribox_field_object__', as do 'X' and 'x' at
+  '__x__attribox_field_object__'. Declaring two such fields on one
+  class, the same name once in each spelling, leaves them sharing one
+  storage, and the behaviour is then undefined.
   """
 
   # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
@@ -218,6 +236,23 @@ class AttriBox(BaseDescriptor[T]):
   #  DOMAIN SPECIFIC  # # # # # # # # # # # # # # # # # # # # # # # # # # # #
   # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
 
+  def _getStorageName(self) -> str:
+    """
+    The '_getStorageName' method returns the name under which each
+    instance stores the value of this field: the private name from
+    'getPrivateName', followed by the lower-case name of the box class
+    and '_field_object__'. An 'AttriBox' named 'fooBar' stores at
+    '__foo_bar__attribox_field_object__' and a 'FixBox' of that name at
+    '__foo_bar__fixbox_field_object__', so anyone who meets the name
+    can tell what put it there. The double underscore inside sets the
+    name apart from every name written in the '__snake_case__' style, so
+    the stored value never lands on a dunder Python uses, on the state
+    'Object' keeps, or on a private class attribute of the owner, such
+    as the '__foo_bar__' of the 'Field' pattern.
+    """
+    boxName = type(self).__name__.lower()
+    return '%s%s_field_object__' % (self.getPrivateName(), boxName)
+
   def _resolve(self, *args, **kwargs) -> T:
     """
     The '_resolve' method builds a new instance of the field type from
@@ -343,7 +378,8 @@ class AttriBox(BaseDescriptor[T]):
     ------
     TypeException
         If neither the cast nor the field-type constructor accepts the
-        arguments.
+        arguments, or if the constructor returns something that is not
+        an instance of the field type.
     """
     fieldType = self.getFieldType()
     fieldObject = None
@@ -371,6 +407,11 @@ class AttriBox(BaseDescriptor[T]):
         name = 'value'
         badValue = args[0] if args else None
         raise TypeException(name, badValue, fieldType) from exception
+      if not isinstance(fieldObject, fieldType):
+        #  A constructor may return anything at all. Storing what it
+        #  returned would break the rule that the field always holds an
+        #  instance of its field type.
+        raise TypeException(self.getFieldName(), fieldObject, fieldType)
     try:
       setattr(fieldObject, '__field_name__', self.getFieldName())
       setattr(fieldObject, '__field_owner__', self.getFieldOwner())
@@ -386,7 +427,7 @@ class AttriBox(BaseDescriptor[T]):
     field-type instance on the first read and caching it under the
     private name.
     """
-    pvtName = self.getPrivateName()
+    pvtName = self._getStorageName()
     try:
       value = getattr(instance, pvtName)
     except AttributeError as attributeError:
@@ -409,7 +450,7 @@ class AttriBox(BaseDescriptor[T]):
     contract.
     """
     fieldType = self.getFieldType()
-    pvtName = self.getPrivateName()
+    pvtName = self._getStorageName()
     if isinstance(value, fieldType) or kwargs.get('_root', False):
       return setattr(instance, pvtName, value)
     #  Catch recursion
@@ -444,7 +485,7 @@ class AttriBox(BaseDescriptor[T]):
     instance by storing the 'DELETED' sentinel under the private
     attribute name, which a later read translates into 'MissingVariable'.
     """
-    pvtName = self.getPrivateName()
+    pvtName = self._getStorageName()
     setattr(instance, pvtName, DELETED)
 
   # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

{worktoy-1.0.1.dev0 → worktoy-1.0.1.dev1}/src/worktoy/desc/_base_descriptor.py

@@ -30,6 +30,12 @@ class BaseDescriptor(Object, Generic[T]):
   original. Registering the same method name twice records it twice and
   fires it twice.
 
+  A callback may declare fewer parameters than the descriptor passes it,
+  and the positional arguments it does not declare are dropped. Each
+  decorator returns the callback wrapped by 'flexCall' for this, so the
+  wrapping happens once as the class body runs, and an override that was
+  never decorated is wrapped as it is called.
+
   The following example illustrates an exhaustively decorated descriptor
   in a class body:
 
@@ -155,32 +161,32 @@ class BaseDescriptor(Object, Generic[T]):
   def preGet(self, callback: Func) -> Func:
     existing = self._getPreGetKeys()
     self.__pre_get_keys__ = (*existing, callback.__name__)
-    return callback
+    return flexCall(callback)
 
   def onGet(self, callback: Func) -> Func:
     existing = self._getOnGetKeys()
     self.__on_get_keys__ = (*existing, callback.__name__)
-    return callback
+    return flexCall(callback)
 
   def preSet(self, callback: Func) -> Func:
     existing = self._getPreSetKeys()
     self.__pre_set_keys__ = (*existing, callback.__name__)
-    return callback
+    return flexCall(callback)
 
   def onSet(self, callback: Func) -> Func:
     existing = self._getOnSetKeys()
     self.__on_set_keys__ = (*existing, callback.__name__)
-    return callback
+    return flexCall(callback)
 
   def preDelete(self, callback: Func) -> Func:
     existing = self._getPreDeleteKeys()
     self.__pre_delete_keys__ = (*existing, callback.__name__)
-    return callback
+    return flexCall(callback)
 
   def onDelete(self, callback: Func) -> Func:
     existing = self._getOnDeleteKeys()
     self.__on_delete_keys__ = (*existing, callback.__name__)
-    return callback
+    return flexCall(callback)
 
   def setName(self, callback: Func) -> Func:
     existing = self._getSetNameKeys()

{worktoy-1.0.1.dev0 → worktoy-1.0.1.dev1}/src/worktoy/desc/_fix_box.py

@@ -42,7 +42,7 @@ class FixBox(AttriBox[T]):
     'AttributeError' rather than 'is None', so an explicit assignment of
     'None' still counts as the one write.
     """
-    pvtName = self.getPrivateName()
+    pvtName = self._getStorageName()
     try:
       oldValue = object.__getattribute__(instance, pvtName)
     except AttributeError:

{worktoy-1.0.1.dev0 → worktoy-1.0.1.dev1}/src/worktoy/dispatch/_dispatcher.py

@@ -79,6 +79,17 @@ class Dispatcher(Object):
   signature you want to match first; any later, broader signature
   becomes a fallback for what the earlier ones did not catch.
 
+  When 'BaseSpace' builds a 'Dispatcher' for a class, it registers the
+  class body's own signatures first, followed by those inherited from
+  the classes in its method resolution order, nearest first, each with
+  its distance from the class. FASTEST and FAST try them in that order,
+  so an override wins every type match it competes in, including a
+  'THIS' signature that a further subclass matches only through
+  'isinstance'. SLOW tries the greatest distance first instead: a
+  signature added in a subclass then only receives the calls none of
+  the inherited signatures could take through a cast, and never
+  redirects a call its parent already handled.
+
   Performance contract
   --------------------
   FASTEST is roughly one or two orders of magnitude faster than FAST
@@ -100,7 +111,9 @@ class Dispatcher(Object):
 
   #  Private Variables
   __sig_funcs__ = None
+  __sig_distances__ = None
   __variadic_funcs__ = None
+  __variadic_distances__ = None
   __fallback_func__ = None
   __field_name__ = None
   __field_owner__ = None
@@ -120,6 +133,45 @@ class Dispatcher(Object):
   def _getVariadicFuncs(self) -> SigFuncList:
     return maybe(self.__variadic_funcs__, [])
 
+  def _getSigDistances(self) -> list[int]:
+    return maybe(self.__sig_distances__, [])
+
+  def _getVariadicDistances(self) -> list[int]:
+    return maybe(self.__variadic_distances__, [])
+
+  @staticmethod
+  def _getCastOrder(
+      sigFuncs: SigFuncList,
+      distances: list[int],
+  ) -> SigFuncList:
+    """
+    The '_getCastOrder' method returns the order in which the cast passes
+    try the registrations: the greatest distance first, and registration
+    order among equal distances. 'distances' lists the distance of each
+    pair in 'sigFuncs', position by position. A signature inherited from
+    a parent is therefore cast to before a signature its subclass added,
+    so adding a signature in a subclass never redirects a call the parent
+    already handled through a cast.
+
+    Parameters
+    ----------
+    sigFuncs : SigFuncList
+        Spells out to 'list[tuple[TypeSig, Method]]'. The registrations
+        in registration order.
+    distances : list[int]
+        The distance of each registration, in the same order.
+
+    Returns
+    -------
+    SigFuncList
+        The same registrations in the order the cast passes try them.
+    """
+    #  Indexing rather than zipping raises 'IndexError' should the two
+    #  lists ever fall out of step, where 'zip' would silently drop the
+    #  unmatched registrations from the cast passes.
+    positions = sorted(range(len(sigFuncs)), key=lambda i: -distances[i])
+    return [sigFuncs[i] for i in positions]
+
   def _getFallbackFunction(self) -> Optional[Method]:
     return self.__fallback_func__
 
@@ -169,12 +221,15 @@ class Dispatcher(Object):
       raise MissingVariable(self, '__field_owner__', type)
     return fieldOwner
 
-  def _getCachedKey(self, ) -> str:
-    return '__bound_dispatch_%s__' % self._getFieldName()
-
   def _createCachedFunction(self) -> None:
     sigFuncMap = self._getSigFuncMap()
     variadicFuncs = self._getVariadicFuncs()
+    castFuncs = self._getCastOrder(
+        self._getSigFuncList(), self._getSigDistances(),
+    )
+    castVariadics = self._getCastOrder(
+        variadicFuncs, self._getVariadicDistances(),
+    )
     fallback = self._getFallbackFunction()
     finalizer = self._getFinalizerFunction()
     dispatcher = self
@@ -216,7 +271,7 @@ class Dispatcher(Object):
           if matched:
             return func(instance, *args, **kwargs)
         #  SLOW
-        for sig, func in sigFuncMap.items():
+        for sig, func in castFuncs:
           castArgs = []
           if not sig.__allow_flex__:
             continue
@@ -235,7 +290,7 @@ class Dispatcher(Object):
           else:
             return func(instance, *castArgs, **kwargs)
         #  SLOW (variadic)
-        for sig, func in variadicFuncs:
+        for sig, func in castVariadics:
           if not sig.__allow_flex__:
             continue
           rawTypes = sig.getRawTypes()
@@ -299,7 +354,12 @@ class Dispatcher(Object):
   #  SETTERS  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
   # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
 
-  def addSigFunc(self, sig: TypeSig, func: Method) -> Method:
+  def addSigFunc(
+      self,
+      sig: TypeSig,
+      func: Method,
+      distance: int = 0,
+  ) -> Method:
     """
     The 'addSigFunc' method adds a signature-function pair to the
     internal signature-function map.
@@ -311,6 +371,12 @@ class Dispatcher(Object):
     func : Method
         The function to register. 'Method' expands to
         'Callable[[Any, ...], Any]'.
+    distance : int, optional
+        How far from the owning class the registration comes: 0 for the
+        owning class itself, 1 for the nearest class it inherits the
+        registration from, and so on. The exact-type and isinstance
+        passes ignore it and try registrations in registration order.
+        The cast passes try the greatest distance first. Defaults to 0.
 
     Returns
     -------
@@ -328,10 +394,16 @@ class Dispatcher(Object):
       if existingSig == sig:
         raise DuplicateSignature(sig, existingFunc, func)
     self.__sig_funcs__ = [*existing, (sig, func,)]
+    self.__sig_distances__ = [*self._getSigDistances(), distance]
     self.__compiled_func__ = None
     return func
 
-  def addVariadicSigFunc(self, sig: TypeSig, func: Method) -> Method:
+  def addVariadicSigFunc(
+      self,
+      sig: TypeSig,
+      func: Method,
+      distance: int = 0,
+  ) -> Method:
     """
     The 'addVariadicSigFunc' method registers a '(variadicSig, func)'
     pair on this dispatcher. Unlike 'addSigFunc', it does not reject
@@ -350,6 +422,9 @@ class Dispatcher(Object):
     func : Method
         The function to register. 'Method' expands to
         'Callable[[Any, ...], Any]'.
+    distance : int, optional
+        How far from the owning class the registration comes, with the
+        same meaning as in 'addSigFunc'. Defaults to 0.
 
     Returns
     -------
@@ -359,6 +434,7 @@ class Dispatcher(Object):
     """
     existing = self._getVariadicFuncs()
     self.__variadic_funcs__ = [*existing, (sig, func,)]
+    self.__variadic_distances__ = [*self._getVariadicDistances(), distance]
     self.__compiled_func__ = None
     return func
 
@@ -434,7 +510,7 @@ class Dispatcher(Object):
   #  Python API   # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
   # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
 
-  def __get__(self, instance: Any, owner: type, **kwargs) -> Callable:
+  def __get__(self, instance: Any, owner: type) -> Callable:
     """
     The '__get__' method is the descriptor protocol entry point. It
     always returns a callable suitable for dispatching against the
@@ -447,11 +523,14 @@ class Dispatcher(Object):
     argument. The compiled function is built lazily by
     '_getCachedFunction' and cached on the 'Dispatcher' itself.
 
-    Instance-level access ('obj.attr') returns a bound 'MethodType'
-    wrapping that compiled function. The bound object is created on
-    first access and cached on the instance under a reserved key
-    derived from '_getCachedKey', so subsequent accesses on the
-    same instance return the same bound object.
+    Instance-level access ('obj.attr') returns a fresh bound
+    'MethodType' wrapping that compiled function on every access, just
+    as Python does for a plain method. Nothing is stored on the
+    instance. A bound method stored there would be found again by
+    whichever 'Dispatcher' of the same name reads the instance next,
+    such as the parent's 'Dispatcher' reached through 'super'. It would
+    also be carried along by 'copy.copy', still bound to the original,
+    and it would keep the instance alive through a reference cycle.
 
     The live 'Dispatcher' is no longer reachable through normal
     attribute access on the owning class. Reach it through
@@ -474,24 +553,7 @@ class Dispatcher(Object):
     """
     if instance is None:
       return self._getCachedFunction()
-    key = self._getCachedKey()
-    try:
-      boundCache = getattr(instance, key)
-    except AttributeError as attributeError:
-      if kwargs.get('_recursion', False):
-        raise RecursionError from attributeError
-      unboundCache = self._getCachedFunction()
-      boundCache = MethodType(unboundCache, instance)
-      try:
-        setattr(instance, key, boundCache)
-      except AttributeError:
-        #  An instance refusing attribute creation, such as a frozen
-        #  enumeration member, cannot host the per-instance cache. The
-        #  bound method is then rebuilt on every access instead.
-        return boundCache
-      return self.__get__(instance, owner, _recursion=True)
-    else:
-      return boundCache
+    return MethodType(self._getCachedFunction(), instance)
 
   def __set__(self, instance: Any, value: Any, **kwargs) -> Never:
     """
@@ -544,8 +606,8 @@ class Dispatcher(Object):
   def clone(self, ) -> Self:
     """
     The 'clone' method builds a copy of this 'Dispatcher' carrying the
-    same registered signature/function pairs (including variadic ones),
-    the same fallback, and the same finalizer.
+    same registered signature/function pairs (including variadic ones)
+    with their distances, the same fallback, and the same finalizer.
 
     Returns
     -------
@@ -556,9 +618,11 @@ class Dispatcher(Object):
     """
     newLoad = type(self)()
     newLoad.__sig_funcs__ = self._getSigFuncList()
+    newLoad.__sig_distances__ = self._getSigDistances()
     variadicFuncs = self._getVariadicFuncs()
     if variadicFuncs:
       newLoad.__variadic_funcs__ = [*variadicFuncs, ]
+      newLoad.__variadic_distances__ = [*self._getVariadicDistances(), ]
     fallback = self._getFallbackFunction()
     if fallback is not None:
       newLoad.__fallback_func__ = fallback

{worktoy-1.0.1.dev0 → worktoy-1.0.1.dev1}/src/worktoy/dispatch/_flex_call.py

@@ -41,18 +41,47 @@ def isFlex(func: FunctionType) -> bool:
     return True
 
 
+def _missingNames(
+    requiredNames: tuple[str, ...],
+    received: int,
+    kwargs: dict,
+) -> tuple[str, ...]:
+  """
+  The '_missingNames' function returns the names of the required
+  positional parameters that a call leaves without a value.
+  'requiredNames' lists those parameters in order, and the first
+  'received' of them took their values by position. Each later one is
+  missing unless 'kwargs' names it. A positional-only parameter named in
+  'kwargs' counts as supplied here, and the wrapped function then refuses
+  it with its own 'TypeError', which says what went wrong.
+  """
+  out = []
+  for name in requiredNames[received:]:
+    if name not in kwargs:
+      out.append(name)
+  return (*out,)
+
+
 def flexCall(func: FunctionType) -> FunctionType:
   """Wrap 'func' with truncating positional-argument dispatch.
 
+  The descriptor notification callbacks of 'BaseDescriptor' are wrapped
+  this way, since a descriptor passes each of them the same arguments
+  however few it declares. So is every plain function in the body of a
+  class whose namespace declares 'FlexCallHook'. An ordinary method is
+  otherwise left as it was written.
+
   The returned wrapper:
   - silently drops positional args beyond the wrapped function's
     declared positional arity,
-  - raises TypeError when fewer than the required number of
-    positional-or-keyword arguments is supplied (parameters with
+  - raises TypeError when a required positional parameter receives no
+    value, neither by position nor by keyword (parameters with
     defaults are not counted as required); a missing required
-    keyword-only argument is not checked here and surfaces as the
-    wrapped function's own TypeError,
+    keyword-only argument, or a positional-only parameter named by
+    keyword, is not checked here and surfaces as the wrapped
+    function's own TypeError,
   - passes keyword args through unchanged,
+  - carries the attributes set on the wrapped function,
   - caches arity at wrap time; per-call cost is one length check,
     one comparison, and a slice only when truncation fires.
 
@@ -100,22 +129,25 @@ def flexCall(func: FunctionType) -> FunctionType:
   #  re-introspected per call.
   maxPos: int = code.co_argcount
   minPos: int = code.co_argcount - len(func.__defaults__ or ())
-  posNames: tuple[str, ...] = code.co_varnames[:maxPos]
+  requiredNames: tuple[str, ...] = code.co_varnames[:minPos]
 
   def wrapper(*args, **kwargs) -> Any:
     n: int = len(args)
     if n < minPos:
-      missing: tuple[str, ...] = posNames[n:minPos]
-      infoSpec: str = """Function '%s' requires at least '%d' positional 
-      arguments but received only '%d', missing arguments: (%s)!"""
-      missingStr = joinWords(*missing, )
-      info = infoSpec % (name, minPos, n, missingStr)
-      raise TypeError(textFmt(info))
+      missing = _missingNames(requiredNames, n, kwargs)
+      if missing:
+        infoSpec: str = """Function '%s' requires at least '%d' positional
+        arguments but received only '%d', missing arguments: (%s)!"""
+        missingStr = joinWords(*missing, )
+        info = infoSpec % (name, minPos, n, missingStr)
+        raise TypeError(textFmt(info))
     if n > maxPos:
       args = args[:maxPos]
     return func(*args, **kwargs)
 
-  #  Manual metadata copy: explicit, dependency-free.
+  #  Manual metadata copy: explicit, dependency-free. The attributes set
+  #  on 'func' come first, so the ones the wrapper sets below win.
+  wrapper.__dict__.update(func.__dict__)
   wrapper.__name__ = func.__name__
   wrapper.__qualname__ = func.__qualname__
   wrapper.__module__ = func.__module__

{worktoy-1.0.1.dev0 → worktoy-1.0.1.dev1}/src/worktoy/dispatch/_overload.py

@@ -56,10 +56,10 @@ class overload:  # NOQA
   matches in three kinds of pass (see 'Dispatcher' docstring):
   exact-type hash lookup, then isinstance iteration, then 'typeCast'
   iteration. Only the first is constant-time; the other two scan
-  every registered overload in registration order and return the
-  first match.
+  every registered overload in order and return the first match.
+  Within one class body that order is the declaration order.
 
-  Two consequences for how you stack '@overload' decorators:
+  Three consequences for how you stack '@overload' decorators:
 
   1. Register against the exact concrete types callers will pass.
      '@overload(int)' for a caller that supplies 'int' values keeps
@@ -75,6 +75,14 @@ class overload:  # NOQA
      Order your decorators to match the dispatch you want; treat
      overlapping isinstance coverage as deliberate, not as a bug
      for the dispatcher to second-guess.
+
+  3. A subclass overloading an inherited name keeps the inherited
+     overloads and adds its own. Its own come first in the exact-type
+     and isinstance passes, so an override wins wherever it matches,
+     and an equal signature replaces the inherited one outright. The
+     'typeCast' pass tries the inherited overloads first, so a
+     signature the subclass adds never takes a call its parent
+     already handled through a cast.
   """
 
   # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #