mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-11 14:44:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Merge: #18036: update .pyc FAQ entry in light of PEP 3147.

Browse source
This commit is contained in:
R David Murray 2013-12-13 12:30:29 -05:00
commit 18701160cc
1 changed files with 26 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

43
Doc/faq/programming.rst
View file

@ -1607,26 +1607,34 @@ Modules
How do I create a .pyc file? How do I create a .pyc file?
---------------------------- ----------------------------
When a module is imported for the first time (or when the source is more recent When a module is imported for the first time (or when the source file has
than the current compiled file) a ``.pyc`` file containing the compiled code changed since the current compiled file was created) a ``.pyc`` file containing
should be created in the same directory as the ``.py`` file. the compiled code should be created in a ``__pycache__`` subdirectory of the
directory containing the ``.py`` file. The ``.pyc`` file will have a
filename that starts with the same name as the ``.py`` file, and ends with
``.pyc``, with a middle component that depends on the particular ``python``
binary that created it. (See :pep:`3147` for details.)
One reason that a ``.pyc`` file may not be created is permissions problems with One reason that a ``.pyc`` file may not be created is a permissions problem
the directory. This can happen, for example, if you develop as one user but run with the directory containing the source file, meaning that the ``__pycache__``
as another, such as if you are testing with a web server. Creation of a .pyc subdirectory cannot be created. This can happen, for example, if you develop as
file is automatic if you're importing a module and Python has the ability one user but run as another, such as if you are testing with a web server.
(permissions, free space, etc...) to write the compiled module back to the
directory. Unless the :envvar:`PYTHONDONTWRITEBYTECODE` environment variable is set,
creation of a .pyc file is automatic if you're importing a module and Python
has the ability (permissions, free space, etc...) to create a ``__pycache__``
subdirectory and write the compiled module to that subdirectory.
Running Python on a top level script is not considered an import and no Running Python on a top level script is not considered an import and no
``.pyc`` will be created. For example, if you have a top-level module ``.pyc`` will be created. For example, if you have a top-level module
``foo.py`` that imports another module ``xyz.py``, when you run ``foo``, ``foo.py`` that imports another module ``xyz.py``, when you run ``foo`` (by
``xyz.pyc`` will be created since ``xyz`` is imported, but no ``foo.pyc`` file typing ``python foo.py`` as a shell command), a ``.pyc`` will be created for
will be created since ``foo.py`` isn't being imported. ``xyz`` because ``xyz`` is imported, but no ``.pyc`` file will be created for
``foo`` since ``foo.py`` isn't being imported.
If you need to create ``foo.pyc`` -- that is, to create a ``.pyc`` file for a module If you need to create a ``.pyc`` file for ``foo`` -- that is, to create a
that is not imported -- you can, using the :mod:`py_compile` and ``.pyc`` file for a module that is not imported -- you can, using the
:mod:`compileall` modules. :mod:`py_compile` and :mod:`compileall` modules.
The :mod:`py_compile` module can manually compile any module. One way is to use The :mod:`py_compile` module can manually compile any module. One way is to use
the ``compile()`` function in that module interactively:: the ``compile()`` function in that module interactively::
@ -1634,8 +1642,9 @@ the ``compile()`` function in that module interactively::
>>> import py_compile >>> import py_compile
>>> py_compile.compile('foo.py') # doctest: +SKIP >>> py_compile.compile('foo.py') # doctest: +SKIP
This will write the ``.pyc`` to the same location as ``foo.py`` (or you can This will write the ``.pyc`` to a ``__pycache__`` subdirectory in the same
override that with the optional parameter ``cfile``). location as ``foo.py`` (or you can override that with the optional parameter
``cfile``).
You can also automatically compile all files in a directory or directories using You can also automatically compile all files in a directory or directories using
the :mod:`compileall` module. You can do it from the shell prompt by running the :mod:`compileall` module. You can do it from the shell prompt by running