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.")
Submitting ESI Links to zKillboard¶
To streamline the process for users, you can accept ESI killmail links and then submits them to zKillboard.com and uses the new zKillboard.com link as the canonical URL for the request.
from decimal import Decimal
from flask import Markup
from evesrp.killmail import ESIMail
class SubmittedESIZKillmail(ESIMail):
"""Accepts and validates ESI killmail links, but submits them to
ZKillboard and substitutes the zKB link in as the canonical link
"""
def __init__(self, url, **kwargs):
# Let ESIMail validate the ESI link
super(self.__class__, self).__init__(url, **kwargs)
# Submit the ESI URL to ZKillboard
resp = self.requests_session.post('https://zkillboard.com/post/',
data={'killmailurl': url})
# Use the URL we get from ZKillboard as the new URL (if it's successful).
if self.kill_id in resp.url:
self.url = resp.url
else:
# Leave the ESI URL as-is and finish
return
# Grab zkb's data from their API
api_url = ('https://zkillboard.com/api/no-attackers/'
'no-items/killID/{}').format(self.kill_id)
zkb_api = self.requests_session.get(api_url)
retrieval_error = LookupError(u"Error retrieving killmail data (zKB): {}"
.format(zkb_api.status_code))
if zkb_api.status_code != 200:
raise retrieval_error
try:
json = zkb_api.json()
except ValueError as e:
raise retrieval_error
try:
json = json[0]
except IndexError as e:
raise LookupError(u"Invalid killmail: {}".format(url))
# Recent versions of zKillboard calculate a loss' value.
try:
self.value = Decimal(json[u'zkb'][u'totalValue'])
except KeyError:
self.value = Decimal(0)
description = Markup(u'An ESI external killmail link that will be '
u'automatically submitted to <a href="https://'
u'zkillboard.com">zKillboard.com</a>.')
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.
- 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.Killmail, evesrp.killmail.RequestsSessionMixin, evesrp.killmail.ShipNameMixin, evesrp.killmail.LocationMixin
A killmail sourced from a zKillboard based killboard.
- domain¶
The domain name of this killboard.
- __init__(url, **kwargs)[source]¶
Create a killmail from the given zKillboard URL.
Parameters: url (str) – The URL of the killmail.
Raises: - ValueError – if url isn’t a valid zKillboard killmail.
- LookupError – if the zKillboard API response is in an unexpected format.
- 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.
- 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.