struggle to upgrade pip on visual studio code
hello, i successfully installed openpyxl but it is saying this about my pip: WARNING: You are using pip version 22.0.2; however, version 22.0.4 is available.You should consider upgrading via the 'C:\Program Files\Python310\python.exe -m pip install --upgrade pip' command. And then when I try to upgrade using 'C:\Program Files\Python310\python.exe -m pip install --upgrade pip command it says this: C:\Program : The term 'C:\Program' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again. At line:1 char:1 + C:\Program Files\Python310\python.exe -m pip install --upgrade pip+ ~~ + CategoryInfo : ObjectNotFound: (C:\Program:String) [], Comma ndNotFoundException + FullyQualifiedErrorId : CommandNotFoundException please what do I do? -- https://mail.python.org/mailman/listinfo/python-list
Re: struggle to upgrade pip on visual studio code
On 4/22/22 6:11 AM, Tola Oj wrote: hello, i successfully installed openpyxl but it is saying this about my pip: WARNING: You are using pip version 22.0.2; however, version 22.0.4 is available.You should consider upgrading via the 'C:\Program Files\Python310\python.exe -m pip install --upgrade pip' command. And then when I try to upgrade using 'C:\Program Files\Python310\python.exe -m pip install --upgrade pip command it says this: C:\Program : The term 'C:\Program' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again. At line:1 char:1 + C:\Program Files\Python310\python.exe -m pip install --upgrade pip+ ~~ + CategoryInfo : ObjectNotFound: (C:\Program:String) [], Comma ndNotFoundException + FullyQualifiedErrorId : CommandNotFoundException please what do I do? When a program name/path includes spaces, you need to put the whole name in quotes, like "C:\Program Files\Python310\python.exe" -m pip install --upgrade Now, if python is on your path (and 3.10 is the first python found), you should be able to simpify that to python -m pip install --upgrade -- Richard Damon -- https://mail.python.org/mailman/listinfo/python-list
How to have python 2 and 3 both on windows?
I have some scripts that are old and won't work under python2 and at the same time I am writing new scripts which will use python3. However, if python 2 and 3 cannot co-exist in a windows box it will be impossible to transition What I try:- remove all pythons and launchers- Use windows installer and install python2 in python27 directory- Use windows installer and install python3 in python310 directory- When installing python3 I opt in to install the launcher- Test with py -2 and py -3 and see that I get the expected prompt- just typing python gets me python2 -- https://mail.python.org/mailman/listinfo/python-list
Re: How to have python 2 and 3 both on windows?
Please excuse the formatting in my previous message. And it is not complete even, so here is the rest of it. What happens after I follow the above steps: - Upon running one of my python 2 scripts (using python2), I see this error: """ ^SyntaxError: (unicode error) 'unicodeescape' codec can't decode bytes in position 237-238: truncated \u escape I tried for a bit, but I could not isolate the content of the file that may be causing this problem. But any idea about this problem would be greatly appreciated. Removing python3 solves this issue.. Sunil On Friday, April 22, 2022, 09:09:22 AM PDT, Sunil KR via Python-list wrote: I have some scripts that are old and won't work under python2 and at the same time I am writing new scripts which will use python3. However, if python 2 and 3 cannot co-exist in a windows box it will be impossible to transition What I try:- remove all pythons and launchers- Use windows installer and install python2 in python27 directory- Use windows installer and install python3 in python310 directory- When installing python3 I opt in to install the launcher- Test with py -2 and py -3 and see that I get the expected prompt- just typing python gets me python2 -- https://mail.python.org/mailman/listinfo/python-list -- https://mail.python.org/mailman/listinfo/python-list
Re: How to have python 2 and 3 both on windows?
Barry wrote: Tip “py.exe -0” will list the state of installed pythons. Not here; 'py.exe -0' gives: Requested Python version (0) not installed Which PyInstaller version support this '-0' option? -- --gv -- https://mail.python.org/mailman/listinfo/python-list
Re: How to have python 2 and 3 both on windows?
On 4/22/22 11:40, Gisle Vanem wrote: > Barry wrote: > >> Tip “py.exe -0” will list the state of installed pythons. > Not here; 'py.exe -0' gives: > Requested Python version (0) not installed > > Which PyInstaller version support this '-0' option? > Looks like this got added around 3.7... https://bugs.python.org/issue30362 -- https://mail.python.org/mailman/listinfo/python-list
Re: How to have python 2 and 3 both on windows?
> On 22 Apr 2022, at 17:10, Sunil KR via Python-list > wrote: > > I have some scripts that are old and won't work under python2 and at the > same time I am writing new scripts which will use python3. However, if python > 2 and 3 cannot co-exist in a windows box it will be impossible to transition > What I try:- remove all pythons and launchers- Use windows installer and > install python2 in python27 directory- Use windows installer and install > python3 in python310 directory- When installing python3 I opt in to install > the launcher- Test with py -2 and py -3 and see that I get the expected > prompt- just typing python gets me python2 As you have proved you can install many versions of python at the same time on windows. In your scripts set the shebang to run the python version you want. E.g #!/usr/bin/python2 Or #!/usr/bin/python3 The python launcher py.exe will then do the right thing after looking at en shebang line. Also you can edit the INI file of the py.exe launcher to set the defaults the way you want them. Do a search for “py.exe ini” to file the path to the file, I do not have it my finger tips. Tip “py.exe -0” will list the state of installed pythons. Barry > -- > https://mail.python.org/mailman/listinfo/python-list > -- https://mail.python.org/mailman/listinfo/python-list
Re: Style for docstring
On Fri, 22 Apr 2022 14:36:27 -0500, Michael F. Stemper wrote: > I'm writing a function that is nearly self-documenting by its name, > but still want to give it a docstring. Which of these would be best from > a stylistic point of view: > > >Tells caller whether or not a permutation is even. > >Determines if a permutation is even. (Alternative is that it's odd.) > >Returns True if permutation is even, False if it is odd. > > > (Before somebody suggests it, I'm not going to put six weeks' worth of a > course in group theory in there to help somebody who doesn't know what > those standard terms mean.) four guidance I would sugest Pep257 as a start point which would suggest "Return True if permutation is even" -- I think my career is ruined! -- https://mail.python.org/mailman/listinfo/python-list
Style for docstring
I'm writing a function that is nearly self-documenting by its name, but still want to give it a docstring. Which of these would be best from a stylistic point of view: Tells caller whether or not a permutation is even. Determines if a permutation is even. (Alternative is that it's odd.) Returns True if permutation is even, False if it is odd. (Before somebody suggests it, I'm not going to put six weeks' worth of a course in group theory in there to help somebody who doesn't know what those standard terms mean.) -- Michael F. Stemper 87.3% of all statistics are made up by the person giving them. -- https://mail.python.org/mailman/listinfo/python-list
Re: Style for docstring
On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper wrote: > > I'm writing a function that is nearly self-documenting by its name, > but still want to give it a docstring. Which of these would be > best from a stylistic point of view: > > >Tells caller whether or not a permutation is even. > >Determines if a permutation is even. (Alternative is that it's odd.) > >Returns True if permutation is even, False if it is odd. > > > (Before somebody suggests it, I'm not going to put six weeks' worth > of a course in group theory in there to help somebody who doesn't > know what those standard terms mean.) > I'd go with the third one, but "Return" rather than "Returns". Or possibly "Test whether a permutation is even". That's just one opinion though, others may disagree :) ChrisA -- https://mail.python.org/mailman/listinfo/python-list
Re: Style for docstring
On 4/22/22 12:36, Michael F. Stemper wrote: Tells caller whether or not a permutation is even. Determines if a permutation is even. (Alternative is that it's odd.) Returns True if permutation is even, False if it is odd. Third option. -- ~Ethan~ -- https://mail.python.org/mailman/listinfo/python-list
Re: How to have python 2 and 3 both on windows?
> On 22 Apr 2022, at 18:43, Gisle Vanem wrote: > > Barry wrote: > >> Tip “py.exe -0” will list the state of installed pythons. > Not here; 'py.exe -0' gives: > Requested Python version (0) not installed > > Which PyInstaller version support this '-0' option? I do not when it was first added all the installs I have done in the last few years have it working. Barry > > -- > --gv > -- > https://mail.python.org/mailman/listinfo/python-list -- https://mail.python.org/mailman/listinfo/python-list
Re: Style for docstring
On 22/04/2022 14.59, Chris Angelico wrote: On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper wrote: I'm writing a function that is nearly self-documenting by its name, but still want to give it a docstring. Which of these would be best from a stylistic point of view: Tells caller whether or not a permutation is even. Determines if a permutation is even. (Alternative is that it's odd.) Returns True if permutation is even, False if it is odd. I'd go with the third one, but "Return" rather than "Returns". Or possibly "Test whether a permutation is even". "So let it be written. So let it be done." That's just one opinion though, others may disagree :) Two for two. Thanks. -- Michael F. Stemper Always remember that you are unique. Just like everyone else. -- https://mail.python.org/mailman/listinfo/python-list
Re: Style for docstring
On 2022-04-22 at 15:35:15 -0500, "Michael F. Stemper" wrote: > On 22/04/2022 14.59, Chris Angelico wrote: > > On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper > > wrote: > > > > > > I'm writing a function that is nearly self-documenting by its name, > > > but still want to give it a docstring. Which of these would be > > > best from a stylistic point of view: > > > > > > > > > Tells caller whether or not a permutation is even. > > > > > > Determines if a permutation is even. (Alternative is that it's odd.) > > > > > > Returns True if permutation is even, False if it is odd. > > > > > > I'd go with the third one, but "Return" rather than "Returns". Or > > possibly "Test whether a permutation is even". > > "So let it be written. So let it be done." "Test whether a permutation is even," while technically factual, leaves the reader to wonder what form the result takes, and what happens to that result. Yes, we'd all like to think that programmers are smart enough to *assume* that the function returns the result of the test. I've also seen functions that perform tests and then print the results out, or write them to a database, or simply execute the tests for their side effects (or leave it up to the individual tests to do something with the result). Do you want callers of the function also to assume that True means that the permutation is even? There are other reasonable strategies, such as an enumerated type (whose items are Even, Odd, and FileNotFound), or throwing an exception if the permutation is odd. I prefer the "return" (rather than "returns") version of the third option. Assuming that the programmers are familiar with the domain, the other two leave out important information. -- https://mail.python.org/mailman/listinfo/python-list
Re: Style for docstring
On Sat, 23 Apr 2022 at 08:24, <2qdxy4rzwzuui...@potatochowder.com> wrote: > > On 2022-04-22 at 15:35:15 -0500, > "Michael F. Stemper" wrote: > > > On 22/04/2022 14.59, Chris Angelico wrote: > > > On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper > > > wrote: > > > > > > > > I'm writing a function that is nearly self-documenting by its name, > > > > but still want to give it a docstring. Which of these would be > > > > best from a stylistic point of view: > > > > > > > > > > > > Tells caller whether or not a permutation is even. > > > > > > > > Determines if a permutation is even. (Alternative is that it's odd.) > > > > > > > > Returns True if permutation is even, False if it is odd. > > > > > > > > > > I'd go with the third one, but "Return" rather than "Returns". Or > > > possibly "Test whether a permutation is even". > > > > "So let it be written. So let it be done." > > "Test whether a permutation is even," while technically factual, leaves > the reader to wonder what form the result takes, and what happens to > that result. While it's definitely possible to have other results and other ways to deliver them, the return of a boolean would be the most obvious default. > Do you want callers of the function also to assume that True means that > the permutation is even? There are other reasonable strategies, such as > an enumerated type (whose items are Even, Odd, and FileNotFound), or > throwing an exception if the permutation is odd. I'm assuming that the function is called something like "is_even()" and that it either is a method on a permutation object, or its parameters make it very clear what the permutation is. If it returns an enumeration, I would say that in the docstring. If the docstring doesn't say, I would assume it returns True or False. > I prefer the "return" (rather than "returns") version of the third > option. Assuming that the programmers are familiar with the domain, the > other two leave out important information. Core Python methods and functions seem to prefer either "Return ..." or "Verb the thing" where the result is implicit (eg str.zfill.__doc__ which says "Pad a numeric string..."). Both are used extensively. Neither form leaves out anything that wouldn't be the obvious default. We don't need to say "Figures out algorithmically whether the permutation is even. If it is, will return True; if it isn't, will return False; if something goes wrong, will raise an exception". This is Python; we know that if something goes wrong, an exception is raised. (Though it can help to say WHICH exception will be raised under WHAT circumstances). Some things are obvious. ChrisA -- https://mail.python.org/mailman/listinfo/python-list
Re: Style for docstring
On Sat, 23 Apr 2022 at 09:31, Rob Cliffe via Python-list wrote: > > I don't use docstrings much; instead I put a line or two of comments > after the `def ` line. > But my practice in such situations is as per the OP's 3rd suggestion, e.g. > # Returns True if . The point of docstrings is that they can be read by various tools. Otherwise, they are every bit as good as comments. > I'm curious as to why so many people prefer "Return" to "Returns". > Checking out help() on a few functions in the stdlib, they all used > "Return" or a grammatical equivalent, so this does seem to be a Python > cultural thing. But why? To me, "Returns" begins a description as to > what the function does, whereas "Return" is an imperative. But who is > it addresed to? Is a function considered to be a sentient entity that > can respond to a command? Is it an invocation to the lines of code > following the docstring: "Do this!" Might not the programmer mistakenly > think (if only for a moment) that the imperative is addressed to him? That's a very broad convention; for instance, git commit messages are conventionally written imperatively, too. You can think of a commit message as "If applied, this patch will blah blah blah", and a docstring as "When called, this function will blah blah blah". Aside from the initial capital letter, an imperative sentence will nicely complete those descriptions. ChrisA -- https://mail.python.org/mailman/listinfo/python-list
upgrade pip
im trying to upgrade my pip so i can install openpyxl. i though i had successfully upgraded pip, and then I was trying to install openpyxl, but I was getting this: C:\Users\ojomo>"C:\Program Files\Python310\python.exe" -m pip install --upgrade Traceback (most recent call last): File "C:\Program Files\Python310\lib\runpy.py", line 196, in _run_module_as_main return _run_code(code, main_globals, None, File "C:\Program Files\Python310\lib\runpy.py", line 86, in _run_code exec(code, run_globals) File "C:\Users\ojomo\AppData\Roaming\Python\Python310\site-packages\pip\__main__.py", line 29, in from pip._internal.cli.main import main as _main File "C:\Users\ojomo\AppData\Roaming\Python\Python310\site-packages\pip\_internal\cli\main.py", line 9, in from pip._internal.cli.autocompletion import autocomplete File "C:\Users\ojomo\AppData\Roaming\Python\Python310\site-packages\pip\_internal\cli\autocompletion.py", line 10, in from pip._internal.cli.main_parser import create_main_parser File "C:\Users\ojomo\AppData\Roaming\Python\Python310\site-packages\pip\_internal\cli\main_parser.py", line 8, in from pip._internal.cli import cmdoptions File "C:\Users\ojomo\AppData\Roaming\Python\Python310\site-packages\pip\_internal\cli\cmdoptions.py", line 23, in from pip._internal.cli.parser import ConfigOptionParser File "C:\Users\ojomo\AppData\Roaming\Python\Python310\site-packages\pip\_internal\cli\parser.py", line 12, in from pip._internal.configuration import Configuration, ConfigurationError File "C:\Users\ojomo\AppData\Roaming\Python\Python310\site-packages\pip\_internal\configuration.py", line 20, in from pip._internal.exceptions import ( File "C:\Users\ojomo\AppData\Roaming\Python\Python310\site-packages\pip\_internal\exceptions.py", line 13, in from pip._vendor.requests.models import Request, Response File "C:\Users\ojomo\AppData\Roaming\Python\Python310\site-packages\pip\_vendor\requests\__init__.py", line 43, in from pip._vendor import urllib3 ImportError: cannot import name 'urllib3' from 'pip._vendor' (C:\Users\ojomo\AppData\Roaming\Python\Python310\site-packages\pip\_vendor\__init__.py) and then I realised no matter what I type into the terminal (for example if I'm trying to check what version pip is, or I'm to import another module), it will print out this same specific lines of code. -- https://mail.python.org/mailman/listinfo/python-list
Re: Style for docstring
On 2022-04-23 at 08:33:37 +1000, Chris Angelico wrote: > On Sat, 23 Apr 2022 at 08:24, <2qdxy4rzwzuui...@potatochowder.com> wrote: > > > > On 2022-04-22 at 15:35:15 -0500, > > "Michael F. Stemper" wrote: > > > > > On 22/04/2022 14.59, Chris Angelico wrote: > > > > On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper > > > > wrote: > > > > > > > > > > I'm writing a function that is nearly self-documenting by its name, > > > > > but still want to give it a docstring. Which of these would be > > > > > best from a stylistic point of view: > > > > > > > > > > > > > > > Tells caller whether or not a permutation is even. > > > > > > > > > > Determines if a permutation is even. (Alternative is that it's > > > > > odd.) > > > > > > > > > > Returns True if permutation is even, False if it is odd. > > > > > > > > > > > > > > I'd go with the third one, but "Return" rather than "Returns". Or > > > > possibly "Test whether a permutation is even". > > > > > > "So let it be written. So let it be done." > > > > "Test whether a permutation is even," while technically factual, leaves > > the reader to wonder what form the result takes, and what happens to > > that result. > > While it's definitely possible to have other results and other ways to > deliver them, the return of a boolean would be the most obvious > default. Maybe, depending on the context and purpose of the application. > > Do you want callers of the function also to assume that True means that > > the permutation is even? There are other reasonable strategies, such as > > an enumerated type (whose items are Even, Odd, and FileNotFound), or > > throwing an exception if the permutation is odd. > > I'm assuming that the function is called something like "is_even()" > and that it either is a method on a permutation object, or its > parameters make it very clear what the permutation is. > > If it returns an enumeration, I would say that in the docstring. If > the docstring doesn't say, I would assume it returns True or False. I think we're agreeing, but the OP didn't provide that information. I've seen enough oddball (yes, that's my professional opinion :-)) APIs (and worked with enough programmers from enough backgrounds) to know that "most obvious default" is subjective. > > I prefer the "return" (rather than "returns") version of the third > > option. Assuming that the programmers are familiar with the domain, > > the other two leave out important information. [...] > We don't need to say "Figures out algorithmically whether the > permutation is even. If it is, will return True; if it isn't, will > return False; if something goes wrong, will raise an exception". This > is Python; we know that if something goes wrong, an exception is > raised. (Though it can help to say WHICH exception will be raised > under WHAT circumstances). Some things are obvious. No, we don't need to say it that way. I believe that we do need to say what the function returns under what circumstances. If, in fact, the function in question is named is_permutation_even, then it *is* as simple as the OP's third option, but not simpler. -- https://mail.python.org/mailman/listinfo/python-list
Re: Style for docstring
I don't use docstrings much; instead I put a line or two of comments after the `def ` line. But my practice in such situations is as per the OP's 3rd suggestion, e.g. # Returns True if . I'm curious as to why so many people prefer "Return" to "Returns". Checking out help() on a few functions in the stdlib, they all used "Return" or a grammatical equivalent, so this does seem to be a Python cultural thing. But why? To me, "Returns" begins a description as to what the function does, whereas "Return" is an imperative. But who is it addresed to? Is a function considered to be a sentient entity that can respond to a command? Is it an invocation to the lines of code following the docstring: "Do this!" Might not the programmer mistakenly think (if only for a moment) that the imperative is addressed to him? Best wishes Rob Cliffe -- https://mail.python.org/mailman/listinfo/python-list
Re: Style for docstring
On 22Apr2022 17:22, Dan Sommers <2qdxy4rzwzuui...@potatochowder.com> wrote: >"Test whether a permutation is even," while technically factual, leaves >the reader to wonder what form the result takes, and what happens to >that result. Yes, we'd all like to think that programmers are smart >enough to *assume* that the function returns the result of the test. >I've also seen functions that perform tests and then print the results >out, or write them to a database, or simply execute the tests for their >side effects (or leave it up to the individual tests to do something >with the result). Yeah, this. I've got lots of "test and return a Boolean" functions named "is_something" and some "test and raise value error if bad" functions named "validate_something". Those latter are so that I can concisely write stuff like: def foo(bah): validate_bahlike(bah) ... do stuff with bah ... to get a sensible ValueError from foo() if bah is invalid. (And validate_something() often calls is_something() when I want both flavors depending on circumstance.) So I also like option 3, though I also usually write it imperatively: Return `True` if `permutation` is even, `False` otherwise. I'm in two minds about "otherwise" rather than being explicit about the dual of the test. Usually "otherwise" is my choice, but I can imagine being more explicit if there were some third (probably invalid) input choice. "Otherwise" also works well when there are a few valid choices: Return `True` if the weekday is Wednesday or the moon is full, `False` otherwise. Cheers Cameron Simpson -- https://mail.python.org/mailman/listinfo/python-list
Re: Style for docstring
On 2022-04-23 00:25, Rob Cliffe via Python-list wrote: I don't use docstrings much; instead I put a line or two of comments after the `def ` line. But my practice in such situations is as per the OP's 3rd suggestion, e.g. # Returns True if . I'm curious as to why so many people prefer "Return" to "Returns". Checking out help() on a few functions in the stdlib, they all used "Return" or a grammatical equivalent, so this does seem to be a Python cultural thing. But why? To me, "Returns" begins a description as to what the function does, whereas "Return" is an imperative. But who is it addresed to? Is a function considered to be a sentient entity that can respond to a command? Is it an invocation to the lines of code following the docstring: "Do this!" Might not the programmer mistakenly think (if only for a moment) that the imperative is addressed to him? Maybe it's because the function name is often also an imperative, e.g.: >>> import re >>> help(re.search) Help on function search in module re: search(pattern, string, flags=0) Scan through string looking for a match to the pattern, returning a Match object, or None if no match was found. Note "Scan", not "scans". I was going to use 'print' as the example: >>> help(print) Help on built-in function print in module builtins: print(...) print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False) Prints the values to a stream, or to sys.stdout by default. Optional keyword arguments: file: a file-like object (stream); defaults to the current sys.stdout. sep: string inserted between values, default a space. end: string appended after the last value, default a newline. flush: whether to forcibly flush the stream. but it says "Prints", not "Print"... -- https://mail.python.org/mailman/listinfo/python-list
Re: Style for docstring
Python does have a concept of "truthy" that includes meaning for not just the standard Booleans but for 0 and non-zero and the empty string and many more odd things such as an object that defines __bool__ (). But saying it returns a Boolean True/False valuesounds direct and simple and informative enough if that is True. What bothers me is the assumption that anyone knows not so muchjust group theory but what the argument to the function looks like as a Python object of some kind. Does the function accept only some permutation object managed by a specific module? Will it accept some alternate representation such as a list structure or other iterator? Obviously deeper details would normally be in a manual page or other documentation but as "permutations" are likely not to be what most people think about before breakfast, or even after, odd as that may seem, ... And, yes, I know what it means and some users will too. But as all permutations must be even or odd, errors thrown might be based on whether the data structure has valid contents or is so complex that it uses up all system resources, I would think. So the docstring could be fairly short and something like: Given a permutation in Returns the Boolean value True if it is graded as or False if or an exception if the argument is not valid. As noted by others, Many things can be returned including multiple values where perhaps the second one tells if there was an error but thatthe user can ignore or not even catch. -Original Message- From: Chris Angelico To: python-list@python.org Sent: Fri, Apr 22, 2022 6:33 pm Subject: Re: Style for docstring On Sat, 23 Apr 2022 at 08:24, <2qdxy4rzwzuui...@potatochowder.com> wrote: > > On 2022-04-22 at 15:35:15 -0500, > "Michael F. Stemper" wrote: > > > On 22/04/2022 14.59, Chris Angelico wrote: > > > On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper > > > wrote: > > > > > > > > I'm writing a function that is nearly self-documenting by its name, > > > > but still want to give it a docstring. Which of these would be > > > > best from a stylistic point of view: > > > > > > > > > > > > Tells caller whether or not a permutation is even. > > > > > > > > Determines if a permutation is even. (Alternative is that it's odd.) > > > > > > > > Returns True if permutation is even, False if it is odd. > > > > > > > > > > I'd go with the third one, but "Return" rather than "Returns". Or > > > possibly "Test whether a permutation is even". > > > > "So let it be written. So let it be done." > > "Test whether a permutation is even," while technically factual, leaves > the reader to wonder what form the result takes, and what happens to > that result. While it's definitely possible to have other results and other ways to deliver them, the return of a boolean would be the most obvious default. > Do you want callers of the function also to assume that True means that > the permutation is even? There are other reasonable strategies, such as > an enumerated type (whose items are Even, Odd, and FileNotFound), or > throwing an exception if the permutation is odd. I'm assuming that the function is called something like "is_even()" and that it either is a method on a permutation object, or its parameters make it very clear what the permutation is. If it returns an enumeration, I would say that in the docstring. If the docstring doesn't say, I would assume it returns True or False. > I prefer the "return" (rather than "returns") version of the third > option. Assuming that the programmers are familiar with the domain, the > other two leave out important information. Core Python methods and functions seem to prefer either "Return ..." or "Verb the thing" where the result is implicit (eg str.zfill.__doc__ which says "Pad a numeric string..."). Both are used extensively. Neither form leaves out anything that wouldn't be the obvious default. We don't need to say "Figures out algorithmically whether the permutation is even. If it is, will return True; if it isn't, will return False; if something goes wrong, will raise an exception". This is Python; we know that if something goes wrong, an exception is raised. (Though it can help to say WHICH exception will be raised under WHAT circumstances). Some things are obvious. ChrisA -- https://mail.python.org/mailman/listinfo/python-list -- https://mail.python.org/mailman/listinfo/python-list
Re: Style for docstring
We know some people using "professional" language make things shorteror talk from a point of view different than others and often in otherwise incomprehensible jargon. If a programmer is taking about the algorithm that a function implements, then, yes, they may write "scan" and "return". But if they realize the darn documentation is for PEOPLE asking how to use the darn thing, and want to write in more informal and understandable English, I think it makes more sense to say what the function does as in "scans" and importantly what it "returns" to the user as a result. So if you are taking a programming course and the instructor or textbook is giving imperitave commands, they may well tell youto scan something then calculate something and use a return statement a certain way. I can read many ways and am not particularly bothered by either style but when documenting what is, I prefer proper English (or any otherlanguage) in communicating what it does for them. As with many such things, if you work for a company or with groups of others, it is wise to find out what is expected and do the same as much as reasonable. -Original Message- From: MRAB To: python-list@python.org Sent: Fri, Apr 22, 2022 8:57 pm Subject: Re: Style for docstring On 2022-04-23 00:25, Rob Cliffe via Python-list wrote: > I don't use docstrings much; instead I put a line or two of comments > after the `def ` line. > But my practice in such situations is as per the OP's 3rd suggestion, e.g. > # Returns True if . > I'm curious as to why so many people prefer "Return" to "Returns". > Checking out help() on a few functions in the stdlib, they all used > "Return" or a grammatical equivalent, so this does seem to be a Python > cultural thing. But why? To me, "Returns" begins a description as to > what the function does, whereas "Return" is an imperative. But who is > it addresed to? Is a function considered to be a sentient entity that > can respond to a command? Is it an invocation to the lines of code > following the docstring: "Do this!" Might not the programmer mistakenly > think (if only for a moment) that the imperative is addressed to him? Maybe it's because the function name is often also an imperative, e.g.: >>> import re >>> help(re.search) Help on function search in module re: search(pattern, string, flags=0) Scan through string looking for a match to the pattern, returning a Match object, or None if no match was found. Note "Scan", not "scans". I was going to use 'print' as the example: >>> help(print) Help on built-in function print in module builtins: print(...) print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False) Prints the values to a stream, or to sys.stdout by default. Optional keyword arguments: file: a file-like object (stream); defaults to the current sys.stdout. sep: string inserted between values, default a space. end: string appended after the last value, default a newline. flush: whether to forcibly flush the stream. but it says "Prints", not "Print"... -- https://mail.python.org/mailman/listinfo/python-list -- https://mail.python.org/mailman/listinfo/python-list
