Add documentation for a *data* field to the given docstring. Parameters ---------- docstring : str The input docstring. replace_names : list of str or None The list of parameter names which arguments should be replaced by ``data[name]`` (if ``data[name]`
(docstring, replace_names)
| 1406 | |
| 1407 | |
| 1408 | def _add_data_doc(docstring, replace_names): |
| 1409 | """ |
| 1410 | Add documentation for a *data* field to the given docstring. |
| 1411 | |
| 1412 | Parameters |
| 1413 | ---------- |
| 1414 | docstring : str |
| 1415 | The input docstring. |
| 1416 | replace_names : list of str or None |
| 1417 | The list of parameter names which arguments should be replaced by |
| 1418 | ``data[name]`` (if ``data[name]`` does not throw an exception). If |
| 1419 | None, replacement is attempted for all arguments. |
| 1420 | |
| 1421 | Returns |
| 1422 | ------- |
| 1423 | str |
| 1424 | The augmented docstring. |
| 1425 | """ |
| 1426 | if (docstring is None |
| 1427 | or replace_names is not None and len(replace_names) == 0): |
| 1428 | return docstring |
| 1429 | docstring = inspect.cleandoc(docstring) |
| 1430 | |
| 1431 | data_doc = ("""\ |
| 1432 | If given, all parameters also accept a string ``s``, which is |
| 1433 | interpreted as ``data[s]`` if ``s`` is a key in ``data``.""" |
| 1434 | if replace_names is None else f"""\ |
| 1435 | If given, the following parameters also accept a string ``s``, which is |
| 1436 | interpreted as ``data[s]`` if ``s`` is a key in ``data``: |
| 1437 | |
| 1438 | {', '.join(map('*{}*'.format, replace_names))}""") |
| 1439 | # using string replacement instead of formatting has the advantages |
| 1440 | # 1) simpler indent handling |
| 1441 | # 2) prevent problems with formatting characters '{', '%' in the docstring |
| 1442 | if _log.level <= logging.DEBUG: |
| 1443 | # test_data_parameter_replacement() tests against these log messages |
| 1444 | # make sure to keep message and test in sync |
| 1445 | if "data : indexable object, optional" not in docstring: |
| 1446 | _log.debug("data parameter docstring error: no data parameter") |
| 1447 | if 'DATA_PARAMETER_PLACEHOLDER' not in docstring: |
| 1448 | _log.debug("data parameter docstring error: missing placeholder") |
| 1449 | return docstring.replace(' DATA_PARAMETER_PLACEHOLDER', data_doc) |
| 1450 | |
| 1451 | |
| 1452 | def _preprocess_data(func=None, *, replace_names=None, label_namer=None): |
no test coverage detected
searching dependent graphs…