Skip to content

PokeLance

logo

license black ty ruff stars downloads commits py versions

A flexible, statically typed and easy to use PokéAPI wrapper for Python 🚀

Features:

  • Dual Client Architecture: Full support for both Asynchronous (PokeLanceAsyncClient) and Synchronous (PokeLanceSyncClient) paradigms.
  • Modern HTTP Engine: Built on top of niquests with HTTP/2 and HTTP/3 support.
  • Statically Typed: Fully typed with strict typing support using ty.
  • Automatic Caching: Dual-level caching with in-memory LRU model caches, endpoint pre-warming, and disk serialization.
  • Media Helpers: Built-in async and sync media loaders (get_image, get_audio) with dedicated caching.
  • Developer Experience: Fuzzy "did you mean...?" suggestions on invalid lookups and structured logging.

Installation

# Using uv (recommended)
$ uv add git+https://github.com/FallenDeity/PokeLance.git@beta-v1

# Using pip
$ python -m pip install -U git+https://github.com/FallenDeity/PokeLance.git@beta-v1

Quickstart

Asynchronous Client

import asyncio
from pokelance import PokeLanceAsyncClient


async def main() -> None:
    async with PokeLanceAsyncClient() as client:
        print(await client.ping())

        # Fetch from network (and populate LRU cache)
        berry = await client.berry.fetch_berry("cheri")
        print(f"Fetched: {berry.name} (id={berry.id})")

        # Instant synchronous cache lookup
        cached_berry = client.berry.get_berry("cheri")
        print(f"Cached: {cached_berry}")


asyncio.run(main())

Synchronous Client

from pokelance import PokeLanceSyncClient

with PokeLanceSyncClient() as client:
    print(client.ping())

    berry = client.berry.fetch_berry("cheri")
    print(f"Fetched: {berry.name} (id={berry.id})")

    cached_berry = client.berry.get_berry("cheri")
    print(f"Cached: {cached_berry}")

Guide

Head to the Guide for a full walkthrough covering quickstart, configuration, caching, error handling, media helpers, extensions reference, and recipes for Discord bots and FastAPI services.

Comments