day 2 – lesson 5 function interfaces

Python Mini-CourseUniversity of Oklahoma

Department of Psychology

Day 2 – Lesson 5Function Interfaces

4/18/09Python Mini-Course: Day 2 - Lesson 51

Questions from Day 1

InstallationPython syntaxVariables and data typesCreating and using functionsUsing the math library

4/18/09Python Mini-Course: Day 2 - Lesson 52

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

4/18/09Python Mini-Course: Day 2 - Lesson 53

Designing function interfaces

InterfaceA summary of how the function is used

Documentation specifies:What the function doesParameters to be passed into the

functionWhat (if anything) the function

returns

4/18/09Python Mini-Course: Day 2 - Lesson 54

Designing function interfaces

Design principles:1. KISS2. Encapsulate3. 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!!!

4/18/09Python Mini-Course: Day 2 - Lesson 55

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)

4/18/09Python Mini-Course: Day 2 - Lesson 56

Example

Driving a carYou need to know how to use:

Gas and brake petalsSteering wheelGear shifter

You don’t need to know:The kind of engineHow the engine (or any other system)

works

4/18/09Python Mini-Course: Day 2 - Lesson 57

Why encapsulate?

Makes it easier to change the internal mechanisms

Protects the integrity of the componentprevents users from setting the

internal data of the component into an invalid or inconsistent state

Reduces system complexity

4/18/09Python Mini-Course: Day 2 - Lesson 58

Code example

def perimeter(length): p = length + length + length \ + length print p

perimeter(3)

4/18/09Python Mini-Course: Day 2 - Lesson 59

Code example

def perimeter(length): p = 4*length print p

perimeter(3)

4/18/09Python Mini-Course: Day 2 - Lesson 510

Code example

def perimeter(length, n_sides): p = length*n_sides print p

perimeter(3, 4)perimeter(3, 6)

4/18/09Python Mini-Course: Day 2 - Lesson 511

Designing for generalizability

Try to think of all the possible uses for this function

Avoid hard-codingUse parameters instead

4/18/09Python Mini-Course: Day 2 - Lesson 512

Parameters and arguments

Parameters are the values that a function receives as inputdef perimeter(length, n_sides):

You can also use parameters that specify a default valuedef perimeter(length, n_sides=4):

4/18/09Python Mini-Course: Day 2 - Lesson 513

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)

4/18/09Python Mini-Course: Day 2 - Lesson 514

Using docstrings

A string literal that occurs as the first statement in a module, function, class, or method definitionbecomes the __doc__ special attribute of that object

See PEP-257 for detailshttp://www.python.org/dev/peps/pep-0257/

4/18/09Python Mini-Course: Day 2 - Lesson 515

One-line docstrings

For really obvious casesdef 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

4/18/09Python Mini-Course: Day 2 - Lesson 516

One-line docstrings

Should be a phrase ending in a periodPrescribes the function or method's

effect as a command, not as a description"""Do this.""" or """Return that."""NOT """Returns the pathname ..."""

4/18/09Python Mini-Course: Day 2 - Lesson 517

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)

"""

...

4/18/09Python Mini-Course: Day 2 - Lesson 518

docstring example:

def perimeter(length, n_sides=4): """Print the perimeter of a regular polygon.""" p = length*n_sides print p

perimeter.__doc__

4/18/09Python Mini-Course: Day 2 - Lesson 519

Viewing docstrings

import math, osprint math.exp.__doc__print os.getcwd__doc__

import numpyprint numpy.histogram.__doc__

4/18/09Python Mini-Course: Day 2 - Lesson 520