<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.
~~~if WINGPRO:
Project properties are also used to set options for the project, and to enable and
configure extensions for `Django <ref:howtos/django>`__ and `matplotlib
<ref:howtos/matplotlib>`__.
~~~

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 Python executable that should be used with code in
this project. The default is to use Python found on the PATH, or if none is found there
then the latest version found anywhere on the system. Use ``Command Line`` to enter any
command that invokes Python with all provided arguments. This is often set to the
value of ``sys.executable`` (after ``import sys``) in the selected Python.  A list of all
found Python installations is given in the drop down to the right of the entry area.

To use an environment set up by virtualenv or Anaconda, choose ``Activated Env`` to enter
the full path to ``activate`` or ``activate.bat`` for the selected environment. The drop
down menu to the right of this field lists recently used and automatically found
environments.  If the path to the activate script contains spaces, this option will not
work.  In that case, use ``Command Line`` as described above.

~~~if WINGPRO:
In Wing Pro, this property can tell Wing to run Python on a `container
<ref:proj/containers>`__ or `remote host <ref:proj/remote-hosts>`__. On a container, some
of the other properties listed below (as noted) are ignored if the container configuration
does not enable ``Inherit Project Environment``. On a remote host, 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 by the selected remote host.
~~~

When this property invokes Anaconda Python, Wing will automatically run Anaconda's ``activate
base`` before it starts Python. This is needed to avoid failure to import some modules as
a result of missing environment. See About Anaconda Environments in the `Anaconda How-To
<ref:howtos/anaconda>`__ 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.

~~~if WINGPRO:
When using a container as the ``Python Executable``, this property is ignored unless
the container configuration enables ``Inherit Project Environment``.
~~~

**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 macOS 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.

~~~if WINGPRO:
When using a container as the ``Python Executable``, this property is not used for
debug processes, unit tests, or OS Commands running on the container unless
``Inherit Project Environment`` is checked in the container configuration.  
~~~

~~~if WINGPRO:
**Package Manager** selects the package manager to use with this project.  The
default choice of ``Auto-Detect`` looks for ``requirements.txt``, ``poetry.lock``, 
``uv.lock``, and ``Pyfile``
in the same directory as the Wing project file or in the configured ``Project Home
Directory`` (see below) and chooses either ``pip``, ``poetry``, ``uv``, or ``pipenv``, respectively.

**Auto-Update Package Configuration File** chooses whether Wing will automatically manage
the package configuration file when installing, removing, or upgrading packages. For
``pip``, this is the ``requirements.txt`` file. For Poetry, uv, and pipenv, this option is
ignored since those always update their package management files automatically. Wing
expects the package configuration files in the same directory as the Wing project file or
in the directory set with the ``Project Home Directory`` under the ``Options`` tab in
``Project Properties``.

**Uninstall Removes Unused Packages** controls whether Wing uninstalls unused
dependencies after a package is uninstalled.  This includes only packages not 
mentioned in or used by any of the packages listed in the package configuration 
file. 
~~~

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``.

**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 Child Processes** controls whether or not Wing automatically starts debug in child
processes that are launched from a debug process. Choose ``Use Preferences Setting`` to
use the policy set in preferences, and ``Always Debug Child Processes`` or ``Never Debug
Child Processes`` to enable or disable child process debugging in all cases for this
project, regardless of the preferences setting. See `Debugging Child Processes
<ref:debug/child-processes>`__ for details.

**Initial Directory** sets the initial working directory used for debugging and executing
code. When ``Use default`` is selected and the file is launched as a script, this will
be the directory where the debugged or executed file is located. When ``Use Default``
is selected and the file is launched with ``python -m``, this will be the directory where
the top level module or containing package 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 File 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.

**Auto-reformat** and **Reformatter** select when and how to auto-reformat Python code.
See `Auto-Reformatting <ref:edit/auto-reformatting>`__ for details.

**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
~~~

~~~if WINGPRO:  
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>`__.

Testing
.......

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

**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>`__.

**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.

**Output Wrap Column** specifies at which column to wrap output from tests, when shown
in the ``Testing`` tool.

**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.

~~~
