From stephen at that.guru Fri Jul 12 09:28:02 2019 From: stephen at that.guru (Stephen Finucane) Date: Fri, 12 Jul 2019 14:28:02 +0100 Subject: [code-quality] Adoption of doc8 Message-ID: <87b59dbc788518830d9e53b3597c15c2c00ca518.camel@that.guru> Hi, I'd like to explore the idea of adopting the 'doc8' tool within the PyCQA organization. For anyone not familiar with the tool, 'doc8' markets itself as "an opinionated style checker for rst (with basic support for plain text) styles of documentation." It's currently maintained within the OpenStack community but there have been some valid concerns raised recently regarding the health of the 'doc8' tool [1]. While it is extensively used within OpenStack (and outside it too, fwiw), it's very much secondary to the core goal of OpenStack itself, which probably explains the lack of attention it's received over the last few years. While 'doc8' is not a checker for Python code itself, it is Python- based, is a "quality tool", and rST+docutils/Sphinx remains the documentation tool of choice for the Python community. For this reason, I think PyCQA might be a good fit as a parent organization. The other possible parent organizations I've been looking at are sphinx- doc/sphinx-contrib and docutils, but doc8 isn't actually Sphinx-based, which kind of rules out the former, while the docutils community are _still_ insisting on Sourceforge and Subversion, ruling them out :( Does anyone else think PyCQA might possibly make a good fit for 'doc8'? If so, I'll raise the idea formally within OpenStack and start on the paperwork to move things across. If not, I'd welcome other ideas for where this useful project could live. Stephen [1] http://lists.openstack.org/pipermail/openstack-discuss/2019-July/007669.html From graffatcolmingov at gmail.com Sat Jul 13 13:26:30 2019 From: graffatcolmingov at gmail.com (Ian Stapleton Cordasco) Date: Sat, 13 Jul 2019 12:26:30 -0500 Subject: [code-quality] Adoption of doc8 In-Reply-To: <87b59dbc788518830d9e53b3597c15c2c00ca518.camel@that.guru> References: <87b59dbc788518830d9e53b3597c15c2c00ca518.camel@that.guru> Message-ID: On Sat, Jul 13, 2019 at 12:23 PM Stephen Finucane wrote: > > Hi, > > I'd like to explore the idea of adopting the 'doc8' tool within the > PyCQA organization. For anyone not familiar with the tool, 'doc8' > markets itself as "an opinionated style checker for rst (with basic > support for plain text) styles of documentation." It's currently > maintained within the OpenStack community but there have been some > valid concerns raised recently regarding the health of the 'doc8' tool > [1]. While it is extensively used within OpenStack (and outside it too, > fwiw), it's very much secondary to the core goal of OpenStack itself, > which probably explains the lack of attention it's received over the > last few years. > > While 'doc8' is not a checker for Python code itself, it is Python- > based, is a "quality tool", and rST+docutils/Sphinx remains the > documentation tool of choice for the Python community. For this reason, > I think PyCQA might be a good fit as a parent organization. The other > possible parent organizations I've been looking at are sphinx- > doc/sphinx-contrib and docutils, but doc8 isn't actually Sphinx-based, > which kind of rules out the former, while the docutils community are > _still_ insisting on Sourceforge and Subversion, ruling them out :( > > Does anyone else think PyCQA might possibly make a good fit for 'doc8'? > If so, I'll raise the idea formally within OpenStack and start on the > paperwork to move things across. If not, I'd welcome other ideas for > where this useful project could live. > > Stephen > > [1] http://lists.openstack.org/pipermail/openstack-discuss/2019-July/007669.html I thiink it's definitely a fit given its focus. I don't know that there's anyone in the PyCQA, however, who has the cycles to maintain it. Would you and Sorin be willing to maintain it inside the PyCQA? I'd be happy to set things up so that you both could add more maintainers easily. Cheers, Ian From bassam.khouri at gmail.com Mon Jul 15 15:27:41 2019 From: bassam.khouri at gmail.com (Bassam Khouri) Date: Mon, 15 Jul 2019 15:27:41 -0400 Subject: [code-quality] pylint --no-docstring-rgx issues In-Reply-To: References: Message-ID: I had looked at the pylint source code, and did some python troubleshooting, I discovered the matching was only checking against the beginning of the line. Someone in the community also offered the same suggestion (which prompted me to reply to my own post in hopes this may help someone else). In the end, I used the following: (?i)(?P^(tests?)?_)|(?P.*tests$) I know (?P) is not needed as it can't be used, but I find it useful for reading the regular expression and helping determine what a group is expected to match. Bassam On Wed, May 29, 2019 at 11:22 AM Bassam Khouri wrote: > Hi, > > I'm trying to configure the no-docstring-rgx option to ignore function > and class names that: > - Starts with _ > - Starts with test_ > - Ends with tests > - Ends with Tests > > I came up with the following regular expression: > > (^(test)?_)|((T|t)ests$) > > > When I test the regular expression on https://regex101.com/r/3BXmsa/6, it > matches the text I expect it to match. > > However, when I run pylint against my code, it still reports a docstring > is missing for a class name that ends with Tests. > > For example, if I have the following python 3 code. > > import unittest > > > class _Utils(unittest.TestCase): > pass > > > class Test_Foo(unittest.TestCase): > pass > > > class test_Foo(unittest.TestCase): > pass > > > class UtilsTests(unittest.TestCase): > > def test_function_name(self): > pass > > def _foo(self): > pass > > def my_tests(self): > pass > > > if __name__ == "__main__": > unittest.main() > > > Running pylint --disable=all --enable=missing-docstring > --no-docstring-rgx='(^(test)?_)|((T|t)ests$)' ./test.py yields > > $ pylint --disable=all --enable=missing-docstring > --no-docstring-rgx='(^(test)?_)|((T|t)ests$)' ./test.py > > ************* Module test > > test.py:1:0: C0111: Missing module docstring (missing-docstring) > > test.py:8:0: C0111: Missing class docstring (missing-docstring) > > test.py:16:0: C0111: Missing class docstring (missing-docstring) > > test.py:24:4: C0111: Missing method docstring (missing-docstring) > > > ------------------------------------------------------------------ > > Your code has been rated at 7.50/10 (previous run: 7.50/10, +0.00) > > > I was only expecting to see the Missing module docstring violation, and > the missing class docstring on line 8. > > Here is my environment: > > $ pylint --version > > pylint 2.3.1 > > astroid 2.2.5 > > Python 3.7.3 (default, Mar 27 2019, 09:23:15) > > [Clang 10.0.1 (clang-1001.0.46.3)] > > Any ideas what is going on and how to fix it? > > Cheers, > > Bassam > --- > "What we can or cannot do, what we consider possible or impossible, is > rarely a function of our true capability. It is more likely a function of > our beliefs about who we are." - Tony Robbins > -------------- next part -------------- An HTML attachment was scrubbed... URL: From graffatcolmingov at gmail.com Thu Jul 18 08:36:54 2019 From: graffatcolmingov at gmail.com (Ian Stapleton Cordasco) Date: Thu, 18 Jul 2019 07:36:54 -0500 Subject: [code-quality] Adoption of doc8 In-Reply-To: <288e4eb1868650a8b40bd2a7874aaada0d598b5f.camel@that.guru> References: <87b59dbc788518830d9e53b3597c15c2c00ca518.camel@that.guru> <288e4eb1868650a8b40bd2a7874aaada0d598b5f.camel@that.guru> Message-ID: I'm not sure. Bandit, however, completed the transition a few years ago. I suspect there are clues in Gerrit and on the mailing list archives here and there. Once y'all have a GitHub repository you'd like to move over. You can either add me to it so I can move it into the org or I can make the teams, make y'all moderators and I _think_ that will give you the ability to move it yourselves. On Tue, Jul 16, 2019 at 10:44 AM Stephen Finucane wrote: > > On Sat, 2019-07-13 at 12:26 -0500, Ian Stapleton Cordasco wrote: > > On Sat, Jul 13, 2019 at 12:23 PM Stephen Finucane wrote: > > > Hi, > > > > > > I'd like to explore the idea of adopting the 'doc8' tool within the > > > PyCQA organization. For anyone not familiar with the tool, 'doc8' > > > markets itself as "an opinionated style checker for rst (with basic > > > support for plain text) styles of documentation." It's currently > > > maintained within the OpenStack community but there have been some > > > valid concerns raised recently regarding the health of the 'doc8' tool > > > [1]. While it is extensively used within OpenStack (and outside it too, > > > fwiw), it's very much secondary to the core goal of OpenStack itself, > > > which probably explains the lack of attention it's received over the > > > last few years. > > > > > > While 'doc8' is not a checker for Python code itself, it is Python- > > > based, is a "quality tool", and rST+docutils/Sphinx remains the > > > documentation tool of choice for the Python community. For this reason, > > > I think PyCQA might be a good fit as a parent organization. The other > > > possible parent organizations I've been looking at are sphinx- > > > doc/sphinx-contrib and docutils, but doc8 isn't actually Sphinx-based, > > > which kind of rules out the former, while the docutils community are > > > _still_ insisting on Sourceforge and Subversion, ruling them out :( > > > > > > Does anyone else think PyCQA might possibly make a good fit for 'doc8'? > > > If so, I'll raise the idea formally within OpenStack and start on the > > > paperwork to move things across. If not, I'd welcome other ideas for > > > where this useful project could live. > > > > > > Stephen > > > > > > [1] http://lists.openstack.org/pipermail/openstack-discuss/2019-July/007669.html > > > > I thiink it's definitely a fit given its focus. I don't know that > > there's anyone in the PyCQA, however, who has the cycles to maintain > > it. Would you and Sorin be willing to maintain it inside the PyCQA? > > I'd be happy to set things up so that you both could add more > > maintainers easily. > > Yeah, that would be the expectation, though I would hope that some > other interested parties might eventually discover the project and > pitch in, of course (wishful thinking, perhaps :)). > > What are the next steps? > > Stephen > > > Cheers, > > Ian > From stephen at that.guru Tue Jul 16 11:44:42 2019 From: stephen at that.guru (Stephen Finucane) Date: Tue, 16 Jul 2019 16:44:42 +0100 Subject: [code-quality] Adoption of doc8 In-Reply-To: References: <87b59dbc788518830d9e53b3597c15c2c00ca518.camel@that.guru> Message-ID: <288e4eb1868650a8b40bd2a7874aaada0d598b5f.camel@that.guru> On Sat, 2019-07-13 at 12:26 -0500, Ian Stapleton Cordasco wrote: > On Sat, Jul 13, 2019 at 12:23 PM Stephen Finucane wrote: > > Hi, > > > > I'd like to explore the idea of adopting the 'doc8' tool within the > > PyCQA organization. For anyone not familiar with the tool, 'doc8' > > markets itself as "an opinionated style checker for rst (with basic > > support for plain text) styles of documentation." It's currently > > maintained within the OpenStack community but there have been some > > valid concerns raised recently regarding the health of the 'doc8' tool > > [1]. While it is extensively used within OpenStack (and outside it too, > > fwiw), it's very much secondary to the core goal of OpenStack itself, > > which probably explains the lack of attention it's received over the > > last few years. > > > > While 'doc8' is not a checker for Python code itself, it is Python- > > based, is a "quality tool", and rST+docutils/Sphinx remains the > > documentation tool of choice for the Python community. For this reason, > > I think PyCQA might be a good fit as a parent organization. The other > > possible parent organizations I've been looking at are sphinx- > > doc/sphinx-contrib and docutils, but doc8 isn't actually Sphinx-based, > > which kind of rules out the former, while the docutils community are > > _still_ insisting on Sourceforge and Subversion, ruling them out :( > > > > Does anyone else think PyCQA might possibly make a good fit for 'doc8'? > > If so, I'll raise the idea formally within OpenStack and start on the > > paperwork to move things across. If not, I'd welcome other ideas for > > where this useful project could live. > > > > Stephen > > > > [1] http://lists.openstack.org/pipermail/openstack-discuss/2019-July/007669.html > > I thiink it's definitely a fit given its focus. I don't know that > there's anyone in the PyCQA, however, who has the cycles to maintain > it. Would you and Sorin be willing to maintain it inside the PyCQA? > I'd be happy to set things up so that you both could add more > maintainers easily. Yeah, that would be the expectation, though I would hope that some other interested parties might eventually discover the project and pitch in, of course (wishful thinking, perhaps :)). What are the next steps? Stephen > Cheers, > Ian From stephen at that.guru Thu Jul 18 09:04:48 2019 From: stephen at that.guru (Stephen Finucane) Date: Thu, 18 Jul 2019 14:04:48 +0100 Subject: [code-quality] Adoption of doc8 In-Reply-To: References: <87b59dbc788518830d9e53b3597c15c2c00ca518.camel@that.guru> <288e4eb1868650a8b40bd2a7874aaada0d598b5f.camel@that.guru> Message-ID: <230c8af86b872fea61ee8e9b7593ac38d359d50c.camel@that.guru> On Thu, 2019-07-18 at 07:36 -0500, Ian Stapleton Cordasco wrote: > I'm not sure. Bandit, however, completed the transition a few years > ago. I suspect there are clues in Gerrit and on the mailing list > archives here and there. Once y'all have a GitHub repository you'd > like to move over. You can either add me to it so I can move it into > the org or I can make the teams, make y'all moderators and I _think_ > that will give you the ability to move it yourselves. Sure, I'll get a move on with this now, starting with a mail to openstack-discuss (just sent) and a patch based on [1]. Instead of moving a repo across though, perhaps you could just create an empty 'pycqa/doc8' repo that we can populate, adding us an admins in the process? This means we don't have to work through moving things from the OpenStack organization on GitHub or having the "forked from" metadata on the repo. If there's an empty repo, I can just push everything to that. Stephen [1] https://review.opendev.org/#/c/564453/ > On Tue, Jul 16, 2019 at 10:44 AM Stephen Finucane > wrote: > > On Sat, 2019-07-13 at 12:26 -0500, Ian Stapleton Cordasco wrote: > > > On Sat, Jul 13, 2019 at 12:23 PM Stephen Finucane < > > > stephen at that.guru> wrote: > > > > Hi, > > > > > > > > I'd like to explore the idea of adopting the 'doc8' tool within > > > > the > > > > PyCQA organization. For anyone not familiar with the tool, > > > > 'doc8' > > > > markets itself as "an opinionated style checker for rst (with > > > > basic > > > > support for plain text) styles of documentation." It's > > > > currently > > > > maintained within the OpenStack community but there have been > > > > some > > > > valid concerns raised recently regarding the health of the > > > > 'doc8' tool > > > > [1]. While it is extensively used within OpenStack (and outside > > > > it too, > > > > fwiw), it's very much secondary to the core goal of OpenStack > > > > itself, > > > > which probably explains the lack of attention it's received > > > > over the > > > > last few years. > > > > > > > > While 'doc8' is not a checker for Python code itself, it is > > > > Python- > > > > based, is a "quality tool", and rST+docutils/Sphinx remains the > > > > documentation tool of choice for the Python community. For this > > > > reason, > > > > I think PyCQA might be a good fit as a parent organization. The > > > > other > > > > possible parent organizations I've been looking at are sphinx- > > > > doc/sphinx-contrib and docutils, but doc8 isn't actually > > > > Sphinx-based, > > > > which kind of rules out the former, while the docutils > > > > community are > > > > _still_ insisting on Sourceforge and Subversion, ruling them > > > > out :( > > > > > > > > Does anyone else think PyCQA might possibly make a good fit for > > > > 'doc8'? > > > > If so, I'll raise the idea formally within OpenStack and start > > > > on the > > > > paperwork to move things across. If not, I'd welcome other > > > > ideas for > > > > where this useful project could live. > > > > > > > > Stephen > > > > > > > > [1] > > > > http://lists.openstack.org/pipermail/openstack-discuss/2019-July/007669.html > > > > > > I thiink it's definitely a fit given its focus. I don't know that > > > there's anyone in the PyCQA, however, who has the cycles to > > > maintain > > > it. Would you and Sorin be willing to maintain it inside the > > > PyCQA? > > > I'd be happy to set things up so that you both could add more > > > maintainers easily. > > > > Yeah, that would be the expectation, though I would hope that some > > other interested parties might eventually discover the project and > > pitch in, of course (wishful thinking, perhaps :)). > > > > What are the next steps? > > > > Stephen > > > > > Cheers, > > > Ian From mats at wichmann.us Thu Jul 18 10:52:40 2019 From: mats at wichmann.us (Mats Wichmann) Date: Thu, 18 Jul 2019 08:52:40 -0600 Subject: [code-quality] Adoption of doc8 In-Reply-To: References: <87b59dbc788518830d9e53b3597c15c2c00ca518.camel@that.guru> Message-ID: <9e2e7e8c-17a1-6b9f-c973-36e033f0d290@wichmann.us> On 7/13/19 11:26 AM, Ian Stapleton Cordasco wrote: >> Does anyone else think PyCQA might possibly make a good fit for 'doc8'? >> If so, I'll raise the idea formally within OpenStack and start on the >> paperwork to move things across. If not, I'd welcome other ideas for >> where this useful project could live. >> >> Stephen >> >> [1] http://lists.openstack.org/pipermail/openstack-discuss/2019-July/007669.html > > I thiink it's definitely a fit given its focus. I don't know that > there's anyone in the PyCQA, however, who has the cycles to maintain > it. Would you and Sorin be willing to maintain it inside the PyCQA? > I'd be happy to set things up so that you both could add more > maintainers easily. I haven't done anything within this org except join the mailing list and lurk, but I might be able to give some time to such a project. There'd be a learning curve, natch, so this is just to say I'm here, not that I'd be any immediate help. From graffatcolmingov at gmail.com Thu Jul 18 19:24:03 2019 From: graffatcolmingov at gmail.com (Ian Stapleton Cordasco) Date: Thu, 18 Jul 2019 18:24:03 -0500 Subject: [code-quality] Adoption of doc8 In-Reply-To: <230c8af86b872fea61ee8e9b7593ac38d359d50c.camel@that.guru> References: <87b59dbc788518830d9e53b3597c15c2c00ca518.camel@that.guru> <288e4eb1868650a8b40bd2a7874aaada0d598b5f.camel@that.guru> <230c8af86b872fea61ee8e9b7593ac38d359d50c.camel@that.guru> Message-ID: On Thu, Jul 18, 2019 at 8:04 AM Stephen Finucane wrote: > > On Thu, 2019-07-18 at 07:36 -0500, Ian Stapleton Cordasco wrote: > > I'm not sure. Bandit, however, completed the transition a few years > > ago. I suspect there are clues in Gerrit and on the mailing list > > archives here and there. Once y'all have a GitHub repository you'd > > like to move over. You can either add me to it so I can move it into > > the org or I can make the teams, make y'all moderators and I _think_ > > that will give you the ability to move it yourselves. > > Sure, I'll get a move on with this now, starting with a mail to > openstack-discuss (just sent) and a patch based on [1]. Instead of > moving a repo across though, perhaps you could just create an empty > 'pycqa/doc8' repo that we can populate, adding us an admins in the > process? This means we don't have to work through moving things from > the OpenStack organization on GitHub or having the "forked from" > metadata on the repo. If there's an empty repo, I can just push > everything to that. Sure thing. That's done. I've invited Sorin to the organization but I don't know your GitHub username to add you, Stephen. > Stephen > > [1] https://review.opendev.org/#/c/564453/ > > > On Tue, Jul 16, 2019 at 10:44 AM Stephen Finucane > > wrote: > > > On Sat, 2019-07-13 at 12:26 -0500, Ian Stapleton Cordasco wrote: > > > > On Sat, Jul 13, 2019 at 12:23 PM Stephen Finucane < > > > > stephen at that.guru> wrote: > > > > > Hi, > > > > > > > > > > I'd like to explore the idea of adopting the 'doc8' tool within > > > > > the > > > > > PyCQA organization. For anyone not familiar with the tool, > > > > > 'doc8' > > > > > markets itself as "an opinionated style checker for rst (with > > > > > basic > > > > > support for plain text) styles of documentation." It's > > > > > currently > > > > > maintained within the OpenStack community but there have been > > > > > some > > > > > valid concerns raised recently regarding the health of the > > > > > 'doc8' tool > > > > > [1]. While it is extensively used within OpenStack (and outside > > > > > it too, > > > > > fwiw), it's very much secondary to the core goal of OpenStack > > > > > itself, > > > > > which probably explains the lack of attention it's received > > > > > over the > > > > > last few years. > > > > > > > > > > While 'doc8' is not a checker for Python code itself, it is > > > > > Python- > > > > > based, is a "quality tool", and rST+docutils/Sphinx remains the > > > > > documentation tool of choice for the Python community. For this > > > > > reason, > > > > > I think PyCQA might be a good fit as a parent organization. The > > > > > other > > > > > possible parent organizations I've been looking at are sphinx- > > > > > doc/sphinx-contrib and docutils, but doc8 isn't actually > > > > > Sphinx-based, > > > > > which kind of rules out the former, while the docutils > > > > > community are > > > > > _still_ insisting on Sourceforge and Subversion, ruling them > > > > > out :( > > > > > > > > > > Does anyone else think PyCQA might possibly make a good fit for > > > > > 'doc8'? > > > > > If so, I'll raise the idea formally within OpenStack and start > > > > > on the > > > > > paperwork to move things across. If not, I'd welcome other > > > > > ideas for > > > > > where this useful project could live. > > > > > > > > > > Stephen > > > > > > > > > > [1] > > > > > http://lists.openstack.org/pipermail/openstack-discuss/2019-July/007669.html > > > > > > > > I thiink it's definitely a fit given its focus. I don't know that > > > > there's anyone in the PyCQA, however, who has the cycles to > > > > maintain > > > > it. Would you and Sorin be willing to maintain it inside the > > > > PyCQA? > > > > I'd be happy to set things up so that you both could add more > > > > maintainers easily. > > > > > > Yeah, that would be the expectation, though I would hope that some > > > other interested parties might eventually discover the project and > > > pitch in, of course (wishful thinking, perhaps :)). > > > > > > What are the next steps? > > > > > > Stephen > > > > > > > Cheers, > > > > Ian >