And yet more edits to this exercise and concept.

Author: BethanyG

concepts/basics/about.md

@@ -2,13 +2,10 @@
 
 Python is a [dynamic and strongly][dynamic typing in python] typed [object-oriented][object oriented programming] programming language.
 It employs both [duck typing][duck typing] and [gradual typing][gradual typing], via [type hints][type hints].
-Imperative, declarative (e.g., functional), and object-oriented programming _styles_ are all supported, but internally [everything in Python is an object][everythings an object].
+Imperative, declarative (e.g., functional), and object-oriented programming _styles_ are all supported, but internally **[everything in Python is an object][everythings an object]**.
 
 Python puts a strong emphasis on code readability and (_similar to Haskell_) uses [significant indentation][significant indentation] to denote function, method, and class definitions.
 
-
-The [zen of Python (PEP 20)][the zen of python] and [What is Pythonic?][what is pythonic] lay out additional philosophies
-
 Python was created by Guido van Rossum and first released in 1991. The [Python Software Foundation][psf] manages and directs resources for Python and CPython development and receives proposals for changes to the language from [members][psf membership] of the community via [Python Enhancement Proposals or PEPs][peps].
 
 
@@ -21,59 +18,77 @@ Complete documentation for the current release can be found at [docs.python.org]
 - [Python FAQs][python faqs]
 - [Python Glossary of Terms][python glossary of terms]
 
+
 This concept introduces 4 major Python language features: Name Assignment (_variables and constants_), Functions (_and the return keyword_), Comments, and Docstrings.
 
 
 ~~~~exercism/note
 
 In general, content, tests, and analyzer tooling for the Python track follow the style conventions outlined in [PEP 8](https://www.python.org/dev/peps/pep-0008/) and [PEP 257](https://www.python.org/dev/peps/pep-0257/) for Python code style, with the additional (strong) suggestion that there be no single letter variable names.
 
-~~~~
+The [zen of Python (PEP 20)][the zen of python] and [What is Pythonic?][what is pythonic] lay out additional philosophies.
+
+On the Python track, [variables][variables] are always written in [`snake_case`][snake case], and constants in `SCREAMING_SNAKE_CASE`
 
 
-## Name Assignment and Re-assignment
+[snake case]: https://en.wikipedia.org/wiki/Snake_case
+[variables]: https://realpython.com/python-variables/
+[what is pythonic]: https://blog.startifact.com/posts/older/what-is-pythonic.html
+[the zen of python]: https://www.python.org/dev/peps/pep-0020/
+~~~~
 
-In Python, there are no keywords to define variables or constants.
-Both are [_names_][facts-and-myths-about-python-names] that help programmers reference values (_objects_) in a program and are written differently only by convention.
-On Exercism, [variables][variables] are always written in [`snake_case`][snake case], and _constants_ in `SCREAMING_SNAKE_CASE`.
 
-Names are assigned to values using `=`, or the [_assignment operator_][assignment statements] (`<name> = <value>`).
-A name (_variable or constant_) can be re-assigned over its lifetime to different values/object types.
+## Name Assignment (Variables & Constants)
+
+In Python, there are no keywords used in creating variables or constants.
+Instead, programmer defined [_names_][facts-and-myths-about-python-names] (also called _variables__) can be bound to any type of object using the assignment `=` operator: `<name> = <value>`.
+A name can be reassigned (or re-bound) to different values (different object types) over its lifetime.
 
 For example, `my_first_variable` can be re-assigned many times using `=`, and can refer to different object types with each re-assignment:
 
+
 ```python
-# Assigning my_first_variable to a numeric value.
->>> my_first_variable = 1
+>>> my_first_variable = 1  # Name bound to an integer object of value one.
+>>> my_first_variable = 2  # Name re-assigned to integer value 2.
+
 >>> print(type(my_first_variable))
 <class 'int'>
 
 >>> print(my_first_variable)
-1
+2
 
-# Reassigning my_first_variable to a new string value.
->>> my_first_variable = "Now, I'm a string."
+>>> my_first_variable = "Now, I'm a string." # You may re-bind a name to a different object type and value.
 >>> print(type(my_first_variable))
 <class 'str'>
 
 >>> print(my_first_variable)
-"Now, I'm a string."
+"Now, I'm a string."  # Strings can be declared using single or double quote marks.
+
+import collections
+>>> my_first_variable = collections.Counter([1,1,2,3,3,3,4,5,6,7])
+>>> print(type(my_first_variable))
+<class 'collections.Counter'>
+
+>>> print(my_first_variable)
+>>> Counter({3: 3, 1: 2, 2: 1, 4: 1, 5: 1, 6: 1, 7: 1})
 ```
 
 
 ### Constants
 
-Constants are typically defined at a [module][module] level, being values that are accessible outside function or class scope.
-Constant names **_can be reassigned to new values_**, but they are _intended_ to be named only once.
-Using `SCREAMING_SNAKE_CASE` warns other programmers that these names should not be mutated or reassigned.
+Constants are names meant to be assigned only once in a program.
+They should be defined at a [module][module] (file) level, and are typically visible to all functions and classes in the program.
+Using `SCREAMING_SNAKE_CASE` signals that the name should not be re-assigned, or its value mutated.
+
 
 ```python
 # All caps signal that this is intended as a constant.
 MY_FIRST_CONSTANT = 16
 
 # Re-assignment will be allowed by the compiler & interpreter,
 # but this is VERY strongly discouraged.
-# Please don't: MY_FIRST_CONSTANT = "Some other value"
+# Please don't do this, it could create problems in your program!
+MY_FIRST_CONSTANT = "Some other value"
 ```
 
 
@@ -85,49 +100,45 @@ Functions can be executed by themselves, passed as arguments to other functions,
 When functions are bound to a [class][classes] name, they're referred to as [methods][method objects].
 Related functions and classes (_with their methods_) can be grouped together in the same file or module, and imported in part or in whole for use in other programs.
 
-The keyword `def` begins a [function definition][function definition].
-It must be followed by the function name and a parenthesized list of zero or more formal [parameters][parameters].
-Parameters can be of several different varieties, and can even [vary][more on functions] in length.
-
-The `def` line is terminated with a colon (`:`):
-
-```python
-# Function definition.
-def my_function_name(parameter, second_parameter):
-    <function body>
-
-```
-
-Statements for the `function body` begin on the line following `def` and must be _indented in a block_.
-There is no strict indentation amount (_either space **OR** [tab] characters are acceptable_), but [indentation][indentation] must be _consistent_ for all indented statements.
+The `def` keyword begins a [function definition][function definition].
+Each function can have zero or more formal [parameters][parameters] in `()` parenthesis, followed by a `:` colon.
+Statements for the _body_ of the function begin on the line following `def` and must be _indented in a block_.
 
 
 ```python
-# Function definition on first line.
+# The body of this function is indented by 2 spaces, & prints the sum of the numbers
 def add_two_numbers(number_one, number_two):
-  print(number_one + number_two)  # Prints the sum of the numbers, and is indented by 2 spaces.
+  total = number_one + number_two
+  print(total)  
 
 >>> add_two_numbers(3, 4)
 7
-```
 
 
+# Inconsistent indentation in your code blocks will raise an error.
+>>> def add_three_numbers_misformatted(number_one, number_two, number_three):
+...     result = number_one + number_two + number_three   # This was indented by 4 spaces.
+...    print(result)     #this was only indented by 3 spaces
+...
+...
+  File "<stdin>", line 3
+    print(result)
+    ^
+IndentationError: unindent does not match any outer indentation level
+```
+
 Functions explicitly return a value or object via the [`return`][return] keyword.
+Functions that do not have an explicit `return` expression will _implicitly_ return [`None`][none].
 
 ```python
 # Function definition on first line.
 def add_two_numbers(number_one, number_two):
-  return number_one + number_two  # Returns the sum of the numbers.
+  result = number_one + number_two
+  return result  # Returns the sum of the numbers.
 
 >>> add_two_numbers(3, 4)
 7
-```
-
-
-
-Functions that do not have an explicit `return` expression will return [`None`][none].
 
-```python
 # This function will return None.
 def add_two_numbers(number_one, number_two):
   result = number_one + number_two
@@ -136,98 +147,39 @@ def add_two_numbers(number_one, number_two):
 None
 ```
 
-While you may choose any indentation depth, _inconsistent_ indentation in your code blocks will raise an error:
-
-```python
-# The return statement line does not match the first line indent.
->>> def add_three_numbers_misformatted(number_one, number_two, number_three):
-...     result = number_one + number_two + number_three   # Indented by 4 spaces.
-...    return result     #this was only indented by 3 spaces
-...
-...
-  File "<stdin>", line 3
-    return result
-                ^
-IndentationError: unindent does not match any outer indentation level
-```
-
 
 ### Calling Functions
 
-Functions are [_called_][calls] using their name followed by `()`.
-The number of arguments passed in the parentheses must match the number of parameters in the original function definition unless [default arguments][default arguments] have been used.
+Functions are [_called_][calls] or invoked using their name followed by `()`.
+Dot (`.`) notation is used for calling functions defined inside a class or module.
 
 ```python
 >>> def number_to_the_power_of(number_one, number_two):
         return number_one ** number_two
 ...
 
->>> number_to_the_power_of(3,3)
+>>> number_to_the_power_of(3,3) # Invoking the function with the arguments 3 and 3.
 27
-```
-
 
-A mis-match between the number of parameters and the number of arguments will raise an error:
 
-```python
+# A mis-match between the number of parameters and the number of arguments will raise an error.
 >>> number_to_the_power_of(4,)
 ...
 Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
 TypeError: number_to_the_power_of() missing 1 required positional argument: 'number_two'
 
-```
-
 
-Adding a [default value][default arguments] for a parameter can defend against such errors:
-
-```python
-# Note the default value of 2 assigned below.
-def number_to_the_power_of_default(number_one, number_two=2):
-    """Raise a number to an arbitrary power.
-    
-    :param number_one: int the base number.
-    :param number_two: int the power to raise the base number to.
-    :return: int - number raised to power of second number
-    
-    Takes number_one and raises it to the power of number_two, returning the result.
-    """
-
-    return number_one ** number_two
-
-# Because there was a default value, this call with only one argument does not throw an error.
->>> number_to_the_power_of_default(4)
-16
-```
-
-
-Methods bound to class names are invoked via dot notation (`<class name>.<method name>(<parameters>))`, as are functions (`<module name>.<function name>(<parameters>)`), constants (`<module name>.<constant name>`), or any other global names imported as part of a module.:
-
-```python
-# This is an example of a method call of the built in str class.
-# Define a variable and assign it to a string.
+# Calling methods or functions in classes and modules.
 >>> start_text = "my silly sentence for examples."
-
-# Uppercase the string by calling the upper method from the str class.
->>> str.upper(start_text)
+>>> str.upper(start_text)  # Calling the upper() method for the built-in str class.
 "MY SILLY SENTENCE FOR EXAMPLES."
 
+# Importing the math module
+import math
 
-# Below is an example of a method call of the built in list class.
-# Define an empty list
->>> my_list = []
-
-# Add an element to the list by calling the append method from the list class.
->>> my_list.append(start_text)
->>> print(my_list)
-["my silly sentence for examples."]
-
-import string
-
-# This is a constant provided by the *string* module.
->>> alphabet = string.ascii_lowercase
->>> print(alphabet)
-"abcdefghijklmnopqrstuvwxyz"
+>>> math.pow(2,4)  # Calling the pow() function from the math module
+>>> 16.0
 ```
 
 
@@ -323,11 +275,9 @@ errors defaults to 'strict'.
 ```
 
 [PEP257]: https://www.python.org/dev/peps/pep-0257/
-[assignment statements]: https://docs.python.org/3/reference/simple_stmts.html#assignment-statements
 [calls]: https://docs.python.org/3/reference/expressions.html#calls
 [classes]: https://docs.python.org/3/reference/datamodel.html#classes
 [comments]: https://realpython.com/python-comments-guide/#python-commenting-basics
-[default arguments]: https://docs.python.org/3/tutorial/controlflow.html#default-argument-values
 [docstring]: https://docs.python.org/3/tutorial/controlflow.html#tut-docstrings
 [doctests]: https://docs.python.org/3/library/doctest.html
 [duck typing]: https://en.wikipedia.org/wiki/Duck_typing
@@ -337,10 +287,8 @@ errors defaults to 'strict'.
 [function definition]: https://docs.python.org/3/tutorial/controlflow.html#defining-functions
 [functions]: https://docs.python.org/3/reference/compound_stmts.html#function
 [gradual typing]: https://en.wikipedia.org/wiki/Gradual_typing
-[indentation]: https://docs.python.org/3/reference/lexical_analysis.html#indentation
 [method objects]: https://docs.python.org/3/c-api/method.html#method-objects
 [module]: https://docs.python.org/3/tutorial/modules.html
-[more on functions]: https://docs.python.org/3/tutorial/controlflow.html#more-on-defining-functions
 [none]: https://docs.python.org/3/library/constants.html
 [object oriented programming]: https://en.wikipedia.org/wiki/Object-oriented_programming
 [objects]: https://docs.python.org/3/reference/datamodel.html#the-standard-type-hierarchy
@@ -357,9 +305,5 @@ errors defaults to 'strict'.
 [python tutorial]: https://docs.python.org/3/tutorial/index.html
 [return]: https://docs.python.org/3/reference/simple_stmts.html#return
 [significant indentation]: https://docs.python.org/3/reference/lexical_analysis.html#indentation
-[snake case]: https://en.wikipedia.org/wiki/Snake_case
-[the zen of python]: https://www.python.org/dev/peps/pep-0020/
 [turtles all the way down]: https://en.wikipedia.org/wiki/Turtles_all_the_way_down
 [type hints]: https://docs.python.org/3/library/typing.html
-[variables]: https://realpython.com/python-variables/
-[what is pythonic]: https://blog.startifact.com/posts/older/what-is-pythonic.html