<type>documentation</type>
<domain>edit</domain>
<id>pep8</id>
<title>PEP 8 Reformatting</title>
<date>$Date: 2011-05-04 11:47:03 -0400 (Wed, 04 May 2011) $</date>
<version>$Revision: 24521 $</version>
<product>all</product>

Wing can automatically reformat code to be compliant with the `PEP 8 Style Guide for Python
Code <https://www.python.org/dev/peps/pep-0008/>`__.

**Manual PEP 8 Reformatting**

The ``Source > PEP 8`` menu group contains items for reformatting the current selection or
current file to be PEP 8 compliant. A single ``Undo`` will undo the reformatting operation.

Note that reformatting large files may take several minutes, and Wing will lock the file
so it cannot be edited during that time. The amount of time spent in reformatting a file
is limited to the number of seconds specified with the `Editor > PEP 8 > Reformatting
Timeout <script:show_preferences_gui#prefname="edit.pep8-timeout">`__ preference. The
default is set purposely low to avoid leaving an editor locked for a long period of time.

Reformatting of selections is not time-limited, so very large selections may lock up 
the IDE until the reformatting operation completes.

**Automatic PEP 8 Reformatting**

~~~if WINGPRO:
PEP 8 formatting may be applied automatically character by character, as you type,
through Wing Pro's auto-editing facility, by enabling the `Editor > Auto-Editing >
Auto-Enter Spaces <script:show_preferences_gui#prefname="edit.auto-edit-spaces">`__ and
`Editor > Auto-Editing > Enforce PEP 8 Style Spacing
<script:show_preferences_gui#prefname="edit.auto-edit-spaces-enforce">`__ preferences.

Alternatively, this may be done by 
~~~
~~~if not WINGPRO:
PEP 8 formatting may be applied automatically by 
~~~
auto-formatting edited lines after the caret leaves the line, or by reformatting
whole files as they are saved to disk.  This is enabled with the `Editor > PEP 8 > 
Auto-Reformat for PEP 8 <script:show_preferences_gui#prefname="edit.pep8-autoformat">`__
preference.  The choices are:

* **Disabled** turns off automatic PEP 8 reformatting.  This is the default.

* **Lines After Edit** reformats individual logical lines (which may span multiple
  physical lines) after the caret leaves any edited line.
  
* **Whole Files Before Save** reformats whole files when they are saved to disk.  
  This option is recommended only for users with small files, since reformatting
  larger files may take substantial amounts of time.  The process is aborted and
  the file is saved without reformatting for PEP 8 if the time required to reformat
  it exceeds the ``Reformatting Timeout`` preference described below.

**PEP 8 Reformatting Options**

Several options for PEP 8 formatting are provided in the ``Editor > PEP 8`` preferences
group:

* **Spaces Around = in Argument Lists** overrides PEP 8 by inserting spaces around 
  ``=`` in argument lists.  This is disabled by default.

* **Enforce Line Length** applies PEP 8 style line wrapping during reformatting,
  using the wrap column configured with the `Editor > Line Wrapping > Reformatting
  Wrap Column <script:show_preferences_gui#prefname="edit.text-wrap-column">`__ preference.
  This is disabled by default.
  
* **Reindent All Lines in Files** causes all lines to be reindented with 4-space 
  indentation when PEP 8 reformatting an entire file.  When this is disabled, reformatting 
  may still alter indentation within logical lines of code.  When reformatting selections,
  this preference is ignored and only indentation within logical lines may be changed.
~~~if not WING101:
  To convert indentation to other styles or sizes, use the `Indentation Manager
  <ref:edit/indentation-manager>`__.
~~~

* **Reformatting Timeout** specifies the number of seconds after which Wing aborts PEP 8
  reformatting of an entire file. The default is 3 seconds, to prevent locking editors for
  long periods of time, and to prevent hanging up the save process when auto-formatting
  files during save has been enabled. Large files may take several minutes to reformat.

~~~if not WING101:  
**Using Other PEP 8 Reformatters**

Wing uses ``autopep8`` to implement PEP 8 reformatting. To use other PEP 8 reformatters like
``YAPF`` and ``Black``, use the `OS Commands <ref:oscommands/index>`__ tool to set up a
command line that converts the file in place. The command line may contains ``%s`` for the
current file name. After conversion on disk, Wing will automatically reload the file into
the editor.

For YAPF::

  yapf -i %s
  
For Black::

  black %s
  
OS Commands may be given a key binding, to make them easier to invoke for the current
file.  However, there is currently no way to use ``YAPF`` or ``Black`` with the 
automatic PEP 8 reformatting features described above.
~~~
