Update : Version Update and Prepared For Release -> v1.2.0

Author: Jones-peter

jsweb/__init__.py

@@ -8,7 +8,6 @@
 from jsweb.validators import *
 from jsweb.blueprints import Blueprint
 
-# Make url_for easily accessible
 from .response import url_for
 
-__VERSION__ = "1.1.0"
+__VERSION__ = "1.2.0"

jsweb/app.py

@@ -13,53 +13,76 @@ class JsWebApp:
     The main application class for the JsWeb framework.
     """
     def __init__(self, config):
+        """
+        Initialize the JsWebApp instance.
+
+        :param config: Configuration object containing settings like SECRET_KEY, TEMPLATE_FOLDER, etc.
+        """
         self.router = Router()
         self.template_filters = {}
         self.config = config
         self.blueprints_with_static_files = []
-        self._init_from_config()  # Initial setup
+        self._init_from_config()
 
     def _init_from_config(self):
         """Initializes components that depend on the config."""
         template_paths = []
 
-        # Add the user's template folder
         if hasattr(self.config, "TEMPLATE_FOLDER") and hasattr(self.config, "BASE_DIR"):
             user_template_path = os.path.join(self.config.BASE_DIR, self.config.TEMPLATE_FOLDER)
             if os.path.isdir(user_template_path):
                 template_paths.append(user_template_path)
 
-        # Add the library's main template folder
         lib_template_path = os.path.join(os.path.dirname(__file__), "templates")
         if os.path.isdir(lib_template_path):
             template_paths.append(lib_template_path)
 
-        # The admin templates are now self-contained in the admin package,
-        # so we no longer add them to the main app's template paths.
-
         if template_paths:
             configure_template_env(template_paths)
 
         if hasattr(self.config, "SECRET_KEY"):
             init_auth(self.config.SECRET_KEY, self._get_actual_user_loader())
 
     def _get_actual_user_loader(self):
+        """
+        Retrieves the user loader callback.
+        
+        :return: The user loader function.
+        """
         if hasattr(self, '_user_loader_callback') and self._user_loader_callback:
             return self._user_loader_callback
         return self.user_loader
 
     def user_loader(self, user_id: int):
+        """
+        Default user loader that attempts to load a user from a 'models' module.
+        
+        :param user_id: The ID of the user to load.
+        :return: The User object or None.
+        """
         try:
             from models import User
             return User.query.get(user_id)
         except (ImportError, AttributeError):
             return None
 
     def route(self, path, methods=None, endpoint=None):
+        """
+        Decorator to register a new route.
+
+        :param path: The URL path.
+        :param methods: List of HTTP methods allowed.
+        :param endpoint: Optional endpoint name.
+        :return: The decorator function.
+        """
         return self.router.route(path, methods, endpoint)
 
     def register_blueprint(self, blueprint: Blueprint):
-        """Registers a blueprint with the application."""
+        """
+        Registers a blueprint with the application.
+
+        :param blueprint: The Blueprint instance to register.
+        """
         for path, handler, methods, endpoint in blueprint.routes:
             full_path = path
             if blueprint.url_prefix:
@@ -72,12 +95,25 @@ def register_blueprint(self, blueprint: Blueprint):
             self.blueprints_with_static_files.append(blueprint)
 
     def filter(self, name):
+        """
+        Decorator to register a custom template filter.
+
+        :param name: The name of the filter to use in templates.
+        :return: The decorator function.
+        """
         def decorator(func):
             self.template_filters[name] = func
             return func
         return decorator
 
     async def _asgi_app_handler(self, scope, receive, send):
+        """
+        Internal ASGI handler for processing requests.
+
+        :param scope: The ASGI scope.
+        :param receive: The ASGI receive channel.
+        :param send: The ASGI send channel.
+        """
         req = scope['jsweb.request']
         try:
             handler, params = self.router.resolve(req.path, req.method)
@@ -95,7 +131,6 @@ async def _asgi_app_handler(self, scope, receive, send):
             return
 
         if handler:    
-            # Support both sync and async handlers
             if asyncio.iscoroutinefunction(handler):
                 response = await handler(req, **params)
             else:
@@ -107,17 +142,21 @@ async def _asgi_app_handler(self, scope, receive, send):
             if not isinstance(response, Response):
                 raise TypeError(f"View function did not return a Response object (got {type(response).__name__})")
 
-        
-
         if hasattr(req, 'new_csrf_token_generated') and req.new_csrf_token_generated:
             response.set_cookie("csrf_token", req.csrf_token, httponly=False, samesite='Lax')
 
         await response(scope, receive, send)
 
 
     async def __call__(self, scope, receive, send):
+        """
+        The ASGI application entry point.
+
+        :param scope: The ASGI scope.
+        :param receive: The ASGI receive channel.
+        :param send: The ASGI send channel.
+        """
         if scope["type"] != "http":
-            # For now, we only support http
             return
 
         req = Request(scope, receive, self)
@@ -136,12 +175,9 @@ async def __call__(self, scope, receive, send):
         static_url = getattr(self.config, "STATIC_URL", "/static")
         static_dir = getattr(self.config, "STATIC_DIR", "static")
 
-        # The middleware needs to be ASGI compatible.
-        # This will require rewriting the middleware classes.
-        # For now, I will assume they are ASGI compatible.
         handler = self._asgi_app_handler
         handler = DBSessionMiddleware(handler)
         handler = StaticFilesMiddleware(handler, static_url, static_dir, blueprint_statics=self.blueprints_with_static_files)
         handler = CSRFMiddleware(handler)
 
-        await handler(scope, receive, send)
+        await handler(scope, receive, send)

jsweb/auth.py

@@ -1,69 +1,121 @@
-from functools import wraps
 import asyncio
+from functools import wraps
+
 from itsdangerous import URLSafeTimedSerializer, SignatureExpired, BadTimeSignature
-from .response import redirect, url_for, Forbidden
 
-# This will be initialized by the JsWebApp instance
+from .response import redirect, url_for
+
 _serializer = None
 _user_loader = None
 
-def init_auth(secret_key, user_loader_func):
-    """Initializes the authentication system."""
+def init_auth(secret_key: str, user_loader_func: callable):
+    """
+    Initializes the authentication system with a secret key and a user loader.
+
+    This function must be called once at application startup to set up the
+    components needed for session management and user retrieval.
+
+    Args:
+        secret_key: The secret key used to sign and verify session tokens.
+        user_loader_func: A callable that takes a user ID and returns the
+                          corresponding user object, or None if not found.
+    """
     global _serializer, _user_loader
     _serializer = URLSafeTimedSerializer(secret_key)
     _user_loader = user_loader_func
 
 def login_user(response, user):
-    """Logs a user in by creating a secure session cookie."""
+    """
+    Logs a user in by creating a secure, timestamped session cookie.
+
+    This function serializes the user's ID and sets it in an HTTPOnly cookie
+    on the provided response object.
+
+    Args:
+        response: The Response object to which the session cookie will be attached.
+        user: The user object to log in. Must have an 'id' attribute.
+    """
     session_token = _serializer.dumps(user.id)
     response.set_cookie("session", session_token, httponly=True)
 
 def logout_user(response):
-    """Logs a user out by deleting the session cookie."""
+    """
+    Logs a user out by deleting the session cookie.
+
+    Args:
+        response: The Response object from which the session cookie will be removed.
+    """
     response.delete_cookie("session")
 
 def get_current_user(request):
-    """Gets the currently logged-in user from the session cookie."""
+    """
+    Retrieves the currently logged-in user from the session cookie.
+
+    This function deserializes the session token from the request's cookies,
+    validates its signature and expiration (max_age=30 days), and then uses the
+    user loader to fetch the corresponding user object.
+
+    Args:
+        request: The incoming Request object.
+
+    Returns:
+        The user object if a valid session exists, otherwise None.
+    """
     session_token = request.cookies.get("session")
     if not session_token:
         return None
 
     try:
-        # The max_age check (e.g., 30 days) is handled by the serializer
-        user_id = _serializer.loads(session_token, max_age=2592000)
+        user_id = _serializer.loads(session_token, max_age=2592000)  # 30 days
         return _user_loader(user_id)
     except (SignatureExpired, BadTimeSignature):
         return None
 
-def login_required(handler):
+def login_required(handler: callable) -> callable:
     """
-    A decorator to protect routes from unauthenticated access.
-    It supports both sync and async handlers.
+    A decorator to protect a route from unauthenticated access.
+
+    If the user is not logged in (i.e., `request.user` is not set), they are
+    redirected to the login page. This decorator correctly handles both
+    synchronous and asynchronous view functions.
+
+    Args:
+        handler: The view function to protect.
+
+    Returns:
+        The decorated view function.
     """
     @wraps(handler)
     async def decorated_function(request, *args, **kwargs):
         if not request.user:
             login_url = url_for(request, 'auth.login')
             return redirect(login_url)
 
-        # Await the handler if it's a coroutine function
         if asyncio.iscoroutinefunction(handler):
             return await handler(request, *args, **kwargs)
         else:
             return handler(request, *args, **kwargs)
     return decorated_function
 
-def admin_required(handler):
+def admin_required(handler: callable) -> callable:
     """
-    A decorator to protect routes from non-admin access.
-    It supports both sync and async handlers.
+    A decorator to protect a route, allowing access only to admin users.
+
+    This decorator checks if `request.user` exists and has an attribute
+    `is_admin` that evaluates to True. If the check fails, the user is
+    redirected to the admin index page. It supports both sync and async handlers.
+
+    Args:
+        handler: The view function to protect.
+
+    Returns:
+        The decorated view function.
     """
     @wraps(handler)
     async def decorated_function(request, *args, **kwargs):
         if not request.user or not getattr(request.user, 'is_admin', False):
             return redirect(url_for(request, 'admin.index'))
 
-        # Await the handler if it's a coroutine function
         if asyncio.iscoroutinefunction(handler):
             return await handler(request, *args, **kwargs)
         else:

jsweb/blueprints.py

@@ -1,41 +1,75 @@
+from typing import List, Tuple, Callable, Optional
+
 class Blueprint:
     """
-    A self-contained, reusable component of a JsWeb application.
-    Blueprints have their own routes which are later registered with the main app.
+    Represents a blueprint, a collection of routes that can be registered with an application.
+
+    Blueprints are used to structure a JsWeb application into smaller, reusable
+    components. Each blueprint can have its own routes, URL prefix, and static
+    files. This helps in organizing code and promoting modularity.
     """
-    def __init__(self, name, url_prefix=None, static_folder=None, static_url_path=None):
+    def __init__(self, name: str, url_prefix: Optional[str] = None, static_folder: Optional[str] = None, static_url_path: Optional[str] = None):
         """
         Initializes a new Blueprint.
 
         Args:
-            name (str): The name of the blueprint.
-            url_prefix (str, optional): A prefix to be added to all routes in this blueprint.
-            static_folder (str, optional): The folder for static files for this blueprint.
-            static_url_path (str, optional): The URL path for serving static files.
+            name: The name of the blueprint, used for endpoint namespacing.
+            url_prefix: An optional prefix for all routes defined in this blueprint.
+                        For example, if a prefix is '/api' and a route is '/users',
+                        the final path will be '/api/users'.
+            static_folder: The name of the folder containing static files for this
+                           blueprint, relative to the blueprint's location.
+            static_url_path: The URL path where the blueprint's static files will be
+                             served from. Defaults to the static folder name if not provided.
         """
         self.name = name
         self.url_prefix = url_prefix
-        self.routes = []
+        self.routes: List[Tuple[str, Callable, List[str], str]] = []
         self.static_folder = static_folder
         self.static_url_path = static_url_path
 
-    def add_route(self, path, handler, methods=None, endpoint=None):
+    def add_route(self, path: str, handler: Callable, methods: Optional[List[str]] = None, endpoint: Optional[str] = None):
         """
-        Programmatically adds a route to the blueprint. This is useful for
-        dynamically generated views, like in the admin panel.
+        Programmatically adds a route to the blueprint.
+
+        This method is an alternative to the `@route` decorator and is useful for
+        dynamically generated views, such as those in a class-based view system
+        or an admin panel.
+
+        Args:
+            path: The URL path for the route.
+            handler: The view function that will handle requests to this path.
+            methods: A list of allowed HTTP methods (e.g., ["GET", "POST"]).
+                     Defaults to ["GET"].
+            endpoint: A unique name for this route's endpoint. If not provided,
+                      it defaults to the name of the handler function.
         """
         if methods is None:
             methods = ["GET"]
 
-        # If no endpoint is provided, use the function name as the default.
         route_endpoint = endpoint or handler.__name__
         self.routes.append((path, handler, methods, route_endpoint))
 
-    def route(self, path, methods=None, endpoint=None):
+    def route(self, path: str, methods: Optional[List[str]] = None, endpoint: Optional[str] = None) -> Callable:
         """
         A decorator to register a view function for a given path within the blueprint.
+
+        Example:
+            bp = Blueprint('my_app')
+
+            @bp.route('/index', methods=['GET'])
+            def index(request):
+                return "Hello, World!"
+
+        Args:
+            path: The URL path for the route.
+            methods: A list of allowed HTTP methods. Defaults to ["GET"].
+            endpoint: A unique name for the endpoint. Defaults to the function name.
+
+        Returns:
+            A decorator function that registers the view.
         """
-        def decorator(handler):
+        def decorator(handler: Callable) -> Callable:
             self.add_route(path, handler, methods, endpoint)
             return handler
         return decorator