#!/usr/bin/env python

"""
This is the "hellotest" module.

A small Python module with doctests for saying 'Hello World!' in different
ways. Methods included are hello, hi and helloplace. This module can serve as
a template for how to document and test python code.

The most basic method is hello and hi that do the same thing and the method
helloplace is for advanced users that want more options. 

>>> hello()
Hello World!

>>> hi()
Hello World!

>>> helloplace(3, 'Python')
Hello hello hello Python!

"""

def hello():
    """Default hello method.
   
    >>> hello()
    Hello World!
    """
    
    print "Hello World!"


def helloplace(n, place='World'): 
    """Advanced hello method - says hello to a specific place.
    
    Arguments:
    n     -- number of hello(s) (must be positive).
    place -- the place to say hello to (default 'World')
    
    The typical use cases results in the canonical 'Hello World!'.
    >>> helloplace(1)
    Hello World!
    >>> helloplace(0)
    Traceback (most recent call last):
        ...
    ValueError: Argument n must be positive (recieved 0).
    
    
    The more exotic Hell can be greeted by using the optional argument place
    and increasing n will increase the number of hellos. Rather long greetings
    work fine (output snipped).
    >>> helloplace(1, 'Hell')
    Hello Hell!
    
    >>> helloplace(3)
    Hello hello hello World!
    
    >>> helloplace(3, 'Hell')
    Hello hello hello Hell!
    
    >>> helloplace(1337, 'Caerbannog') # doctest:+ELLIPSIS
    Hello hello hello ... hello hello hello Caerbannog!
    """
    
    if n < 1:
        raise ValueError('Argument n must be positive (recieved {0}).'.format(n))
    
    print 'Hello ' + 'hello '* (n-1) + place + '!'


def hi():
    """Short for hello()."""
    #TODO: Add tests for this method
    hello()
    

if __name__ == '__main__':
    import doctest
    doctest.testmod()
    print "Tests done."