Thursday, July 25, 2013

Writing Code - zKB module - Outline

I want to write a zKB program on par with Entity's eveapi python module.  The problem is that eveapi is awesome, and Entity is a baws... and I am critically low on free time.

But "writing it down" is about the only way I can keep myself honest.  So, let's talk about the outline of what I want to deliver.  I'd appreciate any feedback from the code savvy people out there.

Front End: What the user will see

I imagine user code will look something like this:

import toaster;
... 
zkb_raw = new toaster.zkb_query 
zkb_raw.group=25 
zkb_raw.corporationid=98076299 
zkb_result = zkb_raw.execute
#zkb_result is essentially as-is return from zKB
...
victim_and_killers[]=toaster.zkb_involvedPilots(zkb_result)  
In reality, the imported program will work in two halves.  First, a query builder that will go and fetch data from zkb.  Then second, a set of "common data" queries for the returned data.  

Back End: How it works

Queries and fetching data

I'd like to be able to make something like eveapi's dynamic class constructors that just work without having to define every api option zkb provides.  I will probably have to go with the latter, because mediocre results today trump excellent results 3mo from now.  The idea being that the user can define each part of the query like it's built in the HTTP call.

The harder part is making the fetcher that will grab and concatenate the results into the final JSON object.  zKB's interface is a bit shaky, and I want to make a robust fetcher that "just works" for any call you care to make.  I'm still not settled on the exact design of the fetcher... something that dynamically backs off at execution time is a must, and I'd like to have flagging so users can do other work while the fetch is running.

At the end of the fetch, the first part should return as raw as possible data from zKB.  It will need to zip together the pages from the query and probably shouldn't return a JSON object, but I don't want to do a lot of filtering or parsing to allow users to just do as they please with the returned data.

Parsers and Crunchers

The second half of the program should handle some common queries and return them in usable formats.  Things like "involved pilots", "destroyed cargo", "fittings", maybe some sort of ability to link together kills and related kills.

I expect this is a spot that there will always be another function needed or requested.  The hope is that the first half of the program can be all the hard-core devs use, while the second half gives a leg-up for the greener devs.  

Versioning

I may need to break some features out into reasonable revisions.  1.0 version should have the following features:
  • Able to use every query API call zkb offers
  • Return up to 1,000 killids in a single query
  • Have a crash-and-restart route
  • 5-10 "basic crunch" functions
The longer goals for 1.1-1.2 releases
  • Thread-safe execution mode
  • Robust "back off" controller for large queries
  • Dynamic classing like eveapi... I don't even know the buzzword for this

Just wanted to get some words down so I can reference back to a reasonable plan and not lose sight of the goals.  I only intend to develop this code for Python, so if that's not your language, you're SOL.  If there's anything I'm missing or should look at, I'd appreciate the feedback.

Follow progress on github: Toaster