Guide de démarrage¶

Installation¶

pip install dctdb

from dictdb import DictDB, Condition

Nom du paquet

Le paquet sur PyPI est nommé dctdb, mais le nom à utiliser pour l'import est dictdb.

Installation pour le développement¶

Clonez le dépôt et installez les dépendances :

git clone https://github.com/mhbxyz/dictdb.git
cd dictdb
make setup

Ou manuellement avec uv :

uv sync

Installation depuis les sources¶

pip install -e .

Utilisation de base¶

Créer une base de données¶

from dictdb import DictDB

db = DictDB()

Créer des tables¶

# Créer une table avec la clé primaire par défaut "id"
db.create_table("users")

# Créer une table avec une clé primaire personnalisée
db.create_table("products", primary_key="sku")

# Obtenir une référence vers une table
users = db.get_table("users")
products = db.get_table("products")

Insérer des enregistrements¶

# Clé primaire générée automatiquement
users.insert({"name": "Alice", "email": "alice@example.com"})
# Retourne : 1 (l'identifiant généré automatiquement)

# Clé primaire explicite
users.insert({"id": 100, "name": "Bob", "email": "bob@example.com"})

# Champ de clé primaire personnalisé (sku)
products.insert({"sku": "ABC123", "name": "Widget", "price": 9.99})

Sélectionner des données¶

from dictdb import Condition

# Sélectionner tous les enregistrements
tous_les_utilisateurs = users.select()

# Sélectionner avec une condition
admins = users.select(where=Condition(users.role == "admin"))

# Sélectionner des colonnes spécifiques
noms = users.select(columns=["name", "email"])

# Tri des résultats
utilisateurs_tries = users.select(order_by="name")
ordre_decroissant = users.select(order_by="-name")

# Pagination
page = users.select(order_by="id", limit=10, offset=20)

Mettre à jour des enregistrements¶

# Mettre à jour les enregistrements correspondants
users.update(
    {"role": "moderator"},
    where=Condition(users.name == "Alice")
)

# Retourne le nombre d'enregistrements mis à jour

Supprimer des enregistrements¶

# Supprimer les enregistrements correspondants
users.delete(where=Condition(users.name == "Bob"))

# Retourne le nombre d'enregistrements supprimés

Persistance (Sauvegarde et Chargement)¶

# Sauvegarder au format JSON (lisible)
db.save("database.json", file_format="json")

# Sauvegarder au format Pickle (plus rapide, binaire)
db.save("database.pkl", file_format="pickle")

# Charger depuis un fichier
db = DictDB.load("database.json", file_format="json")

Opérations sur les tables¶

# Lister toutes les tables de la base
db.list_tables()  # ["users", "products"]

# Obtenir les métadonnées d'une table
users.count()           # Nombre d'enregistrements
users.columns()         # Liste des noms de colonnes
users.primary_key_name()  # Nom de la clé primaire ("id")

# Supprimer une table
db.drop_table("products")

Gestion des erreurs¶

from dictdb import (
    DuplicateKeyError,
    DuplicateTableError,
    RecordNotFoundError,
    TableNotFoundError,
    SchemaValidationError,
)

try:
    users.insert({"id": 1, "name": "Duplicate"})
except DuplicateKeyError:
    print("Un enregistrement avec cette clé existe déjà")

try:
    db.create_table("users")
except DuplicateTableError:
    print("La table existe déjà")

try:
    users.delete(where=Condition(users.name == "Inconnu"))
except RecordNotFoundError:
    print("Aucun enregistrement ne correspond aux critères")

Prochaines étapes¶

DSL de requête - Maîtrisez toute la syntaxe de filtrage.
Index - Accélérez vos recherches sur de gros volumes.
Schémas - Ajoutez une validation de type stricte.
Persistance - Sauvegardez et restaurez vos données.
Sauvegardes - Gérez vos sauvegardes automatiques.