Using Wing Pro with Docker Compose
Wing Pro is a Python IDE that can be used to develop, test, and debug Python code running on clusters that are orchestrated by Docker Compose.
This document describes how configure Wing Pro in order to use Docker Compose for Python development.
Getting Started
Before you can work with Docker Compose you will need to download and install it. See Install Docker Compose for details.
You should also install Wing Pro if you don't already have it.
Configuration Overview
To configure Wing to use a Docker Compose cluster, select Cluster for the Python Executable, either in the New Project dialog or Project Properties (both from the Project menu).
In the New Project dialog, this is found under Use Existing Python on the second dialog page, after you have selected your source directory.
In the Project Properties dialog, it is under the Environment tab.
After selecting Cluster for Python Executable, create a new cluster configuration by pressing the New button. This displays the cluster configuration dialog. You will need to enter an identifier to use within Wing and point it at the docker-compose.yml file for the cluster.
You will also need to select the main service to use as the default place to run your Python Shell and unit test processes. Note, however, that both the shell and tests can be configured to run either in synthesized out-of-cluster copies of a cluster service, or on specific services after the cluster as a whole is launched. This is described in more detail in Execution Context below.
Once you have created your cluster configuration, submit the New Project or Project Properties dialog to complete your project setup.
Controlling the Cluster
You can now control your cluster from Wing's Containers tool, found in the Tools menu. The top part of this tool shows the overall status of the cluster and provides buttons for building, starting, debugging, and stopping your cluster.
The Containers tool also lists the services in the cluster and their status. You can right-click on items in the services list to view their configuration in the docker-compose.yml file.
When Show Synthesized Containers is checked in the tool's Options menu, the list of services will include out-of-cluster containers that Wing synthesizes and starts, for example to run the Python Shell or unit tests.
When the Show Console item in the Options menu is checked, the bottom of the tool shows a console containing the output of the docker-compose commands that Wing is running behind the scenes.
Debugging the Cluster
There are several ways to debug code in a cluster managed by Docker Compose:
(1) The most common way to debug a cluster is to select the services that should be debugged in the services list within the Containers tool. Then press the Debug button. Wing launches the cluster in such a way that all Python code run in the selected services will be debugged.
(2) Another way to debug code in a cluster is to first start the cluster as a whole without debug by pressing Start in the Containers tool. Additional processes can be then started and debugged in-cluster by setting up a Named Entry Point from the Debug menu and configuring those to launch code in-cluster. This is done by setting the Python Executable in the associated launch configuration to Cluster, selecting the cluster configuration and service, and checking the In-Cluster checkbox. See Named Entry Points for more information.
(3) It is also possible to debug code in a synthesized out-of-cluster copy of a container. This is useful if the container environment as a whole is not needed by that code, and can be accomplished in the same way as in option (2) above, but by unchecking the In-Cluster checkbox.
Execution Context for Other Processes
Other processes started by Wing may also be run either on a synthesized out-of-cluster copy of a selected container service, or on the live service in-cluster after the cluster as a whole has been started.
Python Shell
By default, Wing starts the Python Shell on a synthesized out-of-cluster copy of the service you selected as you main service during cluster configuration. This can be changed with Use Environment in the Python Shell's Options menu. From here, a launch configuration may be defined that selects Cluster for Python Executable and checks on the In-Cluster checkbox.
Unit Tests
Unit tests work in a similar way: The testing environment can be set up with Environment under the Testing tab in Project Properties, or in the properties set by right-clicking on an individual test file.
OS Commands
The OS Commands tool can also run commands either out-of-cluster or in-cluster. For command lines, this is done by setting the Execution Context under the Environment tab of the OS Command configuration. For Python files, the environment set in the file's properties is used, or you can define a Named Entry Point that pairs a Python file with the desired launch configuration.
For more information on using clusters in Wing, see Working with Clusters.
How it Works
Whole-cluster debug is implemented by creating a derived docker-compose.yml file that mounts Wing's debugger into the container, and also a site-packages/sitecustomize directory that imports wingdbstub in order to initiate debug back to the IDE as soon as Python starts.
Wing also takes care of all the associated configuration for the debugger, including establishing the network connection and mapping between local and container side copies of source files.
Related Documents
For more information see:
- Docker home page provides downloads and documentation.
- Working with Clusters for more information on using clusters with Wing Pro.
- Quickstart Guide contains additional basic information about getting started with Wing Pro.
- Tutorial provides a gentler introduction to Wing Pro's features.
- Wing Pro Reference Manual documents Wing Pro in detail.
