Day 2 – Lesson 5
Function Interfaces
Python Mini-Course
University of Oklahoma
Department of Psychology
1
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Questions from Day 1
 Installation
 Python syntax
 Variables and data types
 Creating and using functions
 Using the math library
2
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Lesson objectives
1. State the principles of good
function interface design
2. Define encapsulation and state
why it is useful
3. Use parameters to make functions
generalizable
4. Use docstrings to document
function interfaces
3
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Designing function interfaces
 Interface
 A summary of how the function is used
 Documentation specifies:
 What the function does
 Parameters to be passed into the
function
 What (if anything) the function
returns
4
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Designing function interfaces
 Design principles:
1. KISS
2. Encapsulate
3. Make it as general as you can
(keeping in mind principle #1)

“An interface is ‘clean’ if it is ‘as simple as
possible, but not simpler.’”
4. Document!!!
5
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Encapsulation
 “The hiding of the internal mechanisms
and data structures of a software
component behind a defined interface,
in such a way that users of the
component (other pieces of software)
only need to know what the component
does, and cannot make themselves
dependent on the details of how it does
it.”
Wikipedia, http://en.wikipedia.org/wiki/Encapsulation_(computer_science)
6
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Example
 Driving a car
 You need to know how to use:
 Gas and brake petals
 Steering wheel
 Gear shifter
 You don’t need to know:
 The kind of engine
 How the engine (or any other system)
works
7
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Why encapsulate?
 Makes it easier to change the
internal mechanisms
 Protects the integrity of the
component
 prevents users from setting the
internal data of the component into an
invalid or inconsistent state
 Reduces system complexity
8
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Code example
def perimeter(length):
p = length + length + length \
+ length
print p
perimeter(3)
9
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Code example
def perimeter(length):
p = 4*length
print p
perimeter(3)
10
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Code example
def perimeter(length, n_sides):
p = length*n_sides
print p
perimeter(3, 4)
perimeter(3, 6)
11
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Designing for generalizability
 Try to think of all the possible
uses for this function
 Avoid hard-coding
 Use parameters instead
12
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Parameters and arguments
 Parameters are the values that
a function receives as input
def perimeter(length, n_sides):
 You can also use parameters that
specify a default value
def perimeter(length, n_sides=4):
13
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Parameters and arguments
 When you call a function, you pass
specific values called arguments for
each parameter
perimeter(3)
perimeter(3, 6)
Perimeter(3, n_sides=6)
perimeter(length=3, n_sides=6)
14
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Using docstrings
 A string literal that occurs as the
first statement in a module,
function, class, or method
definition
 becomes the __doc__ special
attribute of that object
 See PEP-257 for
detailshttp://www.python.org/dev/peps/pe
p-0257/
15
Python Mini-Course: Day 2 - Lesson 5
4/18/09
One-line docstrings
 For really obvious cases
def perimeter (length):
"""Calculate the perimeter of a square."""
 Use triple quotes even though the string
fits on one line
 Closing quotes are on the same line as
the opening quotes
 No blank line either before or after the
docstring
16
Python Mini-Course: Day 2 - Lesson 5
4/18/09
One-line docstrings
 Should be a phrase ending in a period
 Prescribes the function or method's
effect as a command, not as a
description
 """Do this.""" or """Return that."""
 NOT """Returns the pathname ..."""
17
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Multi-line docstrings
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
...
18
Python Mini-Course: Day 2 - Lesson 5
4/18/09
docstring example:
def perimeter(length, n_sides=4):
"""Print the perimeter of a
regular polygon."""
p = length*n_sides
print p
perimeter.__doc__
19
Python Mini-Course: Day 2 - Lesson 5
4/18/09
Viewing docstrings
import math, os
print math.exp.__doc__
print os.getcwd__doc__
import numpy
print numpy.histogram.__doc__
20
Python Mini-Course: Day 2 - Lesson 5
4/18/09