joop 0.0.1__py3-none-any.whl

joop/tests/test_web.py

@@ -0,0 +1,75 @@
+"""Unit tests for joop web components.
+
+We're testing both components, their templates, and the rendering here.
+"""
+
+from joop.web import HTMLComponent
+import unittest
+from dataclasses import is_dataclass, dataclass, asdict
+from joop.tests.test_templater import environment
+from joop.web.examples.hello import (
+    HelloWorld, HelloName, HelloSuperComponent
+)
+
+# Create our classes for the test and
+#   specify the environment via multiple inheritance:
+
+class BaseTestHTMLComponent(HTMLComponent):
+        _jinja_env = environment
+
+class MyHello(HelloWorld,
+BaseTestHTMLComponent): pass
+
+class MyHelloName(HelloName,
+BaseTestHTMLComponent): pass
+
+class MyHelloSuper(HelloSuperComponent,
+BaseTestHTMLComponent):     pass
+
+class TestHTMLComponent(unittest.TestCase):
+    
+    def _setup_hello(self):
+        self.hello = MyHello()
+        self.hello.inputs = MyHello.Inputs()
+        self.hello.subs = MyHello.SubComponents()
+    
+    def _setup_name(self):
+        self.hello_name = MyHelloName()
+        self.hello_name.inputs = MyHelloName.Inputs(first_name = "Justin",
+                                                  last_name = "Rushin")
+        self.hello_name.subs = MyHelloName.SubComponents()
+
+    def _setup_super(self):
+        self.hello_super = MyHelloSuper()
+        self.hello_super.inputs = MyHelloSuper.Inputs()
+
+    def setUp(self):
+        # Configure the Jinja2 environment with a FileSystemLoader
+        self._setup_hello()
+        self._setup_name()
+        self._setup_super()
+
+    def test_000_type_check(self):
+        # here, we are verifying that our custom abstract code works
+        assert is_dataclass(self.hello.inputs) 
+
+    def test_001_hello_world(self):
+        hello_html = self.hello.render()
+        assert hello_html == "<p>Hello, World!</p>"
+    
+    def test_002_hello_name(self):
+        hello_name_html = self.hello_name.render()
+        _tgt_html = """<p>Hello, Justin Rushin!</p>"""
+        assert hello_name_html == _tgt_html
+
+    def test_003_hello_subcomponent(self):
+        _hello = MyHello(parent=self.hello_super)
+        _hello.inputs = MyHello.Inputs()
+        _hello.subs = MyHello.SubComponents()
+        self.hello_super.subs = MyHelloSuper.SubComponents(
+            my_hello = _hello
+        )
+        assert is_dataclass(self.hello_super.subs)
+        hello_super_html = self.hello_super.render()
+        _tgt_html = """<p>I'm a supercomponent! And I say:</p>\n<p>Hello, World!</p>"""
+        assert hello_super_html == _tgt_html

joop/web/__init__.py

@@ -0,0 +1,14 @@
+"""Web module.
+
+All functionality related to web-backends, HTML templating, etc. lives here.
+
+Modules:
+    component: Define web UI or API components.
+    html: Where components get rendered to HTML.
+    view: Register components to webservers, set up views routes, etc.
+
+"""
+
+from joop.web.component import Component #, JSONComponent
+from joop.web.html import HTML, HTMLComponent
+from joop.web.view import View

joop/web/component.py

@@ -0,0 +1,163 @@
+"""
+
+Components are programmatic representations of data or UI elements, designed to be rendered dynamically,
+    in the context of a web server.
+A highly abstract class, the purpose of it is to provide a standard way to define inputs, outputs,
+    and the transformations needed to render them. Components are the backbone of joop.web.
+
+Classes:
+    Component:
+        The base class for all components, providing a structure for inputs, data, and subcomponents.
+
+    JSONComponent:
+        A specialized component for handling JSON data. Implementation pending.
+
+"""
+
+from typing import Optional
+from dataclasses import dataclass, fields
+from abc import ABCMeta
+
+from joop.abstract import AbstractMethod
+
+class Component(metaclass=ABCMeta):
+    '''
+    Base class for programmatically rendering data or UI elements.
+
+    This class provides a structure for defining inputs, data, and subcomponents,
+    and includes methods for processing inputs and rendering components.
+
+    Attributes:
+        inputs (Inputs): The input data for the component.
+        data (Data): The processed data for the component.
+        subs (SubComponents): The subcomponents of the component.
+
+    Methods:
+        _process_inputs():
+            Processes the inputs to generate the component's data.
+
+        render() -> str:
+            Abstract method to render the component as a string.
+    '''
+
+    class Inputs(metaclass=ABCMeta):
+        """Abstract base class for defining the input data structure of a component."""
+        pass
+
+    Inputs = dataclass(Inputs)
+
+    class _Data(metaclass=ABCMeta):
+        """Abstract base class for defining the internal data structure of a component."""
+        pass
+
+    _Data = dataclass(_Data)
+
+    class Data(_Data):
+        """
+        Class for defining the processed data of a component.
+
+        Methods:
+            _from_inputs(inputs: Component.Inputs) -> Component.Data:
+                Creates a Data instance from the given Inputs.
+
+            from_inputs(inputs: Component.Inputs) -> Component.Data:
+                Abstract method to create a Data instance from the given Inputs.
+        """
+
+        @classmethod
+        def _from_inputs(cls, inputs: 'Component.Inputs') -> 'Component.Data':
+            """
+            Create a Data instance from the given Inputs.
+
+            Args:
+                inputs (Component.Inputs): The input data for the component.
+
+            Returns:
+                Component.Data: A new Data instance.
+            """
+            return cls()
+
+        @classmethod
+        def from_inputs(cls, inputs: 'Component.Inputs') -> 'Component.Data':
+            """
+            Abstract method to create a Data instance from the given Inputs.
+
+            Args:
+                inputs (Component.Inputs): The input data for the component.
+
+            Returns:
+                Component.Data: A new Data instance.
+            """
+            return Component.Data() # pragma: no cover
+
+        from_inputs = AbstractMethod(from_inputs)
+
+    class SubComponents(metaclass=ABCMeta):
+        """Abstract base class for defining the subcomponents of a component."""
+        pass
+
+    SubComponents = dataclass(SubComponents)
+
+    inputs: Inputs
+    data: Data
+    subs: SubComponents
+
+    def __init__(self, parent: Optional['Component'] = None, *args, **kwargs):
+        """
+        Initialize a Component instance.
+
+        Args:
+            parent (Optional[Component]): The parent component, if any.
+            *args: Additional positional arguments.
+            **kwargs: Additional keyword arguments.
+        """
+        super().__init__(*args, **kwargs)  # Pass additional arguments to the next class in the MRO
+        if parent is not None:
+            self._parent = parent
+
+    def _process_inputs(self):
+        """
+        Process the inputs to generate the component's data.
+
+        This method uses the `from_inputs` method of the Data class to create a
+        Data instance from the component's inputs.
+        """
+        self.data = self.Data.from_inputs(self.inputs)
+
+    def render(self) -> str:
+        """
+        Abstract method to render the component as a string.
+
+        This method processes the inputs and generates the component's data before
+        rendering it as a string. Subclasses must implement this method.
+
+        Returns:
+            str: The rendered component as a string.
+        """
+        self._process_inputs()
+
+    render.__isabstractmethod__ = True
+
+    def __init_subclass__(cls, **kwargs):
+        """
+        Initialize a subclass of Component.
+
+        This method ensures that the Data, Inputs, and SubComponents classes of the
+        subclass are decorated as dataclasses.
+
+        Args:
+            **kwargs: Additional keyword arguments.
+        """
+        super().__init_subclass__(**kwargs)
+        cls.Data = dataclass(cls.Data)
+        cls.Inputs = dataclass(cls.Inputs)
+        cls.SubComponents = dataclass(cls.SubComponents)
+
+class JSONComponent(Component):
+    """
+    A specialized component for handling JSON data.
+
+    Inherits:
+        Component: The base Component class.
+    """
+    pass

joop/web/components.py

@@ -0,0 +1,116 @@
+"""
+Useful components for web development.
+It includes a base class `AlpineTableComponent` for generating AlpineJS-powered
+    tables based on Pydantic or SQLModel models.
+The module also defines data access object (DAO) classes for handling row data.
+"""
+
+from joop.web.html import HTMLComponent
+from joop.dao import DAO
+import typing
+
+class MetaRowDAO(DAO):
+    """
+    Implementation pending.
+    A base Data Access Object (DAO) class for handling row data.
+    This class can be extended to implement specific data access logic.
+    """
+    pass
+
+class RowDAO(MetaRowDAO):
+    """
+    Implementation pending.
+    A concrete implementation of `MetaRowDAO` for handling generic row data.
+    """
+    pass
+
+class SQLRowDAO(MetaRowDAO):
+    """
+    Implementation pending.
+    A concrete implementation of `MetaRowDAO` for handling SQL-based row data.
+    """
+    pass
+
+'''
+A common base component to allow for ready-made,
+AlpineJS powered
+tables based on Pydantic or SQLModel models.
+'''
+class AlpineTableComponent(HTMLComponent):
+    """
+    A reusable component for rendering tables using Alpine.js and HTML templates.
+
+    Attributes:
+        _template_location (str): Path to the HTML template for the table.
+        _use_prefix_template (bool): Determines whether to use a prefixed template directory.
+        _row_type (typing.Type[MetaRowDAO]): Specifies the type of row data to be used in the table.
+    """
+    _template_location = "table/alp_table.html"
+    _use_prefix_template = False
+    _row_type: typing.Type[MetaRowDAO]
+
+    class Inputs(HTMLComponent.Inputs):
+        """
+        Represents the input data structure for the `AlpineTableComponent`.
+        Extend this class to define specific input fields for the table.
+        """
+        pass
+
+    class Data(HTMLComponent.Data):
+        """
+        Represents the data structure for the `AlpineTableComponent`.
+
+        Attributes:
+            rows (typing.Iterable[MetaRowDAO]): The rows of data to be displayed in the table.
+            table_headers (typing.Any): The headers of the table, derived from the row type.
+            _row_type: The type of row data used in the table.
+        """
+        rows : typing.Iterable[MetaRowDAO]
+        table_headers: typing.Any
+        _row_type = None
+
+        @classmethod
+        def _get_table_headers(cls):
+            """
+            Retrieve the table headers based on the fields of the row type's model.
+
+            Returns:
+                list: A list of field names for the table headers.
+            """
+            return cls._row_type.get_model_fields()
+
+        @classmethod
+        def from_inputs(cls,
+                        inputs : 'AlpineTableComponent.Inputs',
+                        ) -> 'AlpineTableComponent.Data':
+            """
+            Create a `Data` instance from the provided inputs.
+
+            Args:
+                inputs (AlpineTableComponent.Inputs): The input data for the table.
+
+            Returns:
+                AlpineTableComponent.Data: An instance of the Data class with initialized values.
+            """
+            return cls(rows = [],
+                       table_headers = cls._get_table_headers())
+
+    def _process_inputs(self, **kwargs):
+        """
+        Process the input data and set the row type for the table.
+
+        Args:
+            **kwargs: Additional keyword arguments for processing inputs.
+
+        Returns:
+            Any: The processed input data.
+        """
+        self.Data._row_type = self._row_type
+        return super()._process_inputs(**kwargs)
+    
+    class SubComponents(HTMLComponent.SubComponents):
+        """
+        Represents subcomponents of the `AlpineTableComponent`.
+        Extend this class to define specific subcomponents.
+        """
+        pass

joop/web/examples/hello.py

@@ -0,0 +1,148 @@
+"""
+
+This file contains examples for learning, development, and testing of joop.web components.
+Included is examples of how to define and implement web components of the most basic kind.
+
+"""
+
+from joop.web import HTMLComponent
+
+class HelloWorld(HTMLComponent):
+
+    # Every HTMLComponent has a template location.
+    _template_location = "hello.html"
+
+    # A definition of an inner input class is required.
+    class Inputs(HTMLComponent.Inputs):
+        # Even if it's empty.
+        pass
+
+    # For the inner classes, inherit from the parent class:
+    class Data(HTMLComponent.Data):
+        pass
+
+        # `from_inputs` must be defined as well.
+        @classmethod # Yes, you still have to specify classmethod.
+        # Also, it is good to be specific with type hints:
+        def from_inputs(cls, inputs : 'HelloWorld.Inputs') -> 'HelloWorld.Data':
+            # If you've got a no-op class like this, use:
+            return super()._from_inputs(inputs)
+    
+    # Copy-pasting the above ^^^ to a new component is safe
+    
+    # Same as inputs, just make an empty class if there are no
+    #   child/sub components.
+    class SubComponents(HTMLComponent.SubComponents):
+        pass
+
+'''
+To then render the hello world component:
+```
+component         = HelloWorld()
+component.inputs  = component.Inputs()
+# You don't need to do data because of the `from_inputs`.
+component.subs    = component.SubComponents()
+return component.render()
+```
+That's it. But why complicate a "hello world" by
+requiring empty classes, functions etc.?
+A few reasons:
+1. We don't optimize for "hello world" because real
+    components are unlikely to be this simple, but
+    compromise on succintness for the sake of simplicity
+    and consistency.
+2. joop is a declarative paradigm, and accordingly,
+    explicitly declared symbols show the class inheritance.
+3. Explicitly declared stubs show you that nothing is there.
+4. It facilitates the derivation of more complex components
+    from more simple ones (and possibly, vice-versa).
+5. A place for everything, and everything in its place.
+'''
+
+# Now for a component with dynamic data rendering.
+
+class HelloName(HTMLComponent):
+    _template_location = "hello_name.html"  # Adjusted for simplicity
+
+    # Inputs and data are dataclasses via inheritance (there's a bit of trickery).
+    class Inputs(HTMLComponent.Inputs):
+        first_name: str
+        last_name : str
+    
+    # Inputs is what it sounds like.
+    # Data goes to the template to be rendered.
+    class Data(HTMLComponent.Data):
+# The name of the data fields will be used in the template.
+        full_name : str
+
+        @classmethod
+        def from_inputs(cls, inputs: "HelloName.Inputs") -> "HelloName.Data":
+            res = f"{inputs.first_name} {inputs.last_name}"
+            return cls(full_name = res)
+
+    class SubComponents(HTMLComponent.SubComponents):
+        pass
+'''
+To then render the hello name component:
+```
+component         = HelloName()
+component.inputs  = component.Inputs(
+                    first_name  = "Justin",
+                    last_name   = "Rushin")
+component.subs    = res.SubComponents()
+return component.render()
+```
+'''
+
+# Now for an example with subcomponents aka:
+#   child components, or nested components.
+
+class HelloSuperComponent(HTMLComponent):
+        # Of course, this is our/outer's template. Inner
+        #   template isn't specified. It's in the subcomponent.
+        _template_location = "hello_supercomponent.html"
+
+        # Empty inputs and data classes follow:
+        class Inputs(HTMLComponent.Inputs):
+            pass
+
+        class Data(HTMLComponent.Data):
+
+            @classmethod
+            def from_inputs(cls, inputs):
+                return super()._from_inputs(inputs)
+        
+        class SubComponents(HTMLComponent.SubComponents):
+            # No need to specify a default factory.
+            # We use some trickery. Just specify the class
+            #   of the child component.
+            my_hello: HelloWorld
+
+        def render(self) -> str:
+            return super().render()
+
+'''
+To render this component with nesting:
+```
+component           = HelloSuperComponent()
+component.inputs    = component.Inputs() # empty inputs
+subcomponent        = HelloWorld(parent = component)
+subcomponent.inputs = subcomponent.Inputs()
+component.subs      = component.SubComponents(
+    my_hello = subcomponent
+)
+component.render()
+```
+`render` will include subcomponents recursively.
+'''
+
+'''
+To summarize, a component is made by:
+1. Deriving the outer class from the correct class.
+2. Defining the fields/properties of the innner classes.
+3. Implementing the `from_inputs` function to transform
+    input to output.
+4. Carrying out any other special implementation necessary.
+
+Of course, this ignores what's done on the template side.
+'''

joop/web/examples/table.py

@@ -0,0 +1,148 @@
+"""
+This module provides an example implementation of a table component and its integration into a web page.
+It demonstrates the usage of the `AlpineTableComponent` for rendering tables and the `View` class for creating web pages.
+"""
+
+from joop.web.components import AlpineTableComponent
+from joop.web.view import View
+from joop.web.html import HTMLComponent
+from joop.http.methods import HttpMethod
+from joop.web.examples.view import HELLO_DESIG, HELLO_ROOT
+from joop.dao import DAO
+from pydantic import BaseModel
+
+class Hello_DAO(DAO):
+    """
+    A Data Access Object (DAO) for handling data related to the `Hello_Model`.
+
+    Attributes:
+        Hello_Model (BaseModel): A Pydantic model representing the data structure.
+    """
+
+    class Hello_Model(BaseModel):
+        """
+        A Pydantic model representing a simple data structure with a single field `Desig`.
+
+        Attributes:
+            Desig (str): A string field representing a designation.
+        """
+        Desig : str
+
+    _modeltype = Hello_Model
+
+class MyTableComponent(AlpineTableComponent):
+    """
+    A custom table component that extends the `AlpineTableComponent`.
+
+    Attributes:
+        _row_type (type): Specifies the type of row data to be used in the table.
+    """
+    _row_type = Hello_DAO
+
+    class Inputs(AlpineTableComponent.Inputs):
+        """
+        Represents the input data structure for the `MyTableComponent`.
+        Extend this class to define specific input fields for the table.
+        """
+        pass
+
+    class Data(AlpineTableComponent.Data):
+        """
+        Represents the data structure for the `MyTableComponent`.
+
+        Attributes:
+            definition_name (str): The name of the table definition.
+        """
+        definition_name : str = "myTable"
+
+        @classmethod
+        def from_inputs(cls, inputs : 'MyTableComponent.Inputs') -> AlpineTableComponent.Data:
+            """
+            Create a `Data` instance from the provided inputs.
+
+            Args:
+                inputs (MyTableComponent.Inputs): The input data for the table.
+
+            Returns:
+                AlpineTableComponent.Data: An instance of the Data class with initialized values.
+            """
+            return cls(
+                rows = [
+                    Hello_DAO.from_model(Hello_DAO.Hello_Model(Desig = "Hello")),
+                    Hello_DAO.from_model(Hello_DAO.Hello_Model(Desig = "World"))
+                ],
+                table_headers = cls._get_table_headers()
+            )
+        
+    class SubComponents(AlpineTableComponent.SubComponents):
+        """
+        Represents subcomponents of the `MyTableComponent`.
+        Extend this class to define specific subcomponents.
+        """
+        pass
+
+class MyTablePage(HTMLComponent):
+    """
+    A web page component that includes the `MyTableComponent`.
+
+    Attributes:
+        _template_location (str): Path to the HTML template for the page.
+    """
+    _template_location = "table/page.html"
+
+    class Inputs(HTMLComponent.Inputs):
+        """
+        Represents the input data structure for the `MyTablePage`.
+        Extend this class to define specific input fields for the page.
+        """
+        pass
+
+    class Data(HTMLComponent.Data):
+        """
+        Represents the data structure for the `MyTablePage`.
+        """
+
+        @classmethod
+        def from_inputs(cls, inputs : 'MyTablePage.Inputs'):
+            """
+            Create a `Data` instance from the provided inputs.
+
+            Args:
+                inputs (MyTablePage.Inputs): The input data for the page.
+
+            Returns:
+                MyTablePage.Data: An instance of the Data class with initialized values.
+            """
+            return cls()
+    
+    class SubComponents(HTMLComponent.SubComponents):
+        """
+        Represents subcomponents of the `MyTablePage`.
+
+        Attributes:
+            my_t (MyTableComponent): An instance of the `MyTableComponent`.
+        """
+        my_t = MyTableComponent
+        table : my_t = my_t()
+
+class MyTableWholePage(View):
+    """
+    A web view that renders the `MyTablePage` component.
+
+    Attributes:
+        _component_type (type): Specifies the type of the main component for the view.
+    """
+    _component_type = MyTablePage
+
+    class Endpoint():
+        """
+        Defines the endpoint for the `MyTableWholePage` view.
+
+        Attributes:
+            _url (str): The URL path for the endpoint.
+            _name (str): The name of the endpoint.
+            _methods (list): The HTTP methods supported by the endpoint.
+        """
+        _url = HELLO_ROOT + "/table"
+        _name = HELLO_DESIG + "_table"
+        _methods = [HttpMethod.GET.value]

joop/web/examples/view.py

@@ -0,0 +1,30 @@
+"""
+
+This is an example of how to define Views from components.
+
+"""
+
+from joop.http.methods import HttpMethod
+from joop.web.examples.hello import HelloWorld, HelloName
+from joop.web.view import View
+
+HELLO_ROOT = "/hello"
+HELLO_DESIG = "hello"
+
+class HelloView(View):
+
+    _component_type = HelloWorld
+
+    class Endpoint():
+        _url = HELLO_ROOT
+        _name = HELLO_DESIG
+        _methods = [HttpMethod.GET.value]
+    
+class NameView(View):
+
+    _component_type = HelloName
+
+    class Endpoint():
+        _url = HELLO_ROOT + "/<string:first_name>/<string:last_name>"
+        _name = HELLO_DESIG + "_name"
+        _methods = [HttpMethod.GET.value]