Re: Lprint = ( Lisp-style printing ( of lists and strings (etc.) ) in Python )

[Peter J. Holzer via Python-list]

On 2024-05-30 21:47:14 -0700, HenHanna via Python-list wrote:
> [('the', 36225), ('and', 17551), ('of', 16759), ('i', 16696), ('a', 15816),
> ('to', 15722), ('that', 11252), ('in', 10743), ('it', 10687)]
> 
> ((the 36225) (and 17551) (of 16759) (i 16696) (a 15816) (to 15722) (that
> 11252) (in 10743) (it 10687))
> 
> 
> i think the latter is easier-to-read, so i use this code
>(by Peter Norvig)

This doesn't work well if your strings contain spaces:

Lprint(
[
["Just", "three", "words"],
["Just", "three words"],
["Just three", "words"],
["Just three words"],
]
)

prints:

((Just three words) (Just three words) (Just three words) (Just three words))

Output is often a compromise between readability and precision.


> def lispstr(exp):
># "Convert a Python object back into a Lisp-readable string."
> if isinstance(exp, list):

This won't work for your example, since you have a list of tuples, not a
list of lists and a tuple is not an instance of a list.

> return '(' + ' '.join(map(lispstr, exp)) + ')'
> else:
> return str(exp)
> 
> def Lprint(x): print(lispstr(x))

I like to use pprint, but it's lacking support for user-defined types. I
should be able to add a method (maybe __pprint__?) to my classes which
handle proper formatting (with line breaks and indentation).

hp
-- 
   _  | Peter J. Holzer| Story must make more sense than reality.
|_|_) ||
| |   | h...@hjp.at |-- Charles Stross, "Creative writing
__/   | http://www.hjp.at/ |   challenge!"


signature.asc
Description: PGP signature
-- 
https://mail.python.org/mailman/listinfo/python-list

Lprint = ( Lisp-style printing ( of lists and strings (etc.) ) in Python )

[HenHanna via Python-list]

 ;;;  Pls tell me about little tricks you use in Python or Lisp.


[('the', 36225), ('and', 17551), ('of', 16759), ('i', 16696), ('a', 
15816), ('to', 15722), ('that', 11252), ('in', 10743), ('it', 10687)]


((the 36225) (and 17551) (of 16759) (i 16696) (a 15816) (to 15722) (that 
11252) (in 10743) (it 10687))



i think the latter is easier-to-read, so i use this code
   (by Peter Norvig)

def lispstr(exp):
   # "Convert a Python object back into a Lisp-readable string."
if isinstance(exp, list):
return '(' + ' '.join(map(lispstr, exp)) + ')'
else:
return str(exp)

def Lprint(x): print(lispstr(x))
--
https://mail.python.org/mailman/listinfo/python-list

Re: Disable 'style PEP' messages

[dn via Python-list]

On 05/05/2023 04.28, Kevin M. Wilson via Python-list wrote:

Hi... How do I set Pycharm to find only syntax errors?!!


Please review response to previous message re:configuring PyCharm's 
helpful features towards to coders and quality-coding...


--
Regards,
=dn
--
https://mail.python.org/mailman/listinfo/python-list

Re: Disable 'style PEP' messages

[Mats Wichmann]

On 5/4/23 10:28, Kevin M. Wilson via Python-list wrote:

Hi... How do I set Pycharm to find only syntax errors?!!


By configuring PyCharm the way you want.

See PyCharm's documentation for how to do that.

Hint:

Settings -> Editor -> Code Style -> Inspections




--
https://mail.python.org/mailman/listinfo/python-list

Disable 'style PEP' messages

[Kevin M. Wilson via Python-list]

Hi... How do I set Pycharm to find only syntax errors?!!
"When you pass through the waters, I will be with you: and when you pass 
through the rivers, they will not sweep over you. When you walk through the 
fire, you will not be burned: the flames will not set you ablaze."      
Isaiah 43:2

|  | Virus-free.www.avg.com |

-- 
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[dn]

On 26/04/2022 11.47, Rob Cliffe via Python-list wrote:
> Well, de gustibus non est disputandum.  For me, the switch from the
> imperative mode to the descriptive mode produces a mild cognitive
> dissonance.

Disagree!

When coding, to whom?what are you talking?

When writing documentation - same question?

This is the reason why (typically) coders are pretty bad at, or disagree
with a need for, 'documentation' - and particularly documentation that
doesn't fit inside a code-module!

(no insult, pure observation)

See earlier when I described taking a set of Requirements and
progressively applying specific clauses or requirements to a function.
One's thinking is in requirement-satisfaction-mode or 'design-mode'.
Later, when implementing the function, one can work in 'coding-mode'.

Separating tasks/roles removes the dissonance. No split-personality
required!

However, I know what you mean, and earlier today was writing to someone
about why I may not bother with a docstring if I'm in coding-mode and
wanting to 'keep going'. However, I see such as 'technical debt',
justified only in the hope that when I do get back to it (presumably
when the code is working, and I'm basking in the joys of (my own)
success, I'll be in more of a 'documentation' frame of mind...

(and pigs might fly!)



> On 25/04/2022 23:34, Cameron Simpson wrote:
>> On 23Apr2022 03:26, Avi Gross  wrote:
>>> 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.
>> I'm in the imperative camp. But if I think the function requires some
>> elaboration, _then_ I provide description:
>>
>>  def f(x):
>>  ''' Return the frobnangle of `x`.
>>
>>  This iterates over the internals of `x` in blah order
>>  gathering the earliest items which are frobby and composes a
>>  nangle of the items.
>>  '''
>>
>> I very much like the concise imperative opening sentence, sometimes 2
>> sentences. Then the elaboration if the function isn't trivially obvious.
>>
>> Cheers,
>> Cameron Simpson 
> 

-- 
Regards,
=dn
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[Rob Cliffe via Python-list]

Well, de gustibus non est disputandum.  For me, the switch from the 
imperative mode to the descriptive mode produces a mild cognitive 
dissonance.

Best wishes
Rob Cliffe

On 25/04/2022 23:34, Cameron Simpson wrote:

On 23Apr2022 03:26, Avi Gross  wrote:

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.

I'm in the imperative camp. But if I think the function requires some
elaboration, _then_ I provide description:

 def f(x):
 ''' Return the frobnangle of `x`.

 This iterates over the internals of `x` in blah order
 gathering the earliest items which are frobby and composes a
 nangle of the items.
 '''

I very much like the concise imperative opening sentence, sometimes 2
sentences. Then the elaboration if the function isn't trivially obvious.

Cheers,
Cameron Simpson 


--
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[Mats Wichmann]

On 4/25/22 16:34, Cameron Simpson wrote:
> On 23Apr2022 03:26, Avi Gross  wrote:
>> 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.
> 
> I'm in the imperative camp. But if I think the function requires some 
> elaboration, _then_ I provide description:

Just as another data point, if nothing else to prove there will never be
consensus :) - Google's style guide is pretty explicit about what they
expect:

> The docstring should be descriptive-style ("""Fetches rows from a
Bigtable.""") rather than imperative-style ("""Fetch rows from a
Bigtable.""").


-- 
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[Cameron Simpson]

On 23Apr2022 03:26, Avi Gross  wrote:
>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.

I'm in the imperative camp. But if I think the function requires some 
elaboration, _then_ I provide description:

def f(x):
''' Return the frobnangle of `x`.

This iterates over the internals of `x` in blah order  
gathering the earliest items which are frobby and composes a 
nangle of the items.
'''

I very much like the concise imperative opening sentence, sometimes 2 
sentences. Then the elaboration if the function isn't trivially obvious.

Cheers,
Cameron Simpson 
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[Avi Gross via Python-list]

Yes, Michael, a dictionary is an excellent way to represent a closed set of 
transitions which your permutations are.
You examples use numerals but obviously a dictionary will allow transformations 
of anything that can be hashed which mostly is items that are not mutable.
Of course for the purposes you may be using these permutations, accessing them 
may be done carefully as you need to have nothing else in the dictionary and 
must access all the keys and make sure you know which keys have already been 
visited from another item.
Some other data structures may work better or faster on smaller examples.
I think you have satisfied my curiosity and your main and only question really 
was on suggested wording of a Docstring.
Now if only the Docstring idea was replaced by a Dictionary too! Things like:
Dictstring = {"Purpose": "Text", "Args": "Text", "Return(s)": "Text", 
"Optional-Note": "Text", "French version": DocStringFrench}
Too late to seriously change the language now!

-Original Message-
From: Michael F. Stemper 
To: python-list@python.org
Sent: Sun, Apr 24, 2022 9:24 am
Subject: Re: Style for docstring

On 23/04/2022 12.43, Avi Gross wrote:
> Given what you added, Michael, your function is part of a larger collection 
> of functions and being compatible with the others is a valid consideration. 
> Whatever you decide, would ideally be done consistently with all or most of 
> them.
> And, of course, it others in the collection also can handle multiple ways to 
> specify a permutation, it may be simpler to have each call something like 
> as.permutation() that handlesmultiple forms and converts to the one easiest 
> for you to use.
> I am not sure that is needed as I suspect the simplest storage is something 
> like a list:  [0,3,2,4,5,6,7,1,9,8] but could also be shown with each cycle 
> as a sub-list or something like anumpy vector or a customized class.

Since you ask, I'm using dictionaries as the internal representation.
If you think about it, a python dictionary *is* a function from one
finite set to another, mathematically. And a (finite) permutation is
a bijection from a (finite) set to itself.

For convenience, the module provides two methods of defining a permutation
other than just entering a dictionary:

  >>> import PermGroups as pg
  >>> a = {'1':'2', '2':'1', '3':'3'}
  >>> b = pg.ParsePerm( '(12)(3)' )
  >>> c = pg.ParseDomImg( '123', '213' )
  >>> a==b
  True
  >>> b==c
  True
  >>>

All of the other functions work on these dictionaries.

I had thought about defining a permutation object, but the conceptual
match between "dict" and "permutation" was too good to discard.

> Clearly if you control the package and how it is used, errors from bad data 
> may not be a concern.

An invalidly-constructed permutation will cause an exception, so
the function won't return.

  >>> d = {'1':'2', '2':'2', '3':'3'}
  >>> pg.ValidateDict(d)
  False
  >>>

If I was to do it over, I would have named this function something
like IsValidPermutation(), hiding the internal representation as
well as making the function's Boolean nature explicit.

-- 
Michael F. Stemper
No animals were harmed in the composition of this message.
-- 
https://mail.python.org/mailman/listinfo/python-list
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[dn]

On 25/04/2022 01.24, Michael F. Stemper wrote:
> On 23/04/2022 12.43, Avi Gross wrote:
>> Given what you added, Michael, your function is part of a
>> larger collection of functions and being compatible with the others
>> is a valid consideration. Whatever you decide, would ideally be done
>> consistently with all or most of them.
>> And, of course, it others in the collection also can handle multiple
>> ways to specify a permutation, it may be simpler to have each call
>> something like as.permutation() that handlesmultiple forms and
>> converts to the one easiest for you to use.
>> I am not sure that is needed as I suspect the simplest storage is
>> something like a list:  [0,3,2,4,5,6,7,1,9,8] but could also be shown
>> with each cycle as a sub-list or something like anumpy vector or a
>> customized class.
> 
> Since you ask, I'm using dictionaries as the internal representation.
> If you think about it, a python dictionary *is* a function from one
> finite set to another, mathematically. And a (finite) permutation is
> a bijection from a (finite) set to itself.
> 
> For convenience, the module provides two methods of defining a permutation
> other than just entering a dictionary:
> 
>  >>> import PermGroups as pg
>  >>> a = {'1':'2', '2':'1', '3':'3'}
>  >>> b = pg.ParsePerm( '(12)(3)' )
>  >>> c = pg.ParseDomImg( '123', '213' )
>  >>> a==b
>  True
>  >>> b==c
>  True
>  >>>
> 
> All of the other functions work on these dictionaries.
> 
> I had thought about defining a permutation object, but the conceptual
> match between "dict" and "permutation" was too good to discard.
> 
>> Clearly if you control the package and how it is used, errors from bad
>> data may not be a concern.
> 
> An invalidly-constructed permutation will cause an exception, so
> the function won't return.
> 
>  >>> d = {'1':'2', '2':'2', '3':'3'}
>  >>> pg.ValidateDict(d)
>  False
>  >>>
> 
> If I was to do it over, I would have named this function something
> like IsValidPermutation(), hiding the internal representation as
> well as making the function's Boolean nature explicit.


Yes, we live and learn!
(but 'technical debt'...)

Naming something based upon its implementation, eg ValidateDict(),
rather than its purpose, is a definite no-no - and while I'm
nit-picking, is that a function? (and thus validate_dict())

The idea of representing perms as dicts is good-thinking!

Please review UserDict
(https://docs.python.org/3/library/collections.html#collections.UserDict).
Sub-classing UserDict gives the advantages of a dict, without some of
the methods you don't want/need, and the ability to gather custom
permutation-methods into the class.

For a discussion about sub-classing dict or using UserDict, may I
recommend Trey Hunner's analysis, aka "there's no such thing as a free
lunch"
(https://treyhunner.com/2019/04/why-you-shouldnt-inherit-from-list-and-dict-in-python/)

Since then, we've been given (and I haven't had a reason to try it, yet)
"PEP 589 – TypedDict: Type Hints for Dictionaries with a Fixed Set of
Keys" which may offer an alternate approach. This comes with the
advantage of 'compile-time' static analysis/checking
(https://peps.python.org/pep-0589/). When I get around to experimenting
with this, I'll be referring to "TypedDict vs dataclasses in Python"
(https://dev.to/meeshkan/typeddict-vs-dataclasses-in-python-epic-typing-battle-onb)

-- 
Regards,
=dn
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[Michael F. Stemper]

On 24/04/2022 08.24, Michael F. Stemper wrote:

On 23/04/2022 12.43, Avi Gross wrote:

Given what you added, Michael, your function is part of a larger collection of 
functions and being compatible with the others is a valid consideration. 
Whatever you decide, would ideally be done consistently with all or most of 
them.
And, of course, it others in the collection also can handle multiple ways to 
specify a permutation, it may be simpler to have each call something like 
as.permutation() that handlesmultiple forms and converts to the one easiest for 
you to use.
I am not sure that is needed as I suspect the simplest storage is something 
like a list:  [0,3,2,4,5,6,7,1,9,8] but could also be shown with each cycle as 
a sub-list or something like anumpy vector or a customized class.


Since you ask, I'm using dictionaries as the internal representation.
If you think about it, a python dictionary *is* a function from one
finite set to another, mathematically. And a (finite) permutation is
a bijection from a (finite) set to itself.

For convenience, the module provides two methods of defining a permutation
other than just entering a dictionary:

  >>> import PermGroups as pg
  >>> a = {'1':'2', '2':'1', '3':'3'}
  >>> b = pg.ParsePerm( '(12)(3)' )
  >>> c = pg.ParseDomImg( '123', '213' )
  >>> a==b
  True
  >>> b==c
  True
  >>>

All of the other functions work on these dictionaries.

I had thought about defining a permutation object, but the conceptual
match between "dict" and "permutation" was too good to discard.


Clearly if you control the package and how it is used, errors from bad data may 
not be a concern.


An invalidly-constructed permutation will cause an exception, so
the function won't return.


The below was *not* intended to illustrate what I said above. It
shows the validation function provided by the module. This allows
the user to avoid the consequences of an invalidly-constructed
permutation. (It's only for users who don't subscribe to "EAFP",
of course.)


  >>> d = {'1':'2', '2':'2', '3':'3'}
  >>> pg.ValidateDict(d)
  False
  >>>

If I was to do it over, I would have named this function something
like IsValidPermutation(), hiding the internal representation as
well as making the function's Boolean nature explicit.




--
Michael F. Stemper
Psalm 82:3-4
--
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[Michael F. Stemper]

On 23/04/2022 12.43, Avi Gross wrote:

Given what you added, Michael, your function is part of a larger collection of 
functions and being compatible with the others is a valid consideration. 
Whatever you decide, would ideally be done consistently with all or most of 
them.
And, of course, it others in the collection also can handle multiple ways to 
specify a permutation, it may be simpler to have each call something like 
as.permutation() that handlesmultiple forms and converts to the one easiest for 
you to use.
I am not sure that is needed as I suspect the simplest storage is something 
like a list:  [0,3,2,4,5,6,7,1,9,8] but could also be shown with each cycle as 
a sub-list or something like anumpy vector or a customized class.


Since you ask, I'm using dictionaries as the internal representation.
If you think about it, a python dictionary *is* a function from one
finite set to another, mathematically. And a (finite) permutation is
a bijection from a (finite) set to itself.

For convenience, the module provides two methods of defining a permutation
other than just entering a dictionary:

 >>> import PermGroups as pg
 >>> a = {'1':'2', '2':'1', '3':'3'}
 >>> b = pg.ParsePerm( '(12)(3)' )
 >>> c = pg.ParseDomImg( '123', '213' )
 >>> a==b
 True
 >>> b==c
 True
 >>>

All of the other functions work on these dictionaries.

I had thought about defining a permutation object, but the conceptual
match between "dict" and "permutation" was too good to discard.


Clearly if you control the package and how it is used, errors from bad data may 
not be a concern.


An invalidly-constructed permutation will cause an exception, so
the function won't return.

 >>> d = {'1':'2', '2':'2', '3':'3'}
 >>> pg.ValidateDict(d)
 False
 >>>

If I was to do it over, I would have named this function something
like IsValidPermutation(), hiding the internal representation as
well as making the function's Boolean nature explicit.

--
Michael F. Stemper
No animals were harmed in the composition of this message.
--
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[dn]

On 23/04/2022 08.35, 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."
> 
>> That's just one opinion though, others may disagree :)
> 
> Two for two. Thanks.


I've always taken the PEP somewhat for granted (with belated thanks and
respect to the authors and others who exerted effort (or would that be,
efforts?) to publish the finished work.

One of the things that I've taken-as-read, is WHY we use docstrings.
That rationale is wider than Python. Like many others, I just brought
that sort thinking with me.

Have you noticed that the PEP doesn't discuss this? It has taken this
thread to make me realise such.


The elephant in the style room is PEP-008. It's quite old in
'Python-years'! As time went by, PEP-257 became relevant - and I don't
recall which was 'chicken' and which 'egg', between the PEP and the
docutils/help/etc tools which depend upon a level of docstring
uniformity. No matter, together they represent a step of progress, after
PEP-008.

Since then we have added typing. Where once there was an extensive
documentation system to clarify the use of parameters and the definition
of return-values, now much of that can be done on the def-line (or
equivalent).

Another 'development' (I'd prefer 'natural progression') is that as
computers have become more powerful and storage cheaper, we have been
able to first justify, and now habitually, use longer identifier-names.
This step of progress should enable more descriptive and readable code.


So, we can consider that there are (now) three aspects which overlap,
considerably:

1 the name of the function
- descriptive and readable (see OP's assurance on this point)
2 typing
- description and distinction of parameters and return-values
3 docstring
- even more information about the function, how the author intends it be
used, embedded assumptions, etc

Thus, aren't there situations where a short, sharp, DRY, and SRP,
function; once well-named and accurately typed, could stand on its own
merits without a docstring. (yes, others will suck in their breath and
start preparing a bon-fire, at the utterance of such 'heresy'...)

We all hate 'boiler-plate', ie feeling forced to type stuff 'just
because', and particularly when it seems like duplication/repetition
(see recent thread(s) 'here' about __init__() and dataclasses). In fact,
one reason why we have functions is to reduce/remove (code) duplication!
So, why would we indulge in documental 'duplication' just-because we
should?must have a docstring?


While I'm tilting at windmills, wasn't option-2 the best?
(ooh, those flames are starting to warm my feet...)

Why? First, see other discussion about "imperatives".

My habit is to take the Statement of Requirements and copy it into a
brand-new __main__. As development proceeds, various details will be
extracted and copied into function and class docstrings. The language of
a specification should be imperative, ie you will *do* 'this'.

A second reason, is that the docstring should document the function,
which is subtly-different from describing the return-value (and that has
become a task for typing anyway).
(OK, the flames are getting-good, and it's time to break-out the
marsh-mallows and crumpets...)

So, 'nr2' describes what the function DOES!


PS would you mind passing-over the fire-extinguisher?
-- 
Regards,
=dn
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[jan via Python-list]

"return true iff this".

I like this.

jan

On 23/04/2022, Stefan Ram  wrote:
> Rob Cliffe  writes:
>>I'm curious as to why so many people prefer "Return" to "Returns".
>
>   The commands, er, names of functions, use the imperative mood
>   ("print", not "prints"). So, "return" aligns with that mood
>   as a paraphrase of such names.
>
>   In Java, at one point, they decided to start to use the
>   third person at one point and then half-heartedly converted
>   all the documentation, as in
>
> |void println(boolean x)
> |Prints a boolean and then terminate the line.
>
>   , where they modified "print" but did not bother do modify
>   "terminate".
>
>   And instead of "return true if this, false if not this",
>   I might be inclined to write "return true iff this".
>
>   BTW: As a language element that helps to construct a boolean
>   expression from a file name, some languages, like SQL, use
>   "EXISTS", while others, like MS-DOS-batch, use "EXIST".
>
>
> --
> https://mail.python.org/mailman/listinfo/python-list
>
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[Dan Stromberg]

On Fri, Apr 22, 2022 at 12:56 PM Michael F. Stemper <
michael.stem...@gmail.com> 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.)
>

Maybe try pydocstyle?
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[Avi Gross via Python-list]

Given what you added, Michael, your function is part of a larger collection of 
functions and being compatible with the others is a valid consideration. 
Whatever you decide, would ideally be done consistently with all or most of 
them.
And, of course, it others in the collection also can handle multiple ways to 
specify a permutation, it may be simpler to have each call something like 
as.permutation() that handlesmultiple forms and converts to the one easiest for 
you to use.
I am not sure that is needed as I suspect the simplest storage is something 
like a list:  [0,3,2,4,5,6,7,1,9,8] but could also be shown with each cycle as 
a sub-list or something like anumpy vector or a customized class.
Clearly if you control the package and how it is used, errors from bad data may 
not be a concern. But like many Boolean return(s) it is always a problem how to 
deal with a third possibility.







-Original Message-
From: Michael F. Stemper 
To: python-list@python.org
Sent: Sat, Apr 23, 2022 8:57 am
Subject: Re: Style for docstring

On 22/04/2022 21.58, Avi Gross wrote:
> 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?

That's a fair point. However, this function will be the 22nd one in
a module for dealing with permutations and groups of permutations.
The module has a lengthy docstring explaining the several ways provided
to specify a permutation. That way, the same information doesn't need
to be written twenty-plus times.

> 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, ...

I see what you did there :->

-- 
Michael F. Stemper
Psalm 94:3-6
-- 
https://mail.python.org/mailman/listinfo/python-list
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[Michael F. Stemper]

On 22/04/2022 16.12, alister wrote:

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:




for guidance I would sugest Pep257 as a start point
which would suggest "Return True if permutation is even"


I'll take a look at the PEP. Thanks.


--
Michael F. Stemper
This email is to be read by its intended recipient only. Any other party
reading is required by the EULA to send me $500.00.
--
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[Michael F. Stemper]

On 22/04/2022 21.58, Avi Gross wrote:

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?


That's a fair point. However, this function will be the 22nd one in
a module for dealing with permutations and groups of permutations.
The module has a lengthy docstring explaining the several ways provided
to specify a permutation. That way, the same information doesn't need
to be written twenty-plus times.


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, ...


I see what you did there :->

--
Michael F. Stemper
Psalm 94:3-6
--
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

[Avi Gross via Python-list]

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

Re: Style for docstring

[Avi Gross via Python-list]

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

[MRAB]

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

[Cameron Simpson]

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

[Chris Angelico]

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

Re: Style for docstring

[Rob Cliffe via Python-list]

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

[2QdxY4RzWzUUiLuE]

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

[Chris Angelico]

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

[2QdxY4RzWzUUiLuE]

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

[alister via Python-list]

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

Re: Style for docstring

[Michael F. Stemper]

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

[Ethan Furman]

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: Style for docstring

[Chris Angelico]

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

Style for docstring

[Michael F. Stemper]

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

[issue442758] 2.2a1: New style classes and __cmp__

[admin]

Change by admin :


--
github: None -> 34785

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue473512] getopt with GNU style scanning

[admin]

Change by admin :


--
github: None -> 35375

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue467336] doctest failures w/ new-style classes

[admin]

Change by admin :


--
github: None -> 35268

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue442791] 2.2a1: New style classes and __delitem__

[admin]

Change by admin :


--
github: None -> 34786

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue507394] non-string __doc__/new style class prob.

[admin]

Change by admin :


--
github: None -> 35967

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue401121] cosmetic cleanup of cgi.py, using Guido's style conventions

[admin]

Change by admin :


___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue518846] exception cannot be new-style class

[admin]

Change by admin :


--
github: None -> 36116

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue515074] Extended storage in new-style classes

[admin]

Change by admin :


--
github: None -> 36073

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue504343] Unicode docstrings and new style classes

[admin]

Change by admin :


--
github: None -> 35930

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue492345] New-style class with only classic bases

[admin]

Change by admin :


--
github: None -> 35729

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue477752] Drop old-style getargs from curses

[admin]

Change by admin :


--
github: None -> 35457

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue484977] memory leaks with new style classes

[admin]

Change by admin :


--
github: None -> 35572

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue461001] inspect & pydoc vs new-style classes

[admin]

Change by admin :


--
github: None -> 35161

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue451773] new-style objects not weak-referencable

[admin]

Change by admin :


--
github: None -> 34984

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue452747] New-style class instances can't be copied

[admin]

Change by admin :


--
github: None -> 35000

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue442734] 2.2a1: New style classes and pydoc

[admin]

Change by admin :


--
github: None -> 34784

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue400660] Update examples to use new-style extensions

[admin]

Change by admin :


___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue400659] Allows sdist to work with old-style extensions

[admin]

Change by admin :


___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue401121] cosmetic cleanup of cgi.py, using Guido's style conventions

[admin]

Change by admin :


--
github: None -> 32901

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue400660] Update examples to use new-style extensions

[admin]

Change by admin :


--
github: None -> 32477

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue400659] Allows sdist to work with old-style extensions

[admin]

Change by admin :


--
github: None -> 32476

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46168] Incorrect format specified for the "style" key in the configuration file format formatter example

[Stanley]

Stanley  added the comment:

Samriddhi, are you still working on this?

--
nosy: +slateny

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46751] Windows-style path is not recognized under cygwin

[Christoph Reiter]

Christoph Reiter  added the comment:

Afaik Cywin programs only work with native Windows paths if the paths happen to 
get directly passed to the OS APIs and not interpreted in any way before that. 
So I don't think this is a bug and expected behavior.

Use "cygpath C:/path/to/script.py" to convert the path to the right format 
first.

--
nosy: +lazka

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46751] Windows-style path is not recognized under cygwin

[Eryk Sun]

Eryk Sun  added the comment:

MSYS2 has basically the same problem when the script is passed as a Windows 
path, except it uses "/c" for the "C:" drive instead of "/cygdrive/c".

# python3 -VV
Python 3.9.9 (main, Dec 28 2021, 11:05:23)
[GCC 11.2.0]

# echo $PWD
/proc

# python3 C:/Temp/test.py
python3: can't open file '/proc/C:/Temp/test.py': [Errno 2] No such file or 
directory

Windows paths in the command-line arguments appear to be passed without 
conversion:

# python3 -ic 1 C:/Temp/test.py
>>> import os
>>> open(f'/proc/{os.getpid()}/cmdline').read().split('\0')
['python3', '-ic', '1', 'C:/Temp/test.py', '']

They're generally supported:

>>> open('C:/Temp/test.py').read()
'import sys\nprint(sys.executable)\n\n'

>>> os.path.samefile('C:/Temp/test.py', '/c/Temp/test.py')
True

>>> os.path.abspath('C:/Temp/test.py')
'C:/Temp/test.py'

realpath() doesn't support them:

>>> os.path.realpath('C:/Temp/test.py')
'/:/Temp/test.py'

But the C API _Py_wrealpath() does:

>>> import ctypes
>>> path = (ctypes.c_wchar * 1000)()
>>> ctypes.pythonapi._Py_wrealpath('C:/Temp/test.py', path, 1000)
1484496
>>> path.value
'/c/Temp/test.py'

--
nosy: +eryksun

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46751] Windows-style path is not recognized under cygwin

[Mike Kaganski]

Mike Kaganski  added the comment:

> As for 3.9: it's not available through the 64 bit installer (at least, I 
> don't see it there). I'll look and see what's involved in installing it.

I don't remember if I did something special to install it; however, just maybe 
you need to install python39 directly.

> Are you running the 32- or 64-bit version?

64-bit.

> Does Cygwin not use : as a path list separator?

It uses : as path separator:

$ echo $PATH
/opt/lo/bin:/usr/local/bin:/usr/bin:/cygdrive/c/Program 
Files/AdoptOpenJDK/jdk-11.0.7.10-hotspot/bin:/cygdrive/c/Program Files 
(x86)/Common 
Files/Oracle/Java/javapath:/cygdrive/c/ProgramData/Oracle/Java/javapath:/cygdrive/c/Windows/System32:/cygdrive/c/Windows:/cygdrive/c/Windows/System32/wbem:/cygdrive/c/Windows/System32/WindowsPowerShell/v1.0:...

But obviously, it can't use Windows-style paths in the $PATH (for that reason?).

--

___
Python tracker 
<https://bugs.python.org/issue46751>
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46751] Windows-style path is not recognized under cygwin

[Steve Dower]

Steve Dower  added the comment:

Does Cygwin not use : as a path list separator? (What would normally be 
; on Windows.)

Perhaps the CPython build needs to be patched specially here to handle 
different separator character.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46751] Windows-style path is not recognized under cygwin

[Eric V. Smith]

Eric V. Smith  added the comment:

>:) Citing myself:

>> Trying this *bash* command line:

Oops, sorry for missing that.

As for 3.9: it's not available through the 64 bit installer (at least, I don't 
see it there). I'll look and see what's involved in installing it.

Are you running the 32- or 64-bit version?

Also: I suspect this is a cygwin problem that will need to be reported upstream.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46751] Windows-style path is not recognized under cygwin

[Mike Kaganski]

Mike Kaganski  added the comment:

Thanks for looking at this!

> Are you running from bash (or another cygwin shell), or from cmd.exe, or 
> something else?

:) Citing myself:

> Trying this *bash* command line:

> To my knowledge, cygwin's installer doesn't have a 3.9 available.

It does: https://cygwin.com/packages/summary/python3.html

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46751] Windows-style path is not recognized under cygwin

[Eric V. Smith]

Eric V. Smith  added the comment:

Are you running from bash (or another cygwin shell), or from cmd.exe, or 
something else?

How did you install the version of python you're executing in the examples you 
provided? To my knowledge, cygwin's installer doesn't have a 3.9 available.

I don't see this behavior on cygwin's python3.8, either from cmd.exe or from 
zsh.

--
nosy: +eric.smith

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46751] Windows-style path is not recognized under cygwin

[Mike Kaganski]

New submission from Mike Kaganski :

Using cyqwin 3.3.4-2, and python3:

Python 3.9.10 (main, Jan 20 2022, 21:37:52)
[GCC 11.2.0] on cygwin

Trying this bash command line:

> python3 C:/path/to/script.py

results in this error:

"python3: can't open file '/cygdrive/c/path/to/curdir/C:/path/to/script.py': 
[Errno 2] No such file or directory"

OTOH, calling it like

> python3 /cygdrive/c/path/to/script.py

gives the expected output:

"usage: script.py [-h] ..."

It seems that python3 doesn't recognize "C:/path/to/script.py" to be a proper 
full path under cygwin, while most other cygwin apps handle those fine. E.g.,

> nano C:/path/to/script.py

opens the script for editing without problems.

The mentioned path syntax is useful and supported under cygwin, so it would be 
nice if python3 could support it, too. Especially useful it is in mixed 
development environment, mixing Windows native tools and cygwin ones; using 
such path style allows to use same paths for both kinds of tools, simplifying 
scripts.

--
components: Windows
messages: 413247
nosy: mikekaganski, paul.moore, steve.dower, tim.golden, zach.ware
priority: normal
severity: normal
status: open
title: Windows-style path is not recognized under cygwin
type: behavior
versions: Python 3.9

___
Python tracker 
<https://bugs.python.org/issue46751>
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46690] create_autospec() doesn't respect configure_mock style kwargs

[Karthikeyan Singaravelan]

Karthikeyan Singaravelan  added the comment:

I guess the problem is that during the initial mock creation kwargs is passed 
so calling test_method immediately after mock creation raises ValueError. But 
as we loop through the attributes and create new child mock for the attributes 
the original configured mock for the method that raises ValueError is 
overridden by another object without the configuration info. Probably it makes 
sense to call configure_mock again after all children mock are constructed. 
Something like below works and I don't see any test failures in mock related 
test cases.

index 2719f74d6f..585e875c95 100644
--- a/Lib/unittest/mock.py
+++ b/Lib/unittest/mock.py
@@ -2637,6 +2637,7 @@ def create_autospec(spec, spec_set=False, instance=False, 
_parent=None,
f'[object={spec!r}]')
 is_async_func = _is_async_func(spec)
 _kwargs = {'spec': spec}
+original_kwargs = kwargs
 if spec_set:
 _kwargs = {'spec_set': spec}
 elif spec is None:
@@ -2740,6 +2741,9 @@ def create_autospec(spec, spec_set=False, instance=False, 
_parent=None,
 if isinstance(new, FunctionTypes):
 setattr(mock, entry, new)
 
+if _is_instance_mock(mock):
+mock.configure_mock(**original_kwargs)
+
 return mock

--
components: +Library (Lib) -Tests
nosy: +cjw296, lisroach, mariocj89, michael.foord

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46690] create_autospec() doesn't respect configure_mock style kwargs

[Karthikeyan Singaravelan]

Change by Karthikeyan Singaravelan :


--
nosy: +xtreak

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46690] create_autospec() doesn't respect configure_mock style kwargs

[James Marchant]

New submission from James Marchant :

When using `create_autospec()` to create a mock object, it doesn't respect 
values passed through in the style described for passing mock configurations in 
the Mock constructor 
(https://docs.python.org/3.8/library/unittest.mock.html#unittest.mock.Mock.configure_mock).
 Instead, they seem to get discarded somewhere here 
(https://github.com/python/cpython/blob/77bab59c8a1f04922bb975cc4f11e5323d1d379d/Lib/unittest/mock.py#L2693-L2741).

Here's a simple test case:
```
from unittest.mock import create_autospec

class Test:
def test_method(self):
pass

autospec_mock = create_autospec(Test, instance=True, 
**{"test_method.side_effect": ValueError})

# Should throw a ValueError exception
autospec_mock.test_method()

# Assign manually
autospec_mock.test_method.side_effect = ValueError
# Throws as expected
autospec_mock.test_method()
```

--
components: Tests
messages: 412898
nosy: marchant.jm
priority: normal
severity: normal
status: open
title: create_autospec() doesn't respect configure_mock style kwargs
type: behavior
versions: Python 3.10, Python 3.8, Python 3.9

___
Python tracker 
<https://bugs.python.org/issue46690>
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46510] Update Python2-style exception handling

[Irit Katriel]

Change by Irit Katriel :


--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46510] Update Python2-style exception handling

[Irit Katriel]

Irit Katriel  added the comment:


New changeset ec7c17ea236f71c8376abcc2930a7c857d417966 by Irit Katriel in 
branch 'main':
bpo-46510: Add missing test for types.TracebackType/FrameType. Calculate them 
directly from the caught exception. (GH-30880)
https://github.com/python/cpython/commit/ec7c17ea236f71c8376abcc2930a7c857d417966


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46510] Update Python2-style exception handling

[Irit Katriel]

Irit Katriel  added the comment:


New changeset d69d3d8b2fec501e51309221fb1fa4622c8a3db3 by Irit Katriel in 
branch 'main':
bpo-46510: simplify exception handling code in xmlrpc (GH-30878)
https://github.com/python/cpython/commit/d69d3d8b2fec501e51309221fb1fa4622c8a3db3


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46510] Update Python2-style exception handling

[Irit Katriel]

Irit Katriel  added the comment:


New changeset 45f5f52601ebccb195c19cb0a77beaf7f7dfa56a by Kumar Aditya in 
branch 'main':
bpo-46510: update Python2-style exception handling in argparse (GH-30881)
https://github.com/python/cpython/commit/45f5f52601ebccb195c19cb0a77beaf7f7dfa56a


--

___
Python tracker 
<https://bugs.python.org/issue46510>
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46510] Update Python2-style exception handling

[Kumar Aditya]

Kumar Aditya  added the comment:

> It's not my intention here to go on a search-and-destroy mission to remove 
> all calls to sys.exc_info(), that would cause unnecessary code churn. I am 
> reviewing them to see where the call the sys.exc_info is close to other 
> legacy problems/significant complexity/missing tests.

That's my intention too, in argparse it was used to get the currently handled 
exception value which can be easily accessed by using "as" in exception 
handling, so it makes sense to change it, not to mention that using exc_info 
creates a temporary tuple which is of no use in this scenario.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46510] Update Python2-style exception handling

[Irit Katriel]

Irit Katriel  added the comment:

It's not my intention here to go on a search-and-destroy mission to remove all 
calls to sys.exc_info(), that would cause unnecessary code churn. I am 
reviewing them to see where the call the sys.exc_info is close to other legacy 
problems/significant complexity/missing tests.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46510] Update Python2-style exception handling

[Kumar Aditya]

Change by Kumar Aditya :


--
nosy: +kumaraditya303
nosy_count: 1.0 -> 2.0
pull_requests: +29061
pull_request: https://github.com/python/cpython/pull/30881

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46510] Update Python2-style exception handling

[Irit Katriel]

Change by Irit Katriel :


--
pull_requests: +29060
pull_request: https://github.com/python/cpython/pull/30880

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46510] Update Python2-style exception handling

[Irit Katriel]

Change by Irit Katriel :


--
keywords: +patch
pull_requests: +29058
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/30878

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46510] Update Python2-style exception handling

[Irit Katriel]

New submission from Irit Katriel :

Following issue45711 the redundancy in exc_info is now explicit. This means 
that we can now safely update places that still use python2-style exception 
handling code, like:

exc_type, exc_value = sys.exc_info()[:2]
try:
response = dumps(
Fault(1, "%s:%s" % (exc_type, exc_value)),
encoding=self.encoding, allow_none=self.allow_none)
response = response.encode(self.encoding, 'xmlcharrefreplace')
finally:
# Break reference cycle
exc_type = exc_value = None

--
assignee: iritkatriel
components: Library (Lib)
messages: 411561
nosy: iritkatriel
priority: normal
severity: normal
status: open
title: Update Python2-style exception handling
type: enhancement
versions: Python 3.11

___
Python tracker 
<https://bugs.python.org/issue46510>
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46168] Incorrect format specified for the "style" key in the configuration file format formatter example

[Samriddhi Bhardwaj]

Samriddhi Bhardwaj  added the comment:

I would like to help with this issue. It should take me less than 5 days.

--
nosy: +samriddhi.bhardwaj

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46168] Incorrect format specified for the "style" key in the configuration file format formatter example

[Daniel Diniz]

Daniel Diniz  added the comment:

This example was added in issue 43047. It only seems to affect 3.10+ docs. Ian, 
is this something you'd like to tackle?

--
keywords: +easy
nosy: +ajaksu2, iwienand
stage:  -> needs patch
versions: +Python 3.10, Python 3.11 -Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46168] Incorrect format specified for the "style" key in the configuration file format formatter example

[David Bereza]

New submission from David Bereza :

Documentation link: 
https://docs.python.org/3/library/logging.config.html#configuration-file-format

It seems that the example for the "formatter_form01" formatter section 
specifies following for the style(please note the single-quotes around the 
value). 
style='%'

This seems to raise a ValueError with the message "Style must be one of..." 
when parsing the configuration file. Removing the single quotes seems to fix 
the issue:
style=%

--
assignee: docs@python
components: Documentation
messages: 409108
nosy: bokunogf, docs@python
priority: normal
severity: normal
status: open
title: Incorrect format specified for the "style" key in the configuration file 
format formatter example
versions: Python 3.8

___
Python tracker 
<https://bugs.python.org/issue46168>
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[Alex Waygood]

Change by Alex Waygood :


--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[miss-islington]

miss-islington  added the comment:


New changeset 0c0bd78ccf8e1eb1d8ecfce423daf2a2f8ca6d3b by Miss Islington (bot) 
in branch '3.10':
[3.10] bpo-46104: Fix example broken by GH-30148 (GH-30203) (GH-30209)
https://github.com/python/cpython/commit/0c0bd78ccf8e1eb1d8ecfce423daf2a2f8ca6d3b


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[miss-islington]

miss-islington  added the comment:


New changeset 8e4564d14ae0fc97cfea4de9e271468d4c28a6fe by Miss Islington (bot) 
in branch '3.9':
[3.9] bpo-46104: Fix example broken by GH-30148 (GH-30203) (GH-30210)
https://github.com/python/cpython/commit/8e4564d14ae0fc97cfea4de9e271468d4c28a6fe


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[miss-islington]

Change by miss-islington :


--
pull_requests: +28431
pull_request: https://github.com/python/cpython/pull/30210

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[Ken Jin]

Ken Jin  added the comment:


New changeset 7c5c3f7254d78babcaf7a2ec187fd6ec53b8403c by Alex Waygood in 
branch 'main':
bpo-46104: Fix example broken by GH-30148 (GH-30203)
https://github.com/python/cpython/commit/7c5c3f7254d78babcaf7a2ec187fd6ec53b8403c


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[miss-islington]

Change by miss-islington :


--
pull_requests: +28430
pull_request: https://github.com/python/cpython/pull/30209

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[Alex Waygood]

Change by Alex Waygood :


--
resolution: fixed -> 
stage: resolved -> patch review
status: closed -> open

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[Alex Waygood]

Change by Alex Waygood :


--
pull_requests: +28424
pull_request: https://github.com/python/cpython/pull/30203

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[Alex Waygood]

Change by Alex Waygood :


--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[miss-islington]

miss-islington  added the comment:


New changeset a66be9185c6e0299293a06e21a6f599dfe6c3f60 by Miss Islington (bot) 
in branch '3.10':
[3.10] bpo-46104: Reduce use of pre-PEP 526 syntax in typing docs (GH-30148) 
(GH-30179)
https://github.com/python/cpython/commit/a66be9185c6e0299293a06e21a6f599dfe6c3f60


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[miss-islington]

miss-islington  added the comment:


New changeset 43cb8f483b9f815abf9801e05ec70ae55ca3c5a5 by Miss Islington (bot) 
in branch '3.9':
[3.9] bpo-46104: Reduce use of pre-PEP 526 syntax in typing docs (GH-30148) 
(GH-30180)
https://github.com/python/cpython/commit/43cb8f483b9f815abf9801e05ec70ae55ca3c5a5


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[miss-islington]

Change by miss-islington :


--
pull_requests: +28399
pull_request: https://github.com/python/cpython/pull/30180

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[miss-islington]

Change by miss-islington :


--
nosy: +miss-islington
nosy_count: 4.0 -> 5.0
pull_requests: +28398
pull_request: https://github.com/python/cpython/pull/30179

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[Ken Jin]

Ken Jin  added the comment:


New changeset 6ada013df170b0afb6b61a0d942388c6fd81cbc9 by Alex Waygood in 
branch 'main':
bpo-46104: Reduce use of pre-PEP 526 syntax in typing docs (GH-30148)
https://github.com/python/cpython/commit/6ada013df170b0afb6b61a0d942388c6fd81cbc9


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[Alex Waygood]

Change by Alex Waygood :


--
keywords: +patch
pull_requests: +28368
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/30148

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46104] Reduce use of old-style syntax in typing docs

[Alex Waygood]

New submission from Alex Waygood :

There are a few places in the typing docs where old-style (pre-PEP 526) syntax 
is used in examples. It doesn't look like these examples have been updated 
since 2016; it would be good to change them so that they use the newer syntax 
introduced in PEP 526.

--
assignee: docs@python
components: Documentation
messages: 408721
nosy: AlexWaygood, docs@python, gvanrossum, kj
priority: normal
severity: normal
status: open
title: Reduce use of old-style syntax in typing docs
type: enhancement
versions: Python 3.10, Python 3.11, Python 3.9

___
Python tracker 
<https://bugs.python.org/issue46104>
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue22213] Make pyvenv style virtual environments easier to configure when embedding Python

[Nathan Jensen]

Change by Nathan Jensen :


--
nosy: +ndjensen

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45708] PEP 515-style formatting with underscores does not seem to work for Decimal

[Eric V. Smith]

Eric V. Smith  added the comment:

I think your option 2 makes the most sense.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45708] PEP 515-style formatting with underscores does not seem to work for Decimal

[Mark Dickinson]

Mark Dickinson  added the comment:

Christian Heimes pointed out in the PR discussion that we can't simply modify 
libmpdec, since some vendors unbundle the mpdecimal library.

So some options are:

0. Do nothing.
1. Request that this feature to be added upstream, so that it eventually makes 
its way into core Python.
2. Bypass mpd_parse_fmt_str and do our own format string parsing in _decimal.c 
(e.g., by copying and adapting the code in mpdecimal).
3. Wrap mpd_parse_fmt_str and do our own pre- and post- processing in 
_decimal.c (pre-process to convert "_" to "," in the format string, then 
post-process the formatted string to convert "," back to "_").

Option 2 makes sense to me from the point of view of separation of concerns: 
libmpdec aims to implement Cowlishaw's specification, and formatting lies 
outside of that specification. The decimal specification is pretty much set in 
stone, but the formatting mini-language could change again in the future, and 
when that happens we should be able to update the CPython code accordingly. 
(This brings to mind Robert Martin's Single Responsibility Principle: "Gather 
together those things that change for the same reason, and separate those 
things that change for different reasons.") 

I've updated the PR (and turned it into a draft) to show what option 2 looks 
like. The duplication is a little ugly.

--
nosy: +christian.heimes

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45708] PEP 515-style formatting with underscores does not seem to work for Decimal

[Raymond Hettinger]

Change by Raymond Hettinger :


--
assignee: rhettinger -> 

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45708] PEP 515-style formatting with underscores does not seem to work for Decimal

[Mark Dickinson]

Mark Dickinson  added the comment:

> It looks like quite similar changes have already been made: 

Yes, I think this isn't something that needs to be resolved for this issue, but 
it is something we need to think about. (Though perhaps the resolution is just 
"Don't worry about it until we need to.")

> I will send a PR, so we can see what exactly it touches / changes.

Ah, sorry; I already made one before reading your message. I'd be happy to get 
your input on that PR, though. (Or to review a PR from you.)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com