Plinx 1.0.0__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/orm.py

@@ -8,19 +8,121 @@ T = TypeVar("T")
 
 
 class Database:
+    """
+    SQLite database wrapper that provides a simple ORM interface.
+
+    The Database class is the main entry point for ORM operations in Plinx.
+    It handles database connections, table creation, and provides methods for
+    basic CRUD operations (Create, Read, Update, Delete) on Table objects.
+
+    This class uses SQLite as the underlying database engine and provides
+    a simplified interface that avoids writing raw SQL in most cases.
+
+    Examples:
+        Creating a database and defining models:
+
+        ```python
+        from plinx.orm import Database, Table, Column, ForeignKey
+
+        db = Database("app.db")
+
+        class User(Table):
+            name = Column(str)
+            age = Column(int)
+
+        db.create(User)
+
+        # Create a new user
+        john = User(name="John Doe", age=30)
+        db.save(john)
+
+        # Query users
+        all_users = db.all(User)
+        john = db.get(User, id=1)
+
+        # Update a user
+        john.age = 31
+        db.update(john)
+
+        # Delete a user
+        db.delete(john)
+        ```
+    """
+
     def __init__(self, path: str):
+        """
+        Initialize a new database connection.
+
+        Args:
+            path: Path to the SQLite database file. If the file doesn't exist,
+                 it will be created.
+        """
         self.connection = sqlite3.Connection(path)
 
     def create(self, table: "Table"):
+        """
+        Create a database table based on a Table subclass definition.
+
+        This method creates a table in the database with columns corresponding
+        to the Column and ForeignKey attributes defined on the Table subclass.
+        If the table already exists, this method does nothing.
+
+        Args:
+            table: A Table subclass with Column and/or ForeignKey attributes
+
+        Example:
+            ```python
+            class User(Table):
+                name = Column(str)
+                age = Column(int)
+
+            db.create(User)
+            ```
+        """
         self.connection.execute(table._get_create_sql())
 
     def save(self, instance: "Table"):
+        """
+        Save a Table instance to the database.
+
+        This method inserts a new row into the corresponding database table.
+        It automatically sets the instance's id attribute to the new row's ID.
+
+        Args:
+            instance: A Table instance to save
+
+        Example:
+            ```python
+            user = User(name="John Doe", age=30)
+            db.save(user)  # user.id is now set to the new row's ID
+            ```
+        """
         sql, values = instance._get_insert_sql()
         cursor = self.connection.execute(sql, values)
         instance._data["id"] = cursor.lastrowid
         self.connection.commit()
 
     def all(self, table: "Table"):
+        """
+        Retrieve all rows from a table.
+
+        This method selects all rows from the table corresponding to the given
+        Table subclass. It returns a list of instances of that class, with
+        attributes set to the values from the database.
+
+        Args:
+            table: A Table subclass to query
+
+        Returns:
+            List of Table instances, one for each row in the table
+
+        Example:
+            ```python
+            all_users = db.all(User)
+            for user in all_users:
+                print(f"{user.name} is {user.age} years old")
+            ```
+        """
         sql, fields = table._get_select_all_sql()
         rows = self.connection.execute(sql).fetchall()
 
@@ -40,6 +142,32 @@ class Database:
         return result
 
     def get(self, table: "Table", **kwargs):
+        """
+        Retrieve a single row from a table by specified criteria.
+
+        This method selects a row from the database where the specified columns
+        match the given values. It returns an instance of the Table subclass with
+        attributes set to the values from the database.
+
+        Args:
+            table: A Table subclass to query
+            **kwargs: Column-value pairs to filter by
+
+        Returns:
+            A Table instance corresponding to the matched row
+
+        Raises:
+            Exception: If no row matches the criteria
+
+        Example:
+            ```python
+            # Get user by ID
+            user = db.get(User, id=1)
+
+            # Get user by name
+            user = db.get(User, name="John Doe")
+            ```
+        """
         sql, fields, params = table._get_select_where_sql(**kwargs)
         row = self.connection.execute(sql, params).fetchone()
 
@@ -59,42 +187,164 @@ class Database:
         return table(**properties)
 
     def update(self, instance: "Table"):
+        """
+        Update an existing row in the database.
+
+        This method updates the row corresponding to the given instance with the
+        current values of the instance's attributes.
+
+        Args:
+            instance: A Table instance to update. Must have an id attribute.
+
+        Example:
+            ```python
+            user = db.get(User, id=1)
+            user.name = "Jane Doe"
+            db.update(user)
+            ```
+        """
         sql, values = instance._get_update_sql()
         self.connection.execute(sql, values)
         self.connection.commit()
 
     def delete(self, instance: "Table"):
+        """
+        Delete a row from the database.
+
+        This method deletes the row corresponding to the given instance.
+
+        Args:
+            instance: A Table instance to delete. Must have an id attribute.
+
+        Example:
+            ```python
+            user = db.get(User, id=1)
+            db.delete(user)
+            ```
+        """
         sql, values = instance._get_delete_sql()
         self.connection.execute(sql, values)
         self.connection.commit()
 
     def close(self):
+        """
+        Close the database connection.
+
+        This method closes the SQLite connection when the database is no longer
+        needed. It's good practice to call this method when you're done using
+        the database, especially in longer-running applications.
+        """
         if self.connection:
             self.connection.close()
         self.connection = None
 
     @property
     def tables(self):
+        """
+        Get a list of all tables in the database.
+
+        Returns:
+            List of table names as strings
+        """
         SELECT_TABLES_SQL = "SELECT name FROM sqlite_master WHERE type = 'table';"
         return [x[0] for x in self.connection.execute(SELECT_TABLES_SQL).fetchall()]
 
 
 class Column:
+    """
+    Define a column in a database table.
+
+    This class represents a column definition for a Table class. It stores
+    the column's type and can generate the corresponding SQL type.
+
+    Examples:
+        ```python
+        class User(Table):
+            name = Column(str)  # TEXT column
+            age = Column(int)   # INTEGER column
+            active = Column(bool)  # INTEGER column (0=False, 1=True)
+        ```
+    """
+
     def __init__(self, type: Generic[T]):
+        """
+        Initialize a new column.
+
+        Args:
+            type: Python type for the column (str, int, float, bool, bytes)
+        """
         self.type = type
 
     @property
     def sql_type(self):
+        """
+        Get the SQL type corresponding to this column's Python type.
+
+        Returns:
+            SQL type string (e.g., "TEXT", "INTEGER", "REAL")
+        """
         return SQLITE_TYPE_MAP[self.type]
 
 
 class ForeignKey:
+    """
+    Define a foreign key relationship between tables.
+
+    This class represents a foreign key constraint in a database schema,
+    linking one Table class to another.
+
+    Examples:
+        ```python
+        class Author(Table):
+            name = Column(str)
+
+        class Book(Table):
+            title = Column(str)
+            author = ForeignKey(Author)  # Creates author_id column
+        ```
+    """
+
     def __init__(self, table):
+        """
+        Initialize a new foreign key.
+
+        Args:
+            table: The Table subclass that this foreign key references
+        """
         self.table = table
 
 
 class Table:
+    """
+    Base class for ORM models in Plinx.
+
+    This class is used as a base class for defining database tables.
+    Subclasses should define class attributes using Column and ForeignKey
+    to describe the table schema.
+
+    The Table class provides methods for generating SQL statements for
+    CRUD operations, which are used by the Database class.
+
+    Examples:
+        ```python
+        class User(Table):
+            name = Column(str)
+            age = Column(int)
+
+        class Post(Table):
+            title = Column(str)
+            content = Column(str)
+            author = ForeignKey(User)
+        ```
+    """
+
     def __init__(self, **kwargs):
+        """
+        Initialize a new record.
+
+        Args:
+            **kwargs: Column values to initialize with
+        """
         self._data = {"id": None}
 
         for key, value in kwargs.items():
@@ -102,8 +352,16 @@ class Table:
 
     def __getattribute__(self, key):
         """
-        Values to be access are in `self._data`
-        Accessing without __getattribute__ will return Column or ForeignKey and not the actual value
+        Custom attribute access for Table instances.
+
+        This method allows Table instances to access column values as attributes,
+        rather than accessing self._data directly.
+
+        Args:
+            key: Attribute name to access
+
+        Returns:
+            The attribute value
         """
         # Why use super().__getattribute__ instead of self._data[key]?
         # Because otherwise it will create an infinite loop since __getattribute__ will call itself
@@ -115,7 +373,14 @@ class Table:
 
     def __setattr__(self, key, value):
         """
-        Values to be set are in `self._data`
+        Custom attribute assignment for Table instances.
+
+        This method ensures that when setting an attribute that corresponds to
+        a column, the value is stored in self._data.
+
+        Args:
+            key: Attribute name to set
+            value: Value to assign
         """
         super().__setattr__(key, value)
         if key in self._data:
@@ -123,6 +388,12 @@ class Table:
 
     @classmethod
     def _get_create_sql(cls):
+        """
+        Generate SQL for creating the table.
+
+        Returns:
+            SQL string for creating the table
+        """
         CREATE_TABLE_SQL = "CREATE TABLE IF NOT EXISTS {name} ({fields});"
         fields = [
             "id INTEGER PRIMARY KEY AUTOINCREMENT",
@@ -139,6 +410,12 @@ class Table:
         return CREATE_TABLE_SQL.format(name=name, fields=fields)
 
     def _get_insert_sql(self):
+        """
+        Generate SQL for inserting a record.
+
+        Returns:
+            Tuple of (SQL string, parameter values list)
+        """
         INSERT_SQL = "INSERT INTO {name} ({fields}) VALUES ({placeholders});"
 
         cls = self.__class__
@@ -167,6 +444,12 @@ class Table:
 
     @classmethod
     def _get_select_all_sql(cls):
+        """
+        Generate SQL for selecting all records.
+
+        Returns:
+            Tuple of (SQL string, field names list)
+        """
         SELECT_ALL_SQL = "SELECT {fields} FROM {name};"
 
         fields = ["id"]
@@ -177,13 +460,25 @@ class Table:
             elif isinstance(field, ForeignKey):
                 fields.append(name + "_id")
 
-        return SELECT_ALL_SQL.format(
-            fields=", ".join(fields),
-            name=cls.__name__.lower(),
-        ), fields
+        return (
+            SELECT_ALL_SQL.format(
+                fields=", ".join(fields),
+                name=cls.__name__.lower(),
+            ),
+            fields,
+        )
 
     @classmethod
     def _get_select_where_sql(cls, **kwargs):
+        """
+        Generate SQL for selecting records by criteria.
+
+        Args:
+            **kwargs: Column-value pairs to filter by
+
+        Returns:
+            Tuple of (SQL string, field names list, parameter values list)
+        """
         SELECT_WHERE_SQL = "SELECT {fields} FROM {name} WHERE {query};"
 
         fields = ["id"]
@@ -211,6 +506,12 @@ class Table:
         )
 
     def _get_update_sql(self):
+        """
+        Generate SQL for updating a record.
+
+        Returns:
+            Tuple of (SQL string, parameter values list)
+        """
         UPDATE_SQL = "UPDATE {name} SET {fields} WHERE id = ?;"
 
         cls = self.__class__
@@ -227,14 +528,23 @@ class Table:
 
         values.append(getattr(self, "id"))
 
-        return UPDATE_SQL.format(
-            name=cls.__name__.lower(),
-            fields=", ".join([f"{field} = ?" for field in fields]),
-        ), values
+        return (
+            UPDATE_SQL.format(
+                name=cls.__name__.lower(),
+                fields=", ".join([f"{field} = ?" for field in fields]),
+            ),
+            values,
+        )
 
     def _get_delete_sql(self):
+        """
+        Generate SQL for deleting a record.
+
+        Returns:
+            Tuple of (SQL string, parameter values list)
+        """
         DELETE_SQL = "DELETE FROM {name} WHERE id = ?;"
 
-        return DELETE_SQL.format(
-            name=self.__class__.__name__.lower()
-        ), [getattr(self, "id")]
+        return DELETE_SQL.format(name=self.__class__.__name__.lower()), [
+            getattr(self, "id")
+        ]

plinx/orm/utils.py

@@ -3,5 +3,5 @@ SQLITE_TYPE_MAP = {
     float: "REAL",
     str: "TEXT",
     bytes: "BLOB",
-    bool: "INTEGER"
-}
+    bool: "INTEGER",
+}

plinx/response.py

@@ -6,7 +6,57 @@ from webob import Response as WebObResponse
 
 
 class PlinxResponse:
+    """
+    Response class for the Plinx web framework.
+
+    This class provides a simple interface for constructing HTTP responses,
+    with high-level helpers for common response types like JSON and plain text.
+    It wraps WebOb's Response for actual WSGI compliance and output generation.
+
+    The class provides multiple ways to set response content:
+
+    1. Set the `text` attribute for plain text responses
+    2. Set the `json` attribute for JSON responses
+    3. Set the `body` attribute directly for binary data
+
+    It also allows setting status codes, content types, and custom headers.
+
+    Examples:
+        Plain text response:
+        ```python
+        def handler(request, response):
+            response.text = "Hello, World!"
+            response.status_code = 200  # Optional, defaults to 200
+        ```
+
+        JSON response:
+        ```python
+        def handler(request, response):
+            response.json = {"message": "Hello, World!"}
+            # Content-Type will automatically be set to application/json
+        ```
+
+        Custom headers:
+        ```python
+        def handler(request, response):
+            response.text = "Not Found"
+            response.status_code = 404
+            response.headers["X-Custom-Header"] = "Value"
+        ```
+    """
+
     def __init__(self):
+        """
+        Initialize a new response object.
+
+        Sets up default values for the response attributes:
+        - json: None (will be serialized to JSON if set)
+        - text: None (will be encoded to UTF-8 if set)
+        - content_type: None (will be set based on response type)
+        - body: Empty bytes (raw response body)
+        - status_code: 200 (OK)
+        - headers: Empty dict (custom HTTP headers)
+        """
         self.json = None
         self.text = None
         self.content_type = None
@@ -20,10 +70,18 @@ class PlinxResponse:
         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 callable interface for the response.
+
+        This makes the response object act as a WSGI application,
+        which is required for compatibility with WSGI servers.
+        It delegates the actual WSGI handling to WebOb's Response.
+
+        Args:
+            environ: The WSGI environment dictionary
+            start_response: The WSGI start_response callable
+
+        Returns:
+            An iterable of bytes representing the response body
         """
 
         self.set_body_and_content_type()
@@ -37,12 +95,26 @@ class PlinxResponse:
         return response(environ, start_response)
 
     def set_body_and_content_type(self):
+        """
+        Prepare the response body and content type based on the response attributes.
+
+        This method is called automatically before the response is returned.
+        It handles the conversion of high-level response attributes (`json`, `text`)
+        into the raw response body and appropriate content type.
+
+        The priority order is:
+        1. If `json` is set, encode it as JSON and set content_type to application/json
+        2. If `text` is set, encode it as UTF-8 and set content_type to text/plain
+        3. Otherwise, use the existing `body` and `content_type`
+        """
         if self.json is not None:
             self.body = json.dumps(self.json).encode("UTF-8")
             self.content_type = "application/json"
         elif self.text is not None:
-            self.body = self.text.encode("utf-8") if isinstance(self.text, str) else self.text
+            self.body = (
+                self.text.encode("utf-8") if isinstance(self.text, str) else self.text
+            )
             self.content_type = "text/plain"
 
         if self.content_type is not None:
-            self.headers["Content-Type"] = self.content_type
+            self.headers["Content-Type"] = self.content_type

plinx/status_codes.py

@@ -2,18 +2,39 @@ from enum import Enum
 
 
 class StatusCodes(Enum):
-    """Status codes for the API."""
+    """
+    Enumeration of HTTP status codes supported by the Plinx framework.
 
-    # 2XX
+    This enum defines standard HTTP status codes as defined in RFC 7231,
+    organized by their categories (2xx for success, 3xx for redirection, etc.).
+
+    Each status code has a name that reflects its standard description,
+    and a numeric value that is sent in HTTP responses.
+
+    Usage:
+        ```python
+        from plinx.status_codes import StatusCodes
+
+        # Set a 404 status code
+        response.status_code = StatusCodes.NOT_FOUND.value  # 404
+
+        # Get the name of a status code for display
+        status_name = StatusCodes.NOT_FOUND.name  # "NOT_FOUND"
+        # Can be formatted for human display:
+        human_readable = StatusCodes.NOT_FOUND.name.replace("_", " ").title()  # "Not Found"
+        ```
+    """
+
+    # 2XX - Success
     OK = 200
     CREATED = 201
     ACCEPTED = 202
     NO_CONTENT = 204
 
-    # 3XX
+    # 3XX - Redirection
     NOT_MODIFIED = 304
 
-    # 4XX
+    # 4XX - Client Error
     BAD_REQUEST = 400
     UNAUTHORIZED = 401
     FORBIDDEN = 403
@@ -27,7 +48,7 @@ class StatusCodes(Enum):
     TOO_MANY_REQUESTS = 429
     UNAVAILABLE_FOR_LEGAL_REASONS = 451
 
-    # 5XX
+    # 5XX - Server Error
     INTERNAL_SERVER_ERROR = 500
     NOT_IMPLEMENTED = 501
     BAD_GATEWAY = 502

plinx/utils.py

@@ -5,9 +5,24 @@ from plinx.status_codes import StatusCodes
 
 def handle_404(response: Response) -> None:
     """
-    Set the response status code to 404 and return None.
-    :param response:
-    :return:
+    Set up a standardized 404 Not Found response.
+
+    This utility function is used internally by the framework when no route
+    matches the requested URL path. It sets the status code to 404 and
+    the response text to "Not Found".
+
+    Args:
+        response: The Response object to configure with 404 status
+
+    Returns:
+        None
+
+    Example:
+        ```python
+        response = Response()
+        handle_404(response)
+        # response now has status_code=404 and text="Not Found"
+        ```
     """
     response.status_code = StatusCodes.NOT_FOUND.value
     response.text = StatusCodes.NOT_FOUND.name.replace("_", " ").title()

{Plinx-1.0.0.dist-info → plinx-1.0.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: Plinx
-Version: 1.0.0
+Version: 1.0.1
 Summary: Plinx is an experimental, minimalistic, and extensible web framework and ORM written in Python.
 Home-page: https://github.com/dhavalsavalia/plinx
 Author: Dhaval Savalia
@@ -17,6 +17,19 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: webob
 Requires-Dist: parse
+Requires-Dist: requests
+Requires-Dist: requests-wsgi-adapter
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 
 # Plinx
@@ -68,7 +81,7 @@ app = Plinx()
 
 @app.route("/")
 def index(request, response):
-    response.text = "Hello, Plinx 1.0.0!"
+    response.text = "Hello, Plinx 1.0.1!"
 
 # Example using the ORM (requires database setup)
 # from plinx.orm import Database, Table, Column

plinx-1.0.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+plinx/__init__.py,sha256=TkcBtaKtAwXDE6XKgnkfC-fIzNxtCErHDt0WCh1ZF74,54
+plinx/applications.py,sha256=XM5jPYgeJapYxaGcTzphcpr_281et0QDwPMfAGIbRtA,11483
+plinx/methods.py,sha256=uLZmj3KQ4QF-JVNgq3fVY7kOJkKJDMQghyiogU8m2Yc,2101
+plinx/middleware.py,sha256=Kdeau4eZ5f4nKTlH_CNvaIndYwkgIdtWBP50-khEK5s,5050
+plinx/response.py,sha256=-CgkW4cH9pLSa73YdrnceCInObwPzpSplhnWfAg-360,4079
+plinx/status_codes.py,sha256=dPkHkcnULbhrxk6WYhR5wmrd2sKhOQf409G_OtX8Cug,1536
+plinx/utils.py,sha256=da0uiLEvLMrjROeUJ5lfBTRAIqKoSdKkqImPs1qHsF4,769
+plinx/orm/__init__.py,sha256=ryDdzvF6Eh6RIHyEgym6UKCaFMnMitwucazpiWuvICQ,61
+plinx/orm/orm.py,sha256=-eHAgURYWw5kL9zMCO1Mha5gRcPCbqoAY6BALj-gqJc,15790
+plinx/orm/utils.py,sha256=fkP89dYMcNFUOcRryxGTNUEV0Dr40-qwG-IH2AxY4DQ,118
+plinx-1.0.1.dist-info/licenses/LICENSE,sha256=MljMjTJD6oOY41eZWLDZ4x8FrTUcl7ElKxWIXJXUwLM,1066
+plinx-1.0.1.dist-info/METADATA,sha256=nvJIwZYncIm-dAB8_oZC8FX4W8Ow2yr3UA_xBd1WPEg,3116
+plinx-1.0.1.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
+plinx-1.0.1.dist-info/top_level.txt,sha256=U_4P3aFsTEhhvfiE3sVbJKAG9Fp4IPC5d6zpttayAZw,6
+plinx-1.0.1.dist-info/RECORD,,

{Plinx-1.0.0.dist-info → plinx-1.0.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.45.1)
+Generator: setuptools (79.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

Plinx-1.0.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-plinx/__init__.py,sha256=oMho3a3JJZllxtj4lLwS96pwWRBvctDJRFww5lfqlBs,32
-plinx/applications.py,sha256=Oy2pO1zyfKWyYXeJ8AuzdoAab6XJThNHDbOdpKWA5-8,5957
-plinx/methods.py,sha256=CEaousqNXbgdyaEL0BdOtAWh1p03jAaAFzXJkY9xII0,294
-plinx/middleware.py,sha256=OiNDhKWpmpKkAIbSWxRzP_tQXSyfDToos-MQMDPSUWM,2161
-plinx/response.py,sha256=oDZPF9V76HhqdUZLzSmoLw_q-GG9hc5krfCBgNm3OfU,1460
-plinx/status_codes.py,sha256=V7vX7_ujYIaVjO3I3eVUnuNKiTXMSov56wJt8tvMbAM,700
-plinx/utils.py,sha256=WaU_j7YXsdlZh3M33B2vXjRPAU26lBeQ5sV2ZasXVwE,352
-plinx/orm/__init__.py,sha256=ryDdzvF6Eh6RIHyEgym6UKCaFMnMitwucazpiWuvICQ,61
-plinx/orm/orm.py,sha256=FdwLdT-4I5rnhfTCu7v9iBZZ5xlZHZ36equqPAHYvhk,7335
-plinx/orm/utils.py,sha256=uXT2JV9cVgLTnm_EkguqJglsbIfSPXcnjMQBNFJ8M08,116
-Plinx-1.0.0.dist-info/LICENSE,sha256=MljMjTJD6oOY41eZWLDZ4x8FrTUcl7ElKxWIXJXUwLM,1066
-Plinx-1.0.0.dist-info/METADATA,sha256=cDxPb9HkViq-kG_JWVI3YFWI6APojOUiPSZSotzBfFY,2819
-Plinx-1.0.0.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-Plinx-1.0.0.dist-info/top_level.txt,sha256=U_4P3aFsTEhhvfiE3sVbJKAG9Fp4IPC5d6zpttayAZw,6
-Plinx-1.0.0.dist-info/RECORD,,