- Update output to be consistent with the Python interactive-interpreter (e.g. print() prints its argument string without quotes).
- Replace “Python terminal” with “Python shell” for accuracy. While informally acceptable, they are technically different (a shell runs inside a terminal).
- Change parenthesis to plural form: parentheses.
- Replace “return expression” with “return statement” for accuracy.
This thread was automatically created (using commit message) after I made a PR with these changes that was automatically closed.
Hi @abulkeram 
Thank you for starting this thread and for opening a PR. I’m fairly swamped at the moment, but will get back to you here with feedback soon.
Meanwhile, I noticed that you only submitted corrections for the exercise introduction.md, but the concept introduction.md + about.md have overlapping content, so you might want to review them as well.
Thanks again for submitting a PR. 
Thank you for your reply @BethanyG !
My apologies for rushing the PR before reading contribution guidelines. Requiring a forum post discussion ahead of a PR is totally understood.
Indeed, I just noticed that the linked concept files have some of the same content, I will gladly review them as soon as I can, and suggest changes (here first).
I reviewed the linked concept files and made similar changes locally, with the following exceptions:
>>> print(my_first_variable)
>>> Counter({3: 3, 1: 2, 2: 1, 4: 1, 5: 1, 6: 1, 7: 1})
>>> math.pow(2,4) # Calling the pow() function from the math module
>>> 16.0
These are clearly typos – the chevron prompt must not exist in the last line of each example.
To avoid misunderstanding about the change I’ve made to the following sentence:
Functions that do not have an explicit
returnexpression will implicitly return the None object
This is generally true, but a function that doesn’t have a return expression looks like:
def f():
return
Whereas, the example that immediately follows that sentence defines a function without a return statement altogether:
def add_two_numbers(number_one, number_two):
result = number_one + number_two
So I changed “expression” to “statement” to match the example.
Per the Python language reference:
7.6 The return statement
return_stmt ::= "return [expression_list]"
I have made changes to basics/introduction.md and basics/about.md on a new local branch. Whenever you say so, I can push them and make a PR.
Optional “opinionated” suggestions that I haven’t included in my changes:
- I think that the function signature:
number_to_the_power_of(number_one, number_two)
is good, but it’s probably not the best example for a function signature.
Better alternatives might be:power(base, exponent)orraise_to_power(number, power)if you want to be more expressive while using less mathematical jargon.
Hi @abulkeram,
Thank you for going over the additional docs, and for your willingness to discuss things here first. Apologies for the delay in getting back to you on this.
I noticed this change in your original PR, and wanted to point out what you just did: return is a statement that will pass back None if it is not followed by an expression.
So that’s what I think we should say (and provide examples of) here:
Functions that omit `return` or do not have an _explicit_ expression following a `return` will _implicitly_ return the [`None`][none] object.
This means that if you do not use `return` in a function, Python will return the `None` object for you.
Both of these functions will return `None`:
```python
def square_a_number(number):
square = number * number
return # <-- note that this return is not followed by an expression
# This function omits a return keyword altogether
def add_two_numbers(number_one, number_two):
result = number_one + number_two
It still sounds a tad awkward, so open to you massaging it a bit. 
Happy to have you make this change, prefer the raise_to_power(number, power) version.
Happy to have you remove the added >>> in the examples as well.
Finally, I have a quibble with your from vs for change in the PR. To be really pedantic from would be referring to where the method came from, (the string class), or maybe who the caller was. for would be referring to what object the method was applied to (a str object). Since we are calling the method on a str object it would be for.
But maybe the clearest would be
# Calling the upper() method from the built-in str class on start_text.
We could also hammer that home by doing start_text.upper(). But I don’t want students to get into the weeds with str.upper(start_text) vs start_text.upper(), so maybe we keep the code as-is.
1 Like
Apologies - should have added this to my last reply. No need for a new PR - I will reopen the one you submitted, if you want to add your changes there.
Or if you would prefer to start fresh, I am happy with that too. The Auto-closer is still gonna git you … but I can reopen it.
It is notable how you turn ambiguity to clarity (on par with PEP20).
I tried my best to merge your suggested changes related to return expression/statement omission with existing comments and examples, but unlike what you did I introduced these cases separately one after the other for smoother digestion, however I reused your own examples/comments.
Optional follow-up to your quibble with “from”
Your reasoning makes perfect sense, in other words:
from: method source/callerfor: input/argument object
And your conclusion is the natural result of that:
We are calling the method on a str object => for
This implies saying: “calling the method upper() for the str object (e.i. start_text)”
But your original comment in the code was:
Calling the upper() method for the built-in str class.
According your own reasoning, this comment implies doing:
str.upper(str)
Which is obviously not the case.
I’ll keep it as-is upon your request – “for”, but if you’re convinced that it should be “from”, then I’ll be happy to make that change.
Only after I pushed my changes I noticed that there was a little change that I didn’t mention previously, here:
# Printing the __doc__ attribute for the built-in type: str.
I had changed “for → of”, maybe because I thought that this is most likely a typo that isn’t that significant, but now that I learned how precise you like to be, I figured that I must point it out.
I think we should change the comment. One of these, maybe?
# Calling the upper() method from the built-in str class on start_text.
or
# Calling the upper() method from the built-in str class on a string object (start_text).
or
# Calling the upper() method for start_text (a string object).
I think this one works either way. Technically the __doc__ attribute is on the class, and the class is str. So it’s “of” or “from” (it isn’t an instance attribute). But I also feel like most readers would glaze or skip over the distinction.
Beyond that, things are looking good.
I updated the PR with everything we’ve discussed so far.
I enjoyed cooperating with you, and actually did an exercise on how to make (potentially ambiguous) technical detail clear and accessible.
2 Likes
The PR’s been approved and merged. Thank you for your contribution! 
2 Likes