ecomlib 1.0.0
A comprehensive Python library for building scalable and secure e-commerce applications
License: MIT
Requires Python: >=3.7

# EcomLib

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](tests/)

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

```bash
pip install ecomlib
```

### Basic Usage

```python
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

```python
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

```python
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

```python
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

```python
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

```bash
# 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

```bash
# 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

```python
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:

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

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](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](LICENSE) file for details.

## 🙏 Acknowledgments

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

## 📧 Contact

- **GitHub**: [@Shamsulhaq](https://github.com/Shamsulhaq)
- **Issues**: [GitHub Issues](https://github.com/Shamsulhaq/ecomlib/issues)
- **Discussions**: [GitHub Discussions](https://github.com/Shamsulhaq/ecomlib/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**