joop 0.0.1__py3-none-any.whl

joop/web/html.py

@@ -0,0 +1,212 @@
+""" An HTML Component is a joop Component that renders to HTML.
+
+Like many projects, joop achieves this via jinja templating.
+There is a specific structure for template variables that joop imposes to meet
+its goals of providing a "place for everything and everything in its place."
+
+Classes:
+    HTML:
+        A base class for managing Jinja2 templates and rendering HTML content.
+
+    HTMLComponent:
+        A component class that extends both Component and HTML to provide
+        functionality for rendering HTML components with subcomponents and data.
+
+"""
+
+import jinja2
+from typing import Optional
+from dataclasses import asdict, fields
+from joop.web.component import Component
+from joop.web.j_env import get_joop_env
+
+class HTML():
+    """
+    A base class for managing Jinja2 templates and rendering HTML content.
+
+    Its main purpose is to tie behavior to a specific Jinja2 env, especially
+        in terms of template location.
+
+    This class provides methods for initializing and managing a Jinja2 environment
+    and loading templates for rendering HTML.
+
+    Attributes:
+        _template_location (str): The location of the Jinja2 template file.
+        _jinja_env (Optional[jinja2.Environment]): The Jinja2 environment used for rendering.
+
+    Methods:
+        __init__(j_env: Optional[jinja2.Environment] = None):
+            Initializes the HTML class with a Jinja2 environment.
+
+        _get_template() -> jinja2.Template:
+            Retrieves the Jinja2 template based on the template location.
+    """
+    _template_location: None
+    _jinja_env: Optional[jinja2.Environment] = None
+
+    def __init__(self, j_env: Optional[jinja2.Environment] = None):
+        """
+        Initialize the HTML class with a Jinja2 environment.
+
+        Args:
+            j_env (Optional[jinja2.Environment]): The Jinja2 environment to use for rendering.
+
+        Raises:
+            ValueError: If no Jinja2 environment is provided or available.
+        """
+        if j_env is not None:
+            self._jinja_env = j_env
+        elif self._jinja_env is None:
+                self._jinja_env = get_joop_env()
+        
+        if self._jinja_env is None:
+            raise ValueError("A Jinja2 environment must be provided either as a class property or during initialization.")
+
+    def _get_template(self) -> jinja2.Template:
+        """
+        Retrieve the Jinja2 template based on the template location.
+
+        Returns:
+            jinja2.Template: The Jinja2 template object.
+        """
+        _res = self._jinja_env.get_template(self._template_location)
+        return _res
+    
+class HTMLComponent(Component, HTML):
+    """
+    A component class that extends both Component and HTML to provide functionality
+    for rendering HTML components with subcomponents and data.
+
+    This class integrates the base Component class with the HTML class to enable
+    dynamic rendering of HTML components using Jinja2 templates.
+
+    Attributes:
+        _loaded_template (jinja2.Template): The loaded Jinja2 template for the component.
+
+    Methods:
+        __init__(j_env: Optional[jinja2.Environment] = None, parent: Optional[Component] = None):
+            Initializes the HTMLComponent with a Jinja2 environment and an optional parent component.
+
+        _load_template():
+            Loads the Jinja2 template for the component.
+
+        render(as_subcomponent: bool = False, **kwargs) -> str:
+            Renders the component as a string, optionally as a subcomponent.
+
+    Nested Classes:
+        SubComponents:
+            A class for managing subcomponents of the HTMLComponent.
+
+            Methods:
+                get_all -> dict[str, 'Component']:
+                    Retrieves all subcomponents as a dictionary.
+
+                render():
+                    Renders all subcomponents and stores their HTML output.
+
+                get_rendered() -> dict[str, str]:
+                    Returns the rendered HTML output of all subcomponents.
+    """
+
+    class SubComponents(Component.SubComponents):
+        """
+        A class for managing subcomponents of the HTMLComponent.
+
+        Methods:
+            get_all -> dict[str, 'Component']:
+                Retrieves all subcomponents as a dictionary.
+
+            render():
+                Renders all subcomponents and stores their HTML output.
+
+            get_rendered() -> dict[str, str]:
+                Returns the rendered HTML output of all subcomponents.
+        """
+
+        @property
+        def get_all(self) -> dict[str, 'Component']:
+            """
+            Retrieve all subcomponents as a dictionary.
+
+            Returns:
+                dict[str, Component]: A dictionary where keys are subcomponent names
+                and values are the subcomponent instances.
+            """
+            return {field.name: getattr(self, field.name) for field in fields(self)}
+
+        def render(self):
+            """
+            Render all subcomponents and store their HTML output.
+
+            This method iterates through all subcomponents, renders each one, and
+            stores the resulting HTML in a dictionary.
+            """
+            self._rendered_sc_html = {}
+            for _sc_name, _sc_inst in self.get_all.items():
+                self._rendered_sc_html[_sc_name] = _sc_inst.render(as_subcomponent = True)
+
+        def get_rendered(self) -> dict[str, str]:
+            """
+            Return the rendered HTML output of all subcomponents.
+
+            This method ensures that all subcomponents are rendered and returns
+            their HTML output as a dictionary.
+
+            Returns:
+                dict[str, str]: A dictionary where keys are subcomponent names and
+                values are their rendered HTML output.
+            """
+            self.render()
+            return self._rendered_sc_html
+
+    def __init__(self, j_env: Optional[jinja2.Environment] = None, parent: Optional[Component] = None):
+        """
+        Initialize the HTMLComponent with a Jinja2 environment and an optional parent component.
+
+        Args:
+            j_env (Optional[jinja2.Environment]): The Jinja2 environment to use for rendering.
+            parent (Optional[Component]): The parent component, if any.
+        """
+        super().__init__(parent=parent, j_env=j_env)  # Pass both arguments to super()
+
+    _loaded_template: jinja2.Template
+    
+    def _load_template(self):
+        """
+        Load the Jinja2 template for the component.
+
+        This method retrieves the template using the _get_template method and
+        stores it in the _loaded_template attribute.
+        """
+        self._loaded_template = self._get_template()
+
+    def render(self, as_subcomponent : bool = False, **kwargs) -> str:
+        """
+        Render the component as a string, optionally as a subcomponent.
+
+        This method prepares the component for rendering, loads the template,
+        and renders the HTML output using the provided data and subcomponents.
+
+        Args:
+            as_subcomponent (bool): Whether to render the component as a subcomponent.
+            **kwargs: Additional keyword arguments for rendering.
+
+        Returns:
+            str: The rendered HTML output.
+        """
+        if as_subcomponent == True:
+            self.inputs = self.Inputs(**kwargs)
+        super().render()
+        if as_subcomponent == True:
+            self.subs = self.SubComponents()
+        self._load_template()
+        _joop = {
+                'sc' : self.subs.get_rendered(),
+                'data' : asdict(self.data)
+            } 
+        print(_joop)
+        return self._loaded_template.render(
+            joop = _joop
+        )
+
+    # render.__isabstractmethod__ = True

joop/web/j_env.py

@@ -0,0 +1,39 @@
+"""Environment management module for joop.
+
+Important: The main purpose of this module is to be an interface layer for the jinja environment proxy
+    contained within joop for cross platform purposes (ex. run with or without flask.)
+
+This module provides functions to set and get the global templating environment for the joop instance.
+
+Variables:
+    joop_env:
+        A global variable to store the current templating environment.
+
+Functions:
+    set_joop_env(value):
+        Sets the global templating environment to the provided value.
+        
+        Args:
+            value: The new environment to set as the global environment.
+
+    get_joop_env():
+        Retrieves the current global templating environment.
+        
+        Returns:
+            The current global templating environment.
+
+Usage:
+    - Use `set_joop_env(value)` to set the global environment.
+    - Use `get_joop_env()` to retrieve the current global environment.
+
+"""
+
+joop_env = None
+
+def set_joop_env(value):
+    global joop_env
+    joop_env = value
+
+def get_joop_env():
+    global joop_env
+    return(joop_env)

joop/web/templater.py

@@ -0,0 +1,139 @@
+"""Templating environment factory for joop.
+
+Contains key implementation for joop templates, providing structure for data
+    access inside jinja templates.
+If it isn't a joop env, it won't work with joop templating.
+
+Classes:
+    EnvironmentFactory:
+        A factory class for creating and configuring Jinja2 Environment instances.
+
+        Methods:
+            create_environment(**kwargs):
+                Creates and configures a Jinja2 Environment instance.
+                Registers subcomponent and ata functions.
+
+            _get_joop(ctx: Context) -> dict:
+                Retrieves the 'joop' dictionary from the Jinja2 context.
+
+            subcomponent(ctx: Context, subcomponent_name: str) -> Markup:
+                Retrieves and marks a subcomponent as safe HTML.
+
+            data(ctx: Context, key: str) -> str:
+                Retrieves data associated with a key from the Jinja2 context.
+
+Usage:
+    - Use `EnvironmentFactory.create_environment()` to create a Jinja2 Environment.
+    - Use `subcomponent` and `data` methods to access joop data and subcomponents within a rendered template.
+
+"""
+
+from jinja2 import Environment as JinjaEnvironment, pass_context
+from jinja2.runtime import Context
+from markupsafe import Markup
+
+_JOOP_ROOT = 'joop'
+_SUBCOMPONENT_ROOT = 'sc'
+_DATA_ROOT = 'data'
+
+class EnvironmentFactory:
+    """
+    A factory class for creating and configuring Jinja2 Environment instances.
+
+    This class provides static methods to create a Jinja2 Environment and to define custom
+    functions for interacting with the Jinja2 context, such as retrieving subcomponents
+    and data.
+
+    Methods:
+        create_environment(**kwargs):
+            Creates and configures a Jinja2 Environment instance.
+
+        _get_joop(ctx: Context) -> dict:
+            Retrieves the 'joop' dictionary from the Jinja2 context.
+
+        subcomponent(ctx: Context, subcomponent_name: str) -> Markup:
+            Retrieves and marks a subcomponent as safe HTML.
+
+        data(ctx: Context, key: str) -> str:
+            Retrieves data associated with a key from the Jinja2 context.
+    """
+
+    @staticmethod
+    def create_environment(**kwargs):
+        """Factory method to create and configure a Jinja2 Environment.
+
+        Important: Registers the two main joop functions to the environment:
+            'subcomponents' and 'data'.
+
+        Args:
+            **kwargs: Arbitrary keyword arguments to configure the Jinja2 Environment.
+
+        Returns:
+            JinjaEnvironment: A configured Jinja2 Environment instance.
+
+        Usage Example:
+            env = EnvironmentFactory.create_environment(autoescape=True)
+        """
+        env = JinjaEnvironment(**kwargs)
+        env.globals.update({
+            'subcomponent': EnvironmentFactory.subcomponent,
+            'data': EnvironmentFactory.data,
+        })
+        return env
+
+    @staticmethod
+    def _get_joop(ctx: Context) -> dict:
+        """
+        Retrieve the 'joop' dictionary from the Jinja2 context.
+
+        Used by both `subcomponent` and `data` functions.
+        May seem like a lot of overhead, but it centralizes logic
+            and keeps everything in its place.
+
+        Args:
+            ctx (Context): The Jinja2 context object.
+
+        Returns:
+            dict: The 'joop' dictionary if it exists, otherwise an empty dictionary.
+        """
+        return ctx.get(_JOOP_ROOT, {})
+
+    @staticmethod
+    @pass_context
+    def subcomponent(ctx: Context, subcomponent_name: str) -> Markup:
+        """
+        Retrieve and mark a subcomponent as safe HTML.
+
+        Args:
+            ctx (Context): The Jinja2 context object.
+            subcomponent_name (str): The name of the subcomponent to retrieve.
+
+        Returns:
+            Markup: The safe HTML content of the subcomponent, or an empty string if the subcomponent is not found.
+
+        This function accesses the Jinja2 context to fetch a subcomponent stored under a specific name.
+        It ensures that the subcomponent is retrieved safely and marked as safe HTML.
+        If the subcomponent does not exist, an empty string is returned.
+        """
+        _sc_val = EnvironmentFactory._get_joop(ctx).get(_SUBCOMPONENT_ROOT, {}).get(subcomponent_name, "")
+        return Markup(_sc_val)
+    
+    @staticmethod
+    @pass_context
+    def data(ctx: Context, key: str) -> str:
+        """
+        Retrieve data associated with a key from the Jinja2 context.
+
+        Args:
+            ctx (Context): The Jinja2 context object.
+            key (str): The key for the data to be retrieved.
+
+        Returns:
+            str: The data associated with the key, or an empty string if not found.
+
+        This function accesses the Jinja2 context to fetch data stored under a specific key.
+        It ensures that the data is retrieved safely and returns an empty string if the key
+        does not exist in the context.
+        """
+        _sc_val = EnvironmentFactory._get_joop(ctx).get(_DATA_ROOT, {}).get(key, "")
+        return _sc_val

joop/web/view.py

@@ -0,0 +1,214 @@
+"""
+
+Views are how components are integrated with webservers. The view (or route) is defined
+    and established by this class.
+
+Classes:
+    View:
+        The base class for defining and managing views in the joop project.
+
+"""
+
+from typing import List, Callable, Type
+
+from joop.abstract import AbstractMethod
+from joop.http.methods import HttpMethod
+from joop.web.component import Component
+
+class View():
+    """
+    The base class for defining and managing views in the joop project.
+
+    This class provides methods for rendering components, managing inputs and
+    subcomponents, and integrating views with web frameworks.
+
+    Attributes:
+        _component_type (Type[Component]):
+            The type of the component associated with the view.
+
+        _args_to_inputs (bool):
+            Determines whether to automatically map arguments to component inputs.
+
+        _get_default_subs (bool):
+            Determines whether to automatically retrieve default subcomponents.
+
+        _as_response (bool):
+            Determines whether the view should render a response instead of a component.
+
+    Methods:
+        _get_inputs(**kwargs):
+            Retrieves the inputs for the component based on the provided keyword arguments.
+
+        _get_subs(**kwargs):
+            Retrieves the default subcomponents for the component.
+
+        render(**kwargs):
+            Renders the component and returns the rendered output as a string.
+
+        _add_to_app(app: object, view_func: Callable):
+            Abstract method to add the view to a web application.
+
+        add_to_app(app: object):
+            Adds the view to a web application with the specified configuration.
+
+        _get_jinja_env():
+            Abstract method to retrieve the Jinja2 environment.
+
+        get_jinja_env():
+            Retrieves the Jinja2 environment by calling the abstract method.
+    """
+
+    _component_type : Type[Component]
+
+    class Endpoint():
+        _url: str
+        _name : str
+        _methods : List[HttpMethod]
+
+    _args_to_inputs : bool = True
+    _get_default_subs : bool = True
+
+    '''
+    aliases might be added later
+    _arg_aliases : dict = {} # aliases might be added later
+
+    @classmethod
+    def _process_kwargs_aliases(cls, **kwargs):
+        # Rename the keys in kwargs based on the _arg_aliases mapping
+        for old_key, new_key in cls._arg_aliases.items():
+            if kwargs.get(old_key) is not None:
+                if new_key not in kwargs:
+                    kwargs[new_key] = kwargs[old_key]
+                    del(kwargs[old_key])
+                else:
+                    raise KeyError(f"Key conflict: '{new_key}' already exists in kwargs.")
+    '''
+
+    @classmethod
+    def _get_inputs(cls, **kwargs):
+        """
+        Retrieve the inputs for the component based on the provided keyword arguments.
+
+        Args:
+            **kwargs: Keyword arguments to be mapped to the component's inputs.
+
+        Returns:
+            Component.Inputs: The inputs for the component, or None if `_args_to_inputs` is False.
+        """
+        _res = None
+        if cls._args_to_inputs == True:
+            _res = cls._component_type.Inputs(**kwargs)
+            # cls._process_kwargs_aliases(**kwargs)
+        return _res
+    
+    @classmethod
+    def _get_subs(cls, **kwargs):
+        """
+        Retrieve the default subcomponents for the component.
+
+        Args:
+            **kwargs: Keyword arguments (not used in the default implementation).
+
+        Returns:
+            Component.SubComponents: The default subcomponents for the component, or None if `_get_default_subs` is False.
+        """
+        _res = None
+        if cls._get_default_subs == True:
+            _res = cls._component_type.SubComponents()
+        return _res
+
+
+    @classmethod
+    def render(cls, **kwargs):
+        """
+        Render the component and return the rendered output as a string.
+
+        Args:
+            **kwargs: Keyword arguments to be passed to the component's inputs and subcomponents.
+
+        Returns:
+            str: The rendered output of the component.
+        """
+        _component = cls._component_type()
+        _component.inputs = cls._get_inputs(**kwargs)
+        _component.subs = cls._get_subs()
+        return _component.render()
+
+    _as_response : bool = False
+
+    ''' To be implemented. For cases where specific response rendering logic is needed.
+    @classmethod
+    def render_response(cls, instance : 'View' = None, **kwargs):
+        if cls._template_name is None:
+            raise NotImplementedError("Abstract; not implemented")
+        
+        if instance is None:
+            instance = cls(req)
+        
+        rendered = cls.render_template(instance= instance, **kwargs)
+        return instance._site.make_response(rendered)
+    '''
+    
+    @classmethod
+    def _add_to_app(cls, app : object, view_func : Callable):
+        """
+        Abstract method to add the view to a web application.
+
+        Args:
+            app (object): The web application instance.
+            view_func (Callable): The view function to associate with the application.
+
+        Raises:
+            NotImplementedError: If the method is not implemented in a subclass.
+        """
+        raise NotImplementedError("Abstract; not implemented")
+    
+    _add_to_app = AbstractMethod(_add_to_app)
+    
+    @classmethod
+    def add_to_app(cls, app : object):
+        """
+        Add the view to a web application with the specified configuration.
+
+        This method validates the view's configuration and registers it with the
+        web application using the `_add_to_app` method.
+
+        Args:
+            app (object): The web application instance.
+
+        Raises:
+            NotImplementedError: If the view's configuration is incomplete or invalid.
+        """
+        if (cls.Endpoint._url is None or
+            cls.Endpoint._name is None or
+            cls.Endpoint._methods is None or
+            cls._component_type is None):
+            raise NotImplementedError("Abstract; not implemented")
+
+        view_func = cls.render
+        if cls._as_response == True:
+            view_func = cls.render_response
+
+        cls._add_to_app(app, view_func)
+
+    @classmethod
+    def _get_jinja_env(cls):
+        """
+        Abstract method to retrieve the Jinja2 environment.
+
+        Raises:
+            NotImplementedError: If the method is not implemented in a subclass.
+        """
+        raise NotImplementedError("Abstract; not implemented")
+    
+    _get_jinja_env = AbstractMethod(_get_jinja_env)
+
+    @classmethod
+    def get_jinja_env(cls):
+        """
+        Retrieve the Jinja2 environment by calling the abstract method.
+
+        Returns:
+            jinja2.Environment: The Jinja2 environment associated with the view.
+        """
+        return cls._get_jinja_env()