Wing IDE Reference Manual
Version 1.1.10

5. Source Code Browser

This chapter describes the source code browser, which is available only in Wing IDE Standard and higher. The browser acts as an index to your source code, supporting inspection of collections of Python source code from either a module-oriented or class hierarchy-oriented standpoint.

The source code browser is divided into three panels: (1) a hierarchical list view, (2) a panel of display filter options, and (3) an embedded information display area. These panels can be resized by dragging on the seperator handles between them.

5.1 Display Choices

The source code browser offers three ways in which to look at your body of source code. These are selected using the radio buttons along the top edge of the class browser window.

5.1.1 Viewing by Module

Viewing by module shows all files that you have placed into your project file within the top major panel of the source code browser window. This module list is a hierarchical expandable tree view that shows all modules, directories, and packages at the top level in alphabetical order. These major units are defined as follows:

• Packages are directories that contain a number of files and a special file __init__.py. This file contains a special variable __all__ that lists the file-level modules Python should automatically import when the package as a whole is imported. See the Python documentation for additional information on creating packages, or look at the Wing source code for examples.

• Directories found in your project that do not contain the necessary __init__.py file are listed as 'directory' rather than 'package' in the source browser window.

• Python files found at any level are denoted as 'module'.

Within each top-level package, directory, or module, the browser will display all sub-modules, sub-directories, modules, and any Python constructs. These are all labeled by generic type, including the following types:

• variable - a variable defined at the top-level of a Python module
• function - a function defined at the top-level of a Python module
• class - an object class found in Python source
• method - a class method
• attribute - an class or instance attribute

5.1.2 Class Hierarchy

When viewing by class hierachy, the browser replaces the hierarchical tree view with a list of all top-level classes found in analyzed code, in alphabetical order.

In this display mode, the structure on disk of your packages, directories, and modules is completely hidden from view. Instead, the hierarchy of your classes is displayed, starting at base classes and working downward to derived classes.

Within each class, in addition to a list of derived classes, the methods and attributes for the class are shown.

5.1.3 All Classes

In order to find classes by name more easily, the browser can be asked to display a list that includes all found Python classes. In this case, all classes (and not just base classes) are displayed at the top-level of the hierarchical viewer.

This view is otherwise identical to the Class Hierarchy view.

5.1.4 Keyboard Navigation

Once it has the focus, the browser tree view is navigable with the keyboard, using the up/down arrow keys, page up and page down, home/end, and by using the right arrow key on a parent to expand it, or the left arrow key to collapse a parent. Holding down the shift key while pressing the right arrow will expand recursively below the expansion point. Recursive expansion is capped at five additional levels for each operation to avoid difficult-to-detect infinite recursions. Whenever a tree row is selected, pressing enter or return will open the source view for the selected symbol in a seperate window, selecting the point of definition for that symbol.

The source code analyzer will run in the background from the time that you open a project until all files have been analyzed. You may notice this overhead during the first 5 to 30 seconds after you have opened your project, depending on the size of your source base. Until analysis is complete, the class-oriented view within the browser window will only include those classes that have been analyzed. This list is updated as more code is analyzed.

5.2 Display Filters

A number of options are available for filtering the constructs that are presented by the source code browser. These filters are organized into two major groups: (1) construct scope and source, and (2) construct type.

5.2.1 Construct Scope and Source

The following distinctions are made. Constructs in each category can be shown or hidden as a group:

• Public - Constructs for public use by any importer of a module or instantiator of an instance. These are names that have zero leading underscores, such as Print() or kMaxListLength.
• Private - Constructs intended to be private to a module or class. These are names that have two leading underscores, such as __ConstructNameList() or __id_seed. Python enforces local-only access to these constructs in class methods (see the Python documentation for details).
• Semi-Private - Constructs intended for use only within related modules or from related or derived classes. These are names that have one leading underscore, such as _NotifyError() or _gMaxCount. Python doesn't enforce usage of these constructs, but they are helpful in writing clean, well-structured code and are recommended in the Python language style guide.
• Inherited - Constructs inherited from a super-class.
• Imported - Constructs imported into a module with an import statement.

5.2.2 Construct Type

Constructs in the source code browser window can also be shown or hidden on the basis of their basic type within the language:

• Classes - Classes defined in Python source.
• Methods - Methods defined within classes.
• Attributes - Attributes (aka 'instance variables') of a class. Note that these can be either class-wide or per-instance, depending on whether they are defined within the class scope or only within methods of the class.
• Functions - Non-object functions defined in Python source (usually at the top-level of a module).
• Variables - Variables defined anywhere in a module, class, function, or method (but not including function or method parameters).
• Derived Classes - Classes which descend from another class; this controls whether or not a class' derived classes are shown within its scope.

5.3 Sorting

In all the display views, the ordering of constructs within a module or class can be controlled by the radio buttons labeled 'Sort'.

• Alphabetically - Displays all entries within each expanded portion of the tree in alphabetic order, regardless of type.
• By Type - Sorts each expanded portion of the tree first by construct type, and then alphabetically.

Sorting doesn't affect the top-level of the hierarchical list view, which is alphabetic in all cases.

5.4 Embedded Information Display

The tabbed area at the bottom of the source code browser can be used to view information about items selected in the hierarchical list view above.

5.4.1 Documentation

When the Documentation tab is selected, the source code browser will display any available Python 'doc string' information for the construct selected in the hierarchical list view above.

This only contains information when a doc string is defined and only works for packages, modules, classes, functions, and methods (and never for variables or attributes).

5.4.2 Source Display

When the Source tab is selected, the source code browser will display the source at point of definition of the selected construct.

The source view is a fully functional source code editor. If you make changes here, any additional view of that source will be updated.

You may be asked to save changes if you navigate to another source file after making an edit, since the source files are closed if there isn't another view to them open in another window.

You can disable tracking of your selection in the hierarchical list area by unchecking the 'Follow Selection' check box that is displayed under this tab. Otherwise, the source code view will scroll to position as you change your selection above.

5.5 Navigating to Source

A number of options are available for navigating around source from the browser window:

• In order to switch to a full editor window containing the source file for any construct in the hierachical list view, right-click on the construct in the list view and select the Goto Source menu item.
• For classes that have inherited classes, the right-click popup obtained in this way will also contain one item for each base class, allowing navigation within the hierarchical list view upwards to the location at which the base class is defined.

5.6 Preferences

The following preferences are available for control source code analysis and the source browser:

• pysource.builtin-interfaces-dir - Name of the directory with interface files for built-in modules. If a partial path is given, it will be interpreted as relative to WINGHOME. Default='src/pysource/builtin-pi-files'
• pysource.analyze-in-background - Whether or not Wing should should analyze python source in the background. Default=true
• pysource.instance-attrib-scan-mode - How Wing will scan for instance attributes. The scan either covers only the __init__ method or all methods in each class. Valid values are 'init-only' and 'all-methods'. Default='all-methods'.
• pysource.max-disk-cache-size - The maximum size of the disk cache in megabytes. This is the size of the actual data in the files, so actual disk usage will be somewhat greater because of sector sizes and other factors. Set this to 0 to disable writing any disk files. Default=50.
• pysource.max-background-buffers - The maximum number of analysis information buffers allowed in memory at once for files that are not being edited. This value is ignored if the disk cache is disabled. Default=10.

You need to quit and restart Wing before any changes in these preferences take effect.