peewee

peewee Best Practices

Peewee is a lightweight, expressive ORM for Python. These guidelines ensure your Peewee code is clean, efficient, and aligns with modern best practices as of 2025.

---

1. Code Organization and Structure

Always establish a clear, DRY (Don't Repeat Yourself) structure for your Peewee models and database connection.

1.1 Define a BaseModel for Database Connection

Centralize your database instance within a BaseModel to avoid repetitive declarations and ensure all models use the same connection.

❌ BAD: Direct database assignment in every model

from peewee import *

db = SqliteDatabase('app.db')

class User(Model):
    username = CharField()
    class Meta:
        database = db # Repeated for every model

✅ GOOD: Inherit from a BaseModel

from peewee import *

db = SqliteDatabase('app.db')

class BaseModel(Model):
    class Meta:
        database = db

class User(BaseModel):
    username = CharField(unique=True)

1.2 Model Naming Convention

Name your model classes in the singular form. Peewee automatically pluralizes table names (e.g., User -> user).

❌ BAD: Plural model name

class Users(BaseModel): # Table might be 'userss' or 'users' depending on backend
    name = CharField()

✅ GOOD: Singular model name

class User(BaseModel): # Table will be 'user'
    name = CharField()

1.3 Explicit Imports for Model Definitions

For model definition files, use from peewee import * for convenience. This is a common and accepted pattern within the Peewee ecosystem. For other modules or specific utility functions, prefer explicit imports.

❌ BAD: Overly verbose imports for model definitions

from peewee import Model, CharField, IntegerField, SqliteDatabase, DateTimeField # ... and so on

✅ GOOD: Concise model definition imports

from peewee import * # For model definition files (e.g., models.py)
import datetime

# In other files (e.g., main.py, services.py), for specific functions/classes:
from peewee import SqliteDatabase, DoesNotExist