Functions and scope¶

Functions¶

A function is a named block of code that performs one task. Define it once, then call it as many times as you need.

# function definition
def greet():
    # function body
    print("Hello World!")

# function call
greet()

• def creates the function.
• The name is followed by parentheses ().
• The indented lines below are the function body.
• Nothing runs until you call the function.

Arguments¶

Arguments are inputs to a function. You list them inside the parentheses, and the body can use them like normal variables.

def square_number(number):
    return number ** 2

squared_number = square_number(2)
print(squared_number)   # 4

return sends a value back to whoever called the function. Once return runs, the function stops.

A function without return still does its work, but gives back None.

Functions can take several arguments:

def clamp(value, low, high):
    if value > high:
        return high
    if value < low:
        return low
    return value

print(clamp(150, -100, 100))   # 100
print(clamp(-150, -100, 100))  # -100
print(clamp(40, -100, 100))    # 40

Reaching a return ends the function, so at most one of the three runs.

You do not need clamp() for thruster commands. MARLIN already pins those to range for you. It is shown here because clamping a number to a range is a common shape, and because writing it out is a clear way to see several returns in one function.

Libraries¶

A library is a collection of code someone else has already written. Import it with import, then call its functions.

import math

result = math.pow(2, 3)   # 2 to the power of 3
print(result)             # 8.0

Python ships with over 200 built-in libraries, so check whether one already solves your problem before writing it yourself.

You can also import only the parts you need:

from marlin import Robot, Thruster

marlin is the library that controls your robot. It is bundled with the VS Code extension, so there is nothing to install. See the MARLIN API guide.

Full documentation: https://docs.python.org/3/tutorial/modules.html

Variable scope¶

Scope decides where a variable can be used. Python has two you need to know:

number = 2   # global variable

def cube_number(num):
    power = 3          # local variable
    return num ** power

cubed_number = cube_number(number)   # global variable
print(cubed_number)                  # 8

power only exists inside cube_number(). Using it outside the function is an error.

number = 2
power = 2

def cube_number(num):
    power = 3
    return num ** power

cubed_number = cube_number(number)
print(power, cubed_number)

2 8

Full documentation: https://docs.python.org/3/tutorial/controlflow.html#defining-functions

What to read next¶

Classes: how to group data and functions into objects.