(backport from rev. 52845)

I think these changes are correct, but I'm not sure.  Could someone
who knows how this module works test it?  It can at least start on
the cmd line.

Based on lsprof (patch #1212837) by Brett Rosen and Ted Czotter.
With further editing by Michael Hudson and myself.
History in svn repo: http://codespeak.net/svn/user/arigo/hack/misc/lsprof

* Module/_lsprof.c is the internal C module, Lib/cProfile.py a wrapper.
* pstats.py updated to display cProfile's caller/callee timings if available.
* setup.py and NEWS updated.
* documentation updates in the profiler section:
   - explain the differences between the three profilers that we have now
   - profile and cProfile can use a unified documentation, like (c)Pickle
   - mention that hotshot is "for specialized usage" now
   - removed references to the "old profiler" that no longer exists
* test updates:
   - extended test_profile to cover delicate cases like recursion
   - added tests for the caller/callee displays
   - added test_cProfile, performing the same tests for cProfile
* TO-DO:
   - cProfile gives a nicer name to built-in, particularly built-in methods,
     which could be backported to profile.
   - not tested on Windows recently!

From SF patch #852334.

- don't use "file" as the name of local variables

Most of this code was old enough to vote.  Examples of cleanups:

+ Backslashes were used for line continuation even inside unclosed
  bracket structures, from back in the days that was still needed.

+ There was no use of % formats, and e.g. the old fpformat module was
  still used to format floats "by hand" in conjunction with rjust().

+ There was even use of a do-nothing .ignore() method to tack on to the
  end of a chain of method calls, else way back when Python would print
  the non-None result (as it does now in an interactive session -- it
  *used* to do that in batch mode too).

+ Perhaps controversial (although I can't imagine why for real <wink>),
  used augmented assignment where helpful.  Stuff like

      self.total_calls = self.total_calls + other.total_calls

  is just plain harder to follow than

      self.total_calls += other.total_calls

comments, docstrings or error messages. I fixed two minor things in
test_winreg.py ("didn't" -> "Didn't" and "Didnt" -> "Didn't").

There is a minor style issue involved: Guido seems to have preferred English
grammar (behaviour, honour) in a couple places. This patch changes that to
American, which is the more prominent style in the source. I prefer English
myself, so if English is preferred, I'd be happy to supply a patch myself ;)

who writes:

Here is batch 2, as a big collection of CVS context diffs.
Along with moving comments into docstrings, i've added a
couple of missing docstrings and attempted to make sure more
module docstrings begin with a one-line summary.

I did not add docstrings to the methods in profile.py for
fear of upsetting any careful optimizations there, though
i did move class documentation into class docstrings.

The convention i'm using is to leave credits/version/copyright
type of stuff in # comments, and move the rest of the descriptive
stuff about module usage into module docstrings.  Hope this is
okay.

its creation.  I'm assuming these were once valid references to "Jim
Roskind's profile"...