[Pulp-dev] Docstring linting

Ina Panova ipanova at redhat.com
Thu Jun 6 11:59:51 UTC 2019


+1 to create a PUP.

I think PUP will help us identify pros and cons that will contribute to the
final decision. Team is generally favourable to use black, but as mentioned
in other email thread it does create mixed feelings.
--------
Regards,

Ina Panova
Senior Software Engineer| Pulp| Red Hat Inc.

"Do not go where the path may lead,
 go instead where there is no path and leave a trail."


On Wed, Jun 5, 2019 at 10:42 PM David Davis <daviddavis at redhat.com> wrote:

> Given the generally favorable response so far to using black, I was
> thinking of writing up a PUP to add black into pulpcore, pulpcore-plugin,
> pulp_file, and pulp_template. And to make it the recommended format for
> plugins. I can include docstring linting in that PUP as well.
>
> David
>
>
> On Wed, Jun 5, 2019 at 9:25 AM Brian Bouterse <bbouters at redhat.com> wrote:
>
>> I'm +1 on merging the proposals; it just seems easier. If not, I'd bring
>> it as a followup proposal because I see value in this docstring linting.
>>
>> On Tue, Jun 4, 2019 at 11:00 AM Matthias Dellweg <dellweg at atix.de> wrote:
>>
>>> The core problem this proposal tried to counteract is, just like the
>>> one with black, inconsistency across different repositories in the pulp
>>> namespace. Some lint docstrings and others don't even adhere to the
>>> linted style. Given the architecture of flake8 this leads to strange
>>> effects when you try to lint your code in the pulplift boxes.
>>> So what i really am aiming for here is consistency wrt to docstrings
>>> and docstring linting. This sounds like beeing almost the same goal as
>>> the black proposal. It would be fine for me to even merge those
>>> proposals.
>>>
>>> Matthias
>>>
>>> On Tue, 4 Jun 2019 10:29:58 -0400
>>> David Davis <daviddavis at redhat.com> wrote:
>>>
>>> > Black doesn't format docstrings[0] so it won't really help us. Flake8
>>> > is a wrapper for a collection of tools and the one that lints
>>> > docstrings (pydocstyle[1]) can be run independently without flake8.
>>> > So I think this questions around how/if to lint docstrings and
>>> > whether or not we want to use black are independent.
>>> >
>>> > [0] https://github.com/python/black/issues/144
>>> > [1] https://github.com/PyCQA/pydocstyle
>>> >
>>> > David
>>> >
>>> >
>>> > On Tue, Jun 4, 2019 at 10:05 AM Brian Bouterse <bbouters at redhat.com>
>>> > wrote:
>>> >
>>> > > @mdellweg if we adopt Black broadly, how does that affect your
>>> > > proposal here?
>>> > >
>>> > > On Tue, May 21, 2019 at 11:50 AM Austin Macdonald
>>> > > <austin at redhat.com> wrote:
>>> > >
>>> > >> Something else to consider: some docstrings are rendered as
>>> > >> user-facing documentation in the autogenerated REST docs. This
>>> > >> means that docstring linting needs to be ignored for ViewSets. For
>>> > >> example, I have a PR open that alters pulp_file viewset docstrings
>>> > >> to contain html, to pass the linter, we have add docstring
>>> > >> exceptions to the flake8 config.
>>> > >>
>>> > >> My initial reaction is that we might be better off keeping the
>>> > >> flake8-docstring package out of pulplift, and we should also
>>> > >> remove it from travis.
>>> > >>
>>> > >>
>>> > >> On Tue, May 21, 2019 at 11:08 AM Matthias Dellweg <dellweg at atix.de>
>>> > >> wrote:
>>> > >>
>>> > >>> tl;dr: Docstring linting is inconsistent across pulp repositories.
>>> > >>> To make it consistent, do we want to enforce it everywhere, and
>>> > >>> repair more than 700 findings?
>>> > >>>
>>> > >>> What started out as a oneliner [0] surfaced as a bigger problem:
>>> > >>>
>>> > >>> Whether flake8 performs linting on docstrings is solely dependent
>>> > >>> (afaik) on the existence of a specific python package
>>> > >>> (flake8-docstring) in the system.
>>> > >>> At the same time, there are repositories (pulpcore,
>>> > >>> pulpcore-plugin, ???) that do not install this package in their ci
>>> > >>> pipeline, as well as repos that do (pulp_deb, pulp_ansible, ???).
>>> > >>> So it is hard to select whether it should be installed in a
>>> > >>> pulplift source box.
>>> > >>> Not installing it means, there are linting errors showing up in
>>> > >>> travis only, however installing it will prevent linting pulpcore
>>> > >>> locally.
>>> > >>> That said, i think we should follow the same linting rules in all
>>> > >>> repositories, and more specific i tend to include docstring
>>> > >>> linting. However there are over 700 findings in pulpcore alone.
>>> > >>>
>>> > >>> [0] https://github.com/pulp/pulpcore/pull/138
>>> > >>> _______________________________________________
>>> > >>> Pulp-dev mailing list
>>> > >>> Pulp-dev at redhat.com
>>> > >>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>> > >>>
>>> > >> _______________________________________________
>>> > >> Pulp-dev mailing list
>>> > >> Pulp-dev at redhat.com
>>> > >> https://www.redhat.com/mailman/listinfo/pulp-dev
>>> > >>
>>> > > _______________________________________________
>>> > > Pulp-dev mailing list
>>> > > Pulp-dev at redhat.com
>>> > > https://www.redhat.com/mailman/listinfo/pulp-dev
>>>
>> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20190606/a11724fa/attachment.htm>


More information about the Pulp-dev mailing list