lback-framework 1.0.3
A modern and powerful Python web framework.
License: MIT
Requires Python: >=3.8

# Lback Framework
![Python](https://img.shields.io/badge/Python-3.6%2B-blue)
![License](https://img.shields.io/badge/License-MIT-green)
![Version](https://img.shields.io/badge/Version-1.0.0-orange)
<img src="https://raw.githubusercontent.com/hemaabokila/lback_framework/main/lback/static/Logo.png" alt="Lback Logo" width="38"/>

**[Full Documentation](https://hemaabokila.github.io/lback-docs/)**

Lback A modern and powerful Python web framework aiming to accelerate web application development, focusing on structured architecture, scalability, and providing essential tools out-of-the-box.

## Table of Contents
- [Key Features](#key-features)
- [Installation](#installation)
- [Getting Started](#getting-started)
  - [Create a New Project](#create-a-new-project)
  - [Project Structure (Brief)](#project-structure-brief)
  - [Run the Development Server](#run-the-development-server)
- [Detailed Project Structure](#detailed-project-structure)
  - [Project Root Folder](#project-root-folder)
  - [Apps Structure](#apps-structure)
- [Command-Line Interface (CLI)](#command-line-interface-cli)
  - [Using manage.py](#using-managepy)
  - [Command List](#command-list)
- [Configuration System](#configuration-system)
- [Routing System](#routing-system)
- [Views & Responses](#views--responses)
- [Models & Database](#models--database)
- [Database Migrations System](#database-migrations-system)
- [Middleware System](#middleware-system)
- [Authentication](#authentication)
- [Authorization](#authorization)
- [Templating System](#templating-system)
- [Error Handling & Reporting](#error-handling--reporting)
- [Signal System](#signal-system)
- [Security Features](#security-features)
- [Running Tests](#running-tests)
- [Built-in Admin Panel](#built-in-admin-panel)
- [API Tools](#api-tools)
- [Forms](#forms)
- [Static Files](#ftatic-files)
- [Media Files](#media-files)
- [Deployment](#deployment)
- [Full Documentation](#full-documentation)
- [About the Author / Contact](#about-the-author--contact)
- [License](#license)

## Key Features

Lback Framework offers a rich set of features to help you build robust web applications efficiently:

* **Modular Architecture** – Easily extendable with pluggable modules.
* **Organized Project Structure:** Follows a pattern similar to the popular Django framework for ease of learning and adoption.
* **Powerful Command-Line Interface (CLI):** A wide range of commands to manage your project, apps, databases, users, and more via `manage.py`.
* **Flexible Configuration System:** Load settings from `settings.py`, `config.json`, and environment variables (`.env`).
* **Advanced Routing System:** Define clean and dynamic URL patterns with support for path variables and including other URL files.
* **Middleware Management:** A robust structure for processing requests and responses before and after they reach the View, with support for Dependency Injection for middlewares.
* **Strong ORM Integration:** Full support for SQLAlchemy to efficiently manage data models and interact with databases.
* **Database Migrations System:** Utilize Alembic to manage database schema changes automatically and in an organized manner.
* **Authentication & Authorization:** Built-in support for Session-based and JSON Web Tokens (JWT) authentication, plus a flexible permissions system.
* **Efficient Templating System:** Uses the Jinja2 templating engine to render dynamic and reusable HTML interfaces.
* **Error Handling:** Catch errors and generate appropriate responses, with a built-in system for displaying detailed error reports in the browser during development.
* **Security Features:** Tools to protect against common vulnerabilities like CSRF, CORS, SQL Injection, and XSS, along with Rate Limiting and Security Headers.
* **Built-in Admin Panel:** A ready-to-use administrative system with a Dashboard and user management.
* **API Tools:** Helper tools for building Application Programming Interfaces (APIs), including data serialization.
* **forms**: Provides tools for creating and validating HTML forms.
* **Static Files:** Efficiently serves static assets like CSS, JavaScript, and images.
* **Media Files:** Manages user-uploaded media files
* **Signals System:** Allows decoupled applications to get notified when actions occur elsewhere in the framework.
* **Utilities** – Includes helper functions for sessions, users, emails, etc.
* **WSGI Support:** Ready for deployment on production WSGI servers.
* **Integrated Testing:** Support for Pytest to write and run application tests.
* **Other Development Tools:** built-in Logging and Debugging tools.
* **Debugging Tools** – Built-in tools for debugging and performance monitoring.
* **Tailwind CSS Integration** – Optional frontend styling with Tailwind CSS.
* **Documentation** – Comprehensive API documentation and developer guides.

## Installation

To ensure a smooth installation and proper functioning of Lback Framework, especially for file handling features, please follow these steps:

### 1. Create and Activate a Virtual Environment (Recommended)

It's highly recommended to create a dedicated virtual environment for your project. This isolates your project's dependencies and prevents conflicts with other Python projects on your system.

```bash
# Create a virtual environment named 'venv' in your project directory
python3 -m venv venv

# Activate the virtual environment

# On macOS and Linux:
source venv/bin/activate

# On Windows:
.\venv\Scripts\activate
```
Once activated, your terminal prompt will typically show `(venv)` indicating you are in the virtual environment.
### 2. Install System-level Dependencies (for File Type Detection)
Lback Framework utilizes `python-magic` for robust file type detection.

This Python library relies on a native system library called `libmagic`.

You need to install `libmagic` using your system's package manager **before** installing Lback's Python packages.

**For macOS and Linux users:**

**On Debian/Ubuntu-based systems:**
```bash
sudo apt-get update
sudo apt-get install libmagic
```
**On Fedora/RHEL/CentOS-based systems:**
```bash
sudo dnf install file-libs # or sudo yum install file-libs
```
**On macOS (using Homebrew):**
```bash
brew install libmagic
```
**For Windows users:**
No manual steps are typically required for `libmagic`.

Lback's installation process will automatically handle this dependency for you using `python-magic-bin`.
### 3. Install Lback Framework**
With your virtual environment active and system-level dependencies installed (if applicable), you can now install the Lback Framework using pip:
```bash
pip install lback-framework
```
## Getting Started
Start your first project by following these simple steps.

### Create a New Project
Use the startproject command to create a new project structure:

```Bash
lback startproject myproject
```
Replace myproject with your desired project name.

### Project Structure (Brief)
A new folder named after your project (myproject) will be created containing the following basic structure (similar to Django's structure):
```bash
myproject/
├── alembic/
│   ├── versions/
│   ├── env.py
│   └── script.py.mako  
├── myproject/          # Main project package folder
│   ├── __init__.py
│   ├── urls.py         # Main URL configurations
│   └── wsgi.py         # WSGI entry point for production deployment
├── .env                # Environment variables file (optional)
├── config.json         # Additional JSON format config file (optional)
├── manage.py           # Command-line utility for project management
└── settings.py         # Main settings file
```
### Run the Development Server
Navigate into your project folder and run the development server using the runserver command:

```Bash
python manage.py runserver
```
The server will typically run on http://127.0.0.1:8000/ by default.

## Detailed Project Structure
Lback Framework adopts an organized project structure to facilitate efficient development and component management.

### Project Root Folder
The project folder created by `startproject` contains the main files and configurations:
- `manage.py`: The project management script. Used to execute all CLI commands provided by the framework.
- `settings.py`: The main Python settings file for your project. This is where you define installed apps, database settings, Middlewares, etc.
- `urls.py`: The main URL configuration file. Here you define the root URL patterns and include URL patterns from different apps.
- `wsgi.py`: The entry point for your application when deployed using a WSGI server (like Gunicorn or uWSGI).
- `config.json`: An additional configuration file you can use for settings you prefer to keep in JSON format. It's loaded after .env and before `settings.py`.
- `.env`: A file for defining environment variables specific to your project (e.g., database connection details). It's loaded first.
### Apps Structure
Your project can be organized into separate applications (Apps) using the startapp command.

Each app represents a specific functional unit and has its own structure:
```bash
myproject/
└── myapp/  # App folder
    ├── __init__.py
    ├── admin.py      # Register models with the admin panel
    ├── models.py     # Define data models for the app (SQLAlchemy)
    ├── serializer.py # Serialization tools for API (if the app has API endpoints)
    ├── urls.py       # URL configurations for the app
    └── views.py      # Define View functions or classes that handle requests
```
## Command-Line Interface (CLI)
Lback Framework provides a `manage.py` script to manage your project from the command line.

### Using manage.py
To manage your project, navigate to the project folder in your terminal and execute commands using the following syntax:

```Bash
python manage.py <command> [arguments]
```
### Command List
Here is a list of commands available via `python manage.py`:



| Command             | Description                                                                 | Arguments                                      |
|---------------------|-----------------------------------------------------------------------------|------------------------------------------------|
| `startapp <name>`   | Creates a new app folder structure with the specified name.                 | `name`: The name for the new app.              |
| `runserver`         | Runs the local development server for your application.                     | None                                           |
| `makemigrations`    | Creates new database migration files based on changes in your Models.       | None                                           |
| `migrate`           | Applies pending database migrations.                                        | None                                           |
| `rollback <table>`  | Rolls back the last applied migration for a specific table.                 | `table`: The name of the table to rollback.    |
| `test`              | Runs all tests found in your project.                                       | None (Pytest options can be added)             |
| `collectstatic`     | Collects static files (CSS, JavaScript, Images) into a single folder.       | None                                           |
| `init_db`           | Initializes the database (typically used to create initial tables).         | None                                           |
| `create_superuser`  | Creates a superuser account for accessing the admin panel.                  | None (Prompts for username and password)       |
| `reset_password`    | Resets the password for an existing user.                                   | None (Prompts for user details)                |
| `deactivate_user`   | Deactivates an existing user account.                                       | None (Prompts for user details)                |
| `list_users`        | Lists all registered users in the system.                                   | None                                           |
| `activate_user`     | Activates a previously deactivated user account.                            | None (Prompts for user details)                |



## Configuration System
Lback Framework allows you to manage your project's settings with high flexibility.

Settings are loaded in the following order (later sources override earlier ones):

1. `.env` **file:** Environment variables from this file are loaded first.
2. `config.json` **file:** Settings from this JSON file are loaded.
3. `settings.py` **file:** Settings defined in this Python file are loaded (typically your main settings).

4. **Actual Environment Variables:** Environment variables defined in the operating system override all previous sources.

You can access settings anywhere in your application through the `config` object, typically made available via Dependency Injection.

## Routing System
URL configuration in Lback is usually done in `urls.py` files using a `urlpatterns` list.

You define patterns that map a URL path to a View function or class to handle the request.

```Python
# courses/urls.py
from lback.utils.urls import path
from .views import course_list_view

urlpatterns = [
    path("/courses/", course_list_view, allowed_methods=["GET"], name="course_list")
]
```
### URL Including
You can organize app-specific URLs in separate `urls.py` files and include them in the main URL configuration using the `include` function:

```Python
# myproject/urls.py
from lback.core.urls_utils import include

urlpatterns = [
    include('courses.urls', prefix='/'), # Include course URLs at the root path
    include('lback.admin.urls', prefix='/admin/'), # Include Admin URLs under the /admin/ prefix
    # ... other paths
]
```
## Views & Responses
Views are functions or classes that receive a `Request` object and return a `Response` object.

They are responsible for the logic of processing the request, interacting with Models and Templates, and generating the appropriate response.

```Python
# course/views.py
from lback.utils.shortcuts import render
from .models import Course

def course_list_view(request):
    db_session = request.db_session
    courses = db_session.query(Course).all()
    context = {
        "courses": courses, 
    }
    return render(request, "course_list.html", context)
```
The framework provides ready-to-use Response classes like `HTMLResponse`, `JSONResponse`, `RedirectResponse`, etc., to simplify response generation.

## Models & Database
Lback Framework supports database integration using SQLAlchemy as the ORM.

You define your data models as Python classes inheriting from SQLAlchemy's declarative base.

```Python
# courses/models.py
from datetime import datetime
from sqlalchemy import Column, Integer, String, DateTime, ForeignKey
from lback.models.base import BaseModel

class Course(BaseModel):
    __tablename__ = 'courses'

    id = Column(Integer, primary_key=True, autoincrement=True)
    name = Column(String(200), nullable=False)
    description = Column(String)
    created_at = Column(DateTime, default=datetime.utcnow)
    updated_at = Column(DateTime, onupdate=datetime.utcnow)
    image_path = Column(String(255), nullable=True)
    slug = Column(String(255), unique=True, nullable=True)

    def __str__(self):
        return self.name

    # ... relationships and other models
```
Database sessions are typically managed and provided to Views and other components via the SQLAlchemy Middleware and Dependency Injection.

## Database Migrations System
Using Alembic, you can manage database schema changes (adding tables, columns, modifying, deleting) in an organized and automated way.

- Use `python manage.py makemigrations` to create a new migration file based on your Model changes.
- Use `python manage.py migrate` to apply pending migrations to the database.
- Use `python manage.py rollback <table>` to roll back migrations for a specific table.
## Middleware System
Middlewares are components that process requests and responses in a chain before and after they reach the View.

They can be used for common tasks like authentication, logging requests, adding security headers, managing database sessions, and more.

The list of Middlewares is defined in your project's settings (typically in `settings.py`).

The framework provides a set of built-in Middlewares (as seen in the logs):

- `SQLAlchemySessionMiddleware`: Manages database sessions per request.
- `MediaFilesMiddleware`: Serves media files.
- `StaticFilesMiddleware`: Serves static files.
- `SessionMiddleware`: Manages user sessions.
- `FirewallMiddleware`: Acts as an internal firewall.
- `RateLimitingMiddleware`: Limits request rates.
- `SQLInjectionDetectionMiddleware`: Detects and prevents SQL injection.
- `BodyParsingMiddleware`: Parses and prepares request body data.
- `AuthMiddleware`: Handles authentication (Session and JWT).
- `CSRFMiddleware`: Provides protection against Cross-Site Request Forgery attacks.
- `CORSMiddleware`: Manages Cross-Origin Resource Sharing policies.
- `LoggingMiddleware`: Logs request and response details.
- `TimerMiddleware`: Measures and logs request response time.
- `DebugMiddleware`: Displays debugging information and request/response details during development.
- `SecurityHeadersMiddleware`: Adds HTTP security headers.

The framework also supports Dependency Injection in Middlewares, making it easy to access other components (like the Config, Loggers, Managers) from within a Middleware.

## Authentication
The framework provides a comprehensive and ready-to-use system for user management and **authentication**.

You can quickly integrate a full authentication flow into your application with minimal setup.
### Quick Setup for Authentication
To enable and configure the built-in authentication system, follow these simple steps:
#### 1- Create Authentication Templates:

The framework expects specific HTML templates for the authentication pages.

You just need to create these files in your `templates` directory (or wherever your framework is configured to look for templates):

* `register.html`: For user registration.
* `auth_login.html`: For user login.
* `request_password_reset.html`: For requesting a password reset link.
* `reset_password_confirm.html`: For setting a new password after a reset request.

These templates will automatically be rendered by the framework's internal authentication views, providing a consistent user experience.

#### 2- Add `auth_app` to `INSTALLED_APPS`:

Include the authentication application in your project's settings to enable its functionalities and ensure its views and models are loaded:
```python
# settings.py
INSTALLED_APPS = [
    # ... other apps ...
    'auth_app', # Include the built-in authentication application
]
```
#### 3- Include Authentication URLs:

Add the `auth_app` URLs to your project's main `urlpatterns`.

This makes all the necessary authentication endpoints (both web-based and API) accessible:
```python
# myproject/urls.py
from lback.core.urls_utils import include

urlpatterns = [
    include('lback.auth_app.urls', prefix='/auth/'),
    include('lback.admin.urls', prefix='/admin/'),
    # ... other project URLs ...
]
```
#### 4- Configure Email Settings (for Password Resets & Email Verification):
For features like password reset emails or email verification, you'll need to provide your SMTP server details in your `settings.py`:
```python
# settings.py
SMTP_SERVER = "smtp.gmail.com"  # Your SMTP server address
SMTP_PORT = 587                 # Your SMTP server port (e.g., 587 for TLS, 465 for SSL)
EMAIL_USERNAME = "your_email@example.com" # The email address for sending
EMAIL_PASSWORD = "your_app_password" # The password for the sending email (use app-specific passwords for security)
SENDER_EMAIL = "your_email@example.com" # The 'From' email address
USE_TLS = True                  # Set to True for TLS/SSL encryption
SENDER_NAME = "Your App Name"   # The sender name displayed in emails
```
This setup enables the framework to send transactional emails required for the authentication process.
### What the System Provides Automatically
Once configured, the framework's authentication system automatically handles:

* **Session-based Authentication:** Manages user sessions using cookies.
* **JWT Authentication:** Supports JSON Web Tokens for API authentication.
* **Secure Password Hashing:** Stores passwords securely using industry-standard hashing.
* **Pre-built Views & Endpoints:** Provides all necessary URL routes and underlying logic for registration, login, logout, email verification, and password reset (both web-based and API endpoints).
* **User Managers:** Utilizes internal helper classes (`UserManager`, `AdminUserManager`, `SessionManager`) for efficient user and session management.
## Authorization
Beyond authentication (verifying who a user is), **authorization** controls what an authenticated user is allowed to do.

The framework provides a flexible and robust system to define and enforce permissions, ensuring users can only access the resources and functionalities they are authorized for.

### 1- Permissions System: Role-Based Access Control (RBAC)
The core of the authorization system is built around a **Role-Based Access Control (RBAC)** model, allowing you to define granular permissions and organize them effectively.

* **`UserPermission` Model:** This model represents individual, distinct permissions (e.g., `blog.add_post`, `users.view_profile`, `admin.manage_settings`). You can define as many specific permissions as your application needs.

* **`Group` Model:** Groups act as roles.You can create groups (e.g., "Editors", "Moderators", "Managers") and assign a collection of `UserPermission` objects to each group.This simplifies permission management, as you assign users to groups rather than individually assigning many permissions to each user.
* **`User` Model:** Users are then assigned to one or more `Group` objects.A user inherits all permissions from the groups they belong to.The `User` model includes a robust `has_permission(permission_name: str) -> bool` method which efficiently checks if a user possesses a specific permission, considering their group memberships.
### Key Features:

* **Granular Control:** Define specific permissions that represent actions or access rights.
* **Superuser Bypass:** Users designated as "superusers" (typically by being part of an "admin" group or having an `is_superuser` flag) automatically bypass all permission checks, granting them full administrative access.
* **Efficient Checks:** The `has_permission` method on the `User` model uses caching to optimize performance, reducing database queries for frequently checked permissions.

### 2- Managing Permissions, Groups, and Users
The framework's **generic Admin Panel** provides a convenient interface for managing your authorization structure:
* **Adding Permissions:** Through the Admin Panel, you can define new `UserPermission` entries, giving them a unique name and an optional description. These represent the individual capabilities in your system.
* **Creating Groups:** You can create new `Group` objects (roles) and assign a name and description.
* **Assigning Permissions to Groups:** Crucially, the Admin Panel allows you to easily associate any defined `UserPermission` with specific `Group` objects. For example, you could create an "Editor" group and assign it `blog.add_post`, `blog.edit_post`, and `blog.delete_post permissions`.
* **Assigning Users to Groups:** Finally, you can assign individual `User` accounts to one or more `Group` objects. A user will then inherit all permissions from the groups they are a member of.

This integrated approach means you don't have to write custom code for basic permission management; it's all handled through the Admin Panel
### 3- Enforcing Authorization with `PermissionRequired` Decorator
The primary way to enforce authorization on your views is by using the `PermissionRequired`
**decorator**.

This decorator ensures that only users with the necessary permissions can access a particular view.
### How to Use:
You can apply the `PermissionRequired` decorator to your view functions or methods.

It accepts one or more permission strings:
* **Single Permission:**
```python
# myapp/views.py
from lback.auth.permissions import PermissionRequired
from lback.utils.shortcuts import render

@PermissionRequired("blog.view_posts")
def view_blog_posts(request):
    # This view requires the 'blog.view_posts' permission
    # ... fetch blog posts ...
    return render(request, "blog/list.html", {"posts": posts})
```
* **Multiple Permissions (User needs ALL of them):**
```python
# myapp/views.py
from lback.auth.permissions import PermissionRequired
from lback.utils.shortcuts import render

@PermissionRequired(["blog.add_post", "blog.publish_post"])
def create_and_publish_post(request):
    # This view requires BOTH 'blog.add_post' AND 'blog.publish_post' permissions
    # ... logic to create and publish a post ...
    return render(request, "blog/new_post_success.html")
```
* **Dynamic Permissions (Permissions based on request context):**
For more complex scenarios, you can provide a callable (a function) to `PermissionRequired`.
This function will receive the `request` object and should return the required permission(s) dynamically.
```python
# myapp/views.py
from lback.auth.permissions import PermissionRequired
from lback.utils.shortcuts import render

def get_dynamic_edit_permission(request):
    # Example: permission based on the type of user or object being edited
    if request.user and request.user.is_staff: # Assuming 'is_staff' property on User model
        return "article.edit_all"
    return "article.edit_own"

@PermissionRequired(get_dynamic_edit_permission)
def edit_article_view(request, article_id):
    # Permissions are determined by the 'get_dynamic_edit_permission' function at runtime
    # ... logic to edit an article ...
    return render(request, "articles/edit.html", {"article_id": article_id})
```
### 4- Permission Check Flow & Denied Access Handling
When a view decorated with `PermissionRequired` is accessed:

1. The framework attempts to retrieve the authenticated `user` object from the `request`.
2. If the user is a **superuser**, access is immediately granted.
3. Otherwise, the system calls the `user.has_permission()` method for each required permission.
4. If the user lacks any of the specified permissions, access is denied.
5. **Denied Access Handling:**
    * If the user is **not authenticated** at all, they are redirected to the login page (`/auth/login/`) with a flash message.
    * If the user is authenticated but **lacks the required permissions**, they are redirected to a 403 Forbidden page (`return_403`) with a flash message indicating denied access.
### 5- Signals for Authorization Flow
The authorization process also dispatches signals, allowing you to hook into the permission checking lifecycle for custom logic or logging:

* `permission_check_started`: Broadcast when a permission check begins.
    * **Sender:** `PermissionRequired` instance
    * **Kwargs:** `request`, `required_permissions` (set of permissions being checked), `user` (the user object), `view_func_name` (name of the view function).
* `permission_check_succeeded`: Broadcast when a user successfully passes a permission check.
    * **Sender:** `PermissionRequired` instance
    * **Kwargs:** `request`, `required_permissions`, `user`, `view_func_name`.
* `permission_check_failed`: Broadcast when a user fails a permission check.
    * **Sender:** `PermissionRequired` instance
    * **Kwargs:** `request`, `required_permissions`, `user`, `view_func_name`, `reason` (e.g., "user_not_authenticated", "permission_missing").

## Templating System
The framework uses the Jinja2 templating engine to render dynamic HTML pages.

Within your Views, you can use the `render` shortcut function (which leverages the `TemplateRenderer` available via Dependency Injection) to render templates:

```Python
# myapp/views.py
from lback.utils.shortcuts import render # Assuming 'render' is imported from framework shortcuts
from .models import Course
# ...

def course_list_view(request):
    db_session = request.db_session
    courses = db_session.query(Course).all()
    context = {
        "courses": courses, 
    }
    return render(request, "course_list.html", context) # Render the template
```
### How the `render` Shortcut Works
The `render` function simplifies template rendering by automatically handling common tasks.

It retrieves the `TemplateRenderer` from the request context and injects crucial data into your

template, such as:

- `request`: The incoming Request object.
- `current_user`: Information about the authenticated user.
- `session`: Session data.
- `config`: Your application's configuration.
- `csrf_token`: A token for Cross-Site Request Forgery (CSRF) protection.
- `static(path)`: A helper function to generate URLs for static files (e.g., CSS, JavaScript, images).

This approach ensures your templates have access to essential application data and security tokens without repetitive manual inclusion in every view.

### Example Template (`course_list.html`)
Here's how you might structure `course_list.html` to display the `courses` data passed from

the view:
```html
<!DOCTYPE html>
<html>
<head>
    <title>Course List</title>
</head>
<body>
    <h1>All Courses</h1>
    <ul>
        {% for course in courses %}
            <li>{{ course.title }} - {{ course.created_at.strftime('%Y-%m-%d') }}</li>
        {% endfor %}
    </ul>
</body>
</html>
```
This setup provides a clear and concise way to build dynamic web pages using Jinja2 templates in your Lback Framework application.
## Error Handling & Reporting
The framework includes a mechanism to catch errors that occur during request processing and generate appropriate error responses (like 404 Not Found, 500 Internal Server Error).

During development, the framework features a browser error reporting system that provides a detailed report of the error (stack trace, request variables, project settings) to help you debug quickly.

You can customize these error pages using templates.

## Signal System


Lback Framework incorporates a Signal system based on a central SignalDispatcher.

This system provides a mechanism for decoupling components by allowing them to notify other parts of the application about events without needing direct references to the listeners.

This is useful for:

1. **Extensibility:** Allowing developers to hook into core framework events or application-specific events to add custom logic (e.g., sending emails on user registration, logging specific actions).

2. **Monitoring:** Listening to signals related to request lifecycle, errors, cache operations, etc., for logging, monitoring, and debugging purposes.

3. **Decoupling:** Keeping components independent of each other, as they only need to know how to send or receive signals, not directly call other components' methods.

### How to Use:

**Access the Dispatcher:** The framework provides a single, globally accessible SignalDispatcher instance.

This instance is created early in the application's startup process and can be accessed by importing it `from lback.core.dispatcher_instance`.

``` python
# Example: Connecting a function to a signal
from lback.core.dispatcher_instance import dispatcher # Access the dispatcher

def my_custom_error_handler(sender, **kwargs):
    status = kwargs.get('status_code', 'N/A')
    path = getattr(kwargs.get('request'), 'path', 'N/A')
    print(f"Signal received from: {type(sender).__name__}, Status: {status}, Path: {path}")
dispatcher.connect("error_response_generated", my_custom_error_handler)
```
* **Signals Emitted by the Framework:** The framework emits signals at various points, including:
* **Server Lifecycle:** server_starting, server_started, server_shutting_down, server_request_received, server_request_finished, server_response_sent.
* **Middleware Processing:** Signals related to the middleware chain and individual middleware execution.
* **Authentication/Authorization:** user_login_successful, user_login_failed, admin_login_successful, admin_login_failed, etc.
* **Database/ORM:** Signals related to database session management (via SQLAlchemy Middleware).
* **Cache Operations:** cache_item_set, cache_hit, cache_miss, cache_item_deleted.
* **Error Handling:** error_response_generated, unhandled_exception_response_generated.
* **Initialization:** Signals indicating when core components are initialized.

... and many more throughout the framework components.

By connecting your custom logic to these `signals`, you can extend the framework's behavior without modifying its core code.

Refer to the documentation or component source code for a full list of available signals and the data they pass.

## Security Features
In addition to authentication and authorization, the framework provides tools and components to contribute to securing your application:

- **CSRF Protection:** Protection against Cross-Site Request Forgery attacks via Middleware.
- **CORS Handling:** Managing Cross-Origin Resource Sharing policies via Middleware.
- **SQL Injection Protection:** Mechanisms (often integrated into the ORM and database interactions).
- **XSS Protection:** Tools to protect against Cross-Site Scripting attacks (perhaps via input sanitization or safe template rendering).
- **Rate Limiting:** Controlling the rate of incoming requests to protect against Denial of Service attacks.
- **Security Headers:** Adding security headers to responses to enhance browser security.
- **Firewall:** Potentially a basic application-level firewall system.
## Running Tests
The framework supports running tests using Pytest.

You can write tests for different code units (Views, Models, Utilities, etc.) and run them using the `manage.py` command:

```Bash
python manage.py test
```
## Built-in Admin Panel
Lback Framework comes with a ready-to-use administrative panel for managing your application's data models.

The Admin panel URLs are typically included under the `/admin/` prefix in the main URL configuration.

```Python
# myproject/urls.py
from lback.core.urls_utils import include

urlpatterns = [
    # ... other paths ...
    include('lback.admin.urls', prefix='/admin/'),
]
```
The Admin panel provides a graphical interface to add, modify, view, and delete data for models registered with it.

You can register your app's models with the admin panel via the app's `admin.py` file.

## API Tools
The framework provides a robust set of tools to assist you in building powerful and structured Application Programming Interfaces (APIs):

### Serialization:
The framework offers a dedicated Serializer component (found in `lback.api.serializer`).

This allows you to efficiently convert complex Python objects (like database models) into standard data formats such as JSON for API responses, and to parse incoming data from requests back into Python objects for validation and saving.

You can define various field types and create custom serializers.

**Example:** Defining a Model Serializer

Here's how you define a serializer for your `Course` model, allowing it to be easily converted to
and from JSON:
```python
# myapp/serializers.py
from lback.api.serializer import BaseModelSerializer
from .models import Course # Assuming your Course model is defined here

class CourseSerializer(BaseModelSerializer):
    class Meta:
        model = Course
        fields = '__all__' # This includes all fields from the Course model automatically
```

### API Views & Generic Views:
Beyond standard web views, the framework provides specialized **API Views** (from `lback.api.view`) and **Generic Views** (from `lback.api.generics`).

These views are designed to handle data-format requests and responses (typically JSON), offering a structured way to define your API endpoints.

The Generic Views provide pre-built functionality for common API operations (CRUD - Create, Read, Update, Delete), allowing you to write less code for standard endpoints.

**Example: Listing and Creating Courses API**

This example demonstrates how to create an API endpoint that lists all courses (`GET` request) using the `CourseSerializer` to format the output:
```python
# myapp/api_views.py
from lback.utils.response_helpers import json_response
from .models import Course
from .serializers import CourseSerializer # Import your serializer

def api_course_list_create_view(request):
    db_session = request.db_session

    if request.method == "GET":
        courses = db_session.query(Course).all()
        serializer = CourseSerializer(instance=courses, many=True)
        return json_response(serializer.data, status=200)
```
### API Documentation:
The framework includes tools for **API Documentation** (`lback.api.docs.APIDocs`).

This feature helps you automatically generate interactive and comprehensive documentation for your API endpoints, making it easier for consumers to understand and integrate with your API.

## Forms
The framework provides a powerful and flexible Forms system designed to handle HTML form rendering, data validation, and processing with ease.

It abstracts away common boilerplate, allowing you to focus on your application's logic.
### 1- Defining Forms
Forms are defined as Python classes that inherit from `lback.forms.forms.Form`.

You declare form fields as class attributes, and the framework's `FormMetaclass` automatically collects the
#### Example: A Simple Contact Form
Let's look at how you'd define a contact form:
```python
# myapp/forms.py
from lback.forms.fields import CharField, EmailField, IntegerField, BooleanField
from lback.forms.widgets import Textarea, CheckboxInput, PasswordInput
from lback.forms.forms import Form
from lback.forms.validation import ValidationError # For custom validation

class ContactForm(Form):
    """
    A simple form for contact inquiries.
    Demonstrates various field types and custom validation.
    """
    name = CharField(
        min_length=3,
        max_length=100,
        required=True,
        label="Your Name",
        help_text="Please enter your full name."
    )
    email = EmailField(
        required=True,
        label="Your Email"
    )
    age = IntegerField(
        min_value=18,
        max_value=99,
        required=False,
        label="Your Age",
        help_text="Must be between 18 and 99."
    )
    message = CharField(
        required=True,
        widget=Textarea(attrs={'rows': 5, 'cols': 40}), # Custom widget with HTML attributes
        label="Your Message"
    )
    newsletter_signup = BooleanField(
        required=False,
        label="Sign up for newsletter?",
        widget=CheckboxInput # Explicitly setting checkbox widget
    )
    password = CharField(
        required=False,
        widget=PasswordInput, # Renders as <input type="password">
        label="Password (optional)"
    )
    password_confirm = CharField(
        required=False,
        widget=PasswordInput,
        label="Confirm Password"
    )