Message ID | d77b6541-1a2a-f15d-6855-14e206081fa4@suse.cz |
---|---|
State | New |
Headers |
From: mliska@suse.cz (=?utf-8?q?Martin_Li=C5=A1ka?=) Date: Thu, 13 Oct 2022 11:37:47 +0200 Subject: [DOCS] Python Language Conventions Message-ID: <d77b6541-1a2a-f15d-6855-14e206081fa4@suse.cz> |
Series |
[DOCS] Python Language Conventions
|
|
Commit Message
Martin Liška
Oct. 13, 2022, 9:37 a.m. UTC
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(+)
Comments
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
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>
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>
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
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
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
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 >
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>
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>
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>