lightapi 0.1.3__tar.gz → 0.1.5__tar.gz

{lightapi-0.1.3 → lightapi-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lightapi
-Version: 0.1.3
+Version: 0.1.5
 Summary: A lightweight framework for building API endpoints using Python's native libraries.
 Project-URL: Repository, https://github.com/henriqueblobato/LightApi
 Project-URL: Issues, https://github.com/henriqueblobato/LightApi/issues
@@ -22,6 +22,7 @@ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Requires-Python: >=3.8.1
 Requires-Dist: aiohttp<4.0.0,>=3.9.5
 Requires-Dist: pyjwt<3.0.0,>=2.8.0
+Requires-Dist: pyyaml>=5.1
 Requires-Dist: redis<6.0.0,>=5.0.0
 Requires-Dist: sqlalchemy<3.0.0,>=2.0.30
 Requires-Dist: starlette<1.0.0,>=0.37.0
@@ -112,6 +113,66 @@ That's it! You now have a fully functional REST API with:
 - `DELETE /users/{id}` - Delete user
 - `OPTIONS /users` - CORS preflight support
 
+## Dynamic API from YAML Config (SQLAlchemy Reflection)
+
+LightAPI can instantly generate a REST API from a YAML configuration file, reflecting your database schema at runtime using SQLAlchemy. This is ideal for exposing existing databases with zero model code.
+
+### How It Works
+- **Reflects** the schema of specified tables from your database (PostgreSQL, MySQL, SQLite, etc.)
+- **Dynamically generates** SQLAlchemy models and CRUD endpoints for each table
+- **Configurable**: You control which tables and which CRUD operations (GET, POST, PUT, PATCH, DELETE) are exposed
+- **Composite primary keys, unique constraints, foreign keys, BLOBs, JSON, and more** are supported
+- **Advanced edge cases** (triggers, generated columns, partial unique constraints, etc.) are handled
+
+### End-to-End Example
+
+#### 1. Create a YAML Config
+```yaml
+database_url: sqlite:///mydata.db
+
+tables:
+  - name: users
+    crud: [get, post, put, patch, delete]
+  - name: orders
+    crud: [get, post]
+```
+
+#### 2. Create Your Database (SQLite example)
+```bash
+sqlite3 mydata.db "CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE); CREATE TABLE orders (id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER NOT NULL, amount REAL NOT NULL, FOREIGN KEY(user_id) REFERENCES users(id));"
+```
+
+#### 3. Start the API
+```python
+from lightapi import LightApi
+api = LightApi.from_config('config.yaml')
+api.run(host="0.0.0.0", port=8081)
+```
+
+#### 4. Use the API (with curl)
+```bash
+# Create a user
+curl -X POST http://localhost:8080/users/ -H 'Content-Type: application/json' -d '{"name": "Alice", "email": "alice@example.com"}'
+
+# List users
+curl http://localhost:8080/users/
+
+# Create an order for Alice (id=1)
+curl -X POST http://localhost:8080/orders/ -H 'Content-Type: application/json' -d '{"user_id": 1, "amount": 42.5}'
+
+# List orders
+curl http://localhost:8080/orders/
+```
+
+### FAQ & Tips
+- **Server-side defaults**: Only `server_default` (e.g., `server_default=text('...')`) are available after reflection. Python-side defaults are not reflected.
+- **Composite PKs**: Supported transparently in routes and handlers.
+- **Error handling**: Unique, check, not null, and foreign key constraints are enforced. Violations return 409 Conflict with details.
+- **Partial CRUD**: You can expose only the operations you want per table.
+- **Supported DBs**: Any DB supported by SQLAlchemy reflection (PostgreSQL, MySQL, SQLite, etc.)
+
+See the [docs](./docs/getting-started/quickstart.md#dynamic-api-from-yaml-config-sqlalchemy-reflection) for more advanced examples and details.
+
 ## Documentation
 
 Visit our comprehensive documentation at: https://iklobato.github.io/lightapi/
@@ -158,6 +219,9 @@ class UserValidator(Validator):
 app.register(User, validator=UserValidator())
 ```
 
+- All required fields must be defined as NOT NULL in your database schema for correct enforcement.
+- The API will return 409 Conflict if you attempt to create or update a record missing a NOT NULL field, or violating a UNIQUE or FOREIGN KEY constraint.
+
 ### Middleware
 
 ```python
@@ -205,3 +269,5 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 **LightAPI** - *Making web APIs light and fast* ⚡
 
 <!-- Testing development pipeline -->
+
+> **Note:** Only GET, POST, PUT, PATCH, DELETE HTTP verbs are supported. OPTIONS and HEAD are not available. Required fields must be NOT NULL in the schema. Constraint violations (NOT NULL, UNIQUE, FK) return 409.

{lightapi-0.1.3 → lightapi-0.1.5}/README.md

@@ -61,6 +61,66 @@ That's it! You now have a fully functional REST API with:
 - `DELETE /users/{id}` - Delete user
 - `OPTIONS /users` - CORS preflight support
 
+## Dynamic API from YAML Config (SQLAlchemy Reflection)
+
+LightAPI can instantly generate a REST API from a YAML configuration file, reflecting your database schema at runtime using SQLAlchemy. This is ideal for exposing existing databases with zero model code.
+
+### How It Works
+- **Reflects** the schema of specified tables from your database (PostgreSQL, MySQL, SQLite, etc.)
+- **Dynamically generates** SQLAlchemy models and CRUD endpoints for each table
+- **Configurable**: You control which tables and which CRUD operations (GET, POST, PUT, PATCH, DELETE) are exposed
+- **Composite primary keys, unique constraints, foreign keys, BLOBs, JSON, and more** are supported
+- **Advanced edge cases** (triggers, generated columns, partial unique constraints, etc.) are handled
+
+### End-to-End Example
+
+#### 1. Create a YAML Config
+```yaml
+database_url: sqlite:///mydata.db
+
+tables:
+  - name: users
+    crud: [get, post, put, patch, delete]
+  - name: orders
+    crud: [get, post]
+```
+
+#### 2. Create Your Database (SQLite example)
+```bash
+sqlite3 mydata.db "CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, email TEXT NOT NULL UNIQUE); CREATE TABLE orders (id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER NOT NULL, amount REAL NOT NULL, FOREIGN KEY(user_id) REFERENCES users(id));"
+```
+
+#### 3. Start the API
+```python
+from lightapi import LightApi
+api = LightApi.from_config('config.yaml')
+api.run(host="0.0.0.0", port=8081)
+```
+
+#### 4. Use the API (with curl)
+```bash
+# Create a user
+curl -X POST http://localhost:8080/users/ -H 'Content-Type: application/json' -d '{"name": "Alice", "email": "alice@example.com"}'
+
+# List users
+curl http://localhost:8080/users/
+
+# Create an order for Alice (id=1)
+curl -X POST http://localhost:8080/orders/ -H 'Content-Type: application/json' -d '{"user_id": 1, "amount": 42.5}'
+
+# List orders
+curl http://localhost:8080/orders/
+```
+
+### FAQ & Tips
+- **Server-side defaults**: Only `server_default` (e.g., `server_default=text('...')`) are available after reflection. Python-side defaults are not reflected.
+- **Composite PKs**: Supported transparently in routes and handlers.
+- **Error handling**: Unique, check, not null, and foreign key constraints are enforced. Violations return 409 Conflict with details.
+- **Partial CRUD**: You can expose only the operations you want per table.
+- **Supported DBs**: Any DB supported by SQLAlchemy reflection (PostgreSQL, MySQL, SQLite, etc.)
+
+See the [docs](./docs/getting-started/quickstart.md#dynamic-api-from-yaml-config-sqlalchemy-reflection) for more advanced examples and details.
+
 ## Documentation
 
 Visit our comprehensive documentation at: https://iklobato.github.io/lightapi/
@@ -107,6 +167,9 @@ class UserValidator(Validator):
 app.register(User, validator=UserValidator())
 ```
 
+- All required fields must be defined as NOT NULL in your database schema for correct enforcement.
+- The API will return 409 Conflict if you attempt to create or update a record missing a NOT NULL field, or violating a UNIQUE or FOREIGN KEY constraint.
+
 ### Middleware
 
 ```python
@@ -154,3 +217,5 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 **LightAPI** - *Making web APIs light and fast* ⚡
 
 <!-- Testing development pipeline -->
+
+> **Note:** Only GET, POST, PUT, PATCH, DELETE HTTP verbs are supported. OPTIONS and HEAD are not available. Required fields must be NOT NULL in the schema. Constraint violations (NOT NULL, UNIQUE, FK) return 409.

{lightapi-0.1.3 → lightapi-0.1.5}/docs/api-reference/auth.md

@@ -555,7 +555,7 @@ class DebugAuth(JWTAuthentication):
         
         result = super().authenticate(request)
         print(f"Auth result: {result}")
-        
+
         if hasattr(request.state, 'user'):
             print(f"User: {request.state.user}")
         
@@ -566,4 +566,6 @@ class DebugAuth(JWTAuthentication):
 
 - **[Core API](core.md)** - Application and middleware setup
 - **[REST Endpoints](rest.md)** - Endpoint authentication configuration
-- **[Authentication Example](../examples/auth.md)** - Complete implementation example 
+- **[Authentication Example](../examples/auth.md)** - Complete implementation example
+
+> **Note:** Only GET, POST, PUT, PATCH, DELETE HTTP verbs are supported. OPTIONS and HEAD are not available. Required fields must be NOT NULL in the schema. Constraint violations (NOT NULL, UNIQUE, FK) return 409. 

{lightapi-0.1.3 → lightapi-0.1.5}/docs/api-reference/cache.md

@@ -164,4 +164,6 @@ def update_user(id):
 
 - [Core API](core.md) - Core framework functionality
 - [REST API](rest.md) - REST endpoint implementation
-- [Database](database.md) - Database integration 
+- [Database](database.md) - Database integration
+
+> **Note:** Only GET, POST, PUT, PATCH, DELETE HTTP verbs are supported. OPTIONS and HEAD are not available. Required fields must be NOT NULL in the schema. Constraint violations (NOT NULL, UNIQUE, FK) return 409. 

{lightapi-0.1.3 → lightapi-0.1.5}/docs/api-reference/core.md

@@ -83,24 +83,14 @@ app.add_middleware([
 **Parameters:**
 - `middleware_classes` (List[Type[Middleware]]): List of middleware classes to add
 
-#### run()
+#### run(host: str = "0.0.0.0", port: int = 8000, debug: bool = False) -> None
 
-Starts the development server.
-
-```python
-app.run(
-    host="0.0.0.0",
-    port=8000,
-    debug=True,
-    reload=True
-)
-```
+Starts the server. This is the only supported way to start the application. Do not use external libraries to start the server directly.
 
 **Parameters:**
 - `host` (str): Server host address
 - `port` (int): Server port number
 - `debug` (bool): Enable debug mode
-- `reload` (bool): Enable auto-reload on code changes
 
 ### Advanced Configuration
 
@@ -456,4 +446,6 @@ class CustomEndpoint(RestEndpoint):
                 {"error": "Something went wrong"}, 
                 status_code=500
             )
-``` 
+```
+
+**Note:** Only GET, POST, PUT, PATCH, DELETE HTTP verbs are supported. OPTIONS and HEAD are not available. Required fields must be NOT NULL in the schema. Constraint violations (NOT NULL, UNIQUE, FK) return 409. 

{lightapi-0.1.3 → lightapi-0.1.5}/docs/api-reference/models.md

@@ -193,4 +193,6 @@ except ValueError as e:
 
 - [Database](database.md) - Database integration
 - [REST API](rest.md) - REST endpoint implementation
-- [Validation](validation.md) - Request validation 
+- [Validation](validation.md) - Request validation
+
+> **Note:** Only GET, POST, PUT, PATCH, DELETE HTTP verbs are supported. OPTIONS and HEAD are not available. Required fields must be NOT NULL in the schema. Constraint violations (NOT NULL, UNIQUE, FK) return 409. 

{lightapi-0.1.3 → lightapi-0.1.5}/docs/api-reference/rest.md

@@ -490,7 +490,7 @@ class StatisticsEndpoint(RestEndpoint):
     class Configuration:
         authentication_class = JWTAuthentication
         http_method_names = ['GET']
-    
+
     def get(self, request):
         # Complex analytics logic
         return {
@@ -640,7 +640,7 @@ class RobustEndpoint(RestEndpoint):
     
     id = Column(Integer, primary_key=True)
     name = Column(String(100))
-    
+
     def get(self, request):
         try:
             return super().get(request)
@@ -747,4 +747,10 @@ class User(RestEndpoint):
 - [Core API](core.md) - Core framework functionality
 - [Models](models.md) - Data models and schemas
 - [Filtering](filters.md) - Advanced filtering options
-- [Pagination](pagination.md) - Pagination configuration 
+- [Pagination](pagination.md) - Pagination configuration 
+
+- Only GET, POST, PUT, PATCH, DELETE HTTP verbs are supported. OPTIONS and HEAD are not available.
+- All required fields must be defined as NOT NULL in your database schema for correct enforcement.
+- The API will return 409 Conflict if you attempt to create or update a record missing a NOT NULL field, or violating a UNIQUE or FOREIGN KEY constraint. 
+
+To start your API, always use `api.run(host, port)`. Do not use external libraries or 'app = api.app' to start the server directly. 

{lightapi-0.1.3 → lightapi-0.1.5}/docs/examples/auth.md

@@ -483,4 +483,6 @@ class DebugJWTAuth(JWTAuthentication):
 - **[Middleware Example](middleware.md)** - Custom middleware patterns
 - **[Validation Example](validation.md)** - Request validation
 - **[Caching Example](caching.md)** - Performance optimization
-- **[API Reference](../api-reference/auth.md)** - Authentication API details 
+- **[API Reference](../api-reference/auth.md)** - Authentication API details
+
+> **Note:** Only GET, POST, PUT, PATCH, DELETE HTTP verbs are supported. OPTIONS and HEAD are not available. Required fields must be NOT NULL in the schema. Constraint violations (NOT NULL, UNIQUE, FK) return 409. 

{lightapi-0.1.3 → lightapi-0.1.5}/docs/getting-started/configuration.md

@@ -41,3 +41,29 @@ LIGHTAPI_JWT_SECRET=supersecretkey
 ```
 
 Use `python-dotenv` or your own environment loader to populate these variables before starting your app.
+
+## YAML Config for Dynamic API Generation
+
+You can define your API using a YAML config file for dynamic, reflection-based API generation. This is useful for exposing existing databases without writing models.
+
+**Example:**
+```yaml
+database_url: sqlite:///mydata.db
+tables:
+  - name: users
+    crud: [get, post, put, patch, delete]
+  - name: logs
+    crud: [get]
+```
+
+- `database_url`: Connection string (can use environment variables or a file path)
+- `tables`: List of tables to expose, with allowed CRUD operations per table
+  - `name`: Table name in your database
+  - `crud`: List of allowed HTTP verbs (get, post, put, patch, delete)
+
+**Notes:**
+- Only server-side defaults (e.g., `server_default`) are available after reflection.
+- All SQLAlchemy-reflectable constraints (unique, foreign key, etc.) are enforced.
+- Errors (e.g., constraint violations) return 409 Conflict with details.
+
+See the [Quickstart](quickstart.md#dynamic-api-from-yaml-config-sqlalchemy-reflection) or [README](../../README.md) for more details and advanced usage.

lightapi-0.1.5/docs/getting-started/quickstart.md

@@ -0,0 +1,91 @@
+---
+title: Quickstart
+---
+
+This quickstart guide shows you how to create your first LightAPI application in just a few simple steps.
+
+## 1. Create a Virtual Environment
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+## 2. Install LightAPI
+
+```bash
+pip install lightapi
+```
+
+## 3. Define a SQLAlchemy Model
+
+```python
+# models.py
+from sqlalchemy import Column, Integer, String
+from lightapi.database import Base
+
+class Item(Base):
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String, unique=True, index=True)
+    description = Column(String, nullable=True)
+```
+
+## 4. Create and Run Your App
+
+```python
+# main.py
+from lightapi import LightApi
+from models import Item
+
+app = LightApi()
+app.register({'/items': Item})
+
+if __name__ == '__main__':
+    app.run(host='0.0.0.0', port=8000, debug=True)
+```
+
+Now navigate to `http://localhost:8000/items` in your browser or use CURL to interact with the automatically generated CRUD endpoints.
+
+## Dynamic API from YAML Config (SQLAlchemy Reflection)
+
+LightAPI can generate a REST API from a YAML configuration file, reflecting your database schema at runtime. This is ideal for exposing existing databases without writing models.
+
+### End-to-End Example
+
+**1. Create a YAML config:**
+```yaml
+database_url: sqlite:///mydata.db
+tables:
+  - name: users
+    crud: [get, post, put, patch, delete]
+  - name: orders
+    crud: [get, post]
+```
+
+**2. Create your database (SQLite example):**
+```bash
+sqlite3 mydata.db "CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, email TEXT UNIQUE); CREATE TABLE orders (id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER, amount REAL, FOREIGN KEY(user_id) REFERENCES users(id));"
+```
+
+**3. Start the API:**
+```python
+from lightapi import LightApi
+api = LightApi.from_config('my_api_config.yaml')
+api.run(host="0.0.0.0", port=8080)
+```
+
+**4. Use the API (with curl):**
+```bash
+curl -X POST http://localhost:8080/users/ -H 'Content-Type: application/json' -d '{"name": "Alice", "email": "alice@example.com"}'
+curl http://localhost:8080/users/
+curl -X POST http://localhost:8080/orders/ -H 'Content-Type: application/json' -d '{"user_id": 1, "amount": 42.5}'
+curl http://localhost:8080/orders/
+```
+
+### FAQ
+- Only server-side defaults (e.g., `server_default`) are available after reflection.
+- Composite PKs, foreign keys, and constraints are supported.
+- Violations (e.g., unique, FK) return 409 Conflict with details.
+- You can expose only the operations you want per table.
+
+See the [README](../../README.md) for more details and advanced usage.

{lightapi-0.1.3 → lightapi-0.1.5}/docs/index.md

@@ -14,6 +14,7 @@ description: Enterprise-grade REST API framework for Python
 - **Automatic OpenAPI/Swagger documentation** - Interactive API docs generated automatically
 - **Built-in validation** - Request/response validation with customizable validators
 - **Database integration** - Seamless SQLAlchemy integration with automatic table creation
+- **Dynamic API from YAML** - Instantly generate REST APIs from a YAML config file using SQLAlchemy reflection
 
 ### 🔒 **Security & Authentication**
 - **JWT Authentication** - Built-in JSON Web Token support
@@ -134,9 +135,12 @@ Environment-based configuration with sensible defaults:
 Ready to build your first API? Check out our guides:
 
 1. **[Getting Started](getting-started/)** - Basic setup and your first API
-2. **[Tutorial](tutorial/)** - Step-by-step walkthrough
-3. **[Examples](examples/)** - Real-world examples and patterns
-4. **[API Reference](api-reference/)** - Complete API documentation
+2. **[Dynamic API from YAML Config](getting-started/quickstart.md#dynamic-api-from-yaml-config-sqlalchemy-reflection)** - Instantly expose your database as an API from a config file
+3. **[Tutorial](tutorial/)** - Step-by-step walkthrough
+4. **[Examples](examples/)** - Real-world examples and patterns
+5. **[API Reference](api-reference/)** - Complete API documentation
+
+See the [README](../README.md) for a full feature overview and advanced usage.
 
 ## Community & Support
 
@@ -152,3 +156,7 @@ LightAPI is released under the [MIT License](https://github.com/henriqueblobato/
 
 *Built with ❤️ for Python developers who value simplicity and productivity.*
 
+> **Note:** Only GET, POST, PUT, PATCH, DELETE HTTP verbs are supported. OPTIONS and HEAD are not available. Required fields must be NOT NULL in the schema. Constraint violations (NOT NULL, UNIQUE, FK) return 409.
+
+> To start your API, always use `api.run(host, port)`. Do not use external libraries or 'app = api.app' to start the server directly.
+

{lightapi-0.1.3 → lightapi-0.1.5}/docs/technical-reference/core-api.md

@@ -50,7 +50,7 @@ Adds application-wide middleware.
 
 #### run(host: str = "0.0.0.0", port: int = 8000, debug: bool = False) -> None
 
-Starts the ASGI server using Uvicorn.
+Starts the server. This is the only supported way to start the application. Do not use external libraries to start the server directly.
 
 - **Parameters:**
   - `host`: Host address to bind (default: `"0.0.0.0"`).

{lightapi-0.1.3 → lightapi-0.1.5}/examples/README.md

@@ -203,4 +203,7 @@ def get(self, request):
     return {'data': 'ok'}
 ```
 
-## Notes
+## Notes
+- All required fields must be defined as NOT NULL in your database schema for correct enforcement.
+- The API will return 409 Conflict if you attempt to create or update a record missing a NOT NULL field, or violating a UNIQUE or FOREIGN KEY constraint.
+- Only GET, POST, PUT, PATCH, DELETE HTTP verbs are supported. OPTIONS and HEAD are not available.

{lightapi-0.1.3 → lightapi-0.1.5}/lightapi/__init__.py

@@ -1,9 +1,9 @@
 from .auth import JWTAuthentication
 from .cache import RedisCache
+from .lightapi import LightApi
 from .core import (
     AuthenticationMiddleware,
     CORSMiddleware,
-    LightApi,
     Middleware,
     Response,
 )