db/herodb/src/models/py/README.md

Business Models Python Port

This directory contains a Python port of the business models from the Rust codebase, using SQLModel for database integration.

Overview

This project includes:

1. Python port of Rust business models using SQLModel
2. FastAPI server with OpenAPI/Swagger documentation
3. CRUD operations for all models
4. Convenience endpoints for common operations

The models ported from Rust to Python include:

• Currency: Represents a monetary value with amount and currency code
• Customer: Represents a customer who can purchase products or services
• Product: Represents a product or service offered
• ProductComponent: Represents a component of a product
• SaleItem: Represents an item in a sale
• Sale: Represents a sale of products or services

Structure

• models.py: Contains the SQLModel definitions for all business models
• example.py: Demonstrates how to use the models with a sample application
• install_and_run.sh: Bash script to install dependencies using uv and run the example
• api.py: FastAPI server providing CRUD operations for all models
• server.sh: Bash script to start the FastAPI server

Requirements

• Python 3.7+
• uv for dependency management

Installation

The project uses uv for dependency management. To install dependencies and run the example:

./install_and_run.sh

API Server

The project includes a FastAPI server that provides CRUD operations for all models and some convenience endpoints.

Starting the Server

To start the API server:

./server.sh

This script will:

1. Create a virtual environment if it doesn't exist
2. Install the required dependencies using uv
3. Start the FastAPI server with hot reloading enabled

API Documentation

Once the server is running, you can access the OpenAPI documentation at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Available Endpoints

The API provides the following endpoints:

Currencies

• GET /currencies/: List all currencies
• POST /currencies/: Create a new currency
• GET /currencies/{currency_id}: Get a specific currency
• PUT /currencies/{currency_id}: Update a currency
• DELETE /currencies/{currency_id}: Delete a currency

Customers

• GET /customers/: List all customers
• POST /customers/: Create a new customer
• GET /customers/{customer_id}: Get a specific customer
• PUT /customers/{customer_id}: Update a customer
• DELETE /customers/{customer_id}: Delete a customer
• GET /customers/{customer_id}/sales/: Get all sales for a customer

Products

• GET /products/: List all products
• POST /products/: Create a new product
• GET /products/{product_id}: Get a specific product
• PUT /products/{product_id}: Update a product
• DELETE /products/{product_id}: Delete a product
• GET /products/available/: Get all available products
• POST /products/{product_id}/components/: Add a component to a product
• GET /products/{product_id}/components/: Get all components for a product

Sales

• GET /sales/: List all sales
• POST /sales/: Create a new sale
• GET /sales/{sale_id}: Get a specific sale
• PUT /sales/{sale_id}: Update a sale
• DELETE /sales/{sale_id}: Delete a sale
• PUT /sales/{sale_id}/status/{status}: Update the status of a sale
• POST /sales/{sale_id}/items/: Add an item to a sale
• GET /sales/{sale_id}/items/: Get all items for a sale

Dependencies

• SQLModel: For database models and ORM functionality
• Pydantic: For data validation (used by SQLModel)
• FastAPI: For creating the API server
• Uvicorn: ASGI server for running FastAPI applications

Example Usage

The example.py script demonstrates:

1. Creating an SQLite database
2. Defining and creating tables for the models
3. Creating sample data (customers, products, sales)
4. Performing operations on the data
5. Querying and displaying the data

To run the example manually (after activating the virtual environment):

# From the py directory
python example.py

# Or from the parent directory
cd py && python example.py