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


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


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


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


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)


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


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


Code example

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

perimeter(3)


Code example

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

perimeter(3)


Code example

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

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


Designing for generalizability

Try to think of all the possible uses for this function

Avoid hard-codingUse parameters instead


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


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)


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/


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


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


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)

"""

...


docstring example:

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

perimeter.__doc__


Viewing docstrings

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

import numpyprint numpy.histogram.__doc__


day 2 – lesson 5 function interfaces

Documents