[DOCS] Python Language Conventions

[DOCS] Python Language Conventions

[Martin Liška]

I think we should add how Python scripts should be formatted. I noticed
that while reading the Modula-2 patchset where it follows the C/C++ style
when it comes to Python files.

Ready to be installed?
Thanks,
Martin

---
 htdocs/codingconventions.html | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/htdocs/codingconventions.html b/htdocs/codingconventions.html
index e4d30510..180ef35a 100644
--- a/htdocs/codingconventions.html
+++ b/htdocs/codingconventions.html
@@ -80,6 +80,7 @@ the conventions separately from any other changes to the code.</p>
     </li>
     </ul>
 </li>
+<li><a href="#Python_Conventions">Python Language Conventions</a>
 </ul>
 
 
@@ -1483,6 +1484,19 @@ with a right brace, optional closing comment, and a new line.
 Definitions within the body of a namespace are not indented.
 </p>
 
+<h2 id="Python_Conventions">Python Language Conventions</h2>
+
+<p>
+Python scripts should follow <a href="https://peps.python.org/pep-0008/">PEP 8 – Style Guide for Python Code</a>
+which can be verified by <a href="flake8.pycqa.org">flake8</a> tool.
+We do also recommend using the following <code>flake8</code> plug-ins:
+
+<ul>
+    <li>flake8-builtins</li>
+    <li>flake8-import-order</li>
+    <li>flake8-quotes</li>
+</ul>
+</p>
 
 </body>
 </html>
-- 
2.37.3

Re: [DOCS] Python Language Conventions

[Gerald Pfeifer]

[-- Attachment #1: Type: text/plain, Size: 973 bytes --]

Hi Martin,

On Thu, 13 Oct 2022, Martin Liška wrote:
> I think we should add how Python scripts should be formatted. I noticed
> that while reading the Modula-2 patchset where it follows the C/C++ style
> when it comes to Python files.

good initiative, thank you! This makes sense to me, alas I'm not a Python 
hacker, so best wait to see what David and Gaius think, too?


Some suggestions on the web side of things:

> +<li><a href="#Python_Conventions">Python Language Conventions</a>

Since the name of the page already is codingconventions.html, I suggest
making this simply "#python" - shorter and simpler. :-)

> +Python scripts should follow <a href="https://peps.python.org/pep-0008/">PEP 8 – Style Guide for Python Code</a>
> +which can be verified by <a href="flake8.pycqa.org">flake8</a> tool.

...by the...tool.

> +We do also recommend using the following <code>flake8</code> plug-ins:

Here maybe simply say "We recommend using"?

Hope this helps,
Gerald

Re: [DOCS] Python Language Conventions

[Richard Sandiford]

Martin Liška <mliska@suse.cz> writes:
> I think we should add how Python scripts should be formatted. I noticed
> that while reading the Modula-2 patchset where it follows the C/C++ style
> when it comes to Python files.
>
> Ready to be installed?
> Thanks,
> Martin

Did you consider requiring black formatting instead?  Maybe black -l79
to maintain the usual 80-character limit.

At least that way there's only one right answer.

Richard

>
> ---
>  htdocs/codingconventions.html | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
>
> diff --git a/htdocs/codingconventions.html b/htdocs/codingconventions.html
> index e4d30510..180ef35a 100644
> --- a/htdocs/codingconventions.html
> +++ b/htdocs/codingconventions.html
> @@ -80,6 +80,7 @@ the conventions separately from any other changes to the code.</p>
>      </li>
>      </ul>
>  </li>
> +<li><a href="#Python_Conventions">Python Language Conventions</a>
>  </ul>
>  
>  
> @@ -1483,6 +1484,19 @@ with a right brace, optional closing comment, and a new line.
>  Definitions within the body of a namespace are not indented.
>  </p>
>  
> +<h2 id="Python_Conventions">Python Language Conventions</h2>
> +
> +<p>
> +Python scripts should follow <a href="https://peps.python.org/pep-0008/">PEP 8 – Style Guide for Python Code</a>
> +which can be verified by <a href="flake8.pycqa.org">flake8</a> tool.
> +We do also recommend using the following <code>flake8</code> plug-ins:
> +
> +<ul>
> +    <li>flake8-builtins</li>
> +    <li>flake8-import-order</li>
> +    <li>flake8-quotes</li>
> +</ul>
> +</p>
>  
>  </body>
>  </html>

Re: [DOCS] Python Language Conventions

[Martin Liška]

On 10/13/22 12:03, Richard Sandiford wrote:
> Martin Liška <mliska@suse.cz> writes:
>> I think we should add how Python scripts should be formatted. I noticed
>> that while reading the Modula-2 patchset where it follows the C/C++ style
>> when it comes to Python files.
>>
>> Ready to be installed?
>> Thanks,
>> Martin
> 
> Did you consider requiring black formatting instead?  Maybe black -l79
> to maintain the usual 80-character limit.

No, the automatic formatting might be a next step. About 80 chars, can we relax
that for Python scripts? I think it's hairy restriction these days. 

> 
> At least that way there's only one right answer.

Yep. We can definitely recommend using black as an optional approach,
what do you think?

Martin

> 
> Richard
> 
>>
>> ---
>>  htdocs/codingconventions.html | 14 ++++++++++++++
>>  1 file changed, 14 insertions(+)
>>
>> diff --git a/htdocs/codingconventions.html b/htdocs/codingconventions.html
>> index e4d30510..180ef35a 100644
>> --- a/htdocs/codingconventions.html
>> +++ b/htdocs/codingconventions.html
>> @@ -80,6 +80,7 @@ the conventions separately from any other changes to the code.</p>
>>      </li>
>>      </ul>
>>  </li>
>> +<li><a href="#Python_Conventions">Python Language Conventions</a>
>>  </ul>
>>  
>>  
>> @@ -1483,6 +1484,19 @@ with a right brace, optional closing comment, and a new line.
>>  Definitions within the body of a namespace are not indented.
>>  </p>
>>  
>> +<h2 id="Python_Conventions">Python Language Conventions</h2>
>> +
>> +<p>
>> +Python scripts should follow <a href="https://peps.python.org/pep-0008/">PEP 8 – Style Guide for Python Code</a>
>> +which can be verified by <a href="flake8.pycqa.org">flake8</a> tool.
>> +We do also recommend using the following <code>flake8</code> plug-ins:
>> +
>> +<ul>
>> +    <li>flake8-builtins</li>
>> +    <li>flake8-import-order</li>
>> +    <li>flake8-quotes</li>
>> +</ul>
>> +</p>
>>  
>>  </body>
>>  </html>

Re: [DOCS] Python Language Conventions

[Richard Sandiford]

Martin Liška <mliska@suse.cz> writes:
> On 10/13/22 12:03, Richard Sandiford wrote:
>> Martin Liška <mliska@suse.cz> writes:
>>> I think we should add how Python scripts should be formatted. I noticed
>>> that while reading the Modula-2 patchset where it follows the C/C++ style
>>> when it comes to Python files.
>>>
>>> Ready to be installed?
>>> Thanks,
>>> Martin
>> 
>> Did you consider requiring black formatting instead?  Maybe black -l79
>> to maintain the usual 80-character limit.
>
> No, the automatic formatting might be a next step. About 80 chars, can we relax
> that for Python scripts? I think it's hairy restriction these days. 

In practice it seems to work well, even at 79 chars.  The default is 88
and I don't think the extra 8 or 9 columns are enough to make a different
rule for Python worth it.

FWIW, personally I use an 80-column editor for GCC stuff, and it would
be a pain to have to switch to something different to work on Python.

>> At least that way there's only one right answer.
>
> Yep. We can definitely recommend using black as an optional approach,
> what do you think?

IMO the real value is if it's the defined approach, rather than an
optional approach.  It's "format and forget", just like with clang-format.

Thanks,
Richard

Re: [DOCS] Python Language Conventions

[David Malcolm]

On Thu, 2022-10-13 at 11:44 +0200, Gerald Pfeifer wrote:
> Hi Martin,
> 
> On Thu, 13 Oct 2022, Martin Liška wrote:
> > I think we should add how Python scripts should be formatted. I
> > noticed
> > that while reading the Modula-2 patchset where it follows the C/C++
> > style
> > when it comes to Python files.
> 
> good initiative, thank you! This makes sense to me, alas I'm not a
> Python 
> hacker, so best wait to see what David and Gaius think, too?

I'm very much +1 on recommending PEP 8.

My Python skills are bit-rotting somewhat, and I've not used flake8,
but it seems a reasonable recommendation to me.

> 
> 
> Some suggestions on the web side of things:
> 
> > +<li><a href="#Python_Conventions">Python Language Conventions</a>
> 
> Since the name of the page already is codingconventions.html, I
> suggest
> making this simply "#python" - shorter and simpler. :-)
> 
> > +Python scripts should follow <a
> > href="https://peps.python.org/pep-0008/">PEP 8 – Style Guide for
> > Python Code</a>
> > +which can be verified by <a href="flake8.pycqa.org">flake8</a>
> > tool.
> 
> ...by the...tool.
> 
> > +We do also recommend using the following <code>flake8</code> plug-
> > ins:
> 
> Here maybe simply say "We recommend using"?

That's a much better wording.

Dave

> 
> Hope this helps,
> Gerald

Re: [DOCS] Python Language Conventions

[Gaius Mulley]

David Malcolm <dmalcolm@redhat.com> writes:

> On Thu, 2022-10-13 at 11:44 +0200, Gerald Pfeifer wrote:
>> Hi Martin,
>> 
>> On Thu, 13 Oct 2022, Martin Liška wrote:
>> > I think we should add how Python scripts should be formatted. I
>> > noticed
>> > that while reading the Modula-2 patchset where it follows the C/C++
>> > style
>> > when it comes to Python files.
>> 
>> good initiative, thank you! This makes sense to me, alas I'm not a
>> Python 
>> hacker, so best wait to see what David and Gaius think, too?
>
> I'm very much +1 on recommending PEP 8.

hi,

all sounds very sensible - yes I'm also happy to adopt any house style
and will reformat the code accordingly

regards,
Gaius

Re: [DOCS] Python Language Conventions

[Martin Liška]

On 10/13/22 19:16, David Malcolm wrote:
> On Thu, 2022-10-13 at 11:44 +0200, Gerald Pfeifer wrote:
>> Hi Martin,
>>
>> On Thu, 13 Oct 2022, Martin Liška wrote:
>>> I think we should add how Python scripts should be formatted. I
>>> noticed
>>> that while reading the Modula-2 patchset where it follows the C/C++
>>> style
>>> when it comes to Python files.
>>
>> good initiative, thank you! This makes sense to me, alas I'm not a
>> Python 
>> hacker, so best wait to see what David and Gaius think, too?
> 
> I'm very much +1 on recommending PEP 8.
> 
> My Python skills are bit-rotting somewhat, and I've not used flake8,
> but it seems a reasonable recommendation to me.

All right, let me install my initial patch with the improved wording.

Cheers,
Martin

> 
>>
>>
>> Some suggestions on the web side of things:
>>
>>> +<li><a href="#Python_Conventions">Python Language Conventions</a>
>>
>> Since the name of the page already is codingconventions.html, I
>> suggest
>> making this simply "#python" - shorter and simpler. :-)
>>
>>> +Python scripts should follow <a
>>> href="https://peps.python.org/pep-0008/">PEP 8 – Style Guide for
>>> Python Code</a>
>>> +which can be verified by <a href="flake8.pycqa.org">flake8</a>
>>> tool.
>>
>> ...by the...tool.
>>
>>> +We do also recommend using the following <code>flake8</code> plug-
>>> ins:
>>
>> Here maybe simply say "We recommend using"?
> 
> That's a much better wording.
> 
> Dave
> 
>>
>> Hope this helps,
>> Gerald
> 

Re: [DOCS] Python Language Conventions

[Gerald Pfeifer]

[-- Attachment #1: Type: text/plain, Size: 1372 bytes --]

On Mon, 17 Oct 2022, Martin Liška wrote:
> All right, let me install my initial patch with the improved wording.

The validator noticed a small issue which I addressed thusly (by 
moving up the </p> - the beginning of <ul> implicitly closes a <p>).

No worries - that's what validators are for. :-)

Gerald

commit e9164572d233645b51ed8fa27729a52a0e242984
Author: Gerald Pfeifer <gerald@pfeifer.com>
Date:   Thu Oct 20 13:04:48 2022 +0200

    codingconventions: Fix markup

diff --git a/htdocs/codingconventions.html b/htdocs/codingconventions.html
index 9d0a3f14..f88ef019 100644
--- a/htdocs/codingconventions.html
+++ b/htdocs/codingconventions.html
@@ -1486,17 +1486,15 @@ Definitions within the body of a namespace are not indented.
 
 <h2 id="python">Python Language Conventions</h2>
 
-<p>
-Python scripts should follow <a href="https://peps.python.org/pep-0008/">PEP 8 – Style Guide for Python Code</a>
+<p>Python scripts should follow <a href="https://peps.python.org/pep-0008/">PEP 8 – Style Guide for Python Code</a>
 which can be verified by the <a href="flake8.pycqa.org">flake8</a> tool.
-We recommend using the following <code>flake8</code> plug-ins:
+We recommend using the following <code>flake8</code> plug-ins:</p>
 
 <ul>
     <li>flake8-builtins</li>
     <li>flake8-import-order</li>
     <li>flake8-quotes</li>
 </ul>
-</p>
 
 </body>
 </html>

Re: [DOCS] Python Language Conventions

[Martin Liška]

On 10/20/22 13:34, Gerald Pfeifer wrote:
> On Mon, 17 Oct 2022, Martin Liška wrote:
>> All right, let me install my initial patch with the improved wording.
> 
> The validator noticed a small issue which I addressed thusly (by 
> moving up the </p> - the beginning of <ul> implicitly closes a <p>).
> 
> No worries - that's what validators are for. :-)

Heh ;) Thanks for the fix.

Martin

> 
> Gerald
> 
> commit e9164572d233645b51ed8fa27729a52a0e242984
> Author: Gerald Pfeifer <gerald@pfeifer.com>
> Date:   Thu Oct 20 13:04:48 2022 +0200
> 
>     codingconventions: Fix markup
> 
> diff --git a/htdocs/codingconventions.html b/htdocs/codingconventions.html
> index 9d0a3f14..f88ef019 100644
> --- a/htdocs/codingconventions.html
> +++ b/htdocs/codingconventions.html
> @@ -1486,17 +1486,15 @@ Definitions within the body of a namespace are not indented.
>  
>  <h2 id="python">Python Language Conventions</h2>
>  
> -<p>
> -Python scripts should follow <a href="https://peps.python.org/pep-0008/">PEP 8 – Style Guide for Python Code</a>
> +<p>Python scripts should follow <a href="https://peps.python.org/pep-0008/">PEP 8 – Style Guide for Python Code</a>
>  which can be verified by the <a href="flake8.pycqa.org">flake8</a> tool.
> -We recommend using the following <code>flake8</code> plug-ins:
> +We recommend using the following <code>flake8</code> plug-ins:</p>
>  
>  <ul>
>      <li>flake8-builtins</li>
>      <li>flake8-import-order</li>
>      <li>flake8-quotes</li>
>  </ul>
> -</p>
>  
>  </body>
>  </html>