Skip to content

ESO Logs Python

ESO Logs Python Logo

A comprehensive Python client for the ESO Logs API v2

  • Type Safety: Full type hints with Pydantic models
  • Async First: Native async/await support with HTTP and WebSocket
  • GraphQL Integration: Code generation with `ariadne-codegen` + Claude
  • Security: OAuth2 authentication with parameter validation
  • Testing: 428 tests with comprehensive coverage

Quickstart

# Install from PyPI
pip install esologs-python

# Or install latest development version
git clone https://github.com/knowlen/esologs-python.git
cd esologs-python
pip install -e .

# Set your API credentials
export ESOLOGS_ID="your_client_id"
export ESOLOGS_SECRET="your_client_secret"

import asyncio
from esologs.client import Client
from esologs.auth import get_access_token

async def main():
    token = get_access_token()

    async with Client(
        url="https://www.esologs.com/api/v2/client",
        headers={"Authorization": f"Bearer {token}"}
    ) as client:

        # Get character information
        character = await client.get_character_by_id(id=12345)
        print(f"Character: {character.character_data.character.name}")

        # Search for reports
        reports = await client.search_reports(
            guild_id=123,
            zone_id=456,
            limit=10
        )

asyncio.run(main())

Architecture

graph TB
    A[User Application] --> B[ESO Logs Python Client]
    B --> C[Authentication Layer]
    B --> D[GraphQL Client]
    B --> E[Data Models]
    C --> F[OAuth2 Provider]
    D --> G[ESO Logs API v2]
    E --> H[Pydantic Validation]

    subgraph "Generated Code"
        D
        E
    end

    subgraph "ESO Logs Infrastructure"
        F
        G
    end

Beta Status

This library is now in beta! With 100% API coverage and comprehensive testing, we're focusing on stability and polish before the 1.0 release. The API is considered stable, though minor changes may still occur. See our changelog for the latest updates.