README.md

python-eveonline

Async Python client library for the Eve Online ESI API.

Built for use with Home Assistant but can be used standalone in any async Python project.

Features

• Fully async — built on aiohttp
• Typed models — all API responses are frozen dataclasses with full type annotations
• 23 endpoints — public (server, character, corporation, universe) and authenticated (wallet, skills, location, industry, market, mail, notifications, clones, fatigue, contacts, calendar, loyalty, killmails)
• Two-layer caching — TTL caching via ESI Expires header bypasses HTTP entirely; ETag/If-None-Match avoids re-downloading unchanged data (HTTP 304)
• Automatic pagination — paginated endpoints fetch all pages and return a single combined list
• Abstract auth — implement AbstractAuth to plug in any OAuth2 token source
• Type-safe — PEP 561 compatible (py.typed), strict mypy configuration
• Tested — ≥98% test coverage

Installation

pip install python-eveonline

Quick start

import asyncio
import aiohttp
from eveonline import EveOnlineClient

async def main():
    async with aiohttp.ClientSession() as session:
        client = EveOnlineClient(session=session)
        status = await client.async_get_server_status()
        print(f"{status.players} players online (v{status.server_version})")

asyncio.run(main())

Documentation

• Quickstart — public and authenticated endpoint examples
• Authentication — implementing AbstractAuth, required OAuth scopes
• Endpoints — full reference with field tables for all 23 methods
• Error Handling — exception hierarchy, rate limiting, ESI cache times

License

MIT