Package: esy
IntroductionThere are many options for consuming the ESI web services. ESY aims to be an easy-to-use library with the nuts and
bolts of dealing with an OpenAPI interface abstracted away.ESY is inspired by Entity's gloriously pythoniceveapilibrary.InstallationThe latest stable version of ESY is available from PyPI:$pipinstallesyDocumentationDocumentation is available atesy.readthedocs.io.For documentation of the various ESI routes, ESY also provides aterse listof their parameters and return types. Further
information can be explored at the mainESI documentation siteUsageESY comes with two interfaces to ESI:An interface generated byBravado, with some added sugar for dealing with pagination.A semantic wrapper generated through pythonic voodoo.The two interfaces caters different needs. The Bravado interface is an OpenAPI wrapper around the ESI that will
be familiar for most developers familiar working with swagger. The semantic wrapper, on the other hand, generates
classes for various entities in ESI like Character, Corporation and Alliance. Neither interface is mutual exclusive and
for many use cases, it makes sense using both.Regardless of interface, to use ESY, you must first initialize a client:fromesy.clientimportESIClientclient=ESIClient.get_client(user_agent='my-user-agent')The client can take a second or two to initialize, as the swagger specification is downloaded and parsed. To speed this
up, you can download the specification locally:$curlhttps://esi.evetech.net/latest/swagger.json-oswagger.jsonThen initialize the client using the local file:importjsonfromesy.clientimportESIClientwithopen('swagger.json','r')asspec_file:spec=json.load(spec_file)client=ESIClient.get_client('my-user-agent',spec=spec)For production instances, keeping the spec inRedisor some other cache is highly recommended.PaginationFor ESI routes which are paginated, ESY will return aESIPageGeneratorwhich is a generator yielding the
native data type of the route.Using the semantic wrapperfromesy.entitiesimportCharacter,Corporation,Alliance,Entity# You can initialize entities using their IDsvittoros=Character(941287462)evolution=Corporation(144749962)ccp=Alliance(434243723)# To speed up initialization, it's recommended to create and share an ESIClient among instances. If no client is# supplied, a new one will be created for each entity instance.fromesy.clientimportESIClientclient=ESIClient.get_client(user_agent='my-user-agent')vittoros=Character(941287462,_client=client)# You can also initialize instances just using the entity namesvittoros=Character.from_name('Vittoros',_client=client)evolution=Corporation.from_name('Evolution',_client=client)# or speed things up by initializing many entites at the same timeentities=Entity.from_names('Vittoros','Evolution','Northern Coalition.',_client=client)print(entities){'Northern Coalition.':<esy.entities.Allianceobjectat0x0000023967F10860>,'Vittoros':<esy.entities.Characterobjectat0x0000023967F10BE0>,'Evolution':<esy.entities.Corporationobjectat0x0000023967F10B70>}Any initialized entity will allow you to access the various public information. To access the private services, you need
to supply an authorization token first.vittoros=Character.from_name('Vittoros',_client=client,_token='hunter2')# or you can set the token after initializationvittoros.set_token('hunter2')After this, you can access all the private services:forasset_pageinvittoros.get_assets():print(asset_page)forcontract_pageinvittoros.get_contracts():forcontractincontract_page:forbidinvittoros.get_contracts_contract_bids(contract_id=contract.get('contract_id')):print(bid.get('bidder_id'),bid.get('amount'),bid.get('date_bid'))Check out theentities APIfor a more extensive list of available services.Using the Bravado interfaceThe Bravado interface is available from the ESIClient instance.fromesy.clientimportESIClientclient=ESIClient.get_client(user_agent='my-user-agent')# Get list of alliancesalliances=client.Alliance.get_alliances()# Get info on a corporationevolution=client.Corporation.get_corporations_corporation_id(corporation_id=144749962)print(evolution){'alliance_id':1727758877,'ceo_id':144509256,'creator_id':144509256,'date_founded':datetime.datetime(2003,7,30,8,33,tzinfo=tzutc()),'description':'Those who cannot adapt become victims of Evolution.','home_station_id':60013843,'member_count':316,'name':'Evolution','shares':1000,'tax_rate':0.5,'ticker':'EVOL','url':'http://www.eve-evol.com','faction_id':None}# Get paginated asset listswag=client.Corporation.get_corporations_corporation_id_assets(corporation_id=144749962,_token='esi token')# swag is an ESIPageGenerator, implementing the generator interface# Loop through it to get the asset pagesforpageinswag:# Returns a list of assetsforassetinpage:# Asset dictprint(asset.get('type_id'),asset.get('location_id'))# 22457# 16074150552CachingESY does not implement caching itself, but supports using a cache through a cache proxy object. The proxy needs
to implement the following interface:classCache(object):defget(self,key:int)->object:passdefset(self,key:int,data:object,cached_until:datetime.datetime):passdef__contains__(self,item:object)->bool:passAuthentication and devel modeESY can handle the authentication flow for you:fromesy.authimportESIAuthenticatorauth=ESIAuthenticator()refresh_token,access_token=auth.verify_authorization_code('authorization code from esi','your client ID','your secret key')auth.verify_access_token(access_token){'CharacterID':941287462,'CharacterName':'Vittoros','ExpiresOn':'2018-06-11T19:01:15.182864Z','Scopes':' ','TokenType':'Character','CharacterOwnerHash':'**********'}new_access_token=auth.get_access_token(refresh_token,'your client ID','your secret key')auth.revoke_token(refresh_token,'your client ID','your secret key')auth.revoke_token(access_token,'your client ID','your secret key',token_type='access_token')To help developers getting started without having to implement the entire authentication
workflow, ESY also implements an ad-hoc web server to get you refresh tokens. You can use
it directly in the python prompt to do some API exploration or you can use it in your tests
to produce refresh or access tokens for testing your ESI calls.First, create a new application athttps://developers.eveonline.com/with callback URL set tohttp://localhost:8000or whichever address and port you'll be
running the devel server.importesy.devel# get_authorization_code has many parameters, but for basic usage:auth_code=esy.devel.get_authorization_code(client_id='your client ID',callback_url='your callback URL',scopes='your space-delimited scopes')# This will start the web server in the background (per-default listening on localhost:8000)# and print the login URL on stdout. After authenticating in your browser, the web server# will get redirect from the SSO with the authorization code, then return that.# For situations where you are not able to reach the network where you are running ESY,# you can also use CLI login:auth_code=esy.devel.get_authorization_code(cli_login=True,client_id='your client ID',callback_url='your callback URL',scopes='your space-delimited scopes')# This will prompt for username and password, then let you pick a character.# If you are running tests, you can also supply username, password and character_id as# keyword arguments to get_authorization_code, in addition to cli_login=True. This will# automate the entire flow. Remember to revoke your tokens afterwards and for bob's sake;# don't display your username and/or password!# After getting the authorization code, you can get the tokens:refresh_token,access_token=esy.devel.verify_authorization_code(auth_code,client_id='your client ID',secret_key='your secret key')# Character infochar_info=esy.devel.verify_access_token(access_token)# Get your swagfromesy.clientimportESIClientclient=ESIClient.get_client(user_agent='your-user-agent')assets=client.Assets.get_characters_character_id_assets(character_id=char_info.get('CharacterId'),_token=access_token)forpageinassets:print(page)The devel mode will use parameters from environment settings, if present:ParameterEnvironment settingDefaultCLIENT_IDESY_CLIENT_IDNoneSECRET_KEYESY_SECRET_KEYNoneSCOPESESY_SCOPESNoneCALLBACK_URLESY_CALLBACK_URLhttp://localhost:8000SERVER_ADDRESSESY_SERVER_ADDRESSlocalhostSERVER_PORTESY_SERVER_PORT8000DevelopmentESY uses theBravadoOpenAPI library to parse the ESI swagger schema and create
an usable interface. The purpose of creating a custom wrapper of Bravado for ESI, is to make the interface a bit more
user friendly. Pagination is handled automatically by returning generators for any route which accepts a page
parameter, while non-paginated data is handled in their native data type. Tokens can be set per-call, instead of
per-client, allowing for using headers and still getting data for many tokens without the ned to reinitialize the client.The authentication flow usesrequests-oauthlib.