From 9abad26be981c1d95cfcab11361006d40859422c Mon Sep 17 00:00:00 2001 From: "J. Sebastian Paez" Date: Sat, 10 Sep 2022 14:47:33 -0500 Subject: [PATCH 1/4] fix issue where passing two styles would fail with index error --- pydocstringformatter/_formatting/base.py | 2 +- .../numpydoc_parameter_spacing.args | 2 + .../multi_style/numpydoc_parameter_spacing.py | 63 ++++++++++++++++ .../numpydoc_parameter_spacing.py.out | 74 +++++++++++++++++++ 4 files changed, 140 insertions(+), 1 deletion(-) create mode 100644 tests/data/format/multi_style/numpydoc_parameter_spacing.args create mode 100644 tests/data/format/multi_style/numpydoc_parameter_spacing.py create mode 100644 tests/data/format/multi_style/numpydoc_parameter_spacing.py.out diff --git a/pydocstringformatter/_formatting/base.py b/pydocstringformatter/_formatting/base.py index 882246f8..a109fe87 100644 --- a/pydocstringformatter/_formatting/base.py +++ b/pydocstringformatter/_formatting/base.py @@ -278,7 +278,7 @@ def treat_string( if first_section: section[0] = section[0].lstrip() first_section = False - elif not section[0][0].isspace(): + elif len(section[0]) > 0 and not section[0][0].isspace(): section[0] = f"{' ' * indent_length:s}{section[0]:s}" # Rejoin sections diff --git a/tests/data/format/multi_style/numpydoc_parameter_spacing.args b/tests/data/format/multi_style/numpydoc_parameter_spacing.args new file mode 100644 index 00000000..ca785ac8 --- /dev/null +++ b/tests/data/format/multi_style/numpydoc_parameter_spacing.args @@ -0,0 +1,2 @@ +--style=numpydoc +--style=pep257 diff --git a/tests/data/format/multi_style/numpydoc_parameter_spacing.py b/tests/data/format/multi_style/numpydoc_parameter_spacing.py new file mode 100644 index 00000000..619d27cf --- /dev/null +++ b/tests/data/format/multi_style/numpydoc_parameter_spacing.py @@ -0,0 +1,63 @@ +"""Example module for numpydoc docstring style. +References +----- +NumPy docstring style guide: +https://numpydoc.readthedocs.io/en/latest/format.html#documenting-modules""" +import math + +EULER_NUMBER = math.e +"""Euler's number. + +Not related to Euler's constant (sometimes called the Euler-Mascheroni +constant. +References +----- +E (mathematical constant) +https://en.wikipedia.org/wiki/E_(mathematical_constant) +Notes +--- +It is the limit of ``(1 + 1/n)**n`` as n approaches infinity, so it +is used in the equation for continuously-compouned interest. + +It is also the sum of the reciprocals of the whole numbers starting +with zero, which is related to some calculus-related properties +mathemeticians find elegant. +""" + + +def sincos(theta): + """Returns + ---- + sin: float + the sine of theta + cos: float + the cosine of theta + Raises + --- + TypeError + If `theta` is not a float. + Parameters + ----- + theta: float + the angle at which to calculate the sine and cosine. +""" + return math.sin(theta), math.cos(theta) + + +def fibbonacci(): + """Generate the Fibonacci sequence. + + Each term is the sum of the two previous; conventionally starts + with two ones. + References + ----- + Fibonacci numbers + https://en.wikipedia.org/wiki/Fibonacci_number + Yields + --- + int""" + curr = 1 + last = 0 + while True: + yield curr + curr, last = curr + last, curr diff --git a/tests/data/format/multi_style/numpydoc_parameter_spacing.py.out b/tests/data/format/multi_style/numpydoc_parameter_spacing.py.out new file mode 100644 index 00000000..d4e4d089 --- /dev/null +++ b/tests/data/format/multi_style/numpydoc_parameter_spacing.py.out @@ -0,0 +1,74 @@ +"""Example module for numpydoc docstring style. + +References +---------- +NumPy docstring style guide: +https://numpydoc.readthedocs.io/en/latest/format.html#documenting-modules +""" +import math + +EULER_NUMBER = math.e +"""Euler's number. + +Not related to Euler's constant (sometimes called the Euler-Mascheroni +constant. + +Notes +----- +It is the limit of ``(1 + 1/n)**n`` as n approaches infinity, so it +is used in the equation for continuously-compouned interest. + +It is also the sum of the reciprocals of the whole numbers starting +with zero, which is related to some calculus-related properties +mathemeticians find elegant. + +References +---------- +E (mathematical constant) +https://en.wikipedia.org/wiki/E_(mathematical_constant) +""" + + +def sincos(theta): + """Returns. + + Parameters + ---------- + theta : float + the angle at which to calculate the sine and cosine. + + Raises + ------ + TypeError + If `theta` is not a float. + + + + sin: float + the sine of theta + cos: float + the cosine of theta + """ + return math.sin(theta), math.cos(theta) + + +def fibbonacci(): + """Generate the Fibonacci sequence. + + Each term is the sum of the two previous; conventionally starts + with two ones. + + Yields + ------ + int + + References + ---------- + Fibonacci numbers + https://en.wikipedia.org/wiki/Fibonacci_number + """ + curr = 1 + last = 0 + while True: + yield curr + curr, last = curr + last, curr From 0c6795b437e01d62e2134eb8efd6099b59e54777 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 10 Sep 2022 19:51:01 +0000 Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- tests/data/format/multi_style/numpydoc_parameter_spacing.py.out | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/data/format/multi_style/numpydoc_parameter_spacing.py.out b/tests/data/format/multi_style/numpydoc_parameter_spacing.py.out index d4e4d089..ac058084 100644 --- a/tests/data/format/multi_style/numpydoc_parameter_spacing.py.out +++ b/tests/data/format/multi_style/numpydoc_parameter_spacing.py.out @@ -43,7 +43,7 @@ def sincos(theta): If `theta` is not a float. - + sin: float the sine of theta cos: float From 903c95fefaa5d9b26edf6dfddac2c84cabb8e3fc Mon Sep 17 00:00:00 2001 From: "J. Sebastian Paez" Date: Mon, 12 Sep 2022 04:53:32 -0400 Subject: [PATCH 3/4] Update pydocstringformatter/_formatting/base.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Daniël van Noord <13665637+DanielNoord@users.noreply.github.com> --- pydocstringformatter/_formatting/base.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pydocstringformatter/_formatting/base.py b/pydocstringformatter/_formatting/base.py index a109fe87..7dff055f 100644 --- a/pydocstringformatter/_formatting/base.py +++ b/pydocstringformatter/_formatting/base.py @@ -278,7 +278,7 @@ def treat_string( if first_section: section[0] = section[0].lstrip() first_section = False - elif len(section[0]) > 0 and not section[0][0].isspace(): + elif section[0] and not section[0][0].isspace(): section[0] = f"{' ' * indent_length:s}{section[0]:s}" # Rejoin sections From c245c032bd4d528b106df27d49ae7f0173695eee Mon Sep 17 00:00:00 2001 From: "J. Sebastian Paez" Date: Mon, 12 Sep 2022 16:06:57 -0500 Subject: [PATCH 4/4] handled empty section name whitespaces --- pydocstringformatter/_formatting/formatters_numpydoc.py | 5 ++++- .../format/multi_style/numpydoc_parameter_spacing.py.out | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/pydocstringformatter/_formatting/formatters_numpydoc.py b/pydocstringformatter/_formatting/formatters_numpydoc.py index 5f3b5d22..8ea54005 100644 --- a/pydocstringformatter/_formatting/formatters_numpydoc.py +++ b/pydocstringformatter/_formatting/formatters_numpydoc.py @@ -121,7 +121,10 @@ def treat_sections( # summary. They have neither a section header nor the # line of hyphens after it. indent_length = section_lines[1].index("-") - section_lines[1] = " " * indent_length + "-" * len(section_name) + + if section_name: + section_lines[1] = " " * indent_length + "-" * len(section_name) + if first_section: # If the second line were not hyphens, the section name # would be summary. This assumes triple quotes, but that diff --git a/tests/data/format/multi_style/numpydoc_parameter_spacing.py.out b/tests/data/format/multi_style/numpydoc_parameter_spacing.py.out index ac058084..802978c1 100644 --- a/tests/data/format/multi_style/numpydoc_parameter_spacing.py.out +++ b/tests/data/format/multi_style/numpydoc_parameter_spacing.py.out @@ -43,7 +43,7 @@ def sincos(theta): If `theta` is not a float. - + ---- sin: float the sine of theta cos: float