Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

loader: use inspect to make callable docs consistent #2071

Merged
merged 1 commit into from
May 26, 2021

Conversation

dgw
Copy link
Member

@dgw dgw commented May 18, 2021

Description

Our own trim_docstring function is OK, but definitely not perfect. What it returns can be inconsistently indented depending on whether the docstring passed in is single- or multi-line, or whether a multi-line docstring starts on line 0 or line 1 (next to or below the """). It's nice to have consistent indentation.

I don't have any strong feelings about where to implement this. Maybe it would make more sense to apply inspect.cleandoc() inside the logic of trim_docstring instead of using inspect.getdoc() on the callable. Either way, our help infrastructure will be easier to improve if we eliminate anything like this that can cause inconsistent output.

Checklist

  • I have read CONTRIBUTING.md
  • I can and do license this contribution under the EFLv2
  • No issues are reported by make qa (runs make quality and make test)
    • Not tested yet (see notes) CI did its job
  • I have tested the functionality of the things this change touches
    • Well, I did when I wrote the patch last year…

Notes

I know this has a merge conflict; it's an old branch I found while cleaning up now that most of 7.1.0's stuff is merged. I'll take care of that (or overwrite the branch with a different approach) when the time comes.

@dgw dgw added the Tweak label May 18, 2021
sopel/loader.py Outdated Show resolved Hide resolved
@dgw dgw added this to the 7.1.0 milestone May 24, 2021
@dgw dgw requested a review from a team May 24, 2021 02:19
Our own `trim_docstring` function is OK, but definitely not perfect.
What it returns can be inconsistently indented depending on whether the
docstring passed in is single- or multi-line, or whether a multi-line
docstring starts on line 0 or line 1 (next to or below the """).

Maybe the `inspect` module wasn't so great in the olden days, or maybe
the maintainers of what was then called Willie just weren't aware of its
existence. Whatever the reason, in the modern Python world, there is no
simpler way to get a consistently (de)indented dostring than by using
`inspect.getdoc()`.

May this 7.5-year-old relic of a function (introduced in late 2013 via
15b171c) enjoy its brief visit to
deprecation limbo before being removed entirely in Sopel 8.

Co-authored-by: Exirel <florian.strzelecki@gmail.com>
@dgw dgw force-pushed the clean-in-trim_docstring branch from 7e9b020 to a70b1e6 Compare May 25, 2021 06:53
@dgw dgw marked this pull request as ready for review May 25, 2021 06:55
Copy link
Contributor

@Exirel Exirel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice.

I had a look at our test suite, which checks what should be in func._docs and since they pass, I think we are all good.

Let's go, this is the last one before 7.1!

@dgw dgw merged commit b6fb3b3 into master May 26, 2021
@dgw dgw deleted the clean-in-trim_docstring branch May 26, 2021 05:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants