Python Language Functions

Internal

• Python Language
• Java Method Parameters and Arguments

TODO

• TO PROCESS PyOOP "Extending built-in functions" + "Case study"
• TO PROCESS PyOOP "An alternative to method overloading" + "Default arguments" + "Variable argument list" + "Unpacking arguments"
• TO PROCESS PyOOP "Functions are objects too"

Overview

A function is a named or unnamed piece of code, which takes any number and type of input parameters and returns any number and type of output results. When a function returns more than one return value, it does that by packaging all the return values in a tuple. The function is first defined, then invoked, or called. As pretty much everything else, functions are objects, and they are "first-class citizens", in that they can be assigned to variables, used as arguments, and return them from other functions.

def f():
  pass

print(type(f))

will display:

<class 'function'>

Each function define its own namespace: variables defined inside a function are distinct from the variables with the same name defined in the main program.

Check whether an Object Instance is a Function

import types

def f():
    pass

assert isinstance(f, types.FunctionType)

Another way:

def f():
    pass

assert callable(f)

Function Definition

A function is defined by the reserved word def, followed by the function name, parentheses enclosing input parameters and a colon:

def function_name([parameters]):
  <function body>

def function_name(par1, par2, par3):
  <function body>

Two blank lines are expected after a function definition.

def add(a, b):
  c = a + b
  return c


print(add(1, 2))

Function Name Rules

The function name rules for function names is the same as for variable names.

Function Parameters

A parameter is a variable name used in the function definition. Each parameter translates to a variable private to the function. The parameters are handles for arguments for a particular function invocation.

A function can have positional parameters and keyword parameters. All positional arguments must be specified when calling the function. Keyword parameters are optional and are most commonly used to specify default values or optional parameters.

When invoked, the keyword arguments must follow the positional arguments, if any. Keyword arguments can be specified in any order, it does not need to match the order in which the corresponding keyword parameters have been declared.

Parameters are optional, a function may have no parameters. However, once a parameter is individually specified in the function definition, and that parameter does not have a default parameter value, a corresponding positional argument must be provided when the function is invoked, otherwise the invocation fails with:

TypeError: my_function() missing 1 required positional argument: 'arg1'

The function can be invoked with a variable number of arguments if the positional arguments are gathered with * or the keyword arguments are gathered with ** in the function definition, or both.

Also see:

Variables, Parameters, Arguments

Default Parameter Values

Default values can be declared for function parameters. The declared default value is used if the caller does not provide the corresponding argument. Naturally, if an argument is provided, it is used instead of the default value.

def make_item(name, color='green', size=1):
    return f"made {color} {name} in size {size}"

assert make_item("hat", "red") == "made red hat in size 1"

⚠️Default argument values are initialized when the function is defined, not when it is invoked. The default argument values are part of the function state, which is initialized only once when it is defined. This behavior is exemplified in the following example:

def m(arg, result=[]):
    result.append(arg)
    print(result)

m(1) # will display [1]
m(2) # will display [1, 2], the state of the list is preserved between the invocation  and is not reset on invocation.

Function Parameter Type Hints

https://docs.python.org/3/library/typing.html#module-typing

https://typing.readthedocs.io/en/latest/

Since 3.5, Python has support for type hints, which can be applied to both function parameters and return values. The Python runtime does not enforce function and variable type annotations. However, they can be used by third party tools such as type checkers, IDEs, linters, etc. This is a function whose parameter and return has type hints.

def some_func(arg: str) -> str:
  return "hello " + arg

def some_other_func(x: str | int) -> None:
  ...

Function Parameter Type Hinds and Default Values

def some_func(par1: str = 'blue') -> str:
    return par1.upper()

assert some_func() == "BLUE"

Spaces around '=' are expected. While the form without spaces is syntactically valid, it will be singled out as a weak warning "PEP 8: E252 missing whitespace around parameter equals".

def some_func(par1: str='blue') -> str: # PEP 8: E252 missing whitespace around parameter equals
    ...

Function Body

The body needs to be indented. It includes statements, an optional docstring and an optional return statement.

Docstring

https://www.python.org/dev/peps/pep-0257/

A docstring is a string declared at the beginning of the function body that serves as function documentation. Upon declaration, the string value is assigned to the __doc__ internal variable within the function instance. The string can be a one-line or multi-line and declared between single-quotes, double-quotes or triple quotes. The recommended style is to use triple double-quoted strings as docstrings. TO PROCESS: https://www.python.org/dev/peps/pep-0257/

def m(color='green'):
    """
    m() builds a widget of the given color.
    It gets the color and reports what it is going to build.
    I'll do so by:
        1. Reporting the color
        2. Building the widget

    Keyword arguments:
    color              -- the color (default green)
    size               -- the size (default 1)
    
    :return: the widget
    """
    print(f"I will build a {color} widget")

def m(color='green'):
    """
    This is what the function does.
    :param color: this is the color
    :return: the widget
    """
    print(f"I will build a {color} widget")

The function's docstring can be printed with the help() function, by passing the function name as argument. The output will be formatted.

help(m)

To print the raw docstring:

print(m.__doc__)

Return Value

The return statement, which is introduced by the return reserved word, ends the function execution and sends back the output result of the function.

def ...
  ...
  return optional_return_value

The compiler will not prevent to declare other statements after the return statement, they be never executed, though. If the function body does not contain a return statement, it will return None.

Returning Multiple Values

A function actually returns just one object, a tuple, which is then being unpacked into the result variables.

def shades(color):
  return 'dark ' + color, 'light ' + color, 'transparent ' + color


a, b, c = shades('red')

assert 'dark red' == a
assert 'light red' == b
assert 'transparent red' == c

Return Value Type Hints

https://docs.python.org/3/library/typing.html#module-typing

Since 3.5, Python has support for type hints, which can be applied to both function parameters and return values:

def some_func(par1: str) -> str:
    return par1.upper()

def some_other_func(x: str) -> int | None:
   ...

For more details on type hints, see Function Parameter Type Hints above.

Style

Exactly 2 blank lines are expected after a function definition. Also see:

Python Style

Function Invocation

A function is invoked by prepending parantheses to the name of the function and specifying arguments between parentheses. With no parentheses, Python treats the function like any other object.

Function Arguments

When the function is invoked, we pass an argument for each parameter declared in the function definition. An argument is a value that is passed into the function as function's input. When the function is called with arguments, the values of those argument are copied to their corresponding parameters inside the function. The argument can be another variable, defined in the block that invokes the function. Arguments are passed in parentheses and they are separated by commas. If the function has no parameters, we pass no arguments, but the parentheses still need to be provided.

function_name(arguments)

function_name(arg1, arg2, arg3)

Python is unusually flexible in the manner it handles function arguments. The most common option is to specify the arguments positionally. Another option is to use keyword arguments. Positional and keyword argument can be mixed, but in this case the positional arguments need to come first.

Also see:

Variables, Parameters, Arguments

Positional Arguments

When passing the arguments positionally, they map in order on the declared positional parameters. Although very common, a downside of positional arguments is that you need to remember the meaning of each position.

def menu(appetizer, entree, dessert):
    print(f"Appetizer: {appetizer}, entree: {entree}, dessert: {dessert}")

menu('salad', 'chicken', 'cake')

Even if only positional parameters were declared in the function definition, the function can be invoked with keyword parameters in any order. For the above function declaration, the following invocation is valid:

menu(dessert='chocolate', entree='steak', appetizer='salad')

Gather Positional Arguments with *

An asterisk (*) preceding a function parameter declaration indicates that a variable number of positional arguments the function is invoked with are grouped together into a tuple of parameter values. It is a common idiom in Python to call to call the tuple parameter args:

def some_func(*args):
  print('tuple:', args)

some_func() # will display "tuple: ()"
some_func(1) # will display "tuple: (1,)"
some_func(1, 'A') # will display "tuple: (1, 'A')"

This is useful to declare function that accept one or more required parameters and then an arbitrary number of parameters:

def some_func(required1, required2, *args):
  ...

Keyword Arguments

Arguments can be specified by name, even in a different order from their definition in the function:

def menu(appetizer, entree, dessert):
    print(f"Appetizer: {appetizer}, entree: {entree}, dessert: {dessert}")

menu(dessert='cake', appetizer='salad', entree='chicken')

Repeating a keyword argument with the same key is a syntax error.

Invoking a function with an improperly formed keyword argument (ex: desert=) is a syntax error.

Invoking the function with an inexistent keyword argument causes:

TypeError: my_function() got an unexpected keyword argument 'some_argument'

Gather Keyword Arguments with **

Two asterisks (**) indicate that a variable number of keyword arguments the function is invoked with are grouped together into a dictionary where the argument names are the keys and their values are the corresponding dictionary values. It is a common idiom in Python to call to call the dictionary parameter kwargs:

def some_func(**kwargs):
  print('keyword args:', kwargs)

some_func() # will display "keyword args: {}"
some_func(color='red') # will display "keyword args: {'color': 'red'}"
some_func(color='red', size='small') # keyword args: {'color': 'red', 'size': 'small'}

This is useful to declare function that accept one or more required parameters and then an arbitrary number of positional parameters:

def some_func(required1, required2, **kwargs):
  ...

If positional parameters are mixed with *args and **kwargs, they need to occur in that order.

Pass by Value and Pass by Reference

Are "primitives" passed by value? A copy is made?

How about more complex data structures?

https://www.geeksforgeeks.org/pass-by-reference-vs-value-in-python/

ints are immutable, so you'll have to build your own class with all the int's methods if you want a "mutable int"

Also see:

Pass by Value vs. Pass by Reference vs. Pass by Pointer in Go

No Reference Variables in Go

Dynamic Invocation

Given access to the function or method instance, obtained via getattr() or inspect.getmembers(), the function can be invoked by providing the parantheses-enclosing arguments to the function or method instance directly.

TODO: This is a dynamic function invocation:

TODO

This is a static method invocation:

class SomeClass:
  @staticmethod
  def some_static_method(arg):
     ...

cls = ...
method = getattr(cls, 'some_static_method')
method('blue')

Applying a Function to an Iterable that Provides the Arguments

def darken(color):
  return "dark " + color

colors = ['red', 'blue', 'green', 'yellow']

for c in map(darken, colors):
  print(c)

Will print:

dark red
dark blue
dark green
dark yellow

Passing Functions as Arguments

def some_function():
    print('something')

def run_something(f):
    f()

run_something(some_function) # will display "something"

This is very useful for mock testing.

Also see dynamic invocation.

Inner Functions

A function can be defined within other function. Inner functions could be useful when performing some complex tax more than once within another function, to avoid loops and code duplication.

def outer(a, b):
    def inner(c, d):
        return c + d
    return inner(a, b)

print(outer(1, 2))

Closures

An inner function can act as a closure. A closure is a function that is dynamically generated by another function and can both change and remember the values of variables that were created outside itself.

def some_func(arg):
    # we define a closure, which is a function and remembers the argument of the enclosing function
    def closure():
        return f"we remember {arg}"
    return closure

a = some_func("A")  # we create a closure that remembers "A"
b = some_func("B")  # we create a closure that remembers "B"

print(a())  # Will display "we remember A"
print(b())  # Will display "we remember B"

Anonymous Functions (Lambdas)

A lambda is an anonymous function expressed a a single statement. It can be used instead of a normal tiny function, by avoiding declaring the function and instead in-lining the behavior. Lambdas are also callable.

lambda <arg>: <one-line-statement>

Lambda takes one argument. Does lambda always takes just one argument? Everything between the colon and the terminating parentheses, or other separator in the invoking statement is the definition of the function.

The following example demonstrates the equivalency between a regular function and a lambda:

def regular_function(s):
    return s.capitalize()

def user_of_function(words, f):
    for w in words:
        print(f(w))

data = ['a', 'b', 'c']
user_of_function(data, regular_function)  # this statement uses a regular function
user_of_function(data, lambda w: w.capitalize())  # this statement uses an equivalent lambda, to the same effect

A lambda may call a regular, multi-line function, previously defined. With the above example, the lambda calls the named function instead of implementing the behavior itself:

user_of_function(data, lambda w: regular_function(w))

Lambda functions are especially convenient in data analysis because there are many cases where data transformation functions will take functions as arguments. It is often less typing, and clearer, to pass a lambda function as opposed to writing a full-out function declaration or even assigning the lambda function to a local variable.

Built-in Functions

These functions exist in the built-in namespace

Built-in functions:

• abs():
• any():
• all():
• ascii():
• bin():
• bool():
• bytearray():
• bytes():
• callable():
• chr():
• compile():
• classmethod():
• complex():
• delattr():
• dict():
• dir(): Return the list of names in the specified namespace
• enumerate(): Access the Index and the Element at the Same Time. enumerate() can be used with any collection.
• eval():
• exec():
• filter():
• format():
• frozenset()
• getattr()
• globals()
• hasattr()
• help(): Display a function's docstring.
• hash()
• input(): Instructs Python to pause and read data from stdin. input() returns a string.

s = input('this is the prompt')
print(s)

• id()
• isinstance()
• issubclass()
• iter(): Creates an iterator instance, see Python Iterators.
• list(): Converts a sequence to a list. See Convert a String to List.
• locals()
• len(): See the length of a string. TO PROCESS PyOOP "The len() function"
• map(): Applying a Function to an Iterable that Provides the Arguments
• next(): Returns the next item in an iterator, see Python Iterators.
• memoryview():
• object():
• oct():
• open(): See File Operations in Python | The open() Built-in.
• ord():
• pow():
• print(): See Printing to stdout in Python
• property()
• range()
• repr():
• reversed(): Iterate over a List in Reversed Order. reversed() is a generator, it does not create the reversed sequence until materialized.
• round():
• set(): Creates a set.
• setattr():
• slice():
• sorted()
• sum():
• staticmethod():
• tuple():
• type(): Returns the type of the argument.
• vars():
• zip(): Create a map from a key sequence and a value sequence
• __import__()
• super():

Built-in Type Conversion (Casting) Functions

• str():
• int():
• float():
• bool():

Built-in Math Functions

• divmod():
• max():
• min():

Callable

TO PROCESS: https://medium.com/swlh/callables-in-python-how-to-make-custom-instance-objects-callable-too-516d6eaf0c8d

Call Stack

Frame

The frame is represented internally as a FrameInfo, which has a code context array.

Also see:

Python Introspection | Introspecting the Calls Stack

Organizatorium

• Document this invocation mode:

options = {
    "api_key": "<YOUR_API_KEY>",
    "app_key": "<YOUR_APP_KEY>",
}
initialize(**options)