<type>documentation</type>
<domain>proj</domain>
<id>project-properties</id>
<title>Project Properties</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

Each project has a set of properties that can be accessed and edited from the
`Project Properties <script:view-project-properties>`__ item in the ``Project`` menu.
These are used to configure the Python environment that is used when debugging, executing,
testing, or inspecting Python code for `source code analysis
<ref:edit/source-code-analysis>`__. Correct configuration of project properties is
important to auto completion, refactoring, error detection, and other features of the IDE.
Project properties are also used to set options for the project, and to enable and
configure extensions for `Django <ref:howtos/django>`__, `matplotlib
<ref:howtos/matplotlib>`__, and `Zope <ref:howtos/zope>`__.

Any string value for a property may contain environment and special variable 
references, as described in `Environment Variable Expansion <ref:proj/variable-expansion>`__.

Environment
...........

The following properties control the Python environment:

**Python Executable** specifies the full path to the Python executable that
should be used with the source code in this project.  When ``Use default`` is selected,
Wing tries to use the Python started by typing ``python`` on the command line.  On OS X,
Wing prefers the latest Apple-provided Python.  If this fails, Wing will search for Python
on the ``PATH`` (on Linux and OS X) or in the registry (on Windows).

To use Wing with ``virtualenv`` just set this property to the Python executable provided
by ``virtualenv``.

An easy way to get the full path to use here is to type ``import sys;
print(sys.executable)`` in the Python you wish to use. This can also be done in the
copy of IDLE that is associated with the Python installation.

~~~if WINGPRO:
In Wing Pro, this property can be used to select a Python to run on a remote host.
When this is done, the default directory used for other fields in ``Project Properties``, 
and for adding files and directories to the project, will be the base directory defined
for the selected remote host.  See `Remote Hosts <ref:proj/remote-hosts>`__ for details.
~~~

**Python Path** sets the ``PYTHONPATH`` environment variable to use whenever Python is
launched for debugging, execution, unit testing, or running the Python Shell. When ``Use
default`` is selected, the ``PYTHONPATH`` environment variable inherited by Wing at
startup is used. Otherwise, when ``Custom`` is selected, the specified ``PYTHONPATH`` is
used instead.

Setting this property is usually only necessary if your code changes ``sys.path`` at
runtime in a way that Wing can't auto-detect or if it depends on ``PYTHONPATH`` being set
from the outside. You should not add Python standard library directories here. Python
already knows those and Wing will be able to obtain them by inspecting your selected
``Python Executable``.

This property allows displaying the entered Python Path either as a list or as text
using the path separator appropriate for the OS.  If you need to paste in a path,
select ``View as Text`` first and then right-click to ``Paste``.  The path is stored
internally as a list, so the same configuration can work on multiple OSes.

Both Python and Wing use the selected ``PYTHONPATH`` to locate modules that are imported
with the ``import`` statement. If necessary directories are missing from the configured
path, Python will raise ``ImportError`` for modules it cannot find, and Wing will fail to
provide auto-completion, goto-definition, and other code intelligence on imported modules.

**Environment** is used to specify values that should be
added, modified, or removed from the environment used for debugging and executing
code from Wing, including also when running unit tests or version control commands.
The values defined here are also used to expand `environment variable
references <ref:proj/variable-expansion>`__ used in other properties.  

Each entry is in ``var=value`` form, without any quotes around the value, and must be
specified one per line. An entry in the form ``var=`` (without a value) will remove the
given variable so it is undefined.

Note that you are operating on the environment inherited by the IDE when it started 
and not modifying an empty environment.  On OS X the environment inherited by Wing 
may differ according to whether you launched Wing from the command line or with 
the Finder.  

When ``Use inherited environment`` is selected, any entered values are ignored and the
inherited environment is used without changes.

**Analyze main entry point for sys.path changes** controls whether
Wing tries to find changes to ``sys.path`` in your main entry point.  It does nothing
if you have not set a main entry point from the ``Debug/Execute`` tab in ``Project 
Properties``.

Debug/Execute
.............

The following properties control environment for debugged and executed code:

**Main Entry Point** defines where execution starts when the debugger is
launched from the IDE.  The default is to start debugging in the current editor
file.  Alternatively, use this property to select a file or `named entry point 
<ref:debug/named-entry-points>`__ where debug should always start, regardless of 
which file is current in the editor.  

For files, the debug environment defined in ``Project Properties`` may be overridden by
clicking on the file and selecting ``Properties``.

**Initial Directory** sets the initial working directory used for debugging and executing
code. When ``Use default`` is selected, this will be the directory where the debugged or
executed file is located. When ``Custom`` is selected, the specified directory is used
instead. Use ``$(WING:PROJECT_DIR)`` for the project's directory.

This property also sets the initial directory for the `Python Shell
<ref:debug/python-shell>`__, determines how Wing resolves partial paths on the
``Python Path`` for `source code analysis <ref:edit/source-code-analysis>`__, and defines
the default initial directory used in `OS Commands <ref:oscommands/index>`__. For these,
Wing will use the directory of the ``Main Entry Point`` in the project as the default
initial directory, or the directory of the project file if there is no defined main entry
point.

**Build Command** specifies a command to execute before starting debug. This is useful
to make sure that extension modules, Cython modules, and other compiled build targets are
rebuilt before each run. The build is configured and run by the `OS Commands
<ref:oscommands/index>`__ tool.

**Python Options** specifies the command line options sent to the Python
interpreter while debugging or executing code. The default of ``-u`` sets Python into
unbuffered I/O mode, which ensures that the debug process output, including prompts shown
for keyboard input, will appear in a timely fashion.

Note that these are *not* the command line arguments to send to your code, but instead
options sent to Python itself. To send arguments to your code, select ``Debug
Environment`` from the ``Debug`` menu. Alternatively, right-click on the Python file,
select ``Properties``, and then set ``Run Arguments`` under the ``Debug/Execute`` tab.

**Debug Server Port** sets the TCP/IP port on which the debugger listens
for externally initiated debug processes. Using this allows multiple instances of Wing
using different projects to concurrently listen for and accept externally initiated debug
connections. See `Advanced Debugging Topics <ref:debug/advanced>`__ for details.

**Automatic Perspectives** can be enabled to cause Wing to create and automatically
switch between the ``Edit`` and ``Debug`` perspectives when debugging is stopped
and started.  See `Perspectives <ref:custom/perspectives>`__ for details.

Options
.......

The following project options are provided:

~~~if WINGPRO:
**Project Type** (Wing Pro only) selects whether or not the project
will be shared among several developers. When shared, the project will be written to two
files, ``*.wpu`` and ``*.wpr``. The latter can be checked into revision control and used
by other developers or on other machines. See `Project Types`__ for details.
~~~

**Default Encoding** sets the text encoding to use for files whose encoding
cannot be determined from the contents of the file. This applies to all files edited when
the project is open, whether or not they are part of the project. By default, this falls
back to the value set by the `Files > Default Encoding
<script:show_preferences_gui#prefname='edit.default-encoding'>`__ preference.

**Project Home Directory** sets the base directory for the project. This overrides the
project file location as the directory on which to base relative paths shown in the
``Project`` tool and elsewhere. It is also used as the default directory in which the
`Python Shell <ref:debug/python-shell>`__ subprocess is launched and for the
starting directory when the `Files > Default Directory Policy
<script:show_preferences_gui#prefname="main.start-dir-policy">`__ preference is set to
``Use Project's Home Directory``.

**Preferred Line Ending** and **Line Ending Policy** control whether or not the project
prefers a particular line ending style, and how to enforce that style, if at all. By
default, projects do not enforce a line ending style but rather insert new lines to match
any existing line endings in the file, and for new files Wing uses the `Files > New File
EOL <script:show_preferences_gui#prefname="edit.new-file-eol-style">`__ preference.

**Preferred Indent Style** and **Indent Style Policy** control whether or not the project
prefers a particular type of indentation style for files, and how to enforce that style,
if at all. By default, projects do not enforce an indent style but rather insert new lines
to match any existing indentation in the file, and for new files Wing uses the `Editor >
Indentation > Default Indent Style
<script:show_preferences_gui#prefname="edit.indent-style">`__ preference.

**Strip Trailing Whitespace** controls whether or not to automatically remove whitespace
at the ends of lines when saving a file to disk. By default, this falls back to the
`Editor > Strip Trailing White Space
<script:show_preferences_gui#prefname="main.auto-rstrip-on-save">`__ preference.
  
~~~if WINGPRO:
__ ref:proj/project-types
~~~
  
Extensions
..........

These properties are used to control and configure framework-specific extensions:

**Enable Django Template Debugging** enables `Django <ref:howtos/django>`__-specific 
functionality that makes it possible for Wing's debugger to stop at breakpoints and step 
through Django template files.

**Matplotlib Event Loop Support** enables `Matplotlib <ref:howtos/matplotlib>`__-specific
event loop support that updates plots continuously when working interactively in the
`Python Shell <ref:debug/python-shell>`__.

**Enable Zope2/Plone Support**, **Zope2 Instance Home**, and **Zope2 Host** enable legacy
support for older Zope installations. They are needed because Zope 2.x implemented import
magic that works differently from Python's ``import``. Wing's source analyzer needs this
extra clue to find and inspect source files.

When this option is activated, Wing will also offer to add the relevant Zope2/Plone files
to the project, and to install the control panel for configuring and initiating debug in
Zope2/Plone. See the `Zope How-To <ref:howtos/zope>`__ for details.

Note that this option is no longer needed in Zope 3+.

~~~if WINGPRO:
Testing
.......

In Wing Pro, these options control Wing's integrated unit testing support:

**Test File Patterns** specifies which files in the project should be shown as unit tests
in the `Testing <ref:testing/index>`__ tool.  Files may be selected by using any combination
of wildcards and/or regular expressions that are matched with the full path of all the
files in the project.

**Default Test Framework** defines the testing framework to use for test files that do not
specify another framework in their `File Properties <ref:proj/file-properties>`__.

**Environment** can be used to select environment for running unit tests
that differs from the environment configured in ``Project Properties``.  This
also allows setting command line arguments to send to all unit tests.  

Use `File Properties <ref:proj/file-properties>`__ on an individual test to set
different arguments for each test.

**Process Model** specifies whether Wing should start one test process for each
test module, or one for each test package.  Different testing frameworks and 
test suites may require one or the other approach.

**Number of Processes** sets the number of test processes that Wing will run
concurrently.  Setting this to a value greater than ``1`` will allow Wing to take
advantage of multiple CPU cores, although it can also cause problems if tests
assume they are run in a series.

**Run as Package Modules** controls whether a test file in a package is run as
part of a package or as a stand-alone module.  The default depends on the requirements
of each unit test framework, and some unit test frameworks ignore this setting.

**Save in Project File** chooses how much of the test results shown in the ``Testing``
tool are saved into the project file for redisplay in future sessions.  Wing can
save all results and output, only results to avoid storing large amounts of output,
or no results or output.

VCS
...

In Wing Pro, this tab can be used to override the `Version Control
<script:show_preferences_gui#prefname="versioncontrol.enable-non-script">`__ 
preferences:

**Version Control** selects whether to use preferences settings, override preferences and
disable version control entirely, or select another version control configuration. This is
used most often when working with a `remote host <ref:proj/remote-hosts>`__ that requires
different version control settings than the local host.

~~~
