def rename_param(source, target):
renamed = False
for i, p in enumerate(params):
if p.name == source:
name = p.name
params[i] = nds.Parameter(target, *p[1:])
renamed = True
break
return renamed
def _parse_param_list(self, *args, **kwargs):
"""
Normalize parameters
"""
parms = super()._parse_param_list(*args, **kwargs)
out = []
for name, type_, desc in parms:
out.append(
nds.Parameter(name.strip(), type_.strip(), [d.rstrip() for d in desc])
)
return out
def normalize(self):
"""
Apply a bunch of heuristic that try to normalise the data.
"""
if (params := self["Parameters"]):
for i, p in enumerate(params):
if not p.type and ":" in p.name:
if p.name.startswith(".."):
continue
name, type_ = [
_.strip() for _ in p.name.split(":", maxsplit=1)
]
params[i] = nds.Parameter(name, type_, p[2])
def _make_doc_parameter(attribute):
if attribute.type is None:
atype = ""
elif isinstance(attribute.type, str):
atype = attribute.type
elif hasattr(attribute.type, "__qualname__"):
atype = attribute.type.__qualname__
else:
try:
atype = str(attribute.type)
except:
atype = ""
return numpydoc.Parameter(attribute.name, atype,
[attribute.metadata.get("description", "")])
def normalize(self):
"""
Apply a bunch of heuristic that try to normalise the data.
"""
if (params := self["Parameters"]) :
for i, p in enumerate(params):
if not p.type and (":" in p.name) and not p.name.endswith(":"):
if p.name.startswith(".."):
continue
if re.match(":\w+:`", p.name):
print("may have a directive", p.name)
try:
name, type_ = [
_.strip() for _ in p.name.split(": ", maxsplit=1)
]
except Exception as e:
raise type(e)(p.name)
params[i] = nds.Parameter(name, type_, p[2])
def parameter_fixer(params, meta_arg, meta, fname, func_name, config, doc):
assert "Parameters" in doc
jump_to_location = False
if not config.run_fixers:
return params, jump_to_location
pnames = [o.strip() for p in params for o in p.name.split(",") if p.name]
if meta_arg and meta_arg[0] in ["self", "cls"]:
meta_arg = meta_arg[1:]
doc_missing = set(meta_arg) - set(pnames) - {"cls"}
doc_extra = {x for x in set(pnames) - set(meta_arg) if not x.startswith("*")} - {
"cls",
}
for p in params:
if p[1].startswith("<"):
jump_to_location = True
assert doc_extra != {""}, (set(a), set(meta_arg), params)
# don't considert template parameter from numpy/scipy
doc_extra = {x for x in doc_extra if not (("$" in x) or ("%" in x))}
def rename_param(source, target):
renamed = False
for i, p in enumerate(params):
if p.name == source:
name = p.name
params[i] = nds.Parameter(target, *p[1:])
renamed = True
break
return renamed
if doc_missing and doc_extra:
# we need to match them maybe:
# are we missing *, ** in args, and kwargs ?
for stars in ("*", "**"):
n_star_missing = doc_missing.intersection({stars + k for k in doc_extra})
if n_star_missing:
correct = list(n_star_missing)[0]
incorrect = correct[len(stars) :]
rename_param(incorrect, correct)
doc_missing.remove(correct)
doc_extra.remove(incorrect)
for param in list(doc_extra):
if (
param.startswith(('"', "'"))
and param.endswith(('"', "'"))
and param[1:-1] in doc_missing
):
correct = param[1:-1]
rename_param(param, correct)
print("unquote", param, "to", correct)
doc_missing.remove(correct)
doc_extra.remove(param)
if len(doc_missing) == len(doc_extra) == 1:
correct = list(doc_missing)[0]
incorrect = list(doc_extra)[0]
do_rename = True
if "*" in correct and ("*" not in incorrect):
if correct.replace("*", "") != incorrect.replace("*", ""):
# this is likely undocumented **kwargs.
do_rename = False
if do_rename:
if rename_param(incorrect, correct):
print(f"{fname}:{func_name}")
print(f" renamed {incorrect!r} to {correct!r}")
doc_missing = {}
doc_extra = {}
else:
print(" could not fix:", doc_missing, doc_extra)
if doc_missing and not doc_extra and config.with_placeholder:
for param in doc_missing:
if "*" in param:
continue
annotation_str = "<Insert Type here>"
current_param = [m for m in meta["simple"] if m.arg == param]
assert len(current_param) == 1, (current_param, meta, param)
current_param = current_param[0]
if type(current_param.annotation).__name__ == "Name":
annotation_str = str(current_param.annotation.id)
doc["Parameters"].append(
nds.Parameter(
param,
f"{annotation_str}",
[f"<Multiline Description Here>"],
)
)
elif (
(not doc_missing)
and doc_extra
and ("Parameters" in doc) # always True
and (not meta["varkwargs"])
):
print(f"{fname}:{func_name}")
to_remove = [p for p in doc["Parameters"] if p[0] in doc_extra]
for remove_me in to_remove:
if " " in remove_me.name and not remove_me.type and not remove_me.desc:
# this is likely some extra text
continue
print(" removing parameters", remove_me.name)
params.remove(remove_me)
elif doc_missing or doc_extra:
print(f"{fname}:{func_name}")
if doc_missing:
print(" missing:", doc_missing)
if doc_extra:
print(" extra:", doc_extra)
return params, jump_to_location
