"""Return whether the callable `f` is a generic function.

if hasattr(f, "_method_registry"):

if hasattr(f, "_register"):

return "generic"

return "typed"

"""Decorator. Make `f` a generic function (in the sense of CLOS or Julia).

"""Parametric decorator. Add a multimethod to generic function `target`.

if not isgeneric(target):

raise TypeError(f"{_function_fullname(target)} is not a generic function, cannot add multimethods to it.")

"""Decorator. Restrict allowed argument types to one combination only.

s = generic(f)

del s._register # remove the ability to register more methods

"""Print, to stdout, a human-readable list of multimethods currently registered to `f`.

"""Format, as a string, a human-readable list of multimethods currently registered to `f`.

function, _ = getfunc(f)

multimethods = list_methods(f)

if multimethods:

thecallables = [thecallable for thecallable, type_signature in multimethods]

methods_list = [f" {_format_callable(x)}" for x in thecallables]

methods_str = "\n".join(methods_list)

else: # pragma: no cover, in practice a generic should always have at least one method.

methods_str = " <no multimethods registered>"

"""Return a list of the multimethods currently registered to `f`.

function, _ = getfunc(f)

if not isgeneric(function):

raise TypeError(f"{_function_fullname(function)} is not a generic function, it does not have multimethods.")

# In case of a bound method (either `Foo.classmeth` or `foo.instmeth`),

# we can get the value for `self`/`cls` argument from its `__self__` attribute.

#

# Otherwise we have a regular function, an unbound method, or a `@staticmethod`;

# in those cases, there's no `self`/`cls`. (Technically, an unbound method has

# a parameter to receive it, but no value has been set yet.)

self_or_cls = f.__self__ if hasattr(f, "__self__") else None

"""Return the full name of the callable `f`, including also its module name."""

function, _ = getfunc(f) # get the raw function also for OOP methods

if not function.__module__: # At least macros defined in the REPL have `__module__=None`.

return function.__qualname__

"""Return the name, as a string, of the first positional parameter of the callable `f`."""

function, _ = getfunc(f) # get the raw function also for OOP methods

parameters = inspect.signature(function).parameters

poskinds = set((inspect.Parameter.POSITIONAL_ONLY,

inspect.Parameter.POSITIONAL_OR_KEYWORD))

for param in parameters.values():

if param.kind in poskinds:

return param.name

"""List multimethods currently registered to a given dispatcher.

# TODO: Compute closest candidates, like Julia does? (see `methods`, `MethodError` in Julia)

# TODO: (If we do that, we need to look at the bound arguments. When just listing multimethods

# TODO: in the REPL, the current ordering is probably fine.)

# For regular functions, ours is the only registry we need to look at:

relevant_registries = [reversed(dispatcher._method_registry)]

# But if this dispatcher is installed on a method, we must

# look up multimethods also in the class's MRO.

#

# For *static methods* MRO is not supported. Basically, one of

# the roles of `cls` or `self` is to define the MRO; a static

# method doesn't have that.

#

# See discussions on interaction between `@staticmethod` and `super` in Python:

# https://bugs.python.org/issue31118

# https://stackoverflow.com/questions/26788214/super-and-staticmethod-interaction/26807879

if self_or_cls:

if isinstance(self_or_cls, type):

cls = self_or_cls

elif hasattr(self_or_cls, "__class__"):

cls = self_or_cls.__class__

else:

assert False

for base in cls.__mro__[1:]: # skip the class itself in the MRO

if hasattr(base, dispatcher.__name__): # does this particular super have f?

base_oop_method = getattr(base, dispatcher.__name__)

base_raw_function, _ = getfunc(base_oop_method)

if isgeneric(base_raw_function): # it's @generic or @typed

base_registry = getattr(base_raw_function, "_method_registry")

relevant_registries.append(reversed(base_registry))

"""Format, as a string, a human-readable description of a callable.

# Our `type_signature` is based on `typing.get_type_hints`,

# but for the error message, we need something that formats

# like source code. Hence we use `inspect.signature`.

thesignature = inspect.signature(thecallable)

function, _ = getfunc(thecallable) # raw function for OOP methods, too

# TODO: Python 3.8: filename sometimes detected incorrectly

# - This is because `inspect.getsourcefile` uses `inspect.getfile`, which looks at

# the `co_filename` of the code object. If the function is decorated, then it sees

# the source file where the decorator was defined, not the original function.

# function = inspect.unwrap(function) # maybe this helps? But now I can't reproduce the bug to test it.

filename = inspect.getsourcefile(function)

source, firstlineno = inspect.getsourcelines(function)

"""Return the first matching multimethod on `dispatcher` for the given `args` and `kwargs`.

multimethods = _list_multimethods(dispatcher, _extract_self_or_cls(dispatcher, args))

for thecallable, type_signature in multimethods:

try:

bound_arguments = _resolve_bindings(thecallable, args, kwargs, _partial=_partial)

if not _get_argument_type_mismatches(type_signature, bound_arguments):

return thecallable

except TypeError: # could not accept the given arguments; this isn't the multimethod we're looking for.

continue

"""Match bound arguments against the given type signature.

mismatches = []

for parameter, value in bound_arguments.arguments.items():

if parameter not in type_signature:

if skip_unannotated:

continue

raise ValueError(f"type_signature has no item for parameter {parameter}, which was supplied in `bound_arguments`. If that was intended, please use `skip_unannotated=True`.")

expected_type = type_signature[parameter]

if not isoftype(value, expected_type):

mismatches.append((parameter, value, expected_type))

"""From `thecallable` and positional arguments `args`, extract the value of `self`/`cls`, if any.

# TODO/FIXME: Not possible to detect `self`/`cls` parameters correctly.

#

# Here we're operating at the wrong abstraction level for that,

# since we see just bare functions. In the OOP case, the dispatcher

# is installed on the raw function before it becomes a bound method.

# (That in itself is just as it should be.)

first_param_name = _name_of_1st_positional_parameter(thecallable)

most_likely_an_oop_method = first_param_name in self_parameter_names

# Let's see if we might have been passed a `self`/`cls` parameter,

# and if so, get its value. (Recall that in Python, it is always

# the first positional parameter.)

if most_likely_an_oop_method:

if len(args) < 1: # pragma: no cover, shouldn't happen.

raise TypeError(f"MRO lookup failed: no value provided for self-like parameter {repr(first_param_name)} for OOP method-like generic function {_function_fullname(thecallable)}")

self_or_cls = args[0]

else:

self_or_cls = None

"""Raise a nicely formatted `TypeError` regarding a failed multiple dispatch (no matching multimethod).

# For `@typed` functions, which have just one valid call signature, we can easily

# report which args or kwargs failed to match.

if len(candidates) == 1:

# TODO: There's some repeated error-reporting code in `unpythonic.fun`.

thecallable, type_signature = candidates[0]

bound_arguments = _resolve_bindings(thecallable, args, kwargs, _partial=_partial)

mismatches = _get_argument_type_mismatches(type_signature, bound_arguments)

mismatches_list = [f"{parameter}={repr(value)}, expected {expected_type}"

for parameter, value, expected_type in mismatches]

mismatches_str = "; ".join(mismatches_list)

one_multimethod_msg_str = f"\nParameter binding(s) do not match type specification: {mismatches_str}"

else:

one_multimethod_msg_str = ""

# TODO: It would be nice to show the type signature of the args actually given,

# TODO: but in the general case this is difficult. We can't just `type(x)`, since

# TODO: the signature may specify something like `Sequence[int]`. Knowing a `list`

# TODO: was passed doesn't help debug that it was `Sequence[str]` when a `Sequence[int]`

# TODO: was expected. The actual value at least implicitly contains the type information.

args_list = [repr(x) for x in args]

args_str = ", ".join(args_list)

if _partial and args_str:

args_str += ", ..."

sep = ", " if args and kwargs else ""

kws_list = [f"{k}={repr(v)}" for k, v in kwargs.items()]

kws_str = ", ".join(kws_list)

if _partial and kws_str:

kws_str += ", ..."

if _partial and not args_str and not kws_str:

args_str = "..."

thecallables = [thecallable for thecallable, type_signature in candidates]

methods_list = [f" {_format_callable(x)}" for x in thecallables]

methods_str = "\n".join(methods_list)

op = "partial application" if _partial else "call"

msg = (f"No multiple-dispatch match for the {op} {dispatcher.__qualname__}({args_str}{sep}{kws_str}).\n"

f"Multimethods for @{isgeneric(dispatcher)} {_function_fullname(dispatcher)} (most recent match attempt last):\n{methods_str}"

f"{one_multimethod_msg_str}")

"""Register a multimethod for a generic function, creating the generic function if necessary.

if fullname not in _dispatcher_registry:

# Create the dispatcher. This will replace the original function.

@wraps(multimethod)

def dispatcher(*args, **kwargs):

thecallable = _resolve_multimethod(dispatcher, args, kwargs)

if thecallable:

return thecallable(*args, **kwargs)

_raise_multiple_dispatch_error(dispatcher, args, kwargs,

candidates=_list_multimethods(dispatcher,

_extract_self_or_cls(dispatcher, args)))

dispatcher._method_registry = []

dispatcher._register = partial(_register_to, dispatcher)

_dispatcher_registry[fullname] = dispatcher

dispatcher = _dispatcher_registry[fullname]

if isgeneric(dispatcher) == "typed":

raise TypeError("@typed: cannot register additional multimethods.")

"""Decorator. Register a new `multimethod` to `dispatcher`.

# Using `inspect.signature` et al., we could auto-`Any` parameters

# that have no type annotation, but that would likely be a footgun.

# So we require a type annotation for each parameter.

#

# One exception: the `self`/`cls` parameter of OOP instance methods and

# class methods is not meaningful for dispatching, and we don't

# have a runtime value to auto-populate its expected type when the

# definition runs. So we set it to `typing.Any` in the multimethod's

# expected type signature, which makes the dispatcher ignore it.

function, _ = getfunc(multimethod)

parameters = inspect.signature(function).parameters

parameter_names = [p.name for p in parameters.values()]

type_signature = typing.get_type_hints(function)

# In the type signature, auto-`Any` the `self`/`cls` parameter, if any.

#

# TODO/FIXME: Not possible to detect `self`/`cls` parameters correctly.

#

# The `@generic` decorator runs while the class body is being

# evaluated. In that context, an instance method looks just like a

# regular function.

#

# Also if `@generic` runs before `@classmethod` (to place Python's

# implicit `cls` handling outermost), also a class method looks

# just like a regular function to us.

#

# So we HACK, and special-case some suggestive *parameter names*

# when they appear the first position, though **Python itself

# doesn't do that**. For any crazy person not following Python

# naming conventions, our approach won't work.

if len(parameter_names) >= 1 and parameter_names[0] in self_parameter_names:

# In Python 3.6+, `dict` preserves insertion order. Make sure

# the `self` parameter appears first, for clearer error messages

# when no matching method is found.

type_signature = {parameter_names[0]: typing.Any, **type_signature}

if not all(name in type_signature for name in parameter_names):

failures = [name for name in parameter_names if name not in type_signature]

plural = "s" if len(failures) > 1 else ""

repr_list = [repr(x) for x in failures]

repr_str = ", ".join(repr_list)

msg = f"Multimethod definition missing type annotation for parameter{plural}: {repr_str}"

raise TypeError(msg)

dispatcher._method_registry.append((multimethod, type_signature))

# Update entry point docstring to include docs for the new multimethod,

# and its call signature.

call_signature_desc = _format_callable(multimethod)

our_doc = call_signature_desc

if multimethod.__doc__:

our_doc += "\n" + multimethod.__doc__

isfirstmultimethod = len(dispatcher._method_registry) == 1

if isfirstmultimethod or not dispatcher.__doc__:

# Override the original doc of the function that was converted

# into the dispatcher; this adds the call signature to the top.

dispatcher.__doc__ = our_doc

else:

# Add the call signature and doc for the new multimethod.

dispatcher.__doc__ += "\n\n" + ("-" * 80) + "\n"

dispatcher.__doc__ += our_doc