ElectricCommander + Python = ec.py

Last week Electric Cloud hosted its biggest customer summit ever, discussing real-world implementation of Continuous Delivery and ways to accelerate your software pipeline. 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:


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


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:


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.


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.


Sandeep Tamhankar

Sandeep Tamhankar is Principal Engineer in Ship.io, Electric Cloud's mobile CI/CD cloud service.

He joined the Electric Cloud engineering team in 2003 to work on various facets of emake and the Accelerator Cluster Manager and wrote the first version of ElectricRunner. Sandeep was a member of the team that began to design and implement ElectricCommander in 2005, where he wrote the Commander Agent and implemented some of the core features of the Commander server.

Sandeep holds a BS in Computer Science from Cornell University and an MS in Computer Science from Stanford University.

Latest posts by Sandeep Tamhankar (see all)

Share this:

9 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:


    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.

  3. Cash says:

    Hi, how could I get a procedure input parameter, which can be gotten by $parameterName in ec-perl?


  4. GD says:


    With the new Electric Commander 5.0 has the python module changed. Is there a new version of this as well. I am upgrading from EC 4.2.x. Are there any significant changes I have to care of while using the python module.

    • Sandeep Tamhankar says:

      No, however, one of our illustrious users who knows Python *way way way* better than I do has submitted a PR that makes the module more robust (though in a totally backward-compatible way).

      I just looked over that PR and made a few comments (a few of which ask for some refinements). You can check that out here: https://github.com/electriccommunity/electriccommander/pull/6

      I’ll merge the PR into master when those issues have been addressed. Feel free to pull the branch if you want to jump on this.

  5. Hi Sandeep ,

    Can you please tell me how can i code runprocedure method using cmdr object with custom defined parameters ?

    • By custom defined parameters, do you mean parameters as specified in a custom UI (e.g. ParameterPanel or xml specified)? If so, that’s a front-end concept. Custom UIs for launching procedures essentially translate parameters specified in the UI into parameters that are actually sent to runProcedure. So you’d have to figure out what your custom UI is doing and do the same thing in your script. The Perl API is similar — it’s a mechanism for issuing api requests to the Commander server, at a lower-level than the UI.

      If you’re still having trouble, I’d recommend opening a ticket with Support, where you’ll be free to share all of your specific info (which I imagine is private info).

      Good luck!


  6. Sridhar Parasuram says:

    Sandeep, this is a great module. I have a minor question.

    What would be the key value pair for extending the Number of Search Results using the findObjects function. For example when there are more than 1000 jobs, in the results, the below function only returns 1000 results.

    objectType = ‘project’,

    I tried “numberofResults” = 2000, “numberOfResults” = 2000 and none of those would work.

    • Avigail Ofer says:

      Hi Sridhar! Options for findObjects API are listed in the documentation: http://docs.electric-cloud.com/eflow_doc/6_4/API/HTML/APIflowHTML.htm#apimisc.htm#findObjects

      There’s a hard upper limit for the number of objects the API will return no matter how high you set it.

      The maximum number of object IDs that will be returned. If omitted, default behavior returns IDs for the first 1000 objects matching the query. If “0” is specified, the ID of every matching object is returned.
      Argument type: Integer

      Specifies the number of full objects (not just the IDs) returned from the findObjects request. This option allows selecting a limited number of full objects to be returned in the initial request. The returned “full objects” correspond to the objects from the beginning of the list of object IDs. If numObjects is not specified, all full objects in the list of object IDs are returned. Any and all objects can be retrieved using the getObjects command.
      Argument type: Integer

      hope this helps. if you need further assistance, feel free to open a support ticket.

Leave a Reply

Your email address will not be published. Required fields are marked *


Subscribe via RSS
Click here to subscribe to the Electric Cloud Blog via RSS

Subscribe to Blog via Email
Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Continuous Delivery (#c9d9) Podcast

c9d9 Continuous Discussion on Agile, DevOps, and Continous Delivery

Next episode:

Episode 92:
All Day DevOps

October 9, 10am PT

By continuing to browse or by dismissing this alert you agree to the storing of first- and third-party cookies on your device to enhance site navigation, analyze site usage, and assist in our marketing efforts. See privacy policy.