@@ -1607,35 +1607,44 @@ Modules
16071607How do I create a .pyc file?
16081608----------------------------
16091609
1610- When a module is imported for the first time (or when the source is more recent
1611- than the current compiled file) a ``.pyc `` file containing the compiled code
1612- should be created in the same directory as the ``.py `` file.
1613-
1614- One reason that a ``.pyc `` file may not be created is permissions problems with
1615- the directory. This can happen, for example, if you develop as one user but run
1616- as another, such as if you are testing with a web server. Creation of a .pyc
1617- file is automatic if you're importing a module and Python has the ability
1618- (permissions, free space, etc...) to write the compiled module back to the
1619- directory.
1610+ When a module is imported for the first time (or when the source file has
1611+ changed since the current compiled file was created) a ``.pyc `` file containing
1612+ the compiled code should be created in a ``__pycache__ `` subdirectory of the
1613+ directory containing the ``.py `` file. The ``.pyc `` file will have a
1614+ filename that starts with the same name as the ``.py `` file, and ends with
1615+ ``.pyc ``, with a middle component that depends on the particular ``python ``
1616+ binary that created it. (See :pep: `3147 ` for details.)
1617+
1618+ One reason that a ``.pyc `` file may not be created is a permissions problem
1619+ with the directory containing the source file, meaning that the ``__pycache__ ``
1620+ subdirectory cannot be created. This can happen, for example, if you develop as
1621+ one user but run as another, such as if you are testing with a web server.
1622+
1623+ Unless the :envvar: `PYTHONDONTWRITEBYTECODE ` environment variable is set,
1624+ creation of a .pyc file is automatic if you're importing a module and Python
1625+ has the ability (permissions, free space, etc...) to create a ``__pycache__ ``
1626+ subdirectory and write the compiled module to that subdirectory.
16201627
16211628Running Python on a top level script is not considered an import and no
16221629``.pyc `` will be created. For example, if you have a top-level module
1623- ``foo.py `` that imports another module ``xyz.py ``, when you run ``foo ``,
1624- ``xyz.pyc `` will be created since ``xyz `` is imported, but no ``foo.pyc `` file
1625- will be created since ``foo.py `` isn't being imported.
1630+ ``foo.py `` that imports another module ``xyz.py ``, when you run ``foo `` (by
1631+ typing ``python foo.py `` as a shell command), a ``.pyc `` will be created for
1632+ ``xyz `` because ``xyz `` is imported, but no ``.pyc `` file will be created for
1633+ ``foo `` since ``foo.py `` isn't being imported.
16261634
1627- If you need to create `` foo .pyc `` .pyc `` file for a module
1628- that is not imported -- you can, using the :mod: ` py_compile ` and
1629- :mod: `compileall ` modules.
1635+ If you need to create a `` .pyc `` file for `` foo `` -- that is, to create a
1636+ `` .pyc `` file for a module that is not imported -- you can, using the
1637+ :mod: `py_compile ` and :mod: ` compileall ` modules.
16301638
16311639The :mod: `py_compile ` module can manually compile any module. One way is to use
16321640the ``compile() `` function in that module interactively::
16331641
16341642 >>> import py_compile
16351643 >>> py_compile.compile('foo.py') # doctest: +SKIP
16361644
1637- This will write the ``.pyc `` to the same location as ``foo.py `` (or you can
1638- override that with the optional parameter ``cfile ``).
1645+ This will write the ``.pyc `` to a ``__pycache__ `` subdirectory in the same
1646+ location as ``foo.py `` (or you can override that with the optional parameter
1647+ ``cfile ``).
16391648
16401649You can also automatically compile all files in a directory or directories using
16411650the :mod: `compileall ` module. You can do it from the shell prompt by running
0 commit comments