diff --git a/concepts/basics/about.md b/concepts/basics/about.md index ef873ce418f..c5a77180cf5 100644 --- a/concepts/basics/about.md +++ b/concepts/basics/about.md @@ -68,8 +68,9 @@ For example, `my_first_variable` can be re-assigned many times using `=`, and ca >>> print(type(my_first_variable)) +>>> my_first_variable = 'You can call me "str".' # Strings can be declared using single or double quote marks. >>> print(my_first_variable) -"Now, I'm a string." # Strings can be declared using single or double quote marks. +You can call me "str". import collections >>> my_first_variable = collections.Counter([1,1,2,3,3,3,4,5,6,7]) # Now my_first_variable has been re-bound to a Counter object. @@ -77,7 +78,7 @@ import collections >>> print(my_first_variable) ->>> Counter({3: 3, 1: 2, 2: 1, 4: 1, 5: 1, 6: 1, 7: 1}) +Counter({3: 3, 1: 2, 2: 1, 4: 1, 5: 1, 6: 1, 7: 1}) ``` @@ -108,7 +109,7 @@ When functions are bound to a [class][classes] name, they're referred to as [met 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 `def` keyword begins a [function definition][function definition]. -Each function can have zero or more formal [parameters][parameters] in `()` parenthesis, followed by a `:` colon. +Each function can have zero or more formal [parameters][parameters] in `()` parentheses, followed by a `:` colon. Statements for the _body_ of the function begin on the line following `def` and must be _indented in a block_: @@ -144,7 +145,7 @@ def add_two_numbers(number_one, number_two): return number_one + number_two -# Calling the function in the Python terminal returns the sum of the numbers. +# Calling the function in the Python shell returns the sum of the numbers. >>> add_two_numbers(3, 4) 7 @@ -155,28 +156,42 @@ def add_two_numbers(number_one, number_two): 11 ``` -Functions that do not have an _explicit_ `return` expression will _implicitly_ return the [`None`][none] object. +Functions that do not have an _explicit_ expression following a `return` will _implicitly_ return the [`None`][none] object. The details of `None` will be covered in a later exercise. For the purposes of this exercise and explanation, `None` is a placeholder that represents nothing, or null: ```python -# This function does not have an explicit return. -def add_two_numbers(number_one, number_two): - result = number_one + number_two +# This function will return `None` +def square_a_number(number): + square = number * number + return # <-- note that this return is not followed by an expression -# Calling the function in the Python terminal appears +# Calling the function in the Python shell appears # to not return anything at all. ->>> add_two_numbers(5, 7) +>>> square_a_number(2) >>> # Using print() with the function call shows that # the function is actually returning the **None** object. ->>> print(add_two_numbers(5, 7)) +>>> print(square_a_number(2)) None +``` + +Functions that omit `return` will also _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. + +```python + +# This function omits a return keyword altogether +def add_two_numbers(number_one, number_two): + result = number_one + number_two +>>> add_two_numbers(5, 7) +>>> print(add_two_numbers(5, 7)) +None # Assigning the function call to a variable and printing # the variable will also show None. @@ -192,32 +207,32 @@ 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 +>>> def raise_to_power(number, power): + return number ** power ... ->>> number_to_the_power_of(3,3) # Invoking the function with the arguments 3 and 3. +>>> raise_to_power(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. ->>> number_to_the_power_of(4,) +>>> raise_to_power(4,) ... Traceback (most recent call last): File "", line 1, in -TypeError: number_to_the_power_of() missing 1 required positional argument: 'number_two' +TypeError: raise_to_power() missing 1 required positional argument: 'power' # Calling methods or functions in classes and modules. >>> start_text = "my silly sentence for examples." >>> str.upper(start_text) # Calling the upper() method for the built-in str class. -"MY SILLY SENTENCE FOR EXAMPLES." +'MY SILLY SENTENCE FOR EXAMPLES.' # Importing the math module import math >>> math.pow(2,4) # Calling the pow() function from the math module ->>> 16.0 +16.0 ``` @@ -273,32 +288,32 @@ Testing and `doctest` will be covered in a later concept. ```python # An example on a user-defined function. ->>> def number_to_the_power_of(number_one, number_two): +>>> def raise_to_power(number, power): """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 + :param number: int the base number. + :param power: int the power to raise the base number to. + :return: int - number raised to the specified power. - Takes number_one and raises it to the power of number_two, returning the result. + Takes a number and raises it to the specified power, returning the result. """ - return number_one ** number_two + return number ** power ... # Calling the .__doc__ attribute of the function and printing the result. ->>> print(number_to_the_power_of.__doc__) +>>> print(raise_to_power.__doc__) 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 + :param number: int the base number. + :param power: int the power to raise the base number to. + :return: int - number raised to the specified power. - Takes number_one and raises it to the power of number_two, returning the result. + Takes a number and raises it to the specified power, returning the result. -# Printing the __doc__ attribute for the built-in type: str. +# Printing the __doc__ attribute of the built-in type: str. >>> print(str.__doc__) str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str diff --git a/concepts/basics/introduction.md b/concepts/basics/introduction.md index 818dd47deac..d44e6c9fd07 100644 --- a/concepts/basics/introduction.md +++ b/concepts/basics/introduction.md @@ -38,8 +38,9 @@ A name can be reassigned (or re-bound) to different values (different object typ >>> print(type(my_first_variable)) +>>> my_first_variable = 'You can call me "str".' #<-- Strings can be declared using single or double quote marks. >>> print(my_first_variable) -"Now, I'm a string." # Strings can be declared using single or double quote marks. +You can call me "str". ``` @@ -54,7 +55,7 @@ Constants should be defined at a [module][module] (file) level, and are typicall ## Functions 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. +Each function can have zero or more formal [parameters][parameters] in `()` parentheses, followed by a `:` colon. Statements for the _body_ of the function begin on the line following `def` and must be _indented in a block_. @@ -90,7 +91,7 @@ def add_two_numbers(number_one, number_two): return number_one + number_two -# Calling the function in the Python terminal returns the sum of the numbers. +# Calling the function in the Python shell returns the sum of the numbers. >>> add_two_numbers(3, 4) 7 @@ -102,29 +103,42 @@ def add_two_numbers(number_one, number_two): ``` -Functions that do not have an _explicit_ `return` expression 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. +Functions that do not have an _explicit_ expression following a `return` will _implicitly_ return the [`None`][none] object. The details of `None` will be covered in a later exercise. For the purposes of this exercise and explanation, `None` is a placeholder that represents nothing, or null: ```python -# This function does not have an explicit return. -def add_two_numbers(number_one, number_two): - result = number_one + number_two +# This function will return `None` +def square_a_number(number): + square = number * number + return # <-- note that this return is not followed by an expression -# Calling the function in the Python terminal appears +# Calling the function in the Python shell appears # to not return anything at all. ->>> add_two_numbers(5, 7) +>>> square_a_number(2) >>> # Using print() with the function call shows that # the function is actually returning the **None** object. ->>> print(add_two_numbers(5, 7)) +>>> print(square_a_number(2)) None +``` + +Functions that omit `return` will also _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. +```python + +# This function omits a return keyword altogether +def add_two_numbers(number_one, number_two): + result = number_one + number_two + +>>> add_two_numbers(5, 7) +>>> print(add_two_numbers(5, 7)) +None # Assigning the function call to a variable and printing # the variable will also show None. diff --git a/exercises/concept/guidos-gorgeous-lasagna/.docs/introduction.md b/exercises/concept/guidos-gorgeous-lasagna/.docs/introduction.md index 20321da5303..303491d7f33 100644 --- a/exercises/concept/guidos-gorgeous-lasagna/.docs/introduction.md +++ b/exercises/concept/guidos-gorgeous-lasagna/.docs/introduction.md @@ -48,8 +48,9 @@ A name can be reassigned (or re-bound) to different values (different object typ >>> print(type(my_first_variable)) +>>> my_first_variable = 'You can call me "str".' #<-- Strings can be declared using single or double quote marks. >>> print(my_first_variable) -"Now, I'm a string." #<-- Strings can be declared using single or double quote marks. +You can call me "str". ``` @@ -63,7 +64,7 @@ Using `SCREAMING_SNAKE_CASE` signals that the name should not be re-assigned, or ## Functions 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. +Each function can have zero or more formal [parameters][parameters] in `()` parentheses, followed by a `:` colon. Statements for the _body_ of the function begin on the line following `def` and must be _indented in a block_. @@ -99,7 +100,7 @@ Functions _explicitly_ return a value or object via the [`return`][return] keywo return number_one + number_two -# Calling the function in the Python terminal returns the sum of the numbers. +# Calling the function in the Python shell returns the sum of the numbers. >>> add_two_numbers(3, 4) 7 @@ -111,29 +112,42 @@ Functions _explicitly_ return a value or object via the [`return`][return] keywo ``` -Functions that do not have an _explicit_ `return` expression 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. +Functions that do not have an _explicit_ expression following a `return` will _implicitly_ return the [`None`][none] object. The details of `None` will be covered in a later exercise. For the purposes of this exercise and explanation, `None` is a placeholder that represents nothing, or null: ```python -# This function does not have an explicit return. -def add_two_numbers(number_one, number_two): - result = number_one + number_two +# This function will return `None` +def square_a_number(number): + square = number * number + return # <-- note that this return is not followed by an expression -# Calling the function in the Python terminal appears +# Calling the function in the Python shell appears # to not return anything at all. ->>> add_two_numbers(5, 7) +>>> square_a_number(2) >>> # Using print() with the function call shows that # the function is actually returning the **None** object. ->>> print(add_two_numbers(5, 7)) +>>> print(square_a_number(2)) None +``` + +Functions that omit `return` will also _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. +```python + +# This function omits a return keyword altogether +def add_two_numbers(number_one, number_two): + result = number_one + number_two + +>>> add_two_numbers(5, 7) +>>> print(add_two_numbers(5, 7)) +None # Assigning the function call to a variable and printing # the variable will also show None. @@ -149,32 +163,32 @@ 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 +>>> def raise_to_power(number, power): + return number ** power ... ->>> number_to_the_power_of(3,3) # Invoking the function with the arguments 3 and 3. +>>> raise_to_power(3,3) # Invoking the function with the arguments 3 and 3. 27 # A mismatch between the number of parameters and the number of arguments will raise an error. ->>> number_to_the_power_of(4,) +>>> raise_to_power(4,) ... Traceback (most recent call last): File "", line 1, in -TypeError: number_to_the_power_of() missing 1 required positional argument: 'number_two' +TypeError: raise_to_power() missing 1 required positional argument: 'power' # Calling methods or functions in classes and modules. >>> start_text = "my silly sentence for examples." >>> str.upper(start_text) # Calling the upper() method for the built-in str class. -"MY SILLY SENTENCE FOR EXAMPLES." +'MY SILLY SENTENCE FOR EXAMPLES.' # Importing the math module import math >>> math.pow(2,4) # Calling the pow() function from the math module ->>> 16.0 +16.0 ``` @@ -216,28 +230,28 @@ Docstrings can also function as [lightweight unit tests][doctests], which will b ```python # An example on a user-defined function. ->>> def number_to_the_power_of(number_one, number_two): +>>> def raise_to_power(number, power): """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 + :param number: int the base number. + :param power: int the power to raise the base number to. + :return: int - number raised to the specified power. - Takes number_one and raises it to the power of number_two, returning the result. + Takes a number and raises it to the specified power, returning the result. """ - return number_one ** number_two + return number ** power ... # Calling the .__doc__ attribute of the function and printing the result. ->>> print(number_to_the_power_of.__doc__) +>>> print(raise_to_power.__doc__) 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 + :param number: int the base number. + :param power: int the power to raise the base number to. + :return: int - number raised to the specified power. - Takes number_one and raises it to the power of number_two, returning the result. + Takes a number and raises it to the specified power, returning the result. ``` [calls]: https://docs.python.org/3/reference/expressions.html#calls