ElectricCommander + Python = ec.py

Last week Electric Cloud hosted its biggest customer summit ever. It was an exciting and educational experience for customers and EC staff. A few customers approached me with the question, “We’re not big on Perl. Are there any plans to develop a Python interface to the Commander server?” This question has come up every year at the customer summit, and the answer has always been the same: “I’m sorry but there are many other features with broader impact that rank higher in priority”… until now! It gives me great joy to introduce the ElectricCommander Python Module 0.1.0!

This module (ec.py) contains an ElectricCommander class which is the analog to the ElectricCommander Perl module.

Download and Installation

Download the module and the httplib2 module:

ec-0.1.1
httplib2-0.7.1

Each module is shipped as a distutils package. To install, unpack the appropriate archive, and issue the following command:

Usage

To issue a request, call a method on the ElectricCommander object with a dictionary of request parameters. Here’s a simple example for retrieving a property:

Login is special since it needs to update the active session in the ElectricCommander object. Failed login raises an exception. Note that the request parameters aren’t in a dictionary for this api:

You can create multiple ElectricCommander objects to connect to multiple servers:

Here’s how you can issue a findObjects request for projects whose names begin with “D” or “E”:

Here’s how you can issue a batch request, in parallel mode:

Here’s how to set a job property from within a job step:

Prerequisites

Python2 or Python3?

Python doesn’t come with an http module that does connection caching, so I wrote ec.py to rely on httplib2. httplib2 in turn has a bug when run on Python 3.2.2 such that it doesn’t issue https requests properly. I tweaked the module to work around the issue and ran into a core Python 3.2.2 issue (which is actually an unresolved issue in OpenSSL). It does issue plain http requests properly, however.

httplib2 works fine on Python 2.7.2 for http and https. ec.py does not work on Python 2.5.x, but both work on Python 2.6.

Recommendation: Use Python 2.7.x or as close a version to it as possible.

httplib2

As was mentioned earlier, ec.py relies on httplib2. I’ve attached httplib-0.7.1 to this blog post.

Behavior Differences from ElectricCommander.pm

There are a few differences between ec.py and ElectricCommander.pm.

  • ec.py doesn’t have a concept of positional arguments for api calls (except login); you must always specify request parameters in a dictionary.
  • ec.py returns responses as xml strings, while ElectricCommander.pm returns an xpath object. Here are a few reasons for choosing to return a response string:
    • Python’s standard library doesn’t include an xpath module/class. The publicly available PyXML package supports xpath, but it is not a pure Python package, so we’d have to build it for every platform that a user wants to use ec.py. Too onerous.
    • For large responses, you may want to have the option of using a SAX parser to parse the result rather than using a DOM parser (required for xpath queries). DOM parsers can create huge data structures in memory for the DOM representation of xml.
  • ec.py does no argument validation. You can set any request parameters on any request (including non-existent request names). The module will create the representative request xml, send it to the server, and the server will perform validation and reject invalid requests. This has the side-effect that ec.py is somewhat future-proof — if new server api’s become available in the next version of ElectricCommander, you need not upgrade your ec.py to use them.

Known Limitations

  • It doesn’t automatically tack on context arguments (e.g. jobStepId for property api calls when run in a job-step context).
  • It does not update the session file. However, it does read it and respects the default session if one exists.
  • It doesn’t have a batch api, but you can use the public methods to issue batch requests yourself (as shown in the example above).
  • It has no retry behavior for failed requests.
  • Functions from the Perl API that are more than just wrappers around issuing server requests are not implemented. This includes (but is not limited to) installPlugin, uninstallPlugin, publishArtifactVersion, and retrieveArtifactVersions.

Legal (non)Restrictions

This module is free for use. Modify it however you see fit to better your experience using ElectricCommander. I’d be happy to incorporate updates into my master.

This module is not officially supported by Electric Cloud. It has undergone no formal testing and you may run into issues that I haven’t in my manual testing. Post your questions/comments, and I’ll respond when I get a chance.

Future Directions

Since I’ve just learned Python, most likely some of the module implementation and interface could be improved. I can’t promise backward-compatibility, but I will document backward-incompatible changes so it’ll be fairly easy for you to update your scripts to work with the new version of ec.py.


Electric Cloud powers Continuous Delivery. We help organizations developing mobile, embedded systems and enterprise web/IT applications deliver better software faster by automating and accelerating build, test, and deployment processes at scale. Industry leaders like Qualcomm, SpaceX, Cisco, GE, Gap, and E*TRADE use Electric Cloud solutions and services to boost DevOps productivity and Agile throughput.

Share this:

2 Responses to “ElectricCommander + Python = ec.py”

  1. Joanne Wilson says:

    When instantiating an ElectricCommander object, I get an error:

    IOError: [Errno 2] No such file or directory: ‘C:Documents and SettingsjwilsonLocal SettingsApplication DataElectric CloudElectricCommander.ecsession’

    Indeed, the file mentioned does not exist. Any ideas what I am doing wrong? I am issuing the following command after importing the necessary modules:

    cmdr = ElectricCommander()

  2. Sandeep Tamhankar says:

    @Joanne: thanks for your interest. This has been a long-standing bug in the library since the very beginning; if you don’t have a .ecsession file (created previously by ectool), this module fails.

    I fixed the issue and uploaded a new version to this post; note that you would now be downloading ec-0.1.1 rather than ec-0.1.0.

    You can also access this and many other Commander-related public domain offerings from our repository on GitHub:

    https://github.com/electriccommunity/electriccommander

    Also, please forgive the formatting of this blog post; we’ve recently made some infrastructure changes and code-snippet formatting seems to have gotten lost. I’m working with the relevant parties to get this resolved.

Leave a Reply