open5e-client 0.1.0

A lightweight Python client for the Open5e API

Open5e Client

Open5e Python Client

This is a small Python wrapper for the Open5e API.
This package has dataclasses that allow the uses to look up spells, monsters, classes, races, and magic items from the 5e System Reference Document and other Open5e-supported content. In future iterations I may add feats and subclasses.

---

Overview

The Open5e API provides 5e rules content in a structured JSON format.
This client wraps that API and provides:

• Python dataclasses for each resource
• Methods like
  list_spells(), list_monsters(), get_spell("fireball"), etc.
• Pagination helpers:
  list_all_spells(), list_all_monsters(), etc.
• Pandas dataframe utilities such as
  spells_dataframe(), monsters_dataframe(), etc.

---

Features

• Query spells, monsters, classes, races, and magic items
• Retrieve single entries by name or slug
• Fetch all paginated results automatically
• Convert results to pandas DataFrames for analysis
• Dataclass models capture all known fields + flexible “extras”
• Built using requests and standard Python libraries

---

Installation

Clone the repository and install in editable mode:

git clone <your_repo_url>
cd open5e_client_project
python -m pip install -e .

##QUICK START

from open5e_client import Open5eClient

client = Open5eClient()

# List first 5 evocation spells
spells = client.list_spells(school="Evocation", limit=5)
for s in spells:
    print(s.name, s.level)

# Retrieve a single monster
dragon = client.get_monster("adult-blue-dragon")
print(dragon.name, dragon.armor_class)


##USAGE EXAMPLES

spells = client.list_spells(level=3)
fireball = client.get_spell("fireball")
all_spells = client.list_all_spells()

##Dataframes 

df_spells = client.spells_dataframe()

#PROJECT STRUCTURE

open5e_client_project/
│
├── open5e_client/
│   ├── __init__.py
│   ├── client.py
│   ├── models.py
│   └── ...
│
├── tests/
│   └── (optional pytest files)
│
├── examples/
│   └── open5e_demo.ipynb
│
└── README.md