lightapi 0.1.8__tar.gz → 0.1.10__tar.gz

lightapi-0.1.10/PKG-INFO

@@ -0,0 +1,449 @@
+Metadata-Version: 2.4
+Name: lightapi
+Version: 0.1.10
+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
+Project-URL: Homepage, https://github.com/henriqueblobato/LightApi
+Author-email: iklobato <iklobato1@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,endpoint,framework,lightweight,rest,restful
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+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
+Requires-Dist: uvicorn<1.0.0,>=0.30.0
+Provides-Extra: dev
+Requires-Dist: black<24.0.0,>=23.3.0; extra == 'dev'
+Requires-Dist: flake8<7.0.0,>=6.0.0; extra == 'dev'
+Requires-Dist: isort<6.0.0,>=5.12.0; extra == 'dev'
+Requires-Dist: mypy<2.0.0,>=1.3.0; extra == 'dev'
+Requires-Dist: pytest<8.0.0,>=7.3.1; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-awesome-pages-plugin; extra == 'docs'
+Requires-Dist: mkdocs-git-authors-plugin; extra == 'docs'
+Requires-Dist: mkdocs-git-committers-plugin-2; extra == 'docs'
+Requires-Dist: mkdocs-git-revision-date-localized-plugin; extra == 'docs'
+Requires-Dist: mkdocs-glightbox; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: httpx<1.0.0,>=0.27.0; extra == 'test'
+Requires-Dist: pyjwt<3.0.0,>=2.8.0; extra == 'test'
+Requires-Dist: pytest<8.0.0,>=7.3.1; extra == 'test'
+Requires-Dist: redis<6.0.0,>=5.0.0; extra == 'test'
+Requires-Dist: starlette<1.0.0,>=0.37.0; extra == 'test'
+Requires-Dist: uvicorn<1.0.0,>=0.30.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# LightAPI: Fast Python REST API Framework with Async, CRUD, OpenAPI, JWT, and YAML
+
+[![PyPI version](https://badge.fury.io/py/lightapi.svg)](https://pypi.org/project/lightapi/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**LightAPI** is a fast, async-ready Python REST API framework that lets you instantly generate CRUD endpoints from SQLAlchemy models or your existing database schema. With built-in OpenAPI documentation, JWT authentication, Redis caching, and YAML-driven configuration, LightAPI is the best choice for building scalable, production-ready APIs in Python.
+
+---
+
+## Table of Contents
+- [Why LightAPI?](#why-lightapi)
+- [Who is LightAPI for?](#who-is-lightapi-for)
+- [Features: Python REST API, Async, CRUD, OpenAPI, JWT, Caching](#features-python-rest-api-async-crud-openapi-jwt-caching)
+- [Feature Details & Usage](#feature-details--usage)
+  - [Automatic CRUD Endpoints with SQLAlchemy](#automatic-crud-endpoints-with-sqlalchemy)
+  - [YAML-Driven API Generation (Database Reflection)](#yaml-driven-api-generation-database-reflection)
+  - [OpenAPI/Swagger Documentation](#openapiswapper-documentation)
+  - [Works with All Major Databases](#works-with-all-major-databases)
+  - [Environment-based Configuration](#environment-based-configuration)
+  - [JWT Authentication and Security](#jwt-authentication-and-security)
+  - [CORS Support for Python APIs](#cors-support-for-python-apis)
+  - [Custom Middleware for Python APIs](#custom-middleware-for-python-apis)
+  - [Async/Await Support for High-Performance Python APIs](#asyncawait-support-for-high-performance-python-apis)
+  - [Redis Caching for Python APIs](#redis-caching-for-python-apis)
+  - [Filtering, Pagination, and Sorting](#filtering-pagination-and-sorting)
+  - [Request Validation](#request-validation)
+  - [Type Hints & Modern Python](#type-hints--modern-python)
+  - [Comprehensive Error Handling](#comprehensive-error-handling)
+- [Quick Start: Build a Python REST API in Minutes](#quick-start-build-a-python-rest-api-in-minutes)
+- [Example Endpoints](#example-endpoints)
+- [Documentation](#documentation)
+- [FAQ](#faq)
+- [Comparison](#comparison)
+- [License](#license)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Why LightAPI?
+
+LightAPI is a modern, async-ready Python REST API framework designed for rapid development and production use. Instantly generate CRUD endpoints from your SQLAlchemy models or YAML config, with full support for OpenAPI docs, JWT authentication, Redis caching, request validation, and more. LightAPI is ideal for anyone who wants to build scalable, maintainable, and high-performance APIs in Python.
+
+---
+
+## Who is LightAPI for?
+
+- **Backend developers** who want to ship APIs fast, with minimal code.
+- **Data engineers** needing to expose existing databases as RESTful services.
+- **Prototypers** and **startups** who want to iterate quickly and scale later.
+- **Anyone** who wants a clean, maintainable, and extensible Python API stack.
+
+---
+
+# Features: Python REST API, Async, CRUD, OpenAPI, JWT, Caching
+
+LightAPI is designed to cover all the essentials for modern API development. Features are grouped for clarity:
+
+## Core Features
+- **Automatic CRUD Endpoints with SQLAlchemy**
+- **YAML-Driven API Generation (Database Reflection)**
+- **OpenAPI/Swagger Documentation**
+- **Works with All Major Databases**
+- **Environment-based Configuration**
+
+## Security & Access Control
+- **JWT Authentication and Security**
+- **CORS Support for Python APIs**
+- **Custom Middleware for Python APIs**
+
+## Performance & Scalability
+- **Async/Await Support for High-Performance Python APIs**
+- **Redis Caching for Python APIs**
+- **Filtering, Pagination, and Sorting**
+
+## Developer Experience
+- **Request Validation**
+- **Type Hints & Modern Python**
+- **Comprehensive Error Handling**
+
+---
+
+# Feature Details & Usage
+
+## Automatic CRUD Endpoints with SQLAlchemy
+Instantly generate RESTful endpoints for your models or tables, so you can create, read, update, and delete records with no manual wiring.
+```python
+from lightapi import LightApi
+from sqlalchemy import Column, Integer, String
+class User(Base):
+    __tablename__ = 'users'
+    id = Column(Integer, primary_key=True)
+    name = Column(String(50))
+app = LightApi()
+app.register(User)
+```
+*How to use:* Define your SQLAlchemy model, register it with `app.register()`, and LightAPI will expose full CRUD endpoints automatically. 
+*Use cases:* Quickly build admin panels, internal tools, or MVPs where you need instant API access to your data.
+
+## YAML-Driven API Generation (Database Reflection)
+Point LightAPI at your existing database and expose tables as REST endpoints without writing model code. [Learn more about SQLAlchemy](https://www.sqlalchemy.org/).
+```yaml
+# config.yaml
+database_url: sqlite:///mydata.db
+tables:
+  - name: users
+    crud: [get, post, put, patch, delete]
+```
+```python
+from lightapi import LightApi
+api = LightApi.from_config('config.yaml')
+api.run()
+```
+*How to use:* Create a YAML config describing your database and tables, then use `LightApi.from_config()` to generate endpoints instantly.
+*Use cases:* Expose legacy or third-party databases as REST APIs for integration, analytics, or migration.
+
+## OpenAPI/Swagger Documentation
+Get interactive API docs and OpenAPI JSON automatically, always in sync with your endpoints. [Learn more about OpenAPI](https://swagger.io/specification/).
+```python
+app = LightApi(swagger_title="My API", swagger_version="1.0.0")
+# Visit http://localhost:8000/docs
+```
+*How to use:* Set Swagger options when creating your app. Docs are auto-generated and always up to date.
+*Use cases:* Share your API with frontend teams, generate client SDKs, or provide public API documentation.
+
+## Works with All Major Databases
+Use SQLite, PostgreSQL, MySQL, or any SQLAlchemy-supported backend. [SQLAlchemy Docs](https://docs.sqlalchemy.org/)
+```python
+app = LightApi(database_url="postgresql://user:pass@localhost/db")
+# or
+app = LightApi(database_url="mysql://user:pass@localhost/db")
+```
+*How to use:* Set the `database_url` parameter to match your database backend.
+*Use cases:* Migrate between databases, support multiple environments, or connect to cloud-hosted DBs.
+
+## Environment-based Configuration
+Configure your app for development, testing, or production using environment variables or YAML.
+```yaml
+# config.yaml
+database_url: sqlite:///dev.db
+debug: true
+```
+```python
+api = LightApi.from_config('config.yaml')
+```
+*How to use:* Store your settings in a YAML file or environment variables, then load them with `from_config()` or `os.environ`.
+*Use cases:* Seamlessly switch between dev, staging, and production setups, or deploy with Docker and CI/CD.
+
+## JWT Authentication and Security
+Secure your API with industry-standard JSON Web Tokens, including login endpoints and protected resources. [Learn more about JWT](https://jwt.io/)
+```python
+from lightapi.auth import JWTAuthentication
+class UserEndpoint(RestEndpoint):
+    class Configuration:
+        authentication_class = JWTAuthentication
+# Set secret
+export LIGHTAPI_JWT_SECRET="supersecret"
+```
+*How to use:* Add `authentication_class = JWTAuthentication` to your endpoint's Configuration. Set the secret key as an environment variable. 
+*Use cases:* Protect sensitive endpoints, implement login/logout, and control access for different user roles.
+
+## CORS Support for Python APIs
+Easily enable Cross-Origin Resource Sharing for frontend/backend integration. [Learn more about CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
+```python
+from lightapi.core import CORSMiddleware
+app.add_middleware([CORSMiddleware])
+```
+*How to use:* Add `CORSMiddleware` to your app's middleware list to allow cross-origin requests from browsers.
+*Use cases:* Enable frontend apps (React, Vue, etc.) to call your API from a different domain during development or production.
+
+## Custom Middleware for Python APIs
+Add logging, rate limiting, authentication, or any cross-cutting logic with a simple middleware interface.
+```python
+from lightapi.core import Middleware
+class LoggingMiddleware(Middleware):
+    def process(self, request, response=None):
+        print(f"{request.method} {request.url}")
+        return response
+app.add_middleware([LoggingMiddleware])
+```
+*How to use:* Subclass `Middleware` and implement the `process` method. Add your middleware to the app.
+*Use cases:* Add request logging, enforce rate limits, or inject custom headers for all responses.
+
+## Async/Await Support for High-Performance Python APIs
+Built on aiohttp for high concurrency and fast response times. All endpoints are async-ready; just use `async def` in your handlers. [Learn more about aiohttp](https://docs.aiohttp.org/)
+```python
+class MyEndpoint(RestEndpoint):
+    async def get(self, request):
+        return {"message": "Async ready!"}
+```
+*How to use:* Write your endpoint methods as `async def` to take full advantage of Python's async capabilities.
+*Use cases:* Handle thousands of concurrent API requests, real-time dashboards, or chat/messaging backends.
+
+## Redis Caching for Python APIs
+Speed up your API with automatic or custom caching of responses, including cache invalidation. [Learn more about Redis](https://redis.io/)
+```python
+from lightapi.cache import RedisCache
+class Product(RestEndpoint):
+    class Configuration:
+        caching_class = RedisCache
+        caching_method_names = ['GET']
+```
+*How to use:* Set `caching_class = RedisCache` and specify which HTTP methods to cache. LightAPI will cache responses transparently.
+*Use cases:* Reduce database load for expensive queries, speed up product catalogs, or cache public data.
+
+## Filtering, Pagination, and Sorting
+Query your data efficiently with flexible filters, paginated results, and sort options.
+```python
+from lightapi.filters import ParameterFilter
+from lightapi.pagination import Paginator
+class ProductFilter(ParameterFilter): ...
+class ProductPaginator(Paginator): ...
+class Product(RestEndpoint):
+    class Configuration:
+        filter_class = ProductFilter
+        pagination_class = ProductPaginator
+```
+*How to use:* Implement custom filter and paginator classes, then assign them in your endpoint's Configuration.
+*Use cases:* Build APIs for large datasets, searchable product listings, or analytics dashboards.
+
+## Request Validation
+Validate incoming data with custom or automatic validators, returning clear error messages.
+```python
+from lightapi.rest import Validator
+class UserValidator(Validator):
+    def validate_name(self, value):
+        if not value:
+            raise ValueError('Name required')
+        return value
+class User(RestEndpoint):
+    class Configuration:
+        validator_class = UserValidator
+```
+*How to use:* Create a Validator class and assign it in your endpoint's Configuration. Validation errors are returned as 400 responses.
+*Use cases:* Enforce business rules, prevent bad data, and provide user-friendly error messages in your API.
+
+## Type Hints & Modern Python
+All code is type-annotated and follows modern Python best practices for maintainability and IDE support.
+
+## Comprehensive Error Handling
+Detailed error messages and robust error handling are built in, making debugging and production support easier.
+
+---
+
+# Quick Start: Build a Python REST API in Minutes
+
+## 1. Install LightAPI
+
+```bash
+pip install lightapi
+```
+
+## 2. Define your model (SQLAlchemy)
+
+```python
+from lightapi import LightApi
+from lightapi.database import Base
+from sqlalchemy import Column, Integer, String
+
+class User(Base):
+    __tablename__ = "users"
+    id = Column(Integer, primary_key=True)
+    name = Column(String(50))
+    email = Column(String(100))
+
+app = LightApi()
+app.register(User)
+
+if __name__ == "__main__":
+    app.run()
+```
+
+## 3. Or use YAML for instant API from your database
+
+```yaml
+# config.yaml
+database_url: sqlite:///mydata.db
+tables:
+  - name: users
+    crud: [get, post, put, patch, delete]
+  - name: orders
+    crud: [get, post]
+```
+
+```python
+from lightapi import LightApi
+api = LightApi.from_config('config.yaml')
+api.run(host="0.0.0.0", port=8081)
+```
+
+---
+
+# Example Endpoints
+
+- `GET    /users/`         - List users
+- `POST   /users/`         - Create user
+- `GET    /users/{id}`     - Get user by ID
+- `PUT    /users/{id}`     - Replace user
+- `PATCH  /users/{id}`     - Update user
+- `DELETE /users/{id}`     - Delete user
+- `GET    /orders/`        - List orders
+- `POST   /orders/`        - Create order
+- `GET    /orders/{id}`    - Get order by ID
+
+---
+
+# Documentation
+
+- [Full Documentation](https://iklobato.github.io/lightapi/)
+- [Getting Started](https://iklobato.github.io/lightapi/getting-started/installation/)
+- [API Reference](https://iklobato.github.io/lightapi/api-reference/core/)
+- [Examples](https://iklobato.github.io/lightapi/examples/basic-rest/)
+- [SQLAlchemy](https://www.sqlalchemy.org/)
+- [aiohttp](https://docs.aiohttp.org/)
+- [OpenAPI](https://swagger.io/specification/)
+- [JWT](https://jwt.io/)
+- [Redis](https://redis.io/)
+
+---
+
+# FAQ
+
+**Q: Can I use LightAPI with my existing database?**  
+A: Yes! Use the YAML config to reflect your schema and instantly expose REST endpoints.
+
+**Q: What databases are supported?**  
+A: Any database supported by SQLAlchemy (PostgreSQL, MySQL, SQLite, etc.).
+
+**Q: How do I secure my API?**  
+A: Enable JWT authentication and CORS with a single line.
+
+**Q: Can I customize endpoints or add business logic?**  
+A: Yes, you can extend or override any handler, add middleware, and use validators.
+
+**Q: Is this production-ready?**  
+A: Yes. LightAPI is designed for both rapid prototyping and production deployment.
+
+---
+
+# Comparison
+
+| Feature                                 | LightAPI | FastAPI | Flask | Django REST |
+|------------------------------------------|----------|---------|-------|-------------|
+| Zero-boilerplate CRUD generation         | ✅       | ❌      | ❌    | ❌          |
+| YAML-driven API/config                   | ✅       | ❌      | ❌    | ❌          |
+| Async/await support                      | ✅       | ✅      | ❌    | ❌          |
+| Automatic OpenAPI/Swagger docs           | ✅       | ✅      | ❌    | ✅          |
+| JWT authentication (built-in)            | ✅       | ❌      | ❌    | ✅          |
+| CORS support (built-in)                  | ✅       | ✅      | ❌    | ✅          |
+| Redis caching (built-in)                 | ✅       | ❌      | ❌    | ✅          |
+| Request validation (customizable)        | ✅       | ✅      | ❌    | ✅          |
+| Filtering, pagination, sorting           | ✅       | ✅      | ❌    | ✅          |
+| Database reflection                      | ✅       | ❌      | ❌    | ❌          |
+| Type hints & modern Python               | ✅       | ✅      | ❌    | ✅          |
+| Custom middleware                        | ✅       | ✅      | ✅    | ✅          |
+| Environment-based configuration          | ✅       | ✅      | ❌    | ✅          |
+| Production-ready out of the box          | ✅       | ✅      | ❌    | ✅          |
+
+---
+
+# License
+
+MIT License. See [LICENSE](LICENSE).
+
+---
+
+> **Note:** Only GET, POST, PUT, PATCH, DELETE HTTP verbs are supported. 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** - The fastest way to build Python REST APIs from your database.
+
+---
+
+# Troubleshooting
+
+### ModuleNotFoundError: No module named 'lightapi'
+
+If you see this error when running example scripts:
+
+```
+Traceback (most recent call last):
+  File "examples/mega_example.py", line 22, in <module>
+    from lightapi.auth import JWTAuthentication
+ModuleNotFoundError: No module named 'lightapi'
+```
+
+**Solution:**
+- Make sure you run the script from the project root directory, not from inside the `examples/` folder.
+- Or, set the `PYTHONPATH` to include the project root:
+
+```bash
+PYTHONPATH=. python3 examples/mega_example.py
+```
+
+This ensures Python can find the `lightapi` package in your local project.