# CS2/examples/objects/README.txt                    David MacQuigg   12-Sept-07
Notes for non-Python programmers

The Python examples in this directory are almost self-explanatory, but if you
don't know Python, there are a few parts that may need explanation.

#** OhNo.py
- Some of the mistakes in this program may make Python look bad. Hold off on
this conclusion until you see the whole sequence.

#** OhHowIwish.py
- line 5: 'doctstrings' are the strings at the beginning of each module, class,
and method.  Typically they are multiline strings, so we use a '''triple
quote'''.  Doctests are lines of executable code in docstrings.  The 'doctest'
module automatically verifies all doctests.

Well-designed doctests can serve not only to explain the program, but also as
unittests supporting a test-driven design methodology.  Making doctests a
requirement in homework helps establish good programming habits.

- line 20:  The 'random' module has lots of useful functions.  Normally, the
'random()' function generates a different random sequence each time, causing
problems for any doctest that needs a repeatable output.  The 'seed()' function
allows us to produce a repeatable pseudorandom sequence.

- line 22:  The error here is deliberate, so you can see the diagnostic output
from doctest.testmod().

- line 38: The __main__ section is optional in a module, but it adds no overhead
when the module is imported into other modules.  Adding lots of tests in this
section is a good idea.

Names with double underscores, left and right, are special names reserve for use
by Python's machinery.

- line 59:  ' ' is a string (a builtin class), and 'join()' is a method of that
class.  This statement joins a list of strings with a single space between each.

#** OhMaybe.py
- line 8:  You can pass any objects you want as arguments to a function.  Here
we are passing a 'coin' object, a float and an int.  In the body of the
function, we run the methods of coin, and attach to it some new data attributes.

When the function exits, all local variables are lost, but since coin is an
external object, it will stay alive.  Garbage collection is automatic after all
references to an object are gone.

- line 14: 'random' is the same module we used in the previous program, but now
it is imported only into the Coins module, so we have to access it through that
module.

- line 14: In Python, we create a new object from a class by "calling" the class
as if it were a function.

- line 48: The classList is a list of strings naming each class.  We need an
executable statment where the selected string is part of the statement itself,
not just a string.  e.g. name = 'BiasedCoin', but we need to execute the string
'Coins.BiasedCoin()' to get a coin instance.  The 'eval' function does the
trick.

#** OhKay.py
- line 14:  __init__() is a special built-in function that initializes a new
object.  There is also a __new__() function that instantiates the object.
Together __new__() and __init__() act like a "constructor" in other languages.
__new__() and __init__() run automatically whenever a new object is created from
a class.  Here we are over-riding the builtin __init__() to set up our own
initial values.  __new__() can be over-ridden the same way, but that is seldom
done.

Functions defined within a class are called "methods".  Methods have a special
first argument, the object from which the method was called.  Other than that,
they act like normal functions with normal local variables, etc.  Instance
variables appear as 'self.whatever', where 'self' is the parameter name chosen
for the first argument.  These are equivalent to "fields" in Java, but the
syntax is more explicit.

This first argument is inserted automatically when the method is called.  If
'tr' is a TestRunner instance, then the call tr.runTrials() will be the same as
calling TestRunner.runTrials(tr).  'self' is the name usually given to this
first argument, but since argument names are just dummies, and the name 'self'
is typed many times in most method defs, you can chose a shorter name, like 's'.
'self' has the advantage that your code will be more readable to other Python
programmers.

- line 24

#** Coins.py 
Module containing coin classes, including a template to write more classes, and
a test function to  check that a new class conforms to the expected interface.

#** Coins.pydoc.txt
pydoc output for the Coins module
>>> help(Coins)  -  command which produced the output

#** __init.py__
Dummy file needed to tell Python this is a package directory.  
Can also put initialization statements here, which will run when the package
is imported.

#**~