<type>documentation</type>
<domain>scripting</domain>
<id>project</id>
<title>API Reference - Project</title>
<product>per+</product>


Class CAPIProject
=================

API to access the project.  This class should not be instantiated directly.
Use ``CAPIApplication.GetProject()`` instead.

**Signals**

A callback can be connected to the following signals using ``Connect(signal, cb)``:
    
  ``destroy``: The project is closing.  Calls ``cb(proj:CAPIProject)``.
  
  ``files-added``: Files have been added. Calls ``cb(filenames)`` where ``filenames`` is
  a list of full paths. File names starting with ``ssh:`` are on a remote host. Use
  ``IsUrl`` to distinguish between urls and local file names.
  
  ``files-removed``: Files have been removed.  Calls cb(filenames) where ``filenames``
  is the same as for the ``files-added`` signal above.

Use ``Disconnect(signal_id)`` to preemptively disconnect a signal handler, where
``signal_id`` is the signal ID previously returned from ``Connect``.


Project Contents
================

**CAPIProject.GetAllFiles()**

Returns a list of all the full path filenames in this project.

File names starting with ``ssh:`` are on a remote host. Use ``IsUrl`` to distinguish
between urls and local file names. 

**CAPIProject.GetAllDirectories(top_only=False)**

Get list of full path names for all directories in this project.

If ``top_only`` is ``True``, only top-level directories are returned.

Directory names starting with ``ssh:`` are on a remote host. Use ``IsUrl`` to
distinguish between urls and local file names.

**CAPIProject.AddFiles(files)**

Add the files with given full path filenames to the project.

**CAPIProject.RemoveFiles(files)**

Remove the given full path filenames from the project.

**CAPIProject.AddDirectory(dirname, recursive=True, filter='*', include_hidden=False, watch_disk=True, excludes=())**

Add the given directory to the project, given its full path name.

When ``recursive`` is ``True``, all children, grand-children, etc, are also added.

The ``filter`` specifies which files to display.

Set ``include_hidden`` to ``True`` to show also hidden files like ``.name``,
``*pyc``, and ``*~``.

Set ``watch_disk`` to watch the disk for changes and update the ``Project`` tool
accordingly.

Set ``excludes`` to a list of relative path names from ``dirname`` for files to
explicitly exclude from the display.

If the directory is already in the project this call will replace it properties
according to the arguments.

**CAPIProject.RemoveDirectory(dirname)**

Remove the given directory, and any recursively added sub-directories, from the
project.


Project Properties
==================

**CAPIProject.GetEnvironment(filename=None, set_pypath=True, overrides_only=False)**

Get the runtime environment for the given debug file in the context of this
project. This is determined by overriding the environment inherited at startup with
any values set in ``Project Properties`` and ``File Properties``.

If the given ``filename`` is ``None``, only the project-wide settings are used.

If a ``Python Path`` is set in ``Project Properties`` and ``set_pypath`` is True, it
is added to the environment as ``PYTHONPATH``, overwriting any ``PYTHONPATH`` in the
inherited environment.

When ``overrides_only`` is ``True``, this call only returns the environment that is
configured for the given file (or project-wide if ``filename`` is ``None``) and not
inherited environment values. This result can be used as the basis for calling
``SetEnvironment``.

**CAPIProject.ExpandEnvVars(txt, filename=None)**

Expand ``$(envname)`` and ``${envname}`` style environment variables within the
given text in the context of the environment returned by ``GetEnvironment(filename,
set_pypath=False)``.

**CAPIProject.SetEnvironment(filename, base, env={})**

Set the runtime environment for debugging or executing the given file or for the
project as a whole if filename is ``None``.

The argument ``base`` indicates which base environment the given environment should
modify:

  ``'startup'``: Modify startup environment
  
  ``'project'``: Modify the project environment (not a valid value when ``filename``
  is ``None``)

In either case, the given ``env`` is applied to the selected base environment by
removing any keys with empty values and adding/updating any keys with non-empty
values.  If the order of the environment keys is important, use collections.OrderedDict
for the value of this argument.

If ``PYTHONPATH`` is included in the environment, it is stored in (or cleared from)
the ``Python Path`` property in ``Project Properties`` or ``File Properties`` and not
the ``Environment`` property.

Using ``SetFileLaunchConfig`` and related API is preferable when ``filename`` is not
``None``.

**CAPIProject.GetPythonExecutable(filename)**

Get the Python executable set for the given file or the project as a whole
if the ``filename`` is ``None``.

Returns ``None`` if using the inherited value, which is the project-wide value for a
file, and the default found Python for a project (when ``filename`` is ``None``). The
default Python can be determined with ``CAPIApplication.FindPython``.

``GetFileLaunchConfig`` and related API is preferable when ``filename`` is not ``None``.

The executable can be on a remote host, in which case this function returns a value in
the form ``ssh://hostname/`` where ``hostname`` is the ``Identifier`` of the `Remote
Host <ref:proj/remote-hosts>`__ that specifies which Python to use.

The executable may be a command that activates a virtualenv or other environment.
In this case, the value returned is in the form ``env://command_line``. 

If executable includes arguments, spaces within arguments are managed by escaping them
with \ or by delimiting arguments with quotes.

**CAPIProject.SetPythonExecutable(filename, executable)**

Set the Python executable to use when debugging or executing the given file. The
filename may be ``None`` to set the project-wide ``Python Executable``. The executable
may be ``None`` to use the project-wide value or default found Python.

The executable can be a url in the form ``ssh://hostname/`` (without any additional
url path) to use the Python specified by the `Remote Host <ref:proj/remote-hosts>`__
for ``hostname``. In this case, if a non-``None`` filename is given it must also be a
file on that remote host, using a url in the form ``ssh://hostname/path/to/file.py``.

The executable may be a command that activates a virtualenv or other environment,
in which case it is in the form ``env://command_line``.

If the executable includes arguments, spaces within the command line must be managed
by escaping them with \ or delimiting arguments with quotes.

Using SetFileLaunchConfig() and related API is preferable when ``filename`` is
not ``None``.

**CAPIProject.GetPythonExecutableProperties(executable=None)**

Get information about the default Python executable or a given Python
executable. If the executable argument is None, the default executable
for the project will be used; otherwise the argument is a str in the same
format as for SetPythonExecutable.

On success, the return value is a dictionary containing the following values:

  fullpath    : The full path to the interpreter's 'python.exe' or 'python'
  version     : The Python version in #.#.# form
  prefix      : The value of sys.prefix
  baseprefix  : The value of sys.base_prefix
  pypath      : The builtin Python Path (an item set to None indicates current directory)
  keywords    : The keywords in this Python version
  builtins    : The builtins in this Python version
  
Each of these values is None if the executable was not found or is invalid.

If the interpreter has not yet been inspected then None is returned instead of a
dictionary. In this case, an inspection is launched and this method may be called
again later to obtain the values.

**CAPIProject.GetInitialDirectory(filename)**

Get the initial directory for debugging the given file. The ``filename`` may be
``None`` to set the project-wide setting. Returns ``None`` when using the startup
directory.

Using ``GetFileLaunchConfig`` and related API is preferable when ``filename``
is not ``None``.

**CAPIProject.SetInitialDirectory(filename, dirname)**

Set the initial directory to use when debugging the given file. The ``filename``
may be ``None`` to set the project-wide setting. The ``dirname`` may be ``None`` to
use the startup directory.

Using ``SetFileLaunchConfig`` and related API is preferable when ``filename`` is not
``None``.

**CAPIProject.GetMainEntryPoint()**

Get the full path for the main entry point for this project. This returns a string
in the form ``"entry:name"`` if the main entry point is a `Named Entry Point
<ref:debug/named-entry-points>`__, or ``None`` if there is none, in which case
debugging and execution start with the current editor file.

**CAPIProject.SetMainEntryPoint(filename)**

Set the main entry point for this project. Pass in a full path, a string in the form
``"entry:name"`` to use a `Named Entry Point <ref:debug/named-entry-points>`__, or
``None`` to unset the main entry point so that debugging and execution start with
the current editor file.

**CAPIProject.SetDebugChildProcesses(enable=True)**

Enable or disable child process debugging in this project. Set ``enable`` to
``True`` to always debug child processes, ``False`` to never debug child processes,
and ``None`` to refer to the `Debugger > Processes > Debug Child Processes
<script:show_preferences_gui#prefname="debug.multi-process-debug-sub-processes">`__
preference.


Launch Configurations
=====================

**CAPIProject.GetLaunchConfigs()**

Get a list of the internal IDs for all the defined `Launch Configurations
<ref:proj/launch-configs>`__ in the project.

**CAPIProject.CreateLaunchConfig()**

Create a new `Launch Configuration <ref:proj/launch-configs>`__. Returns the launch
configuration's internal ID.

**CAPIProject.GetLaunchAttrib(launch_id, attrib, include_hostname=False)**

Get a `Launch Configuration <ref:proj/launch-configs>`__ attribute.

``launch_id`` is the internal launch configuration ID.

``attrib`` is the attribute to get, which may be one of the following.  The
return value varies in type, according to which attribute was retrieved:

  ``name``: The display name of the launch configuration.
  
  ``runargs``: The run arguments as a string.
  
  ``rundir``: ``(which, value)`` where ``which`` is one of ``'project'`` to use the
  project-defined value, ``'default'`` to use the directory of the file being
  launched, or ``'custom'`` to use the specified string ``value``.
                
  ``env``: ``(which, env)`` where ``which`` is one of ``'project'`` to use the
  project-defined value, ``'merge'`` to use env to add/remove from the project-defined
  value, ``'default'`` to use the startup environment, or ``'custom'`` to use ``env``
  to add/remove from the startup environment. ``env`` is a list of ``var=value``
  strings where ``value`` can be blank to remove the named ``var`` from the modified
  environment.
                
  ``buildcmd``: ``(which, value)`` where ``which`` is one of ``'project'`` to use the
  project-defined value, ``'default'`` to use no build command, or ``'custom'`` to use
  the specified value, which is the OS Command internal ID for a build command defined
  with ``CAPIApplication.AddOSCommand`` or by the user in the ``OS Commands`` tool.
                
  ``pyexec``: ``(which, pyexec)`` where ``which`` is one of ``'default'`` to use the
  project-defined value, or ``'custom'`` to use given ``pyexec`` string. When arg
  ``include_hostname`` is ``True``, this is instead in the form ``(which, (hostname,
  pyexec))`` where hostname is ``''`` to indicate localhost.
                
  ``pypath``: ``(which, value)`` where which is one of ``'project'`` to use the
  project-defined value, ``'default'`` to use the startup value, or ``'custom'`` to
  use the specified ``value``, which is a list of strings.
                
  ``pyrunargs``: ``(which, value)`` where ``which`` is one of ``'project'`` to use the
  project-defined value, ``'default'`` to use ``'-u'``, or ``'custom'`` to use the
  specified string value
                
  ``shared``: ``True`` or ``False``, to indicate whether the launch configuration is
  shared between all projects.

Any string value can contain environment variable references in the form
``${ENVNAME}`` or ``$(ENVNAME)``.

Raises ``KeyError`` if the specified launch configuration does not exist.

Compatibility note:

In Wing 6+ the pyexec attribute stored by Wing internally changed from ``(which,
pyexec``) to ``(which, (hostname, pyexec))`` where hostname is ``''`` for localhost.
Set ``include_hostname=True`` to receive that form in the return value.

In Wing 6+ the pypath attribute stored by Wing internally changed from a string with
``os.pathsep`` delimiter to a list of strings.

**CAPIProject.SetLaunchAttrib(launch_id, attrib, value)**

Set a single `Launch Configuration <ref:proj/launch-configs>`__ attribute.

``launch_id`` is the internal launch configuration ID to modify.

See ``GetLaunchAttrib`` for the valid attribute names and values. It is up to the
caller to validate the values specified.

Raises ``KeyError`` if the specified launch configuration does not exist.

**CAPIProject.DeleteLaunchConfig(launch_id)**

Delete the given `Launch Configuration <ref:proj/launch-configs>`__. Any files or
`Named Entry Points <ref:debug/named-entry-points>`__ that reference the
configuration will revert to using the project-defined environment.

**CAPIProject.GetFileLaunchConfig(filename)**

Get the internal ID of the `Launch Configuration <ref:proj/launch-configs>`__ used
by default with the given filename. Returns ``None`` if the project-wide configuration
is being used.

**CAPIProject.SetFileLaunchConfig(filename, launch_id)**

Set the default `Launch Configuration <ref:proj/launch-configs>`__ to use with the
given file.

``filename`` is the full path of the file or a URL in form
``ssh://hostname/path/to/file.py`` for remote files, where ``hostname`` is the
``Identifier`` of a `Remote Host <ref:proj/remote-hosts>`__.

``launch_id`` is the internal launch configuration ID.

**CAPIProject.ClearFileLaunchConfig(filename, runargs)**

Clear the default `Launch Configuration <ref:proj/launch-configs>`__ for the given
file so that launching the file will use the project-defined environment and the given
``runargs``.

``filename`` is the full path of the file or a URL in form
``ssh://hostname/path/to/file.py`` for remote files, where ``hostname`` is the
``Identifier`` of a `Remote Host <ref:proj/remote-hosts>`__.

``runargs`` are the run arguments to use, as a string.


Named Entry Points
==================

**CAPIProject.GetNamedEntryPoints()**

Get a list of names for all the defined `Named Entry Points
<ref:debug/named-entry-points>`__ in the project.

**CAPIProject.CreateNamedEntryPoint(name)**

Create a new `Named Entry Point <ref:debug/named-entry-points>`__. Raises
``KeyError`` if the name already exists.

**CAPIProject.GetNamedEntryPointAttrib(name, attrib)**

Get an attribute for the given `Named Entry Point <ref:debug/named-entry-points>`__.
The valid attribute names are as follows.  The return value varies in type, according
to which attribute is being retrieved:

  ``filename``: The Python file to launch. This is the full path or a URL in the form
  ``ssh://hostname/path/to/file.py`` for remote files where ``hostname`` is the
  ``Identifier`` of a `Remote Host <ref:proj/remote-hosts>`__.
  
  ``runargs``: The command line arguments to use when the named entry point's
  ``launch-id`` is ``None``. This valuecan contain environment variable references in
  the form ``${ENVNAME}`` or `` $(ENVNAME)``.
  
  ``launch-id``: The internal ID of the `Launch Configuration
  <ref:proj/launch-configs>`__ to use, or ``None`` to use the project-defined
  environment with the command line arguments in the ``runargs attribute``.
                          
  ``key-binding-debug``: The key binding for debugging the Launch Configuration.
  See `Key Names <ref:custom/key-names>`__ for details on valid key names.
  
  ``key-binding-execute``: The key binding for executing the Launch Configuration.
  
  ``auto-show``: ``True`` when the named entry point dialog should be shown
  automatically before launching.

Raises ``KeyError`` if the named entry point does not exist.

**CAPIProject.SetNamedEntryPointAttrib(name, attrib, value)**

Set a `Named Entry Point <ref:debug/named-entry-points>`__ attribute.  ``name``
is the entry point's name.

See ``GetNamedEntryPointAttrib`` for the valid attribute names and values. It is up to
the caller to validate the values specified.

Raises ``KeyError`` if the named entry point does not exist.

**CAPIProject.DeleteNamedEntryPoint(name)**

Delete the given `Named Entry Point <ref:debug/named-entry-points>`__.


Attributes

Use these to store information in a project file.

**CAPIProject.GetAttribute(attrib_name, filename=None)**

Get the value for given named attribute previously set with ``SetAttribute``.

If ``filename`` is not ``None``, the attribute is a per-file attribute for the given
file. Otherwise, it's a project-wide attribute.

Raises ``KeyError`` if the attribute is not defined.

**CAPIProject.SetAttribute(attrib_name, value, filename=None)**

Set value for the given attribute. This is used to store data in the project file.
Attributes may either be associated with the project as a whole or with a particular
file.

``attrib_name`` is the attribute name, which can be any string containing letters,
numbers, and dashes.

The ``attrib_name`` is uniquified internally to avoid conflicts between scripts. If
this is not desired, so that other scripts can also access the attribute, prefix the
``attrib_name`` with '.'.

If ``filename`` is not ``None``, the attribute is a per-file attribute. Otherwise,
it's a project-wide attribute.


Utilities
=========

**CAPIProject.GetFilename()**

Gets the filename where the project is stored, as a full path.  Returns the ``*.wpr`` file's
name.  If the project is a shared project, a file ``*.wpu`` in the same 
directory will also exist and contain user-specific project state.

For untitled or scratch buffers, the file name is prefixed with ``unknown:``. For
remote files, the file name will be a URL. Use ``IsUrl`` to distinguish between file
names and URLs.

**CAPIProject.GetSelectedFile()**

Returns the full path filename of the currently selected file on the ``Project``
tool, or ``None`` if there is no selection.

File names starting with ``ssh:`` are on a remote host. Use ``IsUrl`` to distinguish
between urls and local file names.


Run Arguments
=============

**CAPIProject.GetRunArguments(filename)**

Get the run arguments for debugging the given file, or ``''`` if there
are none. The ``filename`` should not be ``None``.

The value returned may come from the file's launch configuration, if one is being used,
or otherwise from the file properties.

**CAPIProject.SetRunArguments(filename, args, add_recent=True)**

Set the run arguments (as a string) for debugging the given file. Use
``None`` for no arguments.

The value is set into the file's launch configuration, if one is being used,
or otherwise into the file properties.

See ``add_recent`` to ``False`` to prevent adding the arguments to the
recent arguments list.

