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