# Introduction Python is a [dynamic and strongly][dynamic typing in python] typed programming language. It employs both [duck typing][duck typing] and [gradual typing][gradual typing] via [type hints][type hints]. While Python supports many different programming _styles_, internally **everything in Python is an [object][everythings an object]**. This includes numbers, strings, lists, and even functions. We'll dig more into what all of that means as we continue through the track. This first exercise introduces 4 major Python language features: 1. Name Assignment (_variables and constants_), 2. Functions (_the `def` keyword and the `return` keyword_), 3. Comments, and 4. 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 or variables named ["_"][uses of _ in Python]. On the Python track, [variables][variables] are always written in [`snake_case`][snake case], and constants in `SCREAMING_SNAKE_CASE`. [variables]: https://realpython.com/python-variables/ [snake case]: https://en.wikipedia.org/wiki/Snake_case [uses of _ in Python]: https://medium.com/better-programming/how-to-use-underscore-properly-in-python-37df5e05ba4c ~~~~
## Name Assignment (Variables & Constants) Programmers can bind [_names_][facts-and-myths-about-python-names] (also called _variables_) to any type of object using the assignment `=` operator: ` = `. A name can be reassigned (or re-bound) to different values (different object types) over its lifetime. ```python >>> my_first_variable = 1 #<-- my_first_variable bound to an integer object of value one. >>> my_first_variable = 2 #<-- my_first_variable re-assigned to integer value 2. >>> print(type(my_first_variable)) >>> print(my_first_variable) 2 >>> 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)) >>> my_first_variable = 'You can call me "str".' #<-- Strings can be declared using single or double quote marks. >>> print(my_first_variable) You can call me "str". ``` ### Constants 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. ## Functions The `def` keyword begins a [function definition][function definition]. 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_. ```python # The body of a function is indented by 2 spaces, & prints the sum of the numbers. def add_two_numbers(number_one, number_two): 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 "", 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: ```python # Function definition on first line, explicit return used on final line. >>> def add_two_numbers(number_one, number_two): return number_one + number_two # Calling the function in the Python shell returns the sum of the numbers. >>> add_two_numbers(3, 4) 7 # Assigning the function call to a variable and printing it # will also return the value. >>> sum_with_return = add_two_numbers(5, 6) >>> print(sum_with_return) 11 ``` 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 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 shell appears # to not return anything at all. >>> square_a_number(2) >>> # Using print() with the function call shows that # the function is actually returning the **None** object. >>> 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. >>> sum_without_return = add_two_numbers(5, 6) >>> print(sum_without_return) None ``` ### Calling Functions 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 raise_to_power(number, power): ... return number ** power ... >>> 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. >>> raise_to_power(4,) ... Traceback (most recent call last): File "", line 1, in 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 from the built-in str class on start_text. '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 ``` ## Comments [Comments][comments] in Python start with a `#` that is not part of a string, and end at line termination. Unlike many other programming languages, Python **does not support** multi-line comment marks. Each line of a comment block must start with the `#` character. ## Docstrings The first statement of a function body can optionally be a [_docstring_][docstring], which concisely summarizes the function or object's purpose. Docstrings are declared using triple double quotes (""") indented at the same level as the code block: ```python # An example from PEP257 of a multi-line docstring # reformatted to use Google style non-type hinted docstrings. # Some additional details can be found in the Sphinx documentation: # https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#getting-started def complex(real=0.0, imag=0.0): """Form a complex number. Keyword Arguments: real (float): The real part of the number (default 0.0) imag (float): The imaginary part of the number (default 0.0) """ if imag == 0.0 and real == 0.0: return complex_zero ``` Docstrings are read by automated documentation tools such as [Sphinx][sphinx] and are returned by calling the special attribute `.__doc__` on the function, method, or class name. General docstring conventions are laid out in [PEP257][pep257], but exact formats will vary by project and team. Exercism concept exercises try to follow the Google style for un-type hinted code. Docstrings can also function as [lightweight unit tests][doctests], which will be covered in a later exercise. ```python # An example on a user-defined function using a Google style docstring. >>> def raise_to_power(number, power): """Raise a number to an arbitrary power. Parameters: number (int): The base number. power (int): The power to raise the base number to. Returns: int: The number raised to the specified power. Takes a number and raises it to the specified power, returning the result. """ return number ** power ... # Calling the .__doc__ attribute of the function and printing the result. >>> print(raise_to_power.__doc__) Raise a number to an arbitrary power. Parameters: number (int): The base number. power (int): The power to raise the base number to. Returns: int: The number raised to the specified power. Takes a number and raises it to the specified power, returning the result. ``` [calls]: https://docs.python.org/3/reference/expressions.html#calls [comments]: https://realpython.com/python-comments-guide/#python-commenting-basics [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 [dynamic typing in python]: https://stackoverflow.com/questions/11328920/is-python-strongly-typed [everythings an object]: https://docs.python.org/3/reference/datamodel.html [facts-and-myths-about-python-names]: https://nedbatchelder.com/text/names.html [function definition]: https://docs.python.org/3/tutorial/controlflow.html#defining-functions [gradual typing]: https://en.wikipedia.org/wiki/Gradual_typing [module]: https://docs.python.org/3/tutorial/modules.html [none]: https://docs.python.org/3/library/constants.html [parameters]: https://docs.python.org/3/glossary.html#term-parameter [pep257]: https://www.python.org/dev/peps/pep-0257/ [return]: https://docs.python.org/3/reference/simple_stmts.html#return [sphinx]: https://www.sphinx-doc.org/en/master/usage/index.html [type hints]: https://docs.python.org/3/library/typing.html