EcomLib

A comprehensive Python library for building scalable and secure e-commerce applications. EcomLib provides production-ready tools for inventory management, order processing, payment handling, and more.

✨ Features

🏪 Inventory Management

• Product & Variant Management: Full CRUD operations with hierarchical categories
• Real-time Stock Tracking: Multi-location inventory with automatic low-stock alerts
• Stock Movements: Track purchases, sales, returns, adjustments, and transfers
• Thread-safe Operations: Built-in locking for concurrent access
• Bulk Operations: Efficient batch processing for high-volume updates

🛒 Shopping Cart

• Add/remove/update items with ease
• Automatic price calculations
• Discount and coupon support
• Persistent cart sessions
• Cart abandonment tracking

📦 Order Management

• Complete order lifecycle management
• Status tracking (pending → processing → shipped → delivered)
• Payment status integration
• Refund and return handling
• Order history and search

💳 Payment Processing

• Multiple payment gateway support (Stripe, PayPal, etc.)
• Secure payment handling
• Webhook integration
• Refund processing
• Transaction history

🔐 Security

• JWT-based authentication
• Role-based access control (RBAC)
• Password hashing with bcrypt
• Input validation and sanitization
• CSRF protection

🌍 Additional Features

• Geolocation services
• Address validation
• Tax calculation
• Shipping cost calculation
• Multi-currency support

🚀 Quick Start

Installation

pip install ecomlib

Basic Usage

from ecomlib.inventory import Product, ProductManager, InventoryManager, StockMovement, StockMovementType
from decimal import Decimal

# Initialize managers
product_manager = ProductManager()
inventory_manager = InventoryManager()

# Create a product
product = Product(
    name="Wireless Headphones",
    description="Premium noise-canceling headphones",
    price=199.99,
    sku="WH-001",
    category="electronics"
)
product = product_manager.add_product(product)

# Add stock
movement = StockMovement(
    product_id=product.id,
    quantity=50,
    movement_type=StockMovementType.PURCHASE,
    reference_id="PO-001"
)
inventory_manager.record_movement(movement)

# Check inventory
level = inventory_manager.get_inventory_level(product.id)
print(f"Current stock: {level.available_quantity} units")

# Process a sale
sale = StockMovement(
    product_id=product.id,
    quantity=-5,
    movement_type=StockMovementType.SALE,
    reference_id="ORDER-001"
)
inventory_manager.record_movement(sale)

📖 Documentation

Core Modules

Inventory Management

from ecomlib.inventory import InventoryManager, ProductManager

# Product operations
product_manager = ProductManager()
product = product_manager.add_product(product_data)
product = product_manager.get_product(product_id)
products = product_manager.search_products(query="headphones")

# Inventory operations
inventory = InventoryManager()
inventory.record_movement(movement)
level = inventory.get_inventory_level(product_id)
low_stock = inventory.check_low_stock_items(threshold=10)

Shopping Cart

from ecomlib.cart import ShoppingCart

cart = ShoppingCart()
cart.add_item(
    product_id="prod_123",
    quantity=2,
    price=19.99,
    attributes={'name': 'Product Name', 'sku': 'SKU-001'}
)
total = cart.get_total()
cart.apply_coupon("SAVE10", 10.00)

Order Management

from ecomlib.order import OrderManager, OrderStatus

orders = OrderManager()
order = orders.create_order(
    customer_id="customer_123",
    items=[{
        "product_id": "prod_123",
        "quantity": 2,
        "unit_price": 19.99,
        "name": "Product Name",
        "sku": "SKU-001"
    }],
    shipping_address=address_data
)

# Update order status
order.update_status(OrderStatus.PROCESSING)

Authentication

from ecomlib.auth import AuthManager

auth = AuthManager()

# Register user
user = auth.register_user(
    username="johndoe",
    password="secure_password",
    email="john@example.com"
)

# Login
token = auth.login("johndoe", "secure_password")

# Verify token
payload = auth.verify_token(token)

🧪 Testing

# Run all tests
bash run_all_tests.sh

# Run specific test suite
pytest tests/test_inventory.py -v

# Run with coverage
pytest --cov=ecomlib --cov-report=html

🛠️ Development

Setup Development Environment

# Clone the repository
git clone https://github.com/Shamsulhaq/ecomlib.git
cd ecomlib

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .
pip install -r requirements-dev.txt

# Run tests
bash run_all_tests.sh

Project Structure

ecomlib/
├── ecomlib/                 # Main package
│   ├── __init__.py
│   ├── auth.py             # Authentication
│   ├── cart.py             # Shopping cart
│   ├── exceptions.py       # Custom exceptions
│   ├── inventory.py        # Inventory management
│   ├── order.py            # Order management
│   ├── payment.py          # Payment processing
│   └── security.py         # Security utilities
├── tests/                   # Test suite
│   ├── test_auth.py
│   ├── test_cart.py
│   ├── test_inventory.py
│   └── test_order.py
├── docs/                    # Documentation
├── examples/                # Usage examples
├── CONTRIBUTING.md          # Contribution guidelines
├── README.md               # This file
├── requirements.txt        # Production dependencies
├── requirements-dev.txt    # Development dependencies
└── setup.py               # Package configuration

📊 API Reference

Exception Handling

from ecomlib.exceptions import (
    InsufficientStockError,
    ProductNotFoundError,
    InvalidQuantityError
)

try:
    inventory.record_movement(sale_movement)
except InsufficientStockError as e:
    print(f"Not enough stock: {e}")
    # Handle out of stock scenario
except ProductNotFoundError as e:
    print(f"Product not found: {e}")
    # Handle missing product

Type Hints

All public APIs include type hints for better IDE support:

def record_movement(
    self,
    movement: StockMovement
) -> StockMovement:
    """Record a stock movement."""
    pass

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests
5. Run tests (bash run_all_tests.sh)
6. Commit (git commit -m 'feat: add amazing feature')
7. Push (git push origin feature/amazing-feature)
8. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Thanks to all contributors who have helped improve EcomLib
• Built with ❤️ for the e-commerce community

📧 Contact

• GitHub: @Shamsulhaq
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🗺️ Roadmap

• GraphQL API support
• Async/await support
• Redis caching integration
• Elasticsearch integration
• Admin dashboard
• REST API framework integration (Django, Flask, FastAPI)
• Webhook management system
• Advanced analytics and reporting

⭐ Star History

If you find EcomLib useful, please consider giving it a star on GitHub!

---

Made with ❤️ by the EcomLib Team