These forums have been archived and are now read-only.

The new forums are live and can be found at https://forums.eveonline.com/

EVE Technology Lab

 
  • Topic is locked indefinitely.
 

EVELink - A Better Set of Python Bindings for the EVE API

Author
Aaeriele
Nobody in Local
Of Sound Mind
#1 - 2012-09-13 06:28:08 UTC  |  Edited by: Aaeriele
EVELink


EVELink is a rich set of bindings for EVE API calls that does more than just wrap HTTP requests - it also transforms the raw API responses into well-organized Python data structures. It's designed to fix some of the weaknesses of other Python API libraries - most specifically, the need to have a deep knowledge of the input and output structures of CCP's API endpoints.

Here's a very basic example of what using EVELink is like:

>>> from evelink.eve import EVE
>>> EVE().character_id_from_name('Aaeriele')
90083631

We've done the hard work of figuring out a lot of the quirks and intricacies of the data returned by CCP's API so that you don't have to. Our goal was to produce output values that wouldn't require consulting documentation to understand.

Features

  • Wraps 100% of the EVE Online REST API.
  • No knowledge of the actual API endpoints required to use.
  • All returned values from wrappers are pure Python data structures with logical layouts.
  • All methods include tests with example output, for ease of browsing.
  • Automatically handles caching properly (with various options for how to store the cache).
  • No extra dependencies - the library is completely self-contained.
  • Convenient command-line tool provided for making test requests or integrating with other scripts.
  • Compatible with Google App Engine (via the AppEngineAPI class provided in evelink.appengine).


The library is licensed under the MIT License, so you're welcome to use it in any project. It explicitly supports Python 2.6 and 2.7; if you're interested in using it with a different version of Python, let's talk.

As it stands, EVELink already provides a complete wrapper for the API, but we have further plans to improve it and make it even easier to use. Stay tuned for even more (hopefully, backwards compatible) updates.


Download

If you just want to use EVELink in a project, you can install the latest release from PyPI via normal methods, e.g. "pip install evelink".

If you want to get the bleeding-edge latest version, want to develop on EVELink itself, or just want to browse the source code, you can find it on GitHub:
https://github.com/eve-val/evelink

A Windows installer is also available in the GitHub downloads tab.


Usage

For more usage details, see the README.md file (or view it on GitHub).


Problems? Suggestions?

If you encounter a bug in EVELink, please open an issue on GitHub. (Pull requests are welcome too!)

Similarly, feel free to file an issue for any feature requests or suggestions.


Thanks

EVELink is brought to you by Valkyries of Night. Thanks to the various members who chip in to help develop it. Also thank you to Entity (ntt) for writing the original eveapi Python module, which was a great inspiration for making this one. Finally, thanks to all of the people who have contributed to eve-id's API docs.


Parting Note

If you like EVELink, you may be interested in the other EVE-related projects developed by Valkyries of Night. You can find them here:
https://github.com/eve-val
Aaeriele
Nobody in Local
Of Sound Mind
#2 - 2012-09-14 07:36:57 UTC
Currently in progress: wrappers for the EVE-Central API. Expect wrappers for other third-party APIs to follow.
Bluedisguise
Moglers Inc.
#3 - 2012-09-14 13:32:11 UTC
Amazing! I'll try this out today, but potentially exactly what I am looking for.

I literally just finished installing and configuring Yapeal to make this exact task possible for me, as I wasn't saavy enough to figure out all the XML calls.

Could you provide a little more detail on how the wrapper handles caching, if it does at all?

Aaeriele
Nobody in Local
Of Sound Mind
#4 - 2012-09-14 16:52:15 UTC  |  Edited by: Aaeriele
Bluedisguise wrote:
Amazing! I'll try this out today, but potentially exactly what I am looking for.

I literally just finished installing and configuring Yapeal to make this exact task possible for me, as I wasn't saavy enough to figure out all the XML calls.

Could you provide a little more detail on how the wrapper handles caching, if it does at all?



By default, EVELink caches the results of all API calls in memory:
https://github.com/eve-val/evelink/blob/master/evelink/api.py#L122


However, it also ships with pre-built support for caching on disk via either Python's shelve library:
https://github.com/eve-val/evelink/blob/master/evelink/cache/shelf.py

or via SQLite:
https://github.com/eve-val/evelink/blob/master/evelink/cache/sqlite.py

To use either of these disk caching options, you simply import the corresponding cache class, create an instance off it (passing the filename where you want it to store the cache), and then pass that instance to the "cache" parameter when constructing an API object. That's all it takes.


In addition, the AppEngine compatibility module provides a way to cache via AppEngine's memcache instance:
https://github.com/eve-val/evelink/blob/master/evelink/appengine.py#L37

or via the Datastore:
https://github.com/eve-val/evelink/blob/master/evelink/appengine.py#L53


Finally, if you want to use your own caching method (for instance, using a memcached server outside of AppEngine), it's really easy to implement your own cache object and pass that in instead. All you have to do is subclass APICache and implement the get() and put() methods.



The command-line client script that comes along with EVELink for convenience uses SQLite caching my default.
Aaeriele
Nobody in Local
Of Sound Mind
#5 - 2012-09-15 07:16:12 UTC  |  Edited by: Aaeriele
Support for EVE-Central APIs is now present in evelink.thirdparty.eve_central.

This has been checked in to master, and will be present in the next packaged release (not sure how soon that will be, though).

Edit: v0.2.0 is now released with EVE-Central support and a bugfix for AppEngine support.
Medas Turan
24th Imperial Crusade
Amarr Empire
#6 - 2012-09-29 16:50:41 UTC
Do you expose the non-data values we get from the api (chached until/time) directly in any way?
June Ting
Nobody in Local
Of Sound Mind
#7 - 2012-09-29 16:54:00 UTC  |  Edited by: June Ting
Not currently. How do you expect to use those values?

If you make a raw API.get() call we could expose it, but when we're doing more complicated processing it seems like it could be confusing if we returned you a single timestamp if more than one call was used to return a value.

https://github.com/eve-val/evelink/blob/master/evelink/api.py#L182 for raw API.get()

Because of the fact that we obey the api's cachedUntil values, you can repeatedly execute a call and it'll handle transparently from the cache, so ordinary use should not have to worry about reading those values.

I fight for the freedom of my people.

Medas Turan
24th Imperial Crusade
Amarr Empire
#8 - 2012-10-01 05:30:07 UTC
Would be useful to determine when exactly I can update cached Data again mostly.
Aaeriele
Nobody in Local
Of Sound Mind
#9 - 2012-10-02 05:30:53 UTC  |  Edited by: Aaeriele
Medas Turan wrote:
Would be useful to determine when exactly I can update cached Data again mostly.


*nod* While in most cases, just reading the data whenever you want it and letting EVELink care about caching suffices, I can certainly see where there might be cases where people want to get a better sense of when new data is likely to be available. We can definitely look into providing a way to get that info.

Edit: In the short term, one way you could work around this would be to implement a cache class that tells you the cache duration of the last item that was requested/stored in it, and grab that after you make an API call. (It's definitely not elegant, but if you want that info now, that'd be one way to get at it until a better way is added.)

I think that there's probably two kinds of data from the EVE API - some of it, no one really cares about cache times on because it either doesn't change or changes frequently enough that you can just assume it updates every X minutes and be fine. The rest of it actually has some meaningful cache duration (say, an hour). It seems like the latter is what we really want to expose cache expiry timestamps for, and that could probably be worked into the returned data structures in a meaningful way (probably as an cache_expiry_ts or some such).

Edit 2: I've opened an issue on the GitHub project for this: https://github.com/eve-val/evelink/issues/120