classification
Title: "How do I create a .pyc file?" FAQ entry is out of date
Type: behavior Stage: resolved
Components: Versions: Python 3.4, Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: akaptur, barry, ezio.melotti, pconnell, python-dev, r.david.murray
Priority: normal Keywords: easy, patch

Created on 2013-05-22 17:37 by r.david.murray, last changed 2013-12-13 17:43 by r.david.murray. This issue is now closed.

Files
File name Uploaded Description Edit
better_pyc_doc_akaptur.patch akaptur, 2013-07-16 21:57 review
issue18036.diff pconnell, 2013-11-23 13:48 review
Messages (7)
msg189829 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-05-22 17:37
It doesn't talk about __pycache__.
msg190821 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-06-08 19:47
FTR here's a link to the FAQ: http://docs.python.org/3/faq/programming.html#how-do-i-create-a-pyc-file
msg193194 - (view) Author: A Kaptur (akaptur) * Date: 2013-07-16 21:57
Here is a suggestion for updated documentation in this section. I've added the description of __pycache__, included a very short description of what a .pyc file is, and moved the troubleshooting to the end of the section.  I'm not sure whether the description ("a byte code cache file") is desirable here, but my sense is that people asking how to generate .pyc files are generally confused beginners.
msg193700 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-07-25 16:32
Well, the FAQ entry is "why didn't a .pyc file get created", so presumably the querant knows enough to be looking for one to get created, and so presumably knows more-or-less what it is.

It seems to me that your rewording loses the sense of answering the question, and instead becomes more of a mini-tutorial on what a .pyc file is.

The changes needed here, it seems to me, are to talk about the __pycache__ directory instead of the .pyc file.  In python2, the issue would be that there was no write access to the source directory, and thus the .pyc file could not be created.  Now that same lack of access will first of all result in the __pycache__ directory not being created.

There is also then a second level: if the __pycache__ directory already exists but is not writable when a new module is first run, the .pyc file will not get created.  But I bet almost no one will notice that, and thus it won't be a FAQ :)  

Still, that issue could be mentioned...but then you also need to mention the full, two-part, version-specific extension, since one has to know which .pyc file to expect, if there are multiple versions of python on the system.  That mention could just be a pointer to the relevant docs, though, since most users will only be dealing with one python3 version.
msg204012 - (view) Author: Phil Connell (pconnell) * Date: 2013-11-23 13:48
I've had a stab at creating a patch for this.

As well as mentioning __pycache__, I've tweaked some wording to reflect the fact that .pyc files are regenerated if the source file's length changes (as per issue13645).
msg206128 - (view) Author: Roundup Robot (python-dev) Date: 2013-12-13 17:31
New changeset a14f830196ec by R David Murray in branch '3.3':
#18036: update .pyc FAQ entry in light of PEP 3147.
http://hg.python.org/cpython/rev/a14f830196ec

New changeset a757bdfce6b3 by R David Murray in branch 'default':
Merge: #18036: update .pyc FAQ entry in light of PEP 3147.
http://hg.python.org/cpython/rev/a757bdfce6b3
msg206130 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-12-13 17:43
Thanks, A Kaptur and Phil.  I used Phil's patch, and added some additional tweaks and words.  (For example, I don't think PYTHONDONTWRITEBYTECODE existed when the FAQ entry was last updated).

I've chosen to maintain the existing flow, since it matches the title of the entry better.  It is quite possible, however, that the "question" is no longer in fact a FAQ, since most people probably don't ever look in the __pycache__ directory unless they are a distro maintainer.  It is possible what is really needed is a section of the docs that covers the actual implementation of PEP 3147 and all the associated issues surrounding .pyc files, but this updated version of the FAQ entry is at least an improvement on the status quo.
History
Date User Action Args
2013-12-13 17:43:35r.david.murraysetstatus: open -> closed
resolution: fixed
messages: + msg206130

stage: needs patch -> resolved
2013-12-13 17:31:09python-devsetnosy: + python-dev
messages: + msg206128
2013-11-23 13:48:23pconnellsetfiles: + issue18036.diff

messages: + msg204012
2013-07-25 16:32:53r.david.murraysetmessages: + msg193700
2013-07-16 21:57:31akaptursetfiles: + better_pyc_doc_akaptur.patch

nosy: + akaptur
messages: + msg193194

keywords: + patch
2013-06-08 19:47:28ezio.melottisetkeywords: + easy

messages: + msg190821
2013-05-26 13:36:32ezio.melottisetnosy: + ezio.melotti
2013-05-25 09:28:08pconnellsetnosy: + pconnell
2013-05-22 17:37:51r.david.murraycreate