# EsiPy - A python swagger lib for ESI

**URL:** <https://forums.eveonline.com/t/esipy-a-python-swagger-lib-for-esi/14958>\
**Category:** Third Party Developers\
**Tags:** esi, library\
**Created:** [August 7, 2017, 5:48pm UTC](https://forums.eveonline.com/t/esipy-a-python-swagger-lib-for-esi/14958 "2017-08-07T17:48:53Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![Althalus\_Stenory](https://sea1.discourse-cdn.com/eveonline/user_avatar/forums.eveonline.com/althalus_stenory/32/429792_2.png) [@Althalus\_Stenory](https://forums.eveonline.com/u/Althalus_Stenory)\
**Post date:** [August 7, 2017, 5:48pm UTC](https://forums.eveonline.com/t/esipy-a-python-swagger-lib-for-esi/14958/1 "2017-08-07T17:48:53Z")

</div>

[![Version](https://img.shields.io/pypi/v/EsiPy.svg "Esipy Version")](https://pypi.python.org/pypi/EsiPy) ![PyVersion](https://img.shields.io/pypi/pyversions/EsiPy.svg "Supported python version")

**EsiPy** is a **python** library for **ESI API** that dynamically generate everything using the `swagger.json`.

It is written on top of **pyswagger** _(which does the boring stuff)_ but rewrites some objects from it, to add functionalities to deal with some specific use case:

- EVE SSO Auth (generate auth url, tokens stuff, adds the `Bearer` header)
- Caching the responses
- Auto retry on 5xx error and parallel requests

The library is compatible with python `2.7` and `3.3+`.  
&nbsp;

## How to get started with EsiPy

Simply include it in your project using `pip install esipy` and there you are !  
&nbsp;

## Documentations / examples ? I have questions / issues

You can find a complete _(I hope so)_ documentation and some examples here:  
[![Doc](https://img.shields.io/badge/Documentation-GitHub%20Page-lightgrey.svg "Documentation")](https://kyria.github.io/EsiPy/)

If you have any issue, questions or maybe you need a little help, you can either:

- Ask here
- Create an issue on [EsiPy Github](https://github.com/Kyria/EsiPy/issues)
- Ask me on tweetfleet (@althalus)

---

<div class="post-metadata">

**Author:** ![Althalus\_Stenory](https://sea1.discourse-cdn.com/eveonline/user_avatar/forums.eveonline.com/althalus_stenory/32/429792_2.png) [@Althalus\_Stenory](https://forums.eveonline.com/u/Althalus_Stenory)\
**Post date:** [October 22, 2017, 2:33pm UTC](https://forums.eveonline.com/t/esipy-a-python-swagger-lib-for-esi/14958/2 "2017-10-22T14:33:03Z")

</div>

Posting here also, as I made a small breaking change, so more users may see it 😉

# Version 0.2.0

Change :

- `EsiSecurity` object no longer require `app` object to be initialized to get SSO Urls (authorize, token).
  - You can still use it, as before and your app will still work the same as before
  - You can manually give a `sso_url` instead, to say whether you want SISI / TQ SSO (default is TQ) instead of the app object.
  - If both are given, priority is set to the `app` object.

- Use of [https://esi.tech.ccp.is/verify/](https://esi.tech.ccp.is/verify/) for verify instead of the sso endpoint ([https://login.eveonline.com/oauth/verify](https://login.eveonline.com/oauth/verify))

This introduce a small breaking change if you init `EsiSecurity` without keyword, since `app` parameter is no longer the first parameter. You need to:

- either use keywords to init
- or put `app` parameter in the 4th parameter [not recommended]

---

<div class="post-metadata">

**Author:** ![Althalus\_Stenory](https://sea1.discourse-cdn.com/eveonline/user_avatar/forums.eveonline.com/althalus_stenory/32/429792_2.png) [@Althalus\_Stenory](https://forums.eveonline.com/u/Althalus_Stenory)\
**Post date:** [December 25, 2017, 11:14pm UTC](https://forums.eveonline.com/t/esipy-a-python-swagger-lib-for-esi/14958/3 "2017-12-25T23:14:28Z")

</div>

# Version 0.3.0 - Contains potential breaking changes.

## Changes

- Do not try to cache response if there’s no `expires` information (#22)
- Fix cache behavior to be the same everywhere. See details below.
- **Breaking changes :**
  - Renamed signal instances to be fully capitalized.
    - `after_token_refresh` become `AFTER_TOKEN_REFRESH`
    - `api_call_stats` become `API_CALL_STATS`

  - Renamed the following `EsiSecurity` methods:
    - `get_access_token_request_params` to become `get_access_token_params`
    - `get_refresh_token_request_params` to become `get_refresh_token_params`

## New Feature: EsiApp

EsiApp is an object that will be used to play with ESI Meta Swagger spec.   
  
That mean you will be able to easily get meta endpoints, like `/verify`, `/status` the same way as the current App object, but it allows you to also get all current swagger spec used in ESI, for versionned endpoint and others.

[Please look at the doc for how to use it.](https://kyria.github.io/EsiPy/advanced_uses/esiapp/)

## Caching behavior change

Until now, cache objects worked differently when timeout was equal to `0` or `None` depending on which engine you used for caching.   
  
To prevent error if switching between engine and to have consistent behavior, if timeout now equals `0` or `None`, the data will not expire.

---

<div class="post-metadata">

**Author:** ![Althalus\_Stenory](https://sea1.discourse-cdn.com/eveonline/user_avatar/forums.eveonline.com/althalus_stenory/32/429792_2.png) [@Althalus\_Stenory](https://forums.eveonline.com/u/Althalus_Stenory)\
**Post date:** [May 21, 2018, 9:05pm UTC](https://forums.eveonline.com/t/esipy-a-python-swagger-lib-for-esi/14958/4 "2018-05-21T21:05:00Z")

</div>

# Version 0.4.0 - Etag support !

## Cache - Possible breaking change

- All cache have lost the timeout parameter in `set()` method.
- If you have a custom cache with timeout, you should remove it, as it will not allow the Etag process to be used. If you keep it with a default value, it will continue to work.

## EsiClient

- Do not cache `POST`, `PUT` and `DELETE` requests anymore
- Support for head requests
- Add `Etag` mechanism in the cache management
- Allow to set a `raise_on_error` flag in `EsiClient.request()` to get an exception when status is not 2XX.
- Add a `timeout` value for requests in the `EsiClient. __init__ ()` to force timeout requests (default is `None`)
- Allow to define a custom Signal to replace `API_CALL_STATS` using `signal_api_call_stats` when initializing the client.

## EsiSecurity

- Allow to define a custom Signal to replace `AFTER_TOKEN_REFRESH` using `signal_token_updated` when initializing the client.
- Add a token identifier that will be returned to the `AFTER_TOKEN_REFRESH` signal listeners, so it can identify a token

## APIException

- Added request\_param and response\_header to the Exception, to have more precise data for error management

## EsiApp

- `cache_time` parameter value has changed. Number and 0 will still behave like before (forcing a cache time or no expiration with `0`), `None` will disable forced cache time and use `Expires` header from swagger specifications. Default is still 1d caching.
- While getting swagger spec (meta or any version), `EsiApp` will make sure to deal correctly with caching (headers `Expires` and `Etag`) by doing a `HEAD` request before (due to how `App` object works).
- Add a `datasource` argument on initialization, to be able to get swagger spec for specific datasource (`tranquility` by default, or `singularity`)
