Metadata-Version: 2.4
Name: open5e_client
Version: 0.1.1
Summary: A lightweight Python client for the Open5e API
Author-email: Lenny Ciotti <lc3328@columbia.edu>
License: MIT
Project-URL: Homepage, https://github.com/QMSS-G5072-2025/ciotti_lenny/tree/main/open5e_client_project
Project-URL: Documentation, https://github.com/QMSS-G5072-2025/ciotti_lenny/tree/main/open5e_client_project/docs
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: pandas
Requires-Dist: regex

# Open5e Client

# Open5e Python Client

This is a small Python wrapper for the [Open5e API](https://api.open5e.com/).  
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:

```bash
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


