An asynchronous Spore Python API using Twisted.
Project description
History
The Twisted Spore API was created more for fun than anything else. There’s really nothing special about it; all resource fetching is done with a Twisted web client (twisted.web.client.getPage).
When possible (given the async nature of the Twisted Spore API), code from the blocking Python API was reused. This was done in an effort to maintain functional compatibility with the synchronous Spore Python API. However, as it turned out, there were several features missing from the other API as well as some REST resources that don’t work anymore as originally written in that API.
Dependencies
To use this API as-is, you will need to have Twisted (Python) installed. Downlowds for the latest release are always linked on the main page:
Further Development
If there is interest in having a synchronous Python API updated to the latest functionality as released by spore.com, I would be more than willing to add explicit support for a non-Twisted API in this source code such that that it could be used even when Twisted is not installed.
For more details on coming changes, be sure to read the TODO section.
Installation
Development
If you want to develop for txSpore or use the latest code we’re working on, you can install from the sources. You’ll need bzr installed, and then just do the following:
$ bzr branch lp:txspore $ cd txspore $ sudo python setup.py install
Easy Install
You can use the setuptools easy_install script to get txSpore on your system:
$ sudo easy_install txSpore
Manual Download
You can manually download the source tarball from the Python Package Index by visiting the following URL:
You’ll need to untar and gunzip the source, cd into the source directory, and then you can do the usual:
$ sudo python setup.py install
Checking the Source
Once installed, as long as you have Twisted installed on your system and the trial script in your PATH, you can test the source code by executing this anywhere:
$ trial txspore
That will run the test suite and report on the success and failure of any unit tests.
Usage
Interactive Prompt
Sometimes it’s not very practical to run Twisted code from the Python interpreter (timeouts can be a problem and accessing results from callbacks can be awkward). Regardless, there is one below showing the use of both the REST service API as well as the static data service provided at spore.com.
The achivement data for a user that’s available via the REST service only has IDs associated with it, no text data. The Spore data service does have the text. We’re going to need to get both. First, though, let’s do some initial imports and setup some callbacks:
>>> from cStringIO import StringIO >>> from twisted.internet import reactor >>> from twisted.internet.defer import DeferredList >>> from txspore import client >>> >>> results = [] >>> data = StringIO() >>> >>> def setResults(callback_results, results): ... results.append(callback_results) ... >>> def printError(error): ... print error.getErrorMessage() ... >>> def finish(ignored): ... reactor.stop() ...
With our callbacks and errback defined, as well as some global objects for holding result data, we’re ready to make the client calls:
>>> d1 = client.getAchievementsForUser("oubiwann", 0, 20) >>> d1.addCallback(setResults, results) <Deferred at 0x91ec16c> >>> d1.addErrback(printError) <Deferred at 0x91ec16c> >>> >>> d2 = client.getAchievementDataXML(fd=data) >>> d2.addErrback(printError) <Deferred at 0x91ec40c> >>> >>> d = DeferredList([d1, d2]) >>> d.addCallback(finish) <DeferredList at 0x91ec64c> >>> reactor.run()
Let’s make sure we get the number of achievements we expected and then take a quick peek at some of the achiements associated with this user:
>>> achievements = results.pop() >>> len(achievements) 20 >>> for achievement in achievements[0:4]: ... print achievement.guid ... 0xaec66642!0x0770b845 0x0cc8b2c9!0xb9ff8f07 0x0cc8b2c9!0x19988ceb 0x0cc8b2c9!0xbc3c424d
We now have the IDs, but not the text. Let’s get the latter:
>>> from txspore import util >>> from txspore import model >>> >>> xmlTree = util.XML(data.getvalue()) >>> achievementsModel = model.RecursiveDataModel(xmlTree) >>> len(achievementsModel.achievements) 124 >>> achievementsLookup = {} >>> for achievement in achievementsModel.achievements: ... achievementsLookup[achievement.id] = ( ... achievement.name, achievement.description) ...
With the lookup dictionary populated, we can re-print our user results with friendlier output:
>>> for achievement in achievements: ... try: ... print "%s: %s" % achievementsLookup[achievement.guid] ... except KeyError: ... print "Couldn't find key '%s' ..." % achievement.guid ... Couldn't find key '0xaec66642!0x0770b845' ... Wanderer Passion: Play as a Wanderer Quest Master: Complete 150 missions in the Space stage Relentless: Complete the Civilization stage 10 times Tribal: Complete the Tribal stage 10 times Gunner: Destroy at least 500 other space vessels Shaman Hero: Achieve Master Badge Level 10 as a Shaman Maxis Scout: Earn 100 badges in the Space stage Universe In A Box: Play in every stage and every creator Slugger: Finish Creature stage without legs Bestial: Play the Creature stage 10 times Max Power: Build a creature with maximum stats in at least 4 abilities in Creature stage Spore Fan: Spend 50 hours in your Spore galaxy Biologist: Make and publish 100 creatures Bard Passion: Play as a Bard General Custer: Lead 30 posse members to their death Spice Hoarder: Control every resource node on the planet simultaneously Rolling Thunder: Complete the Civilization stage in less than an hour Missionary: Finish the Civilization stage with more than 8 religious cities Speed Demon: Finish Creature stage within an hour
Demo
In the top-level source directory for txSpore, there is an examples directory. This contains a demo web application that shows:
one simple way of integrating txSpore into a web app
how to use the client to get user data and assets
how to use callbacks to process results
Unit Tests
The unit tests are actually one of the best places to look for details about usage. There’re two test modules that could provide very enlightening when figuring out how to use the txSpore API:
txspore/tests/test_client.py - basic client usage, and how to handle results
txspore/tests/test_model.py - detailed view of available attributes on returned model objects.
Known Bugs
None so far
TODO
Add support for using a complete, up-to-date sync API without the need to have Twisted installed.
Create a client object and implement caching functionality.
Add validation checks for legal parameters in client.getPartInfo.
Get useful achievement data with secondary query in client.getAchievementsForUser.
Add validation checks for legal parameters in client.searchAssets.
Fix the threading/logging stuff in test_saveFileWithError.
Add search functions to client.
Add code for everything below line 244 in txspore.original.SporeAPICoreUtils.
Changes
Version 0.0.1
Initial release of txSpore, supporting most of the REST and static data APIs.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.