CPX20Subprograms, Scope and Library Modules

Pearson's definition: a subprogram is a distinct, named block of code, with its own scope, that performs a specific task and is called from other code.

• Pre-existing subprograms were written by someone else. You just call them by name.
• Built-in subprograms are always there, with no import: print, input, len, int, float, str, bool, round, range, ord and chr.
• Library modules are collections of subprograms that must be imported first. The PLS uses four: random, math, time and turtle.
• Import at the top of the file, under the # Import libraries banner. Then put the library name, a dot and the subprogram: random.randint (1, 6), math.sqrt (49).
• String and list subprograms are pre-existing too. They are called on a value: name.upper (), scores.append (7).
• User-devised subprograms are the ones you write yourself with def: procedures and functions.
• Built-in and library subprograms in action:

  # -------------------------------------------------------------------
  # Import libraries
  # -------------------------------------------------------------------
  import math
  
  # -------------------------------------------------------------------
  # Main program
  # -------------------------------------------------------------------
  area = float (input ("Area of the square lawn in square metres: "))
  side = math.sqrt (area)                       # library subprogram
  print ("Each side is", round (side, 2), "m")  # built-in subprograms

• With an input of 20, this displays Each side is 4.47 m.

Subprogram

A distinct, named block of code, with its own scope, that performs a specific task and is called from other code.

Built-in subprogram

A subprogram that is part of Python and can be called without importing anything, such as len () or print ().

Library module

A collection of pre-written subprograms that must be imported before use, such as random or math.

User-devised subprogram

A procedure or function written by the programmer.

A procedure is a subprogram that does not return a value. It may or may not take parameters.

• Define it with def, a name, brackets and a colon. The body is indented. Pearson leaves a space before the brackets: def showMenu ():.
• Defining a procedure doesn't run it. It runs only when it is called by name: showMenu ().
• When it is called, the program jumps to the procedure, runs its body, then carries on from the line after the call.
• A procedure with no parameters and one with a parameter:

  def showMenu ():
      print ("1  Add a score")
      print ("2  Show scores")
      print ("3  Quit")
  
  def drawLine (pLength):
      print ("-" * pLength)
  
  drawLine (16)
  showMenu ()
  drawLine (16)

• This displays a line of 16 dashes, the three menu lines, then another 16 dashes.
• A procedure gives nothing back, so call it on a line of its own.
• Put every definition under the # Subprograms banner, before the main program. Never write a def inside the main program's loops or if blocks.

A call jumps to the subprogram; when it ends, the program carries on after the call. A function also sends a value back.

Procedure

A subprogram that may or may not take parameters but does not return a value to the calling code.

Call

Running a subprogram by writing its name, with any arguments in brackets.

A function always returns a value to the calling code. It may or may not take parameters.

• return (value) sends a value back. The PLS writes it with brackets: return (total).
• Call a function as part of an expression, so the value is used: store it, display it, or test it.

  def withVat (pPrice):
      newPrice = pPrice * 1.2
      return (newPrice)
  
  cost = withVat (15.0)          # stored: cost is 18.0
  print (withVat (2.5))          # displayed: 3.0
  if (withVat (cost) > 20):      # tested: 21.6 is over 20
      print ("Over the limit")

• Return isn't the same as print. print shows a value to the user, but the calling code can't use it. return hands the value to the calling code and shows nothing.
• If a function prints instead of returning, the calling code gets None.
• return ends the subprogram at once. Pearson's style is one exit: keep the result in a local variable and return it on the last line.
• A function with no parameters often gets input: def getChoice (): asks the user and returns the choice.
• To send back more than one value, return a list: return ([lowest, highest]), then index the list that comes back.

Function

A subprogram that may or may not take parameters but always returns a value to the calling code. It is called as part of an expression.

Return value

The value a function sends back to the code that called it.

• Parameters are the variables in brackets on the definition line. Arguments are the values or variables passed in when the subprogram is called.
• Arguments are matched to parameters by position: the first argument goes into the first parameter, and so on. List them in the same order as the definition.
• The number must match. One argument short gives a TypeError such as “missing 1 required positional argument”.
• Parameters are local variables of the subprogram: they exist only while it runs.
• Pearson's tip: start parameter names with p (pName, pNights) so they can't be confused with variables elsewhere.
• An argument can be a literal, a variable, an expression or a whole list.

  def showBooking (pName, pNights, pRate):
      cost = pNights * pRate
      print (pName, "owes", cost)
  
  guest = "Ayo"
  nights = 3
  showBooking (guest, nights, 45)       # Ayo owes 135
  showBooking ("Kit", nights + 1, 40)   # Kit owes 160

• Arguments in the wrong order don't always crash. Sometimes they just give a wrong answer, which is a logic error.

Parameter

A variable named in a subprogram's definition line that receives a value when the subprogram is called. It is local to the subprogram.

Argument

A value or variable passed into a subprogram in the call.

The scope of a variable is the part of the program in which it exists and can be used.

• A global variable is created at the level of the main program (Pearson puts them under # Global variables). It can be used anywhere.
• A local variable is created inside a subprogram, and that includes its parameters. It exists only while the subprogram runs, then it's gone.
• The same identifier can mean different things in different scopes. A local total is a different variable from a global total.

  total = 100                  # global
  
  def addBonus (pScore):
      total = pScore + 5       # a new local variable, also called total
      return (total)
  
  print (addBonus (40))        # 45
  print (total)                # 100: the global hasn't changed

• Using a local variable outside its subprogram gives a NameError, because it no longer exists.
• Why keep globals to a minimum: names can clash, any line can change a global (so bugs are harder to trace), and a subprogram that depends on globals can't be reused or tested on its own.
• Good practice: pass data in as arguments and send results out with return. Don't reach out to global variables from inside a subprogram.
• Constants can be used inside subprograms, because their values never change.
• The global keyword isn't in the PLS, and Pearson advises against it. If a value is needed everywhere, declare and initialise it at the main program level.

Each subprogram has its own local variables. The two variables called total are different variables.

Scope

The part of a program in which a variable exists and can be used.

Global variable

A variable defined at the level of the main program, accessible from anywhere in the program.

Local variable

A variable defined inside a subprogram (including its parameters). It can only be used inside that subprogram and stops existing when the subprogram finishes.

• random.randint (a, b) returns a random whole number from a to b, including both ends. A dice roll is random.randint (1, 6).
• A random index into a list: random.randint (0, len (pList) - 1). The last index is one less than the length.
• random.random () returns a random real number from 0.0 up to, but not including, 1.0.
• Use random.random () for a percentage chance: if (random.random () < 0.3): is True about 30% of the time.
• Multiply to change the range: random.random () * 50 is a real from 0 up to 50.
• Random programs give different output each run. Test by running several times and checking every value is in range, and that the end values (such as 1 and 6) do turn up.
• Picking a random item by index:

  import random
  
  tips = ["Drink water", "Stretch", "Look away from the screen", "Walk"]
  index = random.randint (0, len (tips) - 1)
  print ("Break tip:", tips[index])

random.randint (a, b)

Returns a random integer X so that a ≤ X ≤ b.

random.random ()

Returns a random real number from 0.0 up to (not including) 1.0.

• Use math.ceil whenever you need whole packs, boxes, buses or trays: 50 cakes in boxes of 12 need math.ceil (50 / 12), which is 5 boxes.
• round is wrong for packs: round (50 / 12) is 4, leaving 2 cakes with no box.
• math.floor gives the number of completely full boxes: math.floor (50 / 12) is 4.
• For negative numbers math.floor and int differ: math.floor (-4.1) is −5, but int (-4.1) is −4.
• Use math.pi rather than typing 3.14: it's more accurate and easier to read.
• time.sleep slows a program down for countdowns, animations and simulations. The number of seconds can be a real, such as 1.5.

math.ceil (x)

Returns the smallest integer greater than or equal to x.

math.floor (x)

Returns the largest integer less than or equal to x.

time.sleep (sec)

Suspends the program for sec seconds, then resumes at the next line.

The turtle library draws pictures. A turtle moves around a canvas, trailing a pen behind it.

• Setting up: import turtle, then turtle.mode ("standard"), screen = turtle.Screen (), screen.setup (WIDTH, HEIGHT), and create your turtle: theTurtle = turtle.Turtle (). Finish with turtle.done () so the window stays open.
• Standard mode: the turtle starts at (0, 0), the centre, facing east (heading 0). Angles go anticlockwise (the PLS says “counterclockwise”): 90 is north, 180 west, 270 south. (Logo mode starts facing north and turns clockwise.)
• Window commands use the library name or the screen variable (turtle.mode, turtle.Screen, turtle.screensize, turtle.done). Drawing commands use your turtle's name.
• Moving: forward, back, left, right (degrees), setheading, setposition (x, y), home ().
• The pen: penup () to move without drawing, pendown () to draw, pensize, pencolor ("navy"), speed ("fastest") (or 0).
• Filling: fillcolor ("gold"), then begin_fill () before drawing the shape and end_fill () after it.
• Circles: circle (radius). The centre is radius units to the turtle's left, so the turtle sits on the edge. circle (50, 180) draws a half circle.
• hideturtle () and showturtle () hide or show the turtle's arrow.
• A filled triangle:

  import turtle
  
  turtle.mode ("standard")
  pen = turtle.Turtle ()
  pen.fillcolor ("lime")
  pen.begin_fill ()
  for side in range (3):
      pen.forward (100)
      pen.left (120)
  pen.end_fill ()
  pen.hideturtle ()
  turtle.done ()

• A regular shape with n sides turns 360 / n degrees at each corner: 120 for a triangle, 90 for a square, 60 for a hexagon.

Standard mode: (0, 0) is the centre, heading 0 is east and angles go anticlockwise. A circle's centre is to the turtle's left.

Standard mode

The turtle starts facing east (heading 0) and angles are anticlockwise.

begin_fill () / end_fill ()

Called just before and just after drawing a shape, so the shape is filled with the fill colour.

• Decompose the problem: one subprogram for each task, and a short main program that mostly calls them.
• Choose a function when the calling code needs a value back (a calculation, a True/False check, a value the user enters). Choose a procedure when it only does something (display, draw, write).
• Name subprograms after what they do: getChoice, isValidCode, showReport. A function returning True or False often starts with “is”.
• Lay the file out in Pearson's sections, in this order: Import libraries, Constants, Global variables, Subprograms, Main program.
• A patio tile calculator, decomposed:

  # -------------------------------------------------------------------
  # Import libraries
  # -------------------------------------------------------------------
  import math
  
  # -------------------------------------------------------------------
  # Constants
  # -------------------------------------------------------------------
  COVER_PER_BOX = 1.5       # Square metres one box of tiles covers
  
  # -------------------------------------------------------------------
  # Global variables
  # -------------------------------------------------------------------
  length = 0.0
  width = 0.0
  area = 0.0
  boxes = 0
  
  # -------------------------------------------------------------------
  # Subprograms
  # -------------------------------------------------------------------
  def patioArea (pLength, pWidth):
      total = pLength * pWidth
      return (total)
  
  def boxesNeeded (pArea):
      numBoxes = math.ceil (pArea / COVER_PER_BOX)
      return (numBoxes)
  
  def showResult (pArea, pBoxes):
      print ("Patio area: {:.1f} square metres".format (pArea))
      print ("Boxes of tiles to buy:", pBoxes)
  
  # -------------------------------------------------------------------
  # Main program
  # -------------------------------------------------------------------
  length = float (input ("Patio length in m: "))
  width = float (input ("Patio width in m: "))
  
  area = patioArea (length, width)
  boxes = boxesNeeded (area)
  showResult (area, boxes)

• For a patio 4 m by 3.5 m, the area is 14.0 square metres and 10 boxes are needed (14 ÷ 1.5 = 9.33, rounded up).
• Each subprogram can be tested on its own: print (boxesNeeded (15)) should show 10, and print (boxesNeeded (15.1)) should show 11.

A structure chart for the patio tile calculator: the main program calls three subprograms.

Decomposition (in code)

Breaking a program into subprograms, each doing one task, with a main program that calls them.

Subprogram interface

A subprogram's name, its parameters and what it returns: all another programmer needs to use it.

Paper 2 questions on subprograms ask you to complete, fix or write them in a starting file. These are the instructions that come up, and what earns the mark.

• Use the constants the file gives you (PACK_SIZE), not the number they stand for.
• Test a subprogram on its own before the main program uses it: call it with arguments where you know the answer, and print what comes back.
• Keep each subprogram's work local: set its counters and totals inside it, so they start again from 0 each time it's called.

def countPasses (pMarks, pPassMark):
    for mark in pMarks:
        count = 0
        if (mark >= pPassMark):
            count = count + 1
    return (count)