<type>documentation</type>
<domain>edit</domain>
<id>auto-reformatting</id>
<title>Auto-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 Python code to be compliant with the `PEP 8 Style Guide
for Python Code <https://www.python.org/dev/peps/pep-0008/>`__ or using the `Black
<https://github.com/psf/black>`__, `Ruff <https://docs.astral.sh/ruff/>`__ or 
`YAPF <https://github.com/google/yapf>`__ code formatting tools.

**Installing Reformatters**

Wing uses its own copy of ``autopep8`` for PEP 8 style formatting. If you plan to use
Black, Ruff, or YAPF formatting then you must first install the formatter into the Python
you are using with your code, with ``pip`` or other package manager. For example::

  pip install black
  pip install ruff
  pip install yapf

In Wing Pro, this can also be done with the ``Packages`` tool in the ``Tools`` menu.

**Manual Reformatting**

The ``Source > Reformatting`` menu contains items for reformatting the current file or
selection for PEP 8, or with Black, Ruff, or YAPF. 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 > Auto-formatting >
Reformatting Timeout <script:show_preferences_gui#prefname="edit.pep8-timeout">`__
preference. After the timeout is reached, Wing will abort the reformat process and leave
the file unchanged. The default timeout is 5 seconds, to avoid leaving an editor locked
for a long period of time.

Reformatting PEP8 selections in locally stored files is not time-limited, so very large
selections may lock up the IDE until the reformatting operation completes.

**Automatic Reformatting**

Wing can auto-format edited lines after the caret leaves the line, or whole files as they
are saved to disk. This is enabled with the 
~~~if not WING101:
`Auto-Reformat <script:view_project_properties#highlighted_attrib="proj.auto-reformat-enable">`__ 
property under the ``Options`` tab in ``Project Properties``, or with the 
~~~
`Editor > Auto-formatting > Auto-Reformat <script:show_preferences_gui#prefname="edit.pep8-autoformat">`__
preference.

The choices are:

* **Disabled** turns off all automatic reformatting.  This is the default.

* **Lines After Edit** reformats individual logical lines (which may span multiple
  physical lines) after the caret leaves the 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 if the time required to reformat
  it exceeds the `Editor > Auto-Formatting > Reformatting Timeout 
  <script:show_preferences_gui#prefname="edit.pep8-timeout">`__ preference.

The formatter to use in auto-formatting can be selected with the 
~~~if not WING101:
`Reformatter <script:view_project_properties#highlighted_attrib="proj.auto-reformatter">`__ property
under the ``Options`` tab in ``Project Properties``, or with the 
~~~
`Editor > Auto-formatting > Reformatter <script:show_preferences_gui#prefname="edit.pep8-reformatter">`__ 
preference.

The available reformatters are ``PEP 8`` with ``autopep8``, ``Black``, ``Ruff``, and ``YAPF``.

**Configuration**

Wing provides a few commonly used high-level configuration options to control some of
the auto-reformatters on the ``Editor > Auto-formatting`` preferences page. Other
reformatter configuration should be DONE in the reformatter's configuration file.
Setting the
~~~if not WING101:
`Reformatter Run Directory <script:view_project_properties#highlighted_attrib="proj.auto-reformatter-run-dir">`__ property
under the ``Options`` tab in ``Project Properties``, or the 
~~~
`Editor > Auto-formatting > Reformatter Run Directory <script:show_preferences_gui#prefname="edit.reformat-run-dir">`__ 
preference, may be necessary for the reformatter to find its configuration file.

**Encodings**

All the reformatters used by Wing assume ``utf-8`` encoding if not otherwise specified in
a source file with a `PEP 263 <https://www.python.org/dev/peps/pep-0263/>`__ Python
encoding comment. Whole-file reformatting may fail even if Wing correctly guesses the
file's encoding, since the coding comment is the only way to communicate a non-default
encoding to the reformatters.
