def title(s=None, additional='<STR_LIT>', stream=sys.stdout):
if s is None:<EOL><INDENT>callable_name, file_name, class_name = getCallerInfo(<NUM_LIT:2>)<EOL>s = callable_name<EOL>if class_name is not None:<EOL><INDENT>s = class_name + '<STR_LIT:.>' + callable_name<EOL><DEDENT><DEDENT>lines = (s + additional).split('<STR_LIT:\n>')<EOL>length = max(len(line) for line in lines)<EOL>print >> stream, '<STR_LIT:->' * length<EOL>print >> stream, s + additional<EOL>print >> stream, '<STR_LIT:->' * length<EOL>
Utility function to display nice titles

    It automatically extracts the name of the function/method it is called from
    and you can add additional text. title() will then print the name
    of the function/method and the additional text surrounded by tow lines
    of dashes. If you don't want the name of the function, you can provide
    alternative text (regardless of the additional text)

    :param s: (string) text to display, uses the function name and arguments by
           default
    :param additional: (string) extra text to display (not needed if s is not
           None)
    :param stream: (stream) the stream to print to. Ny default goes to standard
           output

    Examples:

    .. code-block:: python

      def foo():
        title()

    will display:

    .. code-block:: text

      ---
      foo
      ---

    .. code-block:: python

      def foo():
        title(additional='(), this is cool!!!')

    will display:

    .. code-block:: text

      ----------------------
      foo(), this is cool!!!
      ----------------------

    .. code-block:: python

      def foo():
        title('No function name here!')

    will display:

    .. code-block:: text

      ----------------------
      No function name here!
      ----------------------