If a filename couldn't be stat()ed, the code tries to
find it in sys.path. To do this it only takes the
filename and drops any preceding directories.

If the file happens to reside in a package, the name of
the package is lost, which can lead to badness. Eg, if
you have my_package/__init__.py, then just the file
__init__.py will be searched for, which may well be
found in the cache from a different package. This leads
to the wrong file being returned.

This bit me as a result of using pydoc on a set of my
packages. I'll try to put together a minimal example
which demonstates the behaviour.

Logged In: YES 
user_id=1081664

Running the attached code ( from ~/src, not ~/src/pybug) we
see that the contents of the cache are incorrect).

timl@newton:~/src$ tar -zxvf pybug.tar.gz 
pybug/
pybug/pkg1/
pybug/pkg1/__init__.py
pybug/pkg2/
pybug/pkg2/__init__.py
pybug/bug.py
timl@newton:~/src$ python pybug/bug.py 
{'pkg2/__init__.py': (217L, 1051027884, ['#\n', '# The
Python Imaging Library.\n', '# $Id:
//modules/pil/PIL/__init__.py#2 $\n', '#\n', '# package
placeholder\n', '#\n', '# Copyright (c) 1999 by Secret Labs
AB.\n', '#\n', '# See the README file for information on
usage and redistribution.\n', '#\n', '\n', '# ;-)\n'],
'/usr/lib/python2.3/site-packages/PIL/__init__.py'),
'pkg1/__init__.py': (217L, 1051027884, ['#\n', '# The Python
Imaging Library.\n', '# $Id: //modules/pil/PIL/__init__.py#2
$\n', '#\n', '# package placeholder\n', '#\n', '# Copyright
(c) 1999 by Secret Labs AB.\n', '#\n', '# See the README
file for information on usage and redistribution.\n', '#\n',
'\n', '# ;-)\n'],
'/usr/lib/python2.3/site-packages/PIL/__init__.py')}
timl@newton:~/src$

Logged In: YES 
user_id=1081664

I can also confirm that this bug exists in python2.4b2.

Logged In: YES 
user_id=11375

In 2.5trunk, linecache seems to be broken in a different
way; the files are never added to the cache at all, and
getlines() returns an empty list.  

One problem is that, when updatecache searches through
sys.path, it does os.path.join(path, basename), not
filename, so it looks for ./__init__.py, not
./pkg1/__init__.py.  Changing it to filename makes the test
script work in 2.5.

It's not clear if linecache really intends to support
multiple-component filenames, though.  I think it should,
though.

The following issues appear to be the same bug to me:

   http://bugs.python.org/issue1068477
   http://bugs.python.org/issue1309567
   http://bugs.python.org/issue1754483

and are, as of 2008-06-30, unfixed in both rel25-maint and trunk.

Confirmed in py3k and trunk as AMK describes it, fixed by the patch in 
issue 1309567.

Setting #1309567 as superseder.