Plinx 0.0.1__py3-none-any.whl → 1.0.1__py3-none-any.whl

plinx/__init__.py

@@ -1 +1,3 @@
 from .applications import Plinx
+
+__version__ = "1.0.1"

plinx/applications.py

@@ -15,7 +15,58 @@ from .utils import handle_404
 
 
 class Plinx:
+    """
+    The main application class for the Plinx web framework.
+
+    This class serves as the WSGI application entry point and manages routes,
+    middleware, and request handling. It provides a Flask-like decorator syntax
+    for adding routes and Django-like method for explicitly registering them.
+
+    Examples:
+        Creating a simple app with a route:
+
+        ```python
+        from plinx import Plinx
+
+        app = Plinx()
+
+        @app.route("/")
+        def home(request, response):
+            response.text = "Hello, World!"
+        ```
+
+        Using HTTP method-specific decorators:
+
+        ```python
+        @app.get("/users")
+        def list_users(request, response):
+            response.json = {"users": ["user1", "user2"]}
+
+        @app.post("/users")
+        def create_user(request, response):
+            response.text = "User created"
+        ```
+
+        Using class-based views:
+
+        ```python
+        @app.route("/books")
+        class BooksResource:
+            def get(self, request, response):
+                response.text = "List of books"
+
+            def post(self, request, response):
+                response.text = "Book created"
+        ```
+    """
+
     def __init__(self):
+        """
+        Initialize a new Plinx application instance.
+
+        Sets up the routing table, middleware stack, and
+        dynamically generates HTTP method-specific decorators.
+        """
         self.routes: Dict[str, Tuple[HTTPMethods, Callable]] = {}
         self.exception_handler = None
         self.middleware = Middleware(self)
@@ -32,10 +83,17 @@ class Plinx:
         start_response: StartResponse,
     ) -> Iterable[bytes]:
         """
-        Entrypoint for the WSGI application.
-        :param environ: The WSGI environment.
-        :param start_response: The WSGI callable.
-        :return: The response body produced by the middleware.
+        WSGI entry point for the application.
+
+        This method makes the Plinx instance callable as required by the WSGI spec,
+        allowing it to be used directly with WSGI servers like Gunicorn or uWSGI.
+
+        Args:
+            environ: The WSGI environment dictionary containing request information
+            start_response: The WSGI start_response callable
+
+        Returns:
+            An iterable of bytes representing the response body
         """
         return self.middleware(environ, start_response)
 
@@ -46,10 +104,26 @@ class Plinx:
         method: HTTPMethods = HTTPMethods.GET,
     ):
         """
-        Add a route to the application. Django-like syntax.
-        :param path: The path to register.
-        :param handler: The handler to register.
-        :return:
+        Explicitly register a route with the application.
+
+        This provides a Django-like syntax for registering routes,
+        as an alternative to the decorator approach.
+
+        Args:
+            path: URL pattern to match (may contain parameters)
+            handler: Function or class to handle matching requests
+            method: HTTP method to match (defaults to GET)
+
+        Raises:
+            RuntimeError: If the path is already registered
+
+        Example:
+            ```python
+            def home(request, response):
+                response.text = "Hello, World!"
+
+            app.add_route("/home", home)
+            ```
         """
         if path in self.routes:
             raise RuntimeError(f"Route '{path}' is already registered.")
@@ -61,9 +135,32 @@ class Plinx:
         path: str,
     ):
         """
-        Register a route with the given path.
-        :param path: The path to register.
-        :return:
+        Register a route via decorator syntax.
+
+        This implements Flask-like syntax for registering routes. It can be used
+        with both function-based handlers and class-based handlers.
+
+        Args:
+            path: URL pattern to match (may contain parameters)
+
+        Returns:
+            A decorator function that registers the handler
+
+        Example:
+            ```python
+            @app.route("/home")
+            def home(request, response):
+                response.text = "Hello, World!"
+            ```
+
+            For class-based views:
+
+            ```python
+            @app.route("/books")
+            class BooksResource:
+                def get(self, request, response):
+                    response.text = "List of books"
+            ```
         """
 
         def wrapper(handler):
@@ -76,7 +173,21 @@ class Plinx:
         self,
         name: str,
     ):
-        """Allow access to HTTP method decorators like app.get, app.post etc."""
+        """
+        Enable HTTP method-specific decorators like app.get, app.post, etc.
+
+        This magic method is called when an attribute lookup fails, allowing
+        us to dynamically provide HTTP method decorators.
+
+        Args:
+            name: The attribute name being looked up
+
+        Returns:
+            A method-specific decorator function if name matches a HTTP method
+
+        Raises:
+            RuntimeError: If the attribute doesn't match a known HTTP method
+        """
         if name in self._method_decorators:
             return self._method_decorators[name]
         raise RuntimeError(
@@ -85,9 +196,16 @@ class Plinx:
 
     def _create_method_decorator(self, method: HTTPMethods):
         """
-        Creates a decorator for registering routes with a specific HTTP method.
-        :param method: The HTTP method enum value
-        :return: Decorator function
+        Create a decorator for a specific HTTP method.
+
+        This internal method generates the decorators used for HTTP method-specific
+        route registration like @app.get(), @app.post(), etc.
+
+        Args:
+            method: The HTTP method enum value
+
+        Returns:
+            A decorator function for the specified HTTP method
         """
 
         def decorator(path: str):
@@ -104,9 +222,16 @@ class Plinx:
         request: Request,
     ) -> Response:
         """
-        Handle the given request and return the response.
-        :param request: The request object.
-        :return: The response object.
+        Process an incoming request and generate a response.
+
+        This is the core request handling logic that finds a matching route handler,
+        executes it, and handles any exceptions.
+
+        Args:
+            request: The incoming WebOb Request object
+
+        Returns:
+            A Response object containing the response data
         """
         response: Response = Response()
 
@@ -151,16 +276,21 @@ class Plinx:
         self,
         request: Request,
         response: Response,
-    ) -> Tuple[Callable, dict | None] | Tuple[None, None]:
+    ) -> Tuple[Tuple[HTTPMethods, Callable] | None, dict | None]:
         """
-        Find the handler for the given request.
-        If no handler is found, set the response status code to 404
-        and return None.
+        Find the appropriate handler for a request based on URL path matching.
+
+        This method iterates through registered routes and uses the parse library
+        to match URL patterns and extract parameters.
 
-        :param request: The request object.
-        :param response: The response object.
-        :return: A tuple containing the handler and the named parameters.
-        If no handler is found, return tuple[None, None].
+        Args:
+            request: The incoming WebOb Request object
+            response: The Response object being built
+
+        Returns:
+            A tuple containing:
+                - The handler definition (method, handler) if found, or None
+                - A dictionary of extracted URL parameters, or None
         """
         for path, handler in self.routes.items():
             parse_result = parse(path, request.path)
@@ -174,6 +304,24 @@ class Plinx:
         self,
         exception_handler,
     ):
+        """
+        Register a global exception handler for the application.
+
+        The exception handler will be called whenever an uncaught exception
+        occurs during request handling.
+
+        Args:
+            exception_handler: Callable that takes (request, response, exception)
+
+        Example:
+            ```python
+            def handle_exceptions(request, response, exception):
+                response.status_code = 500
+                response.text = f"Error: {str(exception)}"
+
+            app.add_exception_handler(handle_exceptions)
+            ```
+        """
         self.exception_handler = exception_handler
 
     def add_middleware(
@@ -181,12 +329,48 @@ class Plinx:
         middleware_cls: type[Middleware],
     ):
         """
-        Add a middleware class to the application.
-        :param middleware_cls: The middleware class to add.
+        Add a middleware class to the application's middleware stack.
+
+        Middleware classes must inherit from the Middleware base class and can
+        process requests before they reach handlers and responses before they're returned.
+
+        Args:
+            middleware_cls: A class inheriting from Middleware
+
+        Example:
+            ```python
+            class SimpleMiddleware(Middleware):
+                def process_request(self, request):
+                    print("Processing request")
+
+                def process_response(self, request, response):
+                    print("Processing response")
+
+            app.add_middleware(SimpleMiddleware)
+            ```
         """
         self.middleware.add(middleware_cls)
 
     def test_session(self, base_url="http://testserver"):
+        """
+        Create a test client session for this application.
+
+        This provides an interface similar to the requests library for testing
+        your application without making actual HTTP calls.
+
+        Args:
+            base_url: Base URL to use for requests (default: "http://testserver")
+
+        Returns:
+            A requests.Session object configured to call this application
+
+        Example:
+            ```python
+            client = app.test_session()
+            response = client.get("/home")
+            assert response.status_code == 200
+            ```
+        """
         session = RequestsSession()
         session.mount(prefix=base_url, adapter=RequestsWSGIAdapter(self))
         return session

plinx/methods.py

@@ -2,7 +2,37 @@ from enum import Enum
 
 
 class HTTPMethods(Enum):
-    """HTTP methods for the API."""
+    """
+    Enumeration of HTTP methods supported by the Plinx framework.
+
+    This enum defines the standard HTTP methods as defined in RFC 7231 and RFC 5789,
+    categorized by their safety and idempotency properties.
+
+    Safe methods (should not modify resources):
+    - GET: Retrieve a representation of a resource
+    - HEAD: Same as GET but returns only headers, no body
+
+    Idempotent methods (multiple identical requests have same effect as single request):
+    - PUT: Replace a resource with the request payload
+    - DELETE: Remove the specified resource
+    - OPTIONS: Describe the communication options for the target resource
+
+    Non-idempotent methods (multiple identical requests may have different effects):
+    - POST: Submit data to be processed, typically creating a new resource
+    - PATCH: Apply partial modifications to a resource
+
+    Usage:
+        ```python
+        from plinx.methods import HTTPMethods
+
+        # Check if a method is GET
+        if method == HTTPMethods.GET:
+            # handle GET request
+
+        # Get the string value of a method
+        method_str = HTTPMethods.POST.value  # "POST"
+        ```
+    """
 
     # Safe methods
     GET = "GET"
@@ -15,4 +45,33 @@ class HTTPMethods(Enum):
 
     # Non-idempotent methods
     POST = "POST"
-    PATCH = "PATCH"
+    PATCH = "PATCH"
+
+
+def is_valid_method(method: str) -> bool:
+    """
+    Check if the given method is a valid HTTP method.
+
+    Args:
+        method: The HTTP method to check
+
+    Returns:
+        bool: True if the method is valid, False otherwise
+    """
+    return method in HTTPMethods.__members__.values()
+
+
+def get_handler_name_for_method(method: str) -> str:
+    """
+    Get the handler name for a given HTTP method.
+
+    Args:
+        method: The HTTP method to get the handler name for
+
+    Returns:
+        str: The handler name corresponding to the HTTP method
+    """
+    if not is_valid_method(method):
+        raise ValueError(f"Invalid HTTP method: {method}")
+
+    return method.lower()

plinx/middleware.py

@@ -3,10 +3,51 @@ from webob import Request, Response
 
 class Middleware:
     """
-    Middleware base class for all middleware classes.
-    This class is used to create middleware for the Plinx application.
-    Middleware classes should inherit from this class and implement the
-    `process_request` and `process_response` methods.
+    Base class for all Plinx middleware components.
+
+    The middleware system in Plinx follows a nested pattern where each middleware
+    wraps the application or another middleware component. This allows for a chain
+    of processing both before a request reaches the application and after the
+    application generates a response.
+
+    Middleware classes should inherit from this base class and override the
+    `process_request` and `process_response` methods to implement custom behavior.
+
+    The middleware execution flow works like this:
+    1. Client request comes in
+    2. Each middleware's `process_request` is called from outermost to innermost
+    3. The application handles the request
+    4. Each middleware's `process_response` is called from innermost to outermost
+    5. The response is sent back to the client
+
+    Examples:
+        ```python
+        class LoggingMiddleware(Middleware):
+            def process_request(self, request):
+                print(f"Request: {request.path}")
+
+            def process_response(self, request, response):
+                print(f"Response: {response.status_code}")
+
+        app = Plinx()
+        app.add_middleware(LoggingMiddleware)
+        ```
+
+        Middleware that modifies the request or response:
+
+        ```python
+        class AuthMiddleware(Middleware):
+            def process_request(self, request):
+                request.user = None
+                auth_header = request.headers.get("Authorization", "")
+                if auth_header.startswith("Bearer "):
+                    token = auth_header[7:]
+                    request.user = self.get_user_from_token(token)
+
+            def get_user_from_token(self, token):
+                # Implementation to validate token and return user
+                pass
+        ```
     """
 
     def __init__(
@@ -14,8 +55,10 @@ class Middleware:
         app,
     ):
         """
-        Middleware base class for all middleware classes.
-        :param app: The WSGI application.
+        Initialize the middleware with a WSGI application.
+
+        Args:
+            app: A WSGI application (typically a Plinx instance or another middleware)
         """
         self.app = app
 
@@ -25,10 +68,19 @@ class Middleware:
         start_response: callable,
     ):
         """
-        Entrypoint for the WSGI middleware since it is now entrypoint for the WSGI application.
-        :param environ: The WSGI environment.
-        :param start_response: The WSGI callable.
-        :return: The response body.
+        WSGI callable interface for the middleware.
+
+        This method makes middleware instances callable according to the WSGI spec,
+        allowing them to be used in a WSGI server. It creates a Request object,
+        passes it to the application's handle_request method, and returns the
+        response.
+
+        Args:
+            environ: The WSGI environment dictionary
+            start_response: The WSGI start_response callable
+
+        Returns:
+            An iterable of bytes representing the response body
         """
         request = Request(environ)
 
@@ -41,8 +93,14 @@ class Middleware:
         middleware_cls,
     ):
         """
-        Add a middleware class to the application.
-        :param middleware_cls: The middleware class to add.
+        Add a new middleware to the stack.
+
+        This method creates an instance of the provided middleware class,
+        passing the current middleware instance (or application) as the app parameter.
+        This builds up a chain of nested middleware instances.
+
+        Args:
+            middleware_cls: A class inheriting from Middleware
         """
         self.app = middleware_cls(self.app)
 
@@ -51,10 +109,15 @@ class Middleware:
         request: Request,
     ):
         """
-        Process the request before it is passed to the application.
-        :param request: The request object.
+        Process the request before it reaches the application.
+
+        Override this method in your middleware subclass to modify or inspect
+        the request before it's handled by the application or the next middleware.
+
+        Args:
+            request: The WebOb Request object
         """
-        pass # pragma: no cover
+        pass  # pragma: no cover
 
     def process_response(
         self,
@@ -62,17 +125,31 @@ class Middleware:
         response: Response,
     ):
         """
-        Process the response after it is passed to the application.
-        :param request: The request object.
-        :param response: The response object.
+        Process the response after it's generated by the application.
+
+        Override this method in your middleware subclass to modify or inspect
+        the response before it's returned to the client or the previous middleware.
+
+        Args:
+            request: The WebOb Request object that generated this response
+            response: The Response object to be returned
         """
-        pass # pragma: no cover
+        pass  # pragma: no cover
 
     def handle_request(self, request: Request):
         """
-        Handle the incoming request.
-        :param request: The request object.
-        :return: The response object.
+        Process a request through this middleware and the wrapped application.
+
+        This method implements the middleware chain by:
+        1. Calling this middleware's process_request method
+        2. Passing the request to the wrapped application/middleware
+        3. Calling this middleware's process_response method with the response
+
+        Args:
+            request: The WebOb Request object
+
+        Returns:
+            The Response object after processing
         """
         self.process_request(request)
         response = self.app.handle_request(request)

plinx/orm/__init__.py

@@ -0,0 +1 @@
+from .orm import Column, Database, ForeignKey, Table  # noqa