Python Language Functions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search

Internal

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. 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.

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"

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')

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"

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))

Built-in Functions

These functions exist in the built-in namespace

Built-in functions:

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

Built-in Type Conversion Functions

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

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)