Topics

Core code styling questions


Luke Davis
 

Hello

I am not as well informed as I would like to be about some of our linting preferences in NVDA. These issues do not appear in the linting readme, nor anywhere else I could find.

1. Space after commas: to space or not to space? I vaguely remember a GitHub discussion about that one, suggesting that the preference is to space, as is my personal preference as well, but I don't know what was decided.
Ex: myMethod(var1,var2)
Ex: myMethod(var1, var2)
The latter just sounds better in eSpeak.

2. Spacing around variable assignment equals signs? My preference is that whenever an assignment is on its own line, it should have a space on both sides of the equals sign; and that in kwargs, there should be no space on either side.
Ex: myObj = myClass(action="fake")

3. Percent substitutions: spaces before or after the percent sign which follows the quotes?
Ex: "This is a %s"%testVariable
Ex: "This is a %s" % testVariable
Ex: "This is a %s" %testVariable

4. Dict elements: space before the colon, after the colon, or both?
Ex: {
"one":"first",
"two": "second",
"three" : "third"
}
My personal preference is the second option--no space before, one space after.

I have seen examples of every one of these versions in core code, and as I'm currently working on PRs for docstrings and stylistic issues, I wanted to be better informed on this.

Luke


Michael Curran
 

Hi Luke,


I believe that most if not all of these stylings are from Python's Pep8 standard.


1. Yes, space after commas.


2. Yes, Space around equals in variable assignment, but not in kwargs. Though, when a type hint is added before the equals sign in a kwarg, then I think the preference is to also put spaces on either side of the equals. E.g. bla: str = "fish"


3. Percent substitutions: actually, don't use them at all. Please use the format method on strings. E.g. "My name is {name}".format(name="Mick")

Format is much more powerful.


4. Dict elements: space after the colon, not before.


Yep, there is all sort of styling in the code. But the idea is that over time we slowly move to this styling, by ensuring that all new code conforms.


Thanks

Mick

On 10/09/2020 3:10 pm, Luke Davis wrote:
Hello

I am not as well informed as I would like to be about some of our linting preferences in NVDA.  These issues do not appear in the linting readme, nor anywhere else I could find.

1. Space after commas: to space or not to space?  I vaguely remember a GitHub discussion about that one, suggesting that the preference is to space, as is my personal preference as well, but I don't know what was decided.
Ex: myMethod(var1,var2)
Ex: myMethod(var1, var2)
The latter just sounds better in eSpeak.

2. Spacing around variable assignment equals signs?  My preference is that whenever an assignment is on its own line, it should have a space on both sides of the equals sign; and that in kwargs, there should be no space on either side.
Ex: myObj = myClass(action="fake")

3. Percent substitutions: spaces before or after the percent sign which follows the quotes?
Ex: "This is a %s"%testVariable
Ex: "This is a %s" % testVariable
Ex: "This is a %s" %testVariable

4. Dict elements: space before the colon, after the colon, or both?
Ex: {
    "one":"first",
    "two": "second",
    "three" : "third"
}
My personal preference is the second option--no space before, one space after.

I have seen examples of every one of these versions in core code, and as I'm currently working on PRs for docstrings and stylistic issues, I wanted to be better informed on this.

Luke


Luke Davis
 

On Thu, 10 Sep 2020, Michael Curran wrote:

I believe that most if not all of these stylings are from Python's Pep8 standard.
I have read PEP8, but I was aware we break it in a few respects (tabs, line lengths, not using underscores in most function names, etc.), so wasn't sure if we had a separate project rule for any of the areas I asked about.

3. Percent substitutions: actually, don't use them at all. Please use the format method on strings. E.g. "My name is {name}".format(name="Mick")
I certainly do, in my own code, but their all over the place in existing code (addonHandler, for example, where I'm currently working).

I don't mind modernizing them when coming across them, but it's not exactly linting so I didn't think to do it automatically.

I appreciate the response!

Luke


Bill Dengler
 

3. Percent substitutions: actually, don't use them at all. Please use
the format method on strings. E.g. "My name is
{name}".format(name="Mick")
What about PEP498 strings? (I've used them since threshold was merged, at
least):
https://www.python.org/dev/peps/pep-0498
Bill

-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Luke Davis
Sent: Thursday, 10 September 2020 07:43
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Core code styling questions

On Thu, 10 Sep 2020, Michael Curran wrote:

I believe that most if not all of these stylings are from Python's
Pep8 standard.
I have read PEP8, but I was aware we break it in a few respects (tabs, line
lengths, not using underscores in most function names, etc.), so wasn't sure
if we had a separate project rule for any of the areas I asked about.

3. Percent substitutions: actually, don't use them at all. Please use
the format method on strings. E.g. "My name is
{name}".format(name="Mick")
I certainly do, in my own code, but their all over the place in existing
code (addonHandler, for example, where I'm currently working).

I don't mind modernizing them when coming across them, but it's not exactly
linting so I didn't think to do it automatically.

I appreciate the response!

Luke


 

Hi,
A few months ago I did bring up this possibility for all sorts of messages,
but Mick then pointed out that there are times when an "f" string isn't
appropriate such as translations as formatted string literals can embed
Python expressions which opens up security issues and bad translation output
(and input). In the log outputs, yes, it makes sense to try standardizing
around formatted string literals, and that's the standard I have adopted
across my add-ons.
Cheers,
Joseph

-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Bill Dengler
Sent: Thursday, September 10, 2020 12:40 PM
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Core code styling questions

3. Percent substitutions: actually, don't use them at all. Please use
the format method on strings. E.g. "My name is
{name}".format(name="Mick")
What about PEP498 strings? (I've used them since threshold was merged, at
least):
https://www.python.org/dev/peps/pep-0498
Bill

-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Luke Davis
Sent: Thursday, 10 September 2020 07:43
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Core code styling questions

On Thu, 10 Sep 2020, Michael Curran wrote:

I believe that most if not all of these stylings are from Python's
Pep8 standard.
I have read PEP8, but I was aware we break it in a few respects (tabs, line
lengths, not using underscores in most function names, etc.), so wasn't sure
if we had a separate project rule for any of the areas I asked about.

3. Percent substitutions: actually, don't use them at all. Please use
the format method on strings. E.g. "My name is
{name}".format(name="Mick")
I certainly do, in my own code, but their all over the place in existing
code (addonHandler, for example, where I'm currently working).

I don't mind modernizing them when coming across them, but it's not exactly
linting so I didn't think to do it automatically.

I appreciate the response!

Luke


Sean
 

Does f-string work successfully with gettex?

I could not do that. It seems like Python cannot get f-string expressions from gettex.

On 10/09/2020 22:46, Joseph Lee wrote:
Hi,
A few months ago I did bring up this possibility for all sorts of messages,
but Mick then pointed out that there are times when an "f" string isn't
appropriate such as translations as formatted string literals can embed
Python expressions which opens up security issues and bad translation output
(and input). In the log outputs, yes, it makes sense to try standardizing
around formatted string literals, and that's the standard I have adopted
across my add-ons. 
Cheers,
Joseph

-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Bill Dengler
Sent: Thursday, September 10, 2020 12:40 PM
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Core code styling questions

3. Percent substitutions: actually, don't use them at all. Please use 
the format method on strings. E.g. "My name is
{name}".format(name="Mick")
What about PEP498 strings? (I've used them since threshold was merged, at
least):
https://www.python.org/dev/peps/pep-0498
Bill

-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Luke Davis
Sent: Thursday, 10 September 2020 07:43
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Core code styling questions

On Thu, 10 Sep 2020, Michael Curran wrote:

I believe that most if not all of these stylings are from Python's
Pep8 standard.
I have read PEP8, but I was aware we break it in a few respects (tabs, line
lengths, not using underscores in most function names, etc.), so wasn't sure
if we had a separate project rule for any of the areas I asked about.

3. Percent substitutions: actually, don't use them at all. Please use 
the format method on strings. E.g. "My name is
{name}".format(name="Mick")
I certainly do, in my own code, but their all over the place in existing
code (addonHandler, for example, where I'm currently working).

I don't mind modernizing them when coming across them, but it's not exactly
linting so I didn't think to do it automatically.

I appreciate the response!

Luke











--
Sean

👨‍🦯 I’m programmer. I coding often Python, sometimes Go and rarely C++.


 

Hi,

No, and it is not really a good string format as it introduces security issues.

Cheers,

Joseph

 

From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Sean
Sent: Thursday, September 10, 2020 1:07 PM
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Core code styling questions

 

Does f-string work successfully with gettex?

I could not do that. It seems like Python cannot get f-string expressions from gettex.

On 10/09/2020 22:46, Joseph Lee wrote:

Hi,
A few months ago I did bring up this possibility for all sorts of messages,
but Mick then pointed out that there are times when an "f" string isn't
appropriate such as translations as formatted string literals can embed
Python expressions which opens up security issues and bad translation output
(and input). In the log outputs, yes, it makes sense to try standardizing
around formatted string literals, and that's the standard I have adopted
across my add-ons. 
Cheers,
Joseph
 
-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Bill Dengler
Sent: Thursday, September 10, 2020 12:40 PM
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Core code styling questions
 
3. Percent substitutions: actually, don't use them at all. Please use 
the format method on strings. E.g. "My name is
{name}".format(name="Mick")
What about PEP498 strings? (I've used them since threshold was merged, at
least):
https://www.python.org/dev/peps/pep-0498
Bill
 
-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Luke Davis
Sent: Thursday, 10 September 2020 07:43
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Core code styling questions
 
On Thu, 10 Sep 2020, Michael Curran wrote:
 
I believe that most if not all of these stylings are from Python's
Pep8 standard.
 
I have read PEP8, but I was aware we break it in a few respects (tabs, line
lengths, not using underscores in most function names, etc.), so wasn't sure
if we had a separate project rule for any of the areas I asked about.
 
3. Percent substitutions: actually, don't use them at all. Please use 
the format method on strings. E.g. "My name is
{name}".format(name="Mick")
 
I certainly do, in my own code, but their all over the place in existing
code (addonHandler, for example, where I'm currently working).
 
I don't mind modernizing them when coming across them, but it's not exactly
linting so I didn't think to do it automatically.
 
I appreciate the response!
 
Luke
 
 
 
 
 
 
 
 
 
 
 

--
Sean

👨🦯 I’m programmer. I coding often Python, sometimes Go and rarely C++.


Reef Turner
 

Hi all,

 

As Mick mentioned, we have tried to follow the pep8 recommendations as much as possible, the flake 8 config file will show where we have made exceptions. Though what has been listed in this thread seems like a good summary.

 

If the docs for linting could use further examples, please create a PR to add them. It’s a challenge to create good docs!

 

f-strings can typically be used in NVDA code, but should not be used with gettext. It simply won’t be able to look up the translation. Variables are inserted before the translation lookup happens for f-string, whereas in using string.format the format can be applied to the result of the lookup. Consider the following demo:

 

>>> def _(myString):

...     print(f"Looking up: {myString}")

...     return myString

...

>>> answer = 42

>>> _(f"the answer is {answer}")

Looking up: the answer is 42

'the answer is 42'

>>> _("the answer is {answer}").format(answer=answer)

Looking up: the answer is {answer}

'the answer is 42'

 

Hope this helps to clarify the problem.

 

From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Joseph Lee
Sent: Thursday, 10 September 2020 10:14 PM
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Core code styling questions

 

Hi,

No, and it is not really a good string format as it introduces security issues.

Cheers,

Joseph

 

From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Sean
Sent: Thursday, September 10, 2020 1:07 PM
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Core code styling questions

 

Does f-string work successfully with gettex?

I could not do that. It seems like Python cannot get f-string expressions from gettex.

On 10/09/2020 22:46, Joseph Lee wrote:

Hi,
A few months ago I did bring up this possibility for all sorts of messages,
but Mick then pointed out that there are times when an "f" string isn't
appropriate such as translations as formatted string literals can embed
Python expressions which opens up security issues and bad translation output
(and input). In the log outputs, yes, it makes sense to try standardizing
around formatted string literals, and that's the standard I have adopted
across my add-ons. 
Cheers,
Joseph
 
-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Bill Dengler
Sent: Thursday, September 10, 2020 12:40 PM
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Core code styling questions
 
3. Percent substitutions: actually, don't use them at all. Please use 
the format method on strings. E.g. "My name is
{name}".format(name="Mick")
What about PEP498 strings? (I've used them since threshold was merged, at
least):
https://www.python.org/dev/peps/pep-0498
Bill
 
-----Original Message-----
From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Luke Davis
Sent: Thursday, 10 September 2020 07:43
To: nvda-devel@groups.io
Subject: Re: [nvda-devel] Core code styling questions
 
On Thu, 10 Sep 2020, Michael Curran wrote:
 
I believe that most if not all of these stylings are from Python's
Pep8 standard.
 
I have read PEP8, but I was aware we break it in a few respects (tabs, line
lengths, not using underscores in most function names, etc.), so wasn't sure
if we had a separate project rule for any of the areas I asked about.
 
3. Percent substitutions: actually, don't use them at all. Please use 
the format method on strings. E.g. "My name is
{name}".format(name="Mick")
 
I certainly do, in my own code, but their all over the place in existing
code (addonHandler, for example, where I'm currently working).
 
I don't mind modernizing them when coming across them, but it's not exactly
linting so I didn't think to do it automatically.
 
I appreciate the response!
 
Luke
 
 
 
 
 
 
 
 
 
 
 

--
Sean

👨🦯 I’m programmer. I coding often Python, sometimes Go and rarely C++.