py. For example:
> import foo
> foo.__file__
‘foo.py’
# baz is a package
> import baz
> baz.__file__
‘baz/__init__.py’

However, this PEP proposes the addition of an __cached__ attribute to modules which will always point to the actual pyc file that was read or written.

When the environment variable $PYTHONDONTWRITEBYTECODE is set, or the -B option is given, or if the source lives on a read-only filesystem, then the __cached__ attribute will point to the location that the pyc file would have been written to if it didnt exist. This includes the __pycache__ subdirectory in its path. For alternative Python implementations which do not support pyc files, the __cached__ attribute may point to whatever information makes sense.

E.g., on Jython, this might be the .class file for the module: __pycache__/foo.jython-32.class. Some implementations may use multiple compiled files to create the module, in which case __cached__ may be a tuple. The exact contents of __cached__ are Python implementation specific.

It is recommended that when nothing sensible can be calculated, implementations should set the __cached_ _ attribute to None. This PEP proposes adding two new methods to the imp package: cache_from_source(py_path) -> pyc_path and source_from_cache(pyc_path) -> py_path. Alternative implementations are free to override these functions to return reasonable values based on their own support for this PEP.

These methods should not raise exceptions, but they may return None when the implementation (or PEP 302 loader in effect) cannot calculate the appropriate file name. This section describes some alternative approaches or details that were considered and rejected during the PEPs development. There is some overlap between the goals of this PEP and PEP 304, which has been withdrawn. However, PEP 304 would allow a user to create a shadow file system hierarchy in which to store pyc files.

Although the PEP does not indicate why it was withdrawn, shadow directories have a number of problems. The location of the shadow pyc files would not be easily discovered and would depend on the proper and consistent use of the $PYTHONBYTECODE environment variable both by the system and by end users. There are also global implications, meaning that while the system might want to shadow pyc files, users might not want to, but the PEP defines only an all-or-nothing approach. An earlier version of this PEP described fat Python byte code files.

These files would contain the equivalent of multiple pyc files in a single pyf file, with a lookup table keyed off the appropriate magic number. This was an extensible file format so that the first 5 parallel Python implementations could be supported fairly efficiently, but with extension lookup tables available to scale pyf byte code objects as large as necessary. The fat byte compilation files were fairly complex and inherently introduced difficult race conditions, so the current simplification of using directories was suggested. The PEP author also considered an approach where multiple thin byte compiled files lived in the same place but used different file extensions to designate the Python version.

E.g., foo.pyc25, foo.pyc26, foo.pyc31 etc. This was rejected because of the clutter involved in writing so many different files and making it more difficult (and an ongoing task) to update any tools that are dependent on the file extension. A proposal was floated to call the __pycache__ directory .pyc or some other dot-file name.

However, this would have the effect of hiding the directory on *nix systems. There are many reasons why this was rejected by the BDFL including but not limited to: dot-files are only special on some platforms and we actually do not want to hide these completely from users. Work on this code is tracked in a Bazaar branch on Launchpad until its ready for merge into Python 3.2. The work-in-progress diff can also be viewed, and is updated automatically as new changes are uploaded.

A Rietveld code review issue has been opened as of April 1st (no, this is not an April Fools joke). Barry Warsaws original idea was for fat Python byte code files. Martin von Loewis reviewed an early draft of the PEP and suggested the simplification to store traditional pyc and pyo files in a directory.

Many other people reviewed early versions of this PEP and provided useful feedback including but not limited to: David Malcolm, Josselin Mouette, Matthias Klose, Michael Hudson, Michael Vogt, Piotr Ożarowski, Scott Kitterman, Toshio Kuratomi. This document has been placed in the public domain.