lemoDB-foxerbn 1.0.0

A lightweight, schema-aware, CSV-based database with auto-increment IDs

🍋 LemonDB

A lightweight, schema-aware database in Python

Simple • Fast • Readable • Perfect for Small Projects

Features • Quick Start • Documentation • Examples

---

🌟 Features

• 🎯 Schema Validation - Define types and constraints (required, unique)
• 📝 Simple API - Intuitive CRUD operations
• 📦 CSV Storage - Human-readable files, no external database
• 🔍 Easy Queries - Find records with simple dict queries
• 🍋 Helpful Logging - All operations log with lemon icons
• 📂 Custom Paths - Store databases anywhere you want
• ⚡ Zero Dependencies - Uses only Python standard library

---

🚀 Quick Start

Installation

pip install lemonDB

Basic Example

from app import LemonDB

# 1. Define schema
schema = {
    "username": "string",
    "email": "string",
    "age": "integer"
}

# 2. Create database
db = LemonDB(name="users", schema=schema)
# 🍋 Schema 'users' was created

# 3. Save records (as tuples matching schema order)
db.save(
    ("alice", "[e-mail]", 25),
    ("bob", "[e-mail]", 30)
)
# 🍋 Saved 2 record(s) to 'users'

# 4. Query data
users = db.findAll()
print(users)
# [{'username': 'alice', 'email': '[e-mail]', 'age': 25}, ...]

# 5. Find specific records
alice = db.find({"username": "alice"})

# 6. Update
db.updateOne({"username": "alice"}, {"age": 26})
# 🍋 Updated 1 record in 'users'

# 7. Delete
db.deleteOne({"username": "bob"})
# 🍋 Deleted 1 record from 'users'

---

📖 Schema Definition

Simple Schema

schema = {
    "name": "string",
    "age": "integer",
    "score": "float",
    "active": "boolean",
    "joined": "date"
}

Supported Types: string, integer, float, boolean, date

Advanced Schema with Constraints

schema = {
    "id": {"type": "integer", "required": True, "unique": True},
    "email": {"type": "string", "required": True, "unique": True},
    "name": {"type": "string", "required": True},
    "active": {"type": "boolean"}
}

Constraints:

• required: True - Field cannot be empty or None
• unique: True - Field must be unique across all records

---

💡 Examples

Example 1: Todo List

from app import LemonDB

schema = {
    "id": {"type": "integer", "required": True, "unique": True},
    "task": {"type": "string", "required": True},
    "done": {"type": "boolean"}
}

todos = LemonDB("todos", schema=schema)

# Add tasks
todos.save(
    (1, "Buy groceries", False),
    (2, "Learn Python", False),
    (3, "Exercise", False)
)

# Mark as done
todos.updateOne({"id": 2}, {"done": True})

# Find incomplete tasks
incomplete = todos.find({"done": False})
print(f"You have {len(incomplete)} tasks left!")

Example 2: Custom Storage Path

# Store in custom location
db = LemonDB(
    name="products",
    schema={"name": "string", "price": "float"},
    data_dir="/path/to/my/data"
)

db.save(("Laptop", 999.99), ("Mouse", 25.50))
# Files created at: /path/to/my/data/products.csv

Example 3: Multiple Databases

# User database
users_db = LemonDB("users", schema={"name": "string", "email": "string"})

# Products database
products_db = LemonDB(
    "products",
    schema={"name": "string", "price": "float", "stock": "integer"},
    data_dir="./inventory"
)

# Activity logs
logs_db = LemonDB(
    "logs",
    schema={"timestamp": "string", "action": "string"},
    data_dir="/var/logs"
)

---

📚 API Reference

Method	Description	Example
save(*records)	Save one or more records	db.save(("Alice", 25))
findAll()	Get all records	db.findAll()
find(query)	Query records	db.find({"age": 25})
deleteOne(query)	Delete first match	db.deleteOne({"name": "Alice"})
deleteAll()	Delete all records	db.deleteAll()
updateOne(query, data)	Update first match	db.updateOne({"id": 1}, {"age": 26})
count()	Count records	db.count()
test()	Test database status	db.test()

Full Documentation →

---

📂 Project Structure

lemonDB/
├── README.md                    # This file
├── docs.md                      # Full documentation
├── LICENSE                      # MIT License
├── setup.py                     # Package setup
├── requirements.txt             # Dependencies
├── .gitignore                   # Git ignore rules
│
├── app/                         # Main package
│   ├── __init__.py             # Package init
│   ├── core.py                 # LemonDB main class
│   ├── schema.py               # Schema validation
│   ├── engine.py               # CSV storage engine
│   └── utils.py                # Helper utilities
│
├── tests/                       # Test files
│   ├── __init__.py
│   ├── test_creation.py        # Test db creation
│   ├── test_count.py           # Test count function
│   └── test_db_test.py         # Test db.test() method
│
└── examples/                    # Usage examples
    ├── example_save.py         # Save operations
    ├── example_find.py         # Query operations
    ├── example_update.py       # Update operations
    ├── example_delete.py       # Delete operations
    └── todo_app.py             # Complete todo app

Running Tests

# Test database creation
python3 -m tests.test_creation

# Test count function
python3 -m tests.test_count

# Test db.test() method
python3 -m tests.test_db_test

Running Examples

# Save operations
python3 -m examples.example_save

# Find/query operations
python3 -m examples.example_find

# Update operations
python3 -m examples.example_update

# Delete operations
python3 -m examples.example_delete

# Complete todo app
python3 -m examples.todo_app

lemondb_data/
├── users.csv                  # Your data
├── users_metadata.json        # Schema definition
├── products.csv
└── products_metadata.json

Example CSV:

username,email,age
alice,[e-mail],25
bob,[e-mail],30

---

🎯 Use Cases

✅ Perfect for:

• Small to medium projects (< 10K records)
• Prototypes and MVPs
• Configuration storage
• Learning database concepts
• Simple data persistence

⚠️ Not suitable for:

• Large datasets (no indexing)
• Concurrent access (no locking)
• Production systems requiring high performance

---

🔧 Advanced Features

Error Handling

# Skip invalid records instead of raising errors
db.save(
    ("Alice", "[e-mail]"),
    ("Bob", None),  # Missing required field
    ("Charlie", "[e-mail]"),
    raise_on_error=False
)
# Skipping record ('Bob', None): Field 'email' is required
# 🍋 Saved 2 record(s) to 'users'

Database Testing

db.test()
# 🍋 DB 'users' is created and working!
# 🍋 Current records: 5
# 🍋 Schema fields: username, email, age

---

📊 Performance

• Small datasets (< 1K records): ⚡ Instant
• Medium datasets (1K - 10K records): 🏃 Fast
• Large datasets (> 10K records): 🐌 Slower (uses full table scans)

---

🤝 Contributing

Contributions are welcome! Feel free to:

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit pull requests

---

📄 License

MIT License - Use freely in your projects!

---

⬆ Back to Top

Made with ❤️ and 🍋

Features

• CSV-Based Storage: No external database required
• Simple API: Intuitive methods like save(), deleteOne(), deleteAll(), find(), etc.
• Schema Definition: Define your data structure upfront
• Easy Installation: Install via pip install lemonDB
• Minimal Dependencies: Keep it lightweight and fast

Installation

pip install lemonDB

Quick Start

1. Define Your Schema

Create a schema that describes your data structure:

from lemondb import LemonDB

# Define your schema (simple dictionary format)
schema = {
    "name": "string",
    "email": "string",
    "age": "integer",
    "active": "boolean"
}

2. Initialize Your Database

# Create a LemonDB instance
db = LemonDB(name="myapp", engine="csv", schema=schema)

3. Save Data

# Create a record matching your schema
user1 = ["Anna", "[e-mail]", 25, True]

# Save it
db.save(user1)

4. Query Data

# Find records
results = db.find({"name": "Anna"})

# Find all
all_users = db.findAll()

# Delete one record
db.deleteOne({"name": "Anna"})

# Delete all records
db.deleteAll()

# Update records
db.updateOne({"name": "Anna"}, {"age": 26})

# Get count
count = db.count()

Schema Format

Supported data types:

schema = {
    "fieldName": "string",      # Text data
    "age": "integer",            # Whole numbers
    "salary": "float",           # Decimal numbers
    "active": "boolean",         # True/False
    "joined": "date"             # YYYY-MM-DD format
}

Folder Structure

lemonDB/
├── README.md
├── setup.py
├── LICENSE
├── requirements.txt
├── lemondb/
│   ├── __init__.py
│   ├── core.py                  # Main LemonDB class
│   ├── schema.py                # Schema validation
│   ├── engine.py                # CSV engine
│   └── utils.py                 # Helper functions
├── tests/
│   ├── __init__.py
│   ├── test_save.py
│   ├── test_query.py
│   └── test_delete.py
└── examples/
    ├── basic_usage.py
    ├── user_database.py
    └── todo_app.py

Example Usage

Create a User Database

from lemondb import LemonDB

# Define schema
user_schema = {
    "username": "string",
    "email": "string",
    "age": "integer",
    "premium": "boolean"
}

# Initialize
db = LemonDB(name="users", engine="csv", schema=user_schema)

# Add users
user1 = ["anna_teku", "[e-mail]", 25, True]
user2 = ["john_doe", "[e-mail]", 30, False]

db.save(user1)
db.save(user2)

# Query
all_users = db.findAll()
premium_users = db.find({"premium": True})

# Delete
db.deleteOne({"username": "john_doe"})

API Reference

Core Methods

• save(record) - Insert a new record
• findAll() - Retrieve all records
• find(query) - Find records matching query
• deleteOne(query) - Delete first matching record
• deleteAll() - Delete all records
• updateOne(query, data) - Update first matching record
• updateAll(query, data) - Update all matching records
• count() - Get total record count

Data Storage

Your data is stored as CSV files in a lemondb_data/ directory:

lemondb_data/
├── myapp.csv          # Your database file
└── myapp_metadata.json # Schema and metadata

Why LemonDB?

✨ Minimal Setup - No database server needed
✨ Human Readable - CSV files you can open and read
✨ Perfect for Small Projects - Prototypes, scripts, small apps
✨ Lightweight - Minimal dependencies

Limitations

• Best suited for small datasets (< 50K records)
• Single file operations (not optimized for concurrent access)
• No complex joins or transactions

Contributing

Contributions welcome! Feel free to submit issues and pull requests.

License

MIT License - feel free to use in your projects!

---

Happy coding! 🍋