#!/usr/bin/env python3

"""

Assorted utility functions.

"""

from functools import update_wrapper

from logging import warning

from traceback import extract_stack

def remapparams(**remap):

"""

Remap the specified named parameters.

Example to support an obsolete `parseAll` parameter:

@remapparams(parseAll='parse_all')

def parse(s, parse_all=True):

"""

if not remap:

raise ValueError("no parameters specified for remapping")

for old, new in remap.items():

if new in remap:

raise ValueError(f"{old}={new!r}: {new!r} is also remapped")

def remapparams_decorator(func):

"""The decorator to apply the remappings."""

# a record of callers whose parameters were remapped

remapped_callers = set()

def remapparams_wrapper(*a, **kw):

remappings = {}

for param, value in list(kw.items()):

try:

remapped = remap[param]

except KeyError:

continue

if remapped in kw:

raise ValueError(

f"remap {param}= to {remapped}=: this is already present in the keyword arguments"

)

del kw[param]

kw[remapped] = value

remappings[param] = remapped

if remappings:

caller_frame = extract_stack(limit=2)[-2]

caller_key = caller_frame.filename, caller_frame.lineno

if caller_key not in remapped_callers:

warning(

"call of %s.%s() from %s:%d: remapped the following obsolete parameters: %s",

func.__module__,

func.__name__,

caller_frame.filename,

caller_frame.lineno,

", ".join(

sorted(f"{old}->{new}" for old, new in remappings.items())

),

)

remapped_callers.add(caller_key)

return func(*a, **kw)

update_wrapper(remapparams_wrapper, func)

return remapparams_wrapper

return remapparams_decorator