Development Guidelines

Some quick notes to keep in mind when writing new code for EVELink:

Raw Access Methods

These should be kept to a minimum - consult with others before adding a method to evelink.api.

Results from API.get are in the form of ElementTree.Element objects. Note that we're trying to keep support for python2.6, so do not use ElementTree methods that are new in it's 1.3 version.

Wrapper Access Functions

One file and one class per top-level segment of the API path (list of API functions). In general, the file corresponding to /foo/*.xml.asp should be of the format evelink/foo.py and the class should be Foo.

One method per API path. The exception to this is that reasonable helper methods are okay - for instance, single-item helpers for normally multi-item calls.

Method return values should consist of basic Python types only (str, int, dict, etc.). Nesting is okay. Aim for the most useful return format possible.

corps = [{'id':123, 'name':'Foobar Corp', 'members': 10}]    # bad - linear lookup time!
corps = {123:{'name':'Foobar Corp', 'members':10}}           # better - but id not available from .values()
corps = {123:{'id':123, 'name':'Foobar Corp', 'members':10}} # best - all info is available even via .values()

Try to keep the names of dict keys that refer to identical things consistent with other EVELink results. For instance, EVELink always uses the key 'ticker' to refer to what the EVE API calls a corporation shortName.

@auto_api

The @auto_api decorator is a time-saving decorator that provides an automatic, no-credentials API() instance as the value of the api keyword argument if it's not explicitly set by the caller. This can be handy when using wrapper calls that don't require auth.

However, this decorator should only be applied to methods that can actually be useful without credentials - if the API call requires an api key in order to return any useful results, don't use @auto_api.

Tests

Pull requests are likely to be denied if they don't have test coverage. EVELink uses standard unittest2 tests, which are located in the top-level tests directory.

Tests for evelink/foo.py should be in tests/test_foo.py and so on.

EVELink uses mock for mocking.