Wing Python IDE

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 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 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, 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, 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 preference.

Launch Configurations

CAPIProject.GetLaunchConfigs()

Get a list of the internal IDs for all the defined Launch Configurations in the project.

CAPIProject.CreateLaunchConfig()

Create a new Launch Configuration. Returns the launch configuration's internal ID.

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

Get a Launch Configuration 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 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. Any files or 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 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 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.

launch_id is the internal launch configuration ID.

CAPIProject.ClearFileLaunchConfig(filename, runargs)

Clear the default Launch Configuration 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.

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 in the project.

CAPIProject.CreateNamedEntryPoint(name)

Create a new Named Entry Point. Raises KeyError if the name already exists.

CAPIProject.GetNamedEntryPointAttrib(name, attrib)

Get an attribute for the given Named Entry Point. 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.

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

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.