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

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

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

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


Deprecated Methods
==================

**CAPIProject.GetRunArguments(filename)**

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

Deprecated in Wing 7.0. Use ``GetFileLaunchConfig``` and related API instead.

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

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

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

Deprecated in Wing 7.0. Use ``SetFileLaunchConfig``, ``ClearFileLaunchConfig``, and
related API instead.

