lightapi 0.1.6__tar.gz → 0.1.8__tar.gz

{lightapi-0.1.6 → lightapi-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lightapi
-Version: 0.1.6
+Version: 0.1.8
 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

{lightapi-0.1.6 → lightapi-0.1.8}/docs/advanced/authentication.md

@@ -732,3 +732,7 @@ app.add_middleware([SecurityHeadersMiddleware])
 ```
 
 This comprehensive authentication system provides enterprise-grade security while maintaining the simplicity and performance that LightAPI is known for. The modular design allows you to implement exactly the authentication strategy your application needs, from simple API keys to complex multi-factor authentication systems.
+
+> **Note:** All JWT-protected endpoints require the `LIGHTAPI_JWT_SECRET` environment variable to be set before running the server.
+
+> **Custom endpoints must specify their intended paths using `route_patterns`. See the mega example for a full-stack authentication and registration demo.**

{lightapi-0.1.6 → lightapi-0.1.8}/docs/api-reference/rest.md

@@ -753,4 +753,19 @@ class User(RestEndpoint):
 - 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. 
+To start your API, always use `api.run(host, port)`. Do not use external libraries or 'app = api.app' to start the server directly. 
+
+## Custom Endpoint Registration with route_patterns
+
+When registering custom (non-model) endpoints, you must specify the intended REST path(s) using the `route_patterns` attribute. Fallback to class names is not supported for custom endpoints.
+
+```python
+class HelloWorldEndpoint(RestEndpoint):
+    route_patterns = ["/hello"]
+    def get(self, request):
+        return {"message": "Hello, World!"}
+
+app.register(HelloWorldEndpoint)
+```
+
+> See the mega example for a comprehensive demonstration of registering multiple endpoints with custom paths. 

{lightapi-0.1.6 → lightapi-0.1.8}/docs/examples/.pages

@@ -6,7 +6,6 @@ nav:
   - Caching: caching.md
   - Filtering and Pagination: filtering-pagination.md
   - Middleware: middleware.md
-  - Relationships: relationships.md
-  - Swagger Documentation: swagger.md
   - Validation: validation.md
-  - Custom Snippets: custom-snippets.md
+  - Custom Application: custom-application.md
+  - Basic CRUD: basic-crud.md

{lightapi-0.1.6 → lightapi-0.1.8}/docs/examples/auth.md

@@ -158,52 +158,41 @@ curl -X POST http://localhost:8000/auth/login \
 }
 ```
 
-### 2. Access Public Endpoint
+### 2. Access User Profile (JWT-protected)
 
-```bash
-curl http://localhost:8000/public
-```
-
-**Response:**
-```json
-{
-  "message": "This is public information"
-}
-```
-
-### 3. Access Protected Endpoint
+> **Note:** The `user_id` field in the profile must match the JWT `sub` claim (e.g., `user_1`).
 
 ```bash
-# Without token (will fail)
-curl http://localhost:8000/secret
-```
-
-**Response:**
-```json
-{
-  "error": "Authentication failed"
-}
-```
+curl -X POST http://localhost:8000/user_profiles \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{
+    "user_id": "user_1",
+    "full_name": "Admin User",
+    "email": "admin@example.com"
+  }'
 
-```bash
-# With valid token
 curl -H "Authorization: Bearer YOUR_TOKEN" \
-     http://localhost:8000/secret
+     http://localhost:8000/user_profiles
 ```
 
 **Response:**
 ```json
 {
-  "message": "Hello, admin! You have admin access.",
-  "secret_data": "This is protected information"
+  "id": 2,
+  "user_id": "user_1",
+  "full_name": "Admin User",
+  "email": "admin@example.com"
 }
 ```
 
-### 4. Access User Profile
+### 3. Troubleshooting
+
+- If you get `{ "error": "Profile not found" }`, ensure you created the profile with `user_id` matching the JWT `sub` claim.
+- Always set the environment variable before running the server:
 
 ```bash
-curl -H "Authorization: Bearer YOUR_TOKEN" \
-     http://localhost:8000/profile
+export LIGHTAPI_JWT_SECRET="your-super-secret-key"
 ```
 
 ## JWT Token Structure

{lightapi-0.1.6 → lightapi-0.1.8}/docs/index.md

@@ -160,3 +160,30 @@ LightAPI is released under the [MIT License](https://github.com/henriqueblobato/
 
 > To start your API, always use `api.run(host, port)`. Do not use external libraries or 'app = api.app' to start the server directly.
 
+## Mega Example: All Features in One App
+
+The `examples/mega_example.py` script demonstrates the full capabilities of LightAPI:
+- RESTful models (products, categories, orders, users, etc.)
+- Custom endpoints (auth, weather, hello, secret, public, etc.)
+- JWT authentication and protected resources
+- Middleware (logging, CORS, rate limiting, authentication)
+- Caching, filtering, pagination, and more
+
+**Available Endpoints:**
+
+| Path                  | Methods                                    | Description                  |
+|-----------------------|--------------------------------------------|------------------------------|
+| /products             | GET, POST, PUT, PATCH, DELETE, OPTIONS     | Product CRUD                 |
+| /categories           | GET, POST, PUT, PATCH, DELETE, OPTIONS     | Category CRUD                |
+| /orders               | GET, POST, PUT, PATCH, DELETE, OPTIONS     | Order CRUD                   |
+| /order_items          | GET, POST, PUT, PATCH, DELETE, OPTIONS     | Order item CRUD              |
+| /users                | GET, POST, PUT, PATCH, DELETE, OPTIONS     | User CRUD                    |
+| /user_profiles        | GET, POST, PUT, PATCH, DELETE, OPTIONS     | User profile (JWT protected) |
+| /auth/login           | POST, OPTIONS                              | JWT login                    |
+| /secret               | GET, OPTIONS (JWT required)                | Protected resource           |
+| /public               | GET, OPTIONS                               | Public resource              |
+| /weather/{city}       | GET, OPTIONS                               | Weather info (custom path)   |
+| /hello                | GET, OPTIONS                               | Hello world (custom path)    |
+
+> All endpoints are registered with explicit RESTful or custom paths using `route_patterns` or `__tablename__`.
+

{lightapi-0.1.6 → lightapi-0.1.8}/docs/tutorial/endpoints.md

@@ -33,6 +33,21 @@ app = LightApi()
 app.register({'/custom-users': CustomUserEndpoint})
 ```
 
+## Registering Custom Endpoints with route_patterns
+
+When defining a custom endpoint (not a SQLAlchemy model), always specify the intended path(s) using the `route_patterns` attribute:
+
+```python
+class HelloWorldEndpoint(RestEndpoint):
+    route_patterns = ["/hello"]
+    def get(self, request):
+        return {"message": "Hello, World!"}
+
+app.register(HelloWorldEndpoint)
+```
+
+> See the mega example for a comprehensive demonstration of this pattern.
+
 ## HTTP Method Configuration
 
 - `http_method_names`: List of allowed HTTP methods.

{lightapi-0.1.6 → lightapi-0.1.8}/examples/README.md

@@ -2,9 +2,9 @@
 
 This directory contains example applications demonstrating various features of the LightAPI framework.
 
-## Basic Examples
+## Example Features
 
-- **user_goal_example.py**: Comprehensive demonstration of intended LightAPI usage patterns
+- **comprehensive_ideal_usage.py**: Comprehensive demonstration of intended LightAPI usage patterns
   - Shows the exact API design philosophy and usage as envisioned
   - Demonstrates custom validators with field-specific validation methods
   - Implements JWT authentication with proper configuration
@@ -13,17 +13,17 @@ This directory contains example applications demonstrating various features of t
   - Includes CORS support and proper environment variable usage
   - **Note**: Some advanced features (caching + pagination) are commented out due to current limitations
 
-- **basic_rest_api.py**: A simple REST API with default CRUD operations
+- **rest_crud_basic.py**: A simple REST API with default CRUD operations
   - Demonstrates minimal setup for a REST endpoint
   - Shows automatic handling of GET, POST, PUT, DELETE operations
   - Illustrates SQLAlchemy model integration with LightAPI
 
-- **validation_example.py**: Data validation with custom validators
+- **validation_custom_fields.py**: Data validation with custom validators
   - Shows field-specific validation rules using Validator class
   - Demonstrates error handling for validation failures
   - Illustrates data transformation (price conversion between dollars and cents)
 
-- **auth_example.py**: JWT authentication with protected resources
+- **authentication_jwt.py**: JWT authentication with protected resources
   - Implements JWT token generation and verification
   - Shows protected endpoints requiring authentication
   - Demonstrates user information extraction from token
@@ -31,45 +31,31 @@ This directory contains example applications demonstrating various features of t
 
 ## Advanced Features
 
-- **custom_snippet.py**: Built-in middleware demonstration
+- **middleware_cors_auth.py**: Built-in middleware demonstration
   - Shows new `CORSMiddleware` and `AuthenticationMiddleware` classes
   - Demonstrates automatic CORS preflight handling with JWT authentication
   - Illustrates seamless integration of authentication with CORS support
   - Uses built-in middleware for cleaner, more maintainable code
 
-- **middleware_example.py**: Custom middleware implementation for request/response processing
-  - Demonstrates request/response lifecycle hooks
-  - Includes logging middleware with request timing
-  - Shows custom CORS headers management for cross-origin requests
-  - Implements rate limiting with custom window controls
-
-- **filtering_pagination_example.py**: Query filtering and result pagination
-  - Shows parameter-based filtering for REST endpoints
-  - Implements custom filter logic for search and range queries
-  - Demonstrates paginated results with metadata
-  - Illustrates dynamic sorting by different fields
-
-- **caching_example.py**: Response caching for improved performance
-  - Shows Redis cache implementation with automatic JSON serialization
-  - Demonstrates cache key generation strategies
-  - Includes time-to-live (TTL) management
-  - Shows manual cache invalidation (DELETE operations)
-  - Implements cache hit/miss HTTP headers
-  - Fixed JSON serialization issues for proper caching
-
-- **swagger_example.py**: Enhanced OpenAPI/Swagger documentation
-  - Demonstrates docstring-based API documentation
-  - Shows custom SwaggerGenerator implementation
-  - Illustrates request/response schema documentation
-  - Implements API grouping with tags
-  - Demonstrates security scheme definitions
-
-- **relationships_example.py**: Complex SQLAlchemy relationships (one-to-many, many-to-many)
-  - Shows many-to-many relationships with association tables
-  - Demonstrates one-to-many relationships with back references
-  - Illustrates cascade behaviors on related objects
-  - Shows nested data serialization across relationships
-  - Implements relationship handling in POST/PUT operations
+- **filtering_pagination.py**: Filtering and pagination
+  - Demonstrates filtering, pagination, and sorting of results
+  - Shows how to use query parameters for advanced queries
+
+- **middleware_custom.py**: Custom middleware and order
+  - Demonstrates how to add custom middleware
+  - Shows the order of middleware execution
+  - Includes logging, CORS, and rate limiting examples
+
+- **relationships_sqlalchemy.py**: SQLAlchemy relationships
+  - Demonstrates one-to-many and many-to-many relationships
+  - Shows how to query related resources
+
+- **swagger_openapi_docs.py**: Swagger/OpenAPI documentation
+  - Shows how to generate and customize API documentation
+  - Demonstrates validator docstrings for better docs
+
+- **general_usage.py**: General usage
+  - Shows custom validator, custom headers, and CRUD
 
 ## New Built-in Features (Latest Updates)
 
@@ -95,17 +81,17 @@ All examples now demonstrate improved CORS handling:
 Each example is self-contained and can be run directly:
 
 ```bash
-# Basic example
-python examples/basic_rest_api.py
+# Basic REST/CRUD example
+python examples/rest_crud_basic.py
 
-# Built-in middleware example (demonstrates new features)
-LIGHTAPI_JWT_SECRET="your-secret-key" python examples/custom_snippet.py
+# Built-in middleware, CORS, Auth example
+LIGHTAPI_JWT_SECRET="your-secret-key" python examples/middleware_cors_auth.py
 
-# Authentication with CORS
-LIGHTAPI_JWT_SECRET="your-secret-key" python examples/auth_example.py
+# JWT Authentication example
+LIGHTAPI_JWT_SECRET="your-secret-key" python examples/authentication_jwt.py
 
 # Caching with Redis (requires Redis running)
-python examples/caching_example.py
+python examples/caching_redis_custom.py
 ```
 
 Most examples will:
@@ -119,11 +105,11 @@ Most examples will:
 The examples now include improved CORS and authentication. Test with:
 
 ```bash
-# Start the custom_snippet example
-LIGHTAPI_JWT_SECRET="test-secret-key-123" python examples/custom_snippet.py
+# Start the middleware_cors_auth example
+LIGHTAPI_JWT_SECRET="test-secret-key-123" python examples/middleware_cors_auth.py
 
-# Start the user goal example (comprehensive demonstration)
-LIGHTAPI_JWT_SECRET="test-secret-key-123" python examples/user_goal_example.py
+# Start the comprehensive_ideal_usage example (comprehensive demonstration)
+LIGHTAPI_JWT_SECRET="test-secret-key-123" python examples/comprehensive_ideal_usage.py
 
 # Test CORS preflight (should work without authentication)
 curl -X OPTIONS http://localhost:8000/custom -v

lightapi-0.1.6/examples/auth_example.py → lightapi-0.1.8/examples/authentication_jwt.py

@@ -124,14 +124,10 @@ if __name__ == "__main__":
         swagger_description="Example showing JWT authentication with LightAPI",
     )
 
-    app.register(
-        {
-            "/auth/login": AuthEndpoint,
-            "/public": PublicResource,
-            "/secret": SecretResource,
-            "/profile": UserProfile,
-        }
-    )
+    app.register(AuthEndpoint)
+    app.register(PublicResource)
+    app.register(SecretResource)
+    app.register(UserProfile)
 
     print("Server running at http://localhost:8000")
     print("API documentation available at http://localhost:8000/docs")
@@ -140,8 +136,6 @@ if __name__ == "__main__":
         'curl -X POST http://localhost:8000/auth/login -H \'Content-Type: application/json\' -d \'{"username": "admin", "password": "password"}\''
     )
     print("\nTo access protected resource:")
-    print(
-        "curl -X GET http://localhost:8000/secret -H 'Authorization: Bearer YOUR_TOKEN'"
-    )
+    print("curl -X GET http://localhost:8000/secret -H 'Authorization: Bearer YOUR_TOKEN'")
 
     app.run(host="localhost", port=8000, debug=True)

lightapi-0.1.8/examples/blog_post.py

@@ -0,0 +1,57 @@
+from datetime import datetime
+
+from sqlalchemy import Column, DateTime, ForeignKey, Integer, String, Text
+from sqlalchemy.orm import relationship
+
+from lightapi import LightApi
+from lightapi.database import Base
+from lightapi.rest import RestEndpoint
+
+print(f"DEBUG: LightApi loaded from {LightApi.__module__}")
+
+
+class BlogPost(Base):
+    __tablename__ = "posts"
+
+    id = Column(Integer, primary_key=True)
+    title = Column(String(200), nullable=False)
+    content = Column(Text, nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+
+    comments = relationship("Comment", back_populates="post", cascade="all, delete-orphan")
+
+
+class Comment(Base):
+    __tablename__ = "comments"
+
+    id = Column(Integer, primary_key=True)
+    content = Column(String(1000), nullable=False)
+    author = Column(String(100), nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    post_id = Column(Integer, ForeignKey("posts.id"), nullable=False)
+
+    post = relationship("BlogPost", back_populates="comments")
+
+
+class Endpoint(RestEndpoint):
+    __tablename__ = "asdasd"
+
+    def get(self, post_id: int):
+        return {"status": "ok"}, 200
+
+    def post(self, data: dict):
+        return {"status": "ok"}, 200
+
+
+if __name__ == "__main__":
+    app = LightApi(
+        enable_swagger=True,
+        swagger_title="Blog Post API",
+        swagger_version="1.0.0",
+        swagger_description="API documentation for the Blog Post application",
+    )
+    app.register(BlogPost)
+    app.register(Comment)
+    app.register(Endpoint)
+
+    app.run(host="0.0.0.0", port=8000)

lightapi-0.1.6/examples/caching_example.py → lightapi-0.1.8/examples/caching_redis_custom.py

@@ -168,9 +168,8 @@ if __name__ == "__main__":
         swagger_description="Example showing caching capabilities with LightAPI",
     )
 
-    app.register(
-        {"/weather/{city}": WeatherEndpoint, "/resource": ConfigurableCacheEndpoint}
-    )
+    app.register(WeatherEndpoint)
+    app.register(ConfigurableCacheEndpoint)
 
     print("Server running at http://localhost:8000")
     print("API documentation available at http://localhost:8000/docs")

lightapi-0.1.6/examples/user_goal_example.py → lightapi-0.1.8/examples/comprehensive_ideal_usage.py

@@ -47,10 +47,10 @@ class Company(RestEndpoint):
         validator_class = CustomEndpointValidator
         filter_class = ParameterFilter
 
-    def post(self, request):
+    async def post(self, request):
         """Handle POST requests with custom Response object"""
         return Response(
-            {"data": "ok", "request_data": getattr(request, "data", {})},
+            {"data": "ok", "request_data": await request.get_data()},
             status_code=200,
             content_type="application/json",
         )
@@ -126,7 +126,8 @@ class CustomCORSMiddleware(Middleware):
 app = LightApi()
 
 # Register endpoints
-app.register({"/custom": CustomEndpoint, "/company": Company})
+app.register(CustomEndpoint)
+app.register(Company)
 
 # Add middleware
 # Note: Custom auth middleware is commented out to avoid blocking all requests

lightapi-0.1.6/examples/filtering_pagination_example.py → lightapi-0.1.8/examples/filtering_pagination.py

@@ -92,9 +92,7 @@ class ProductPaginator(Paginator):
 
                     # Validate the sort field
                     if sort_field in self.valid_sort_fields:
-                        column = getattr(
-                            queryset.column_descriptions[0]["type"], sort_field
-                        )
+                        column = getattr(queryset.column_descriptions[0]["type"], sort_field)
                         if descending:
                             queryset = queryset.order_by(column.desc())
                         else:
@@ -241,9 +239,7 @@ def init_database():
                 category="Clothing",
                 description="Cotton t-shirt",
             ),
-            Product(
-                name="Jeans", price=6000, category="Clothing", description="Denim jeans"
-            ),
+            Product(name="Jeans", price=6000, category="Clothing", description="Denim jeans"),
             Product(
                 name="Sneakers",
                 price=8000,
@@ -341,11 +337,7 @@ if __name__ == "__main__":
         swagger_description="Example showing filtering and pagination with LightAPI",
     )
 
-    app.register(
-        {
-            "/products": Product,
-        }
-    )
+    app.register(Product)
 
     print("Server running at http://localhost:8000")
     print("API documentation available at http://localhost:8000/docs")

lightapi-0.1.6/examples/example.py → lightapi-0.1.8/examples/general_usage.py

@@ -36,13 +36,13 @@ class Company(RestEndpoint):
         validator_class = CustomEndpointValidator
         filter_class = ParameterFilter
 
-    def post(self, request):
+    async def post(self, request):
         """Create a new company.
 
         Accepts company data and creates a new record.
         """
         return Response(
-            {"data": "ok", "request_data": request.data},
+            {"data": "ok", "request_data": await request.get_data()},
             status_code=200,
             content_type="application/json",
         )
@@ -76,7 +76,7 @@ class CustomEndpoint(RestEndpoint):
         caching_method_names = ["GET"]
         pagination_class = CustomPaginator
 
-    def post(self, request):
+    async def post(self, request):
         return {"data": "ok"}, 200
 
     def get(self, request):
@@ -97,12 +97,8 @@ class CORSMiddleware(Middleware):
 
         if hasattr(response, "headers"):
             response.headers["Access-Control-Allow-Origin"] = "*"
-            response.headers[
-                "Access-Control-Allow-Methods"
-            ] = "GET, POST, PUT, DELETE, OPTIONS"
-            response.headers[
-                "Access-Control-Allow-Headers"
-            ] = "Authorization, Content-Type"
+            response.headers["Access-Control-Allow-Methods"] = "GET, POST, PUT, DELETE, OPTIONS"
+            response.headers["Access-Control-Allow-Headers"] = "Authorization, Content-Type"
 
         if request.method == "OPTIONS":
             return Response(status_code=200)
@@ -116,7 +112,8 @@ if __name__ == "__main__":
         swagger_version="1.0.0",
         swagger_description="Example API for demonstrating LightAPI capabilities",
     )
-    app.register({"/companies": Company, "/custom": CustomEndpoint})
+    app.register(Company)
+    app.register(CustomEndpoint)
     # app.add_middleware([MyCustomMiddleware, CORSMiddleware])
 
     print("Server running at http://0.0.0.0:8000")