[issue46282] print() docs do not indicate its return value

[Barry A. Warsaw]

Barry A. Warsaw  added the comment:

> Barry: The PEP 8 'return None' recommendation could be added to the Reference 
> entry for 'return'.  But I think this should be a separate issue as 1) it is 
> about coding rather than documentation and 2) there is the possible objection 
> that choosing completely explicit 'return None' versus half explicit, half 
> implicit 'return' and the latter versus completely implicit  
> should be left to the style PEP.

I do think it's a question of style.  Section 7.6 of the language reference 
says:

> If an expression list is present, it is evaluated, else None is substituted.

which is the important concept that beginners should learn.

I agree that the admonition in PEP 8 is really trying to say "don't mix 
implicit and explicit return styles".  Implicit None return is fine if all exit 
paths are implicit.  But once you add an explicit value to a return path, all 
return paths should use explicit values, including those that return None.

IME, while I do occasionally encounter push back on this when doing reviews, 
most folks come around to this p.o.v.

--

___
Python tracker 

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

[issue46282] print() docs do not indicate its return value

[Terry J. Reedy]

Terry J. Reedy  added the comment:

How about following "The Python interpreter has a number of functions and types 
built into it that are always available. They are listed here in alphabetical 
order." in
https://docs.python.org/3/library/functions.html
with "Here and elsewhere in these docs, entries for functions (including 
methods) that always return None usually omit 'Return None' and just say what 
the function does."

Barry: The PEP 8 'return None' recommendation could be added to the Reference 
entry for 'return'.  But I think this should be a separate issue as 1) it is 
about coding rather than documentation and 2) there is the possible objection 
that choosing completely explicit 'return None' versus half explicit, half 
implicit 'return' and the latter versus completely implicit  
should be left to the style PEP.

--
nosy: +terry.reedy

___
Python tracker 

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

[issue46282] print() docs do not indicate its return value

[Éric Araujo]

Change by Éric Araujo :


--
nosy: +eric.araujo

___
Python tracker 

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

[issue46282] print() docs do not indicate its return value

[James Gerity]

James Gerity  added the comment:

The original question was closer to the related issue of "indicate return types 
for all built-ins," conversation log follows (UTC-5):

```
09:33:50 ringo__ | is there a stdlib api docs which actually has *full* 
functions signature?
   
09:34:27 ringo__ | for example, 
https://docs.python.org/3/library/functions.html, function  

   
 | abs(x), it returns what, int? I need to read the 
whole sentence to figure
   
 | out the return value of a function?  

   
09:34:48 ringo__ | (or argument for that matter)

   
09:35:51 bjs | ringo__: well like it says it doesn't just support 
int 
 
09:36:00 bjs | int, float, or any type that supports it 

   
09:37:01 bjs | in general you can find actual type annotations for 
the functions in the

 | typeshed 

   
 | 
https://github.com/python/typeshed/blob/master/stdlib/builtins.pyi  


09:37:32 bjs | I wonder if it would be useful to include the 
typeshed annotation in the  
  
 | docs, or whether it would be more confusing  

   
09:37:49 ringo__ | Thanks bjs ! I'll bookmark this typeshed 

   
09:38:13  SnoopJ | abs() will do whatever __abs__() on the type does, 
which can be different  
 
 | for any given type. You'd expect T -> T but it's not 
guaranteed. 
   
09:38:18 ringo__ | I used abs() as an example. In fact I was wondering 
what does print()   

 | return. I *guessed* it returns None, but the docs 
won't say   
  
09:39:05 ringo__ | I could do a try-it-yourself approach but I was 
puzzled why the docs

 | simply won't give you full fn signature, ie 
print(..) -> None   

09:39:17  SnoopJ | that one is just an omission :)
```

--

___
Python tracker 

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

[issue46282] print() docs do not indicate its return value

[Steven D'Aprano]

Steven D'Aprano  added the comment:

Sure, there will always be some users who will find certain things not 
obvious. Sometimes I'm that user myself.

What did this user think print() returned? What precisely was their 
question? Perhaps if I saw the conversation in context, I would be more 
sympathetic to this.

I can see a difference between (for example) the questions:

"I see that print('Hello world') returns None, but is it safe to assume 
that print will *always* return None? It is not documented anywhere as 
far as I can see."

and

"What does x = print('Hello world') do?"

--

___
Python tracker 

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

[issue46282] print() docs do not indicate its return value

[Barry A. Warsaw]

Barry A. Warsaw  added the comment:

I think it does a better service to users to explain how Python returns None 
implicitly if a function doesn't have any other explicit return value.  If the 
print() docs had this note, it would be confusing why other similar functions 
don't.

It's also worth explaining that when a function is designed to *explicitly* 
return None in certain cases (e.g. dict.get()) that it shouldn't do so 
implicitly, but should include an explicit `return None` for readability.

--
nosy: +barry

___
Python tracker 

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

[issue46282] print() docs do not indicate its return value

[James Gerity]

James Gerity  added the comment:

I opened this ticket on behalf of a user who asked about print() specifically 
in #python on the Libera IRC network, who I assume does not find this obvious.

I don't think it would be tenable to add this note to every built-in, but 
that's not the intended scope of this issue. I do think it's worth mentioning 
for print(), though.

--

___
Python tracker 

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

[issue46282] print() docs do not indicate its return value

[Steven D'Aprano]

New submission from Steven D'Aprano :

Do the print docs need to mention something so obvious?

Functions and methods which operate by side-effect typically don't mention that 
they return None, see for example the docs for various builtin methods:

https://docs.python.org/3/library/stdtypes.html#mutable-sequence-types

e.g. s.append, s.clear, s.extend, s.insert, s.remove, s.reverse

and likewise for list.sort, set.add, dict.clear and many others.

(However, dict.update is a rare exception, it does mention that it returns 
None.)

We should not feel it necessary to add an explicit comment to every function or 
method that operates by side-effect stating that they return None.

--
nosy: +steven.daprano

___
Python tracker 

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

[issue46282] print() docs do not indicate its return value

[James Gerity]

Change by James Gerity :


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

___
Python tracker 

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

[issue46282] print() docs do not indicate its return value

[James Gerity]

Change by James Gerity :


--
assignee: docs@python
components: Documentation
nosy: SnoopJeDi, docs@python
priority: normal
severity: normal
status: open
title: print() docs do not indicate its return value
versions: Python 3.11

___
Python tracker 

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