Specification - GSoC Scripting Plug-in
From Gephi:Wiki
| This article is work in progress. |
Contents |
Introduction
This page aims to present the specification of the Scripting Plug-in being developed as part of the Google Summer of Code 2011 program. Please, be advised that this page is currently a work in progress and may be subject to modifications.
The Scripting Plug-in will implement the Gython language, originally from GUESS, as close as possible to the specification presented on the CHI 2006 paper.
More information about the proposal itself can be found on the publicly available page on Google Melange.
Student: Luiz Ribeiro
Mentor: Eytan Adar
Project Goals
This project has the following main goals:
- Upgrade the Gython domain-specific language to Jython's latest stable version (2.5.2);
- Expose the Gephi APIs to the scripting language in a concise and scripting-friendly way;
- Develop a console user interface to use Gython from within Gephi.
Specification
The Scripting Plug-in will follow the Model–View–Controller (MVC) architectural pattern in a similar way as described on the How to design a new feature tutorial.
The plug-in will be split in three modules as following:
- Gython Wrapper: wraps the gython.jar library file generated by the Gython source code branch;
- Scripting API: contains the model and controller interfaces of the plug-in (and also it's corresponding implementations) and classes for wrapping graph elements that are going to be exposed to the scripting language;
- Desktop Scripting: contains all the user interfaces of the plug-in (e.g. the console user interface).
The specifications of these modules are discussed in more details on the sections below.
Gython Wrapper
Scripting API
The Scripting API module will play the following roles:
- Instantiate a Python Interpreter for the application and allow other modules to access the interpreter as needed (e.g. the Desktop Scripting module, for evaluating statements on the console UI);
- Manage local namespaces, so that we have a namespace for each workspace (in Jython, namespaces are dictionaries which serve as containers for global and local variable bindings). Each namespace should contain bindings to each graph element of it's corresponding workspace;
- Manage the graph elements that are exposed to the scripting language. In other words, instantiating and destroying PyObjects that wrap the Gephi API objects like Node, Edge and even the Graph itself as needed (I'll refer to these objects simply as wrapping objects from now on).
The first two roles will be performed by the Controller and Model interfaces, respectively. While the latter will work by catching lookup failures in the namespace itself: once the user tries to access a variable, say a variable named v321, the namespace will first look if there is an object bound to the name v321, if there is one the namespace will just return it, otherwise it will look if there is a corresponding graph element with id 321 and instantiate a wrapper accordingly (and also bind it to the namespace). If there is no graph element with the given id, the namespace will just throw an error.
The main advantage of instantiating wrappers whenever a lookup failure occurs is that we'll minimize the number of objects on the namespace, by having wrappers instantiated only for those graph elements that have been used within the console.
Since namespaces in Jython are essentially PyStringMap objects, in order to implement the "lookup failures" the __finditem__ method will be overloaded in a class called GyNamespace (which extends PyStringMap).
In short, the Model will be responsible for storing the local namespace for each workspace. This way, there should be a single Model instance for each workspace. Also, as soon as a new Model is created, it should automatically instantiate a new local namespace (which is actually a PyStringMap object) upon constructor execution.
The Controller will be responsible for handling PythonInterpreter creation and also creating models for each workspace, therefore, it has to be aware of workspace creation and selection. As soon as a new workspace is created the Controller will create a new Model for that workspace and whenever a workspace is selected, the Controller should update the current namespace on the PythonInterpreter object by calling the PythonInterpreter.setLocals method.
Wrapping Objects
As mentioned earlier, the wrapping objects' classes are generalizations of the PyObject class for exposing graph elements and attribute columns to Gython. Note that the names of all of the wrapping objects' classes have the Gy prefix: the class for wrapping Node objects from the GraphAPI is called GyNode and the one for wrapping Edge objects is called GyEdge, for example.
The wrapping objects should also overload a number of methods for implementing the operators between these. For instance, the GyNode class overloads the __bde__, __lde__ and __rde__ methods which implement the <->, <- and -> additional operators respectively. The GyAttribute class, which wraps the AttributeColumn objects, has to overload the __eq__, __lt__ and __gt__ methods (among others), which implement the ==, < and > operators, in order to perform the filtering features.
A class diagram that presents the wrapping objects in a simplistic way is given below (click to zoom in):
Note that other methods to be exposed to the scripting language may be created on these classes but these haven't been specified yet as of the time of this writing. In other words, this part of the specification might be extended sometime (during or after GSoC 2011).
Model and Controller roles
Desktop Scripting
Deliverables
Timeline
The period between May 23 and August 22, known as the coding phase, will be split as follows:
- Week #01: Create the Scripting API's Controller and Model interfaces and it's corresponding implementations (May 23 to May 29);
- Week #02: Start working on the Desktop Scripting module and the GyNamespace feature for namespace lookup failures (May 30 to June 5);
- Weeks #03 to #04: Integration of the Scripting Plug-in with Gephi's Graph API (June 6 to June 22);
- Weeks #05 to #06: Initial integration of the Scripting Plug-in with Gephi's Attributes API (June 23 to July 5);
- Weeks #07 to #08: Implementation of queries by overloading comparison operators on GyAttributes objects and integrating with the Filters API (July 6 to July 16);
- Week #08: Mid-term evaluation deadline (July 13 to July 16);
- Weeks #09 to #10: Polishing the plug-in, testing and working on fixing any bugs. Also, start documenting (July 17 to July 27);
- Weeks #11 to #12: Finishing all the documentation and packing of the plug-in (July 28 to August 15);
- Week #13: Final evaluation deadline (August 16 to August 22).
Note that the work on this specification will be done along with the development of the plug-in during the coding phase.
