Development Guidelines

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

Consistency

Above all else, aim for consistency with existing code. If it's your first time adding code to EVELink, take a couple of minutes to familiarize yourself with the rest of the library and how it's laid out.

For example, here are some things that should remain consistent throughout the wrapper layer code:

• Dictionary keys referring to integers that are references to other things always end in id (location_id, etc).
• "corporation" and "character" are always shortened to corp and char respectively in dictionary keys.
• Function names do not end in _list. For instance, the wrapper for eve/ErrorList is named errors.

(This is not at all an exhaustive list. Worst case, write some code and then ask for someone else to review it.)

Dependencies

EVELink is intentionally designed to have no external dependencies required for library usage. The dependencies specified in requirements.txt are for testing only. As such, you should take care to not introduce any code outside of the tests directory that uses functions from those dependencies.

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. Note: requirements.txt includes nose for test-runner convenience, but please do not use nose-specific features in tests.

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

EVELink uses mock for mocking.

Minimal diffs

When submitting pull requests, please only submit the changes that are actually relevant for that pull request. Avoid including random formatting changes to unrelated portions of the code.