mauribooks 0.1.1

SDK Python pour accéder à l’API MauriBooks

📚 Mauribooks SDK

Un SDK Python moderne et intuitif pour interagir avec l’API Books (dataset inspiré de Goodbooks-10k), spécialement pensé pour les workflows Data.

---

Fonctionnalités principales

• Simple & clair : interface Python ergonomique
• Multi-format : objets Pydantic, dicts et DataFrames Pandas
• Flexible : Compatible avec APIs locales et déployées
• Performant : Optimisé pour l'analyse de données
• Data-friendly : idéal pour l’exploration et la modélisation

---

Installation rapide

pip install mauribooks

Prérequis : Python 3.10+

---

Démarrage rapide

Configuration initiale

from mauribooks import BookClient, BookConfig

# Configuration avec l'API hébergée
config = BookConfig(book_base_url="https://books-project-api.onrender.com")
client = BookClient(config=config)

# Vérification de la connexion
status = client.health_check()
print(status)  # {"message": "API Goodreads opérationnelle"}

Exemples d'utilisation

Récupérer un livre spécifique

# Récupération avec validation Pydantic
book = client.get_book(1)
print(f"Titre : {book.title}")
print(f"Auteurs : {book.authors}")
print(f"Note moyenne : {book.average_rating}")

---

API Reference

Méthodes principales

Méthode	Description	Formats supportés
health_check()	Vérification de l'état de l'API	dict
get_book(id)	Récupération d'un livre par ID	Pydantic
list_books	Liste des livres avec filtres	pydantic, dict, pandas
get_rating(user_id, book_id)	Évaluation d’un utilisateur pour un livre	pydantic
list_book_tags(skip=0, limit=100, book_id=None, tag_id=None, output_format=...)	Relations livre-tag	pydantic, dict, pandas
list_ratings(**kwargs)	Liste des évaluations	pydantic, dict, pandas
get_analytics()	Statistiques globales	pydantic

Multi-formats de sortie

# 1) Pydantic (défaut)
books_p = client.list_books(limit=10)
print(type(books_p[0]))  

# 2) Dictionnaires
books_d = client.list_books(limit=10, output_format="dict")
print(type(books_d))  

# 3) DataFrame
books_df = client.list_books(limit=10, output_format="pandas")
print(books_df.dtypes)

Analyses rapides

import pandas as pd

df = client.list_books(limit=1000, output_format="pandas")

# Top auteurs par nombre de livres dans l'échantillon
print(df['authors'].value_counts().head(10))

# Notes moyennes par langue
lang_stats = (
    df.groupby('language_code', dropna=False)['average_rating']
      .mean()
      .sort_values(ascending=False)
      .round(2)
)
print(lang_stats.head(10))

Relations Livre-Tag

# Relations pour un livre donné
bt_df = client.list_book_tags(book_id=1, limit=20, output_format="pandas")
print(bt_df.head())

# Filtrer par tag_id
bt_df_tag = client.list_book_tags(tag_id=30574, limit=20, output_format="pandas")

Statistics

stats = client.get_analytics()
print(stats)  # ex: book_count, rating_count, tag_count, to_read_count, book_tag_count

Paramètres de configuration

config = BookConfig(
    book_base_url="https://books-project-api.onrender.com",  
    timeout=30,
)

---

Développement local

Pour tester avec une instance locale :

config = BookConfig(book_base_url="http://localhost:8000")
client = BookClient(config=config)

local_df = client.list_books(limit=5, output_format="pandas")
print(local_df)

---

Développement et contribution

Installation en mode développement

git clone https://github.com/Daouda-Ba/Books_Project_API.git
cd mauribooks
pip install -e .

Tests

# (optionnel) tests si présents
pytest -q

---

Roadmap

• Support des requêtes asynchrones
• Cache intelligent des données
• Export vers autres formats (JSON, CSV, Parquet)
• Documentation interactive

---

Public cible

• Data Scientists : Analyse et modélisation de données littéraires
• Data Analysts : Reporting et visualisation
• Développeurs Python : Intégration rapide d'APIs de livres
• Étudiants : Apprentissage de l'analyse de données
• Chercheurs : Études sur les tendances littéraires

---

---

Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

---

Liens utiles

• API (prod) : https://books-project-api.onrender.com
• PyPI Package : https://pypi.org/project/mauribooks
• Docs Swagger : https://books-project-api.onrender.com/docs

---