Killmail Handling

EVE-SRP relies on outside sources for its killmail information. Whether that source is ESI, zKillboard, or some private killboard does not matter, there just has to be some sort of access to the information.

The interface for Killmail is fairly simple. It provides a number of attributes, and for those that correspond to in-game entities, it also provides their ID number. The default implementation has all values set to None. If a killmail is invalid in some way, it can be signaled either by raising a ValueError or LookupError in the killmail’s __init__() method or by defining a Killmail.verified property and returning False from it when the killmail is invalid.

Two implementations for creating a Killmail from a URL are included: ESIMail is created from a ESI external killmail link, and ZKillmail is created from a zKillboard details link.

Extension Examples

The reasoning behind having killmails handled in a separate class was for administrators to be able to customize behavior. Here’re a few useful snippets that may be useful for your situation.

Restricting Valid zKillboards

ZKillmail by default will accept any link that looks and acts like a zKillboard instance. It does not restrict itself to any particular domain name, but it makes allowances for this common requirement.

from evesrp.killmail import ZKillmail


class OnlyZKillboard(ZKillmail):
    def __init__(self, *args, **kwargs):
        super(TestZKillmail, self).__init__(*args, **kwargs)
        if self.domain != 'zkillboard.com':
            raise ValueError(u"This killmail is from the wrong killboard.")

Setting Base Payouts from a Spreadsheet

If you have standardized payout values in a Google spreadsheet, you can set Request.base_payout to the values in this spreadsheet. This is assuming your spreadsheet is set up with ship hull names in one column and payouts in another column. Both Columns need to have a header (‘Hull’ and ‘Payout’ in the example below). This uses the Google Data Python Client which only supports Python 2, and can be installed with pip install gdata.

import gdata.spreadsheets.client
from decimal import Decimal


# patch the spreadsheet's client to use the public feeds
gdata.spreadsheets.client.PRIVATE_WORKSHEETS_URL = \
        gdata.spreadsheets.client.WORKSHEETS_URL
gdata.spreadsheets.client.WORKSHEETS_URL = ('https://spreadsheets.google.com/'
                                            'feeds/worksheets/%s/public/full')
gdata.spreadsheets.client.PRIVATE_LISTS_URL = \
        gdata.spreadsheets.client.LISTS_URL
gdata.spreadsheets.client.LISTS_URL = ('https://spreadsheets.google.com/feeds/'
                                       'list/%s/%s/public/full')


class SpreadsheetPayout(ZKillmail):

    # The spreadsheet's key
    # (https://docs.google.com/spreadsheets/d/THE_PART_HERE/edit).
    # Make sure the spreadsheet has been published (File->Publish to web...)
    spreadsheet_key = 'THE_PART_HERE'

    # The name of the worksheet with the payouts
    worksheet_name = 'Payouts'

    # The header for the hull column (always lowercase, the Google API
    # lowercases it).
    hull_key = 'hull'

    # And the same for the payout column
    payout_key = 'payout'

    client = gdata.spreadsheets.client.SpreadsheetsClient()

    @property
    def value(self):
        # Find the worksheet
        sheets = self.client.get_worksheets(self.spreadsheet_key)
        for sheet in sheets.entry:
            if sheet.title.text == self.worksheet_name:
                worksheet_id = sheet.get_worksheet_id()
                break
        else:
            return Decimal('0')
        # Read the worksheet's data
        lists = self.client.get_list_feed(self.spreadsheet_key, worksheet_id,
                query=gdata.spreadsheets.client.ListQuery(sq='{}={}'.format(
                        self.hull_key, self.ship)))
        for entry in lists.entry:
            return Decimal(entry.get_value(self.payout_key))
        return Decimal('0')

Developer API

class evesrp.killmail.Killmail(**kwargs)[source]

Base killmail representation.

kill_id

The ID integer of this killmail. Used by most killboards and by CCP to refer to killmails.

ship_id

The typeID integer of for the ship lost for this killmail.

ship

The human readable name of the ship lost for this killmail.

pilot_id

The ID number of the pilot who lost the ship. Referred to by CCP as characterID.

pilot

The name of the pilot who lost the ship.

corp_id

The ID number of the corporation pilot belonged to at the time this kill happened.

corp

The name of the corporation referred to by corp_id.

alliance_id

The ID number of the alliance corp belonged to at the time of this kill, or None if the corporation wasn’t in an alliance at the time.

alliance

The name of the alliance referred to by alliance_id.

url

A URL for viewing this killmail’s information later. Typically an online killboard such as zKillboard, but other kinds of links may be used.

value

The extimated ISK loss for the ship destroyed in this killmail. This is an optional attribute, and is None if unsupported. If this attribute is set, it should be a Decimal or at least a type that can be used as the value for the Decimal constructor.

timestamp

The date and time that this kill occured as a datetime.datetime object (with a UTC timezone).

verified

Whether or not this killmail has been API verified (or more accurately, if it is to be trusted when making a Request.

system

The name of the system where the kill occured.

system_id

The ID of the system where the kill occured.

constellation

The name of the constellation where the kill occured.

region

The name of the region where the kill occured.

__init__(**kwargs)[source]

Initialize a Killmail with None for all attributes.

All subclasses of this class, (and all mixins designed to be used with it) must call super().__init__(**kwargs) to ensure all initialization is done.

Param:keyword arguments corresponding to attributes.
__iter__()[source]

Iterate over the attributes of this killmail.

Yields tuples in the form ('<name>', <value>). This is used by Request.__init__ to initialize its data quickly. <name> in the returned tuples is the name of the attribute on the Request.

description = l'A generic Killmail. If you see this text, you need to configure your application.'

A user-facing description of what kind of killmails this Killmail validates/handles. This text is displayed below the text field for a killmail URL to let users know what kinds of links are acceptable.

class evesrp.killmail.ZKillmail(url, **kwargs)[source]

Bases: evesrp.killmail.ESIMail

domain

The domain name of this killboard.

class evesrp.killmail.ESIMail(url, **kwargs)[source]

Bases: evesrp.killmail.Killmail, evesrp.killmail.RequestsSessionMixin, evesrp.killmail.LocationMixin

A killmail with data sourced from a ESI killmail link.

__init__(url, **kwargs)[source]

Create a killmail from a ESI killmail link.

Parameters:

url (str) – the ESI killmail URL.

Raises:
  • ValueError – if url is not a ESI URL.
  • LookupError – if the ESI API response is in an unexpected format.
class evesrp.killmail.RequestsSessionMixin(requests_session=None, **kwargs)[source]

Mixin for providing a requests.Session.

The shared session allows HTTP user agents to be set properly, and for possible connection pooling.

requests_session

A Session for making HTTP requests.

__init__(requests_session=None, **kwargs)[source]

Set up a Session for making HTTP requests.

If an existing session is not provided, one will be created.

Parameters:requests_session – an existing session to use.
class evesrp.killmail.ShipNameMixin[source]

Killmail mixin providing Killmail.ship from Killmail.ship_id.

ship[source]

Looks up the ship name using Killmail.ship_id.

class evesrp.killmail.LocationMixin[source]

Killmail mixin for providing solar system, constellation and region names from Killmail.system_id.

constellation[source]

Provides the constellation name using Killmail.system_id.

region[source]

Provides the region name using Killmail.system_id.

system[source]

Provides the solar system name using Killmail.system_id.