joop 0.0.1__py3-none-any.whl

joop/__init__.py

@@ -0,0 +1,9 @@
+"""Top-level Python package for joop."""
+
+__author__ = """Justin Rushin"""
+__version__ = '0.0.1'
+
+def hello_world():
+    """Prints "Hello World!" to the console.
+    """
+    print("Hello World!")

joop/abstract/README.md

@@ -0,0 +1,3 @@
+# Abstract Utilities
+
+This module provides utilities for abstract behavior, simplifying the creation of abstract methods and customization of dataclass behavior.

joop/abstract/__init__.py

@@ -0,0 +1,95 @@
+"""
+This module provides utilities for abstract behavior.
+
+Classes:
+    AbstractMethod: A descriptor to define abstract methods in classes, particularly useful with ABCMeta and dataclasses.
+
+Functions:
+    exclude_fields_from_my_init(cls, tgt_fields):
+        Modifies a dataclass to exclude specified fields from its `__init__` method.
+"""
+
+from typing import List, Any
+from dataclasses import field
+
+class AbstractMethod:
+    """
+    A descriptor for defining abstract methods in classes.
+
+    This class is particularly useful when working with ABCMeta classes and/or dataclasses.
+    It allows marking methods as abstract, ensuring that they must be overridden in subclasses.
+
+    Example usage:
+        @classmethod
+        def _my_abstract_class_method(cls, something: Any):
+            raise NotImplementedError("Abstract; not implemented")
+
+        _my_abstract_class_method = AbstractMethod(_my_abstract_class_method)
+
+    Attributes:
+        func (callable): The function to be marked as abstract.
+        _isabstract (bool): A flag indicating whether the method is abstract.
+    """
+
+    def __init__(self, func):
+        """
+        Initialize the AbstractMethod descriptor.
+
+        Args:
+            func (callable): The function to be marked as abstract.
+        """
+        self.func = func
+        self._isabstract = True  # Custom flag to mark as abstract
+
+    def __get__(self, instance, owner):
+        """
+        Bind the method to the class or instance.
+
+        Raises:
+            NotImplementedError: If the method is abstract and not overridden.
+
+        Returns:
+            callable: The bound method.
+        """
+        if self._isabstract:
+            raise NotImplementedError(f"The method {self.func.__name__} is abstract and must be overridden.")
+        return self.func.__get__(instance, owner)
+
+    @property
+    def __isabstractmethod__(self):
+        """
+        Check if the method is abstract.
+
+        Returns:
+            bool: True if the method is abstract, False otherwise.
+        """
+        return self._isabstract
+
+    @__isabstractmethod__.setter
+    def __isabstractmethod__(self, value):
+        """
+        Set the abstract status of the method.
+
+        Args:
+            value (bool): The new abstract status.
+        """
+        self._isabstract = value
+
+def exclude_fields_from_my_init(cls, tgt_fields: List[str]):
+    """
+    Exclude specified fields from the `__init__` method of a dataclass.
+
+    This function is intended to be called in the `__init_subclass__` class method
+    of a dataclass. It ensures that the fields with names in the provided list
+    are marked as non-init fields.
+
+    Args:
+        cls (type): The dataclass to modify.
+        tgt_fields (List[str]): A list of field names to exclude from the `__init__` method.
+
+    """
+    for _field_name in tgt_fields:
+        current_value = getattr(cls, _field_name, None)
+        if _field_name not in cls.__annotations__:
+            cls.__annotations__[_field_name] = Any
+        setattr(cls, _field_name, field(init=False, default=current_value))

joop/cli/README.md

@@ -0,0 +1,6 @@
+CLI featuring:
+* a builtin flask webserver, for automated and manual testing. Useful for development purposes.
+
+In an initiated shell (see main README), start with: 
+
+`python -m joop.cli --flask-server`

joop/cli/__init__.py

@@ -0,0 +1 @@
+from joop.cli.__main__ import main

joop/cli/__main__.py

@@ -0,0 +1,39 @@
+"""Console script for joop development and testing purposes.
+
+Includes:
+
+- A hello world for the CLI.
+- Start a Flask webserver for testing purposes using the `--flask-server` option.
+- Display a help menu with usage instructions using the `--help` or `-h` options.
+
+Usage:
+    - Run the CLI normally: `python -m joop.cli`
+    - Start the Flask webserver: `python -m joop.cli --flask-server`
+    - Display the help menu: `python -m joop.cli --help`
+
+"""
+import sys
+import click
+from joop.cli.test_flask import start_test_flask
+
+from joop import hello_world
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option('--flask-server', is_flag=True, help="Spin up a Flask webserver for testing.")
+def main(flask_server, args=None):
+    """Console script for joop.
+
+    Usage:
+      - Run the CLI normally: `python -m joop.cli`
+      - Start the Flask webserver: `python -m joop.cli --flask-server`
+      - Display the help menu: `python -m joop.cli --help`
+    """
+    if flask_server:
+        click.echo("Starting Flask webserver...")
+        start_test_flask()
+    else:
+        click.echo(hello_world())
+    return 0
+
+if __name__ == "__main__":
+    main()

joop/cli/test_flask.py

@@ -0,0 +1,36 @@
+"""Flask testing module for joop.
+
+This module provides functionality to start a Flask webserver for testing and development purposes.
+
+Important: The test joop env is set as the jinja env for the Flask server. This is specific and desirable
+    though your project may implement the environment otherwise.
+
+Functions:
+    start_test_flask():
+        Starts the Flask webserver in debug mode using the `app` instance from `joop.flask`.
+
+Dependencies:
+    - Flask: Ensure Flask is installed. If not, install it using `pip install joop[flask]`.
+
+Usage:
+    - Import the `start_test_flask` function and call it to start the Flask webserver.
+
+"""
+
+from joop.tests.test_templater import environment
+try:
+    from joop.flask import app
+
+    joop_env = environment
+
+
+    def start_test_flask():
+        global app
+
+        app.run(debug=True)
+
+except ImportError as e:
+    raise ImportError(
+        "The 'flask' module requires additional dependencies. "
+        "Install them using 'pip install joop[flask]'."
+    )

joop/dao/__init__.py

@@ -0,0 +1,151 @@
+"""Data Access Object (DAO) module for joop.
+
+This module provides abstract classes for creating Data Access Objects (DAOs) to manage
+Pydantic and SQLModel-based models. DAOs provide a layer of abstraction between the
+representation of the object (especially at the storage layer) and the business logic
+code that uses or manipulates the object.
+
+Classes:
+    DAO:
+        An abstract wrapper for a Pydantic model or any class derived from it.
+
+    SQLDAO:
+        An abstract class for SQL models, extending the DAO class.
+
+"""
+
+from typing import List, Type, Optional
+from dataclasses import dataclass
+import pydantic
+import sqlmodel
+
+class DAO():
+    """
+    An abstract wrapper for a Pydantic model or any class derived from it.
+
+    The DAO class provides methods to interact with the underlying model, including
+    converting it to a dictionary and retrieving its fields. It is typically constructed
+    around an existing model using the `from_model` method.
+
+    Attributes:
+        _modeltype (Type): The type of the model, defaulting to `pydantic.BaseModel`.
+
+    Properties:
+        model (pydantic.BaseModel): The underlying Pydantic model instance.
+
+    Methods:
+        from_model(model: pydantic.BaseModel) -> 'DAO':
+            Creates a DAO instance from a given Pydantic model.
+
+        to_dict() -> dict:
+            Converts the underlying model to a dictionary using aliases for field names.
+
+        get_model_fields() -> List[str]:
+            Retrieves the names of all fields defined in the `_modeltype`.
+    """
+
+    _modeltype : Type = pydantic.BaseModel
+
+    @property
+    def model(self) -> pydantic.BaseModel:
+        return self._model
+    
+    @model.setter
+    def model(self, value : pydantic.BaseModel):
+        self._model = value
+
+    @classmethod
+    def from_model(cls, model : pydantic.BaseModel) -> 'DAO':
+        if model is None:
+            return None
+        
+        if isinstance(type(model), cls._modeltype):
+            raise ("Invalid Model Supplied")
+        
+        res = cls()
+        res._model = model
+        return res
+    
+    def to_dict(self) -> dict:
+        """
+        Convert the underlying model to a dictionary, using aliases for field names.
+
+        Returns:
+            dict: A dictionary representation of the model with aliases as keys.
+
+        Raises:
+            ValueError: If no model is set for this DAO instance.
+            TypeError: If the model does not have Pydantic fields.
+        """
+        if not hasattr(self, '_model') or self._model is None:
+            raise ValueError("No model is set for this DAO instance.")
+        
+        # Ensure the model has the necessary fields and aliases
+        if not hasattr(self._model, '__fields__'):
+            raise TypeError("The model does not have Pydantic fields.")
+        
+        # Use SQLModel's/Pydantic basemodel's dict() method to get the base dictionary
+        base_dict = self._model.dict()
+        
+        # Build the dictionary using aliases
+        result = {}
+        for field_name, field in self._model.__fields__.items():
+            alias = field.alias or field_name  # Use alias if defined, otherwise fallback to field name
+            result[alias] = base_dict[field_name]
+        
+        return result
+    
+    @classmethod
+    def get_model_fields(cls) -> List[str]:
+        """
+        Get the names of all fields defined in the `_modeltype`.
+
+        Returns:
+            List[str]: A list of field names.
+
+        Raises:
+            TypeError: If `_modeltype` is not a subclass of `pydantic.BaseModel`.
+        """
+        if not issubclass(cls._modeltype, pydantic.BaseModel):
+            raise TypeError("_modeltype must be a subclass of pydantic.BaseModel")
+
+        res = [field.alias if field.alias else name for name, field in cls._modeltype.__fields__.items()]
+        return res
+
+class SQLDAO(DAO):
+    """
+    An abstract class for SQL models, extending the DAO class.
+
+    The SQLDAO class provides additional methods for interacting with SQLModel-based
+    models, such as retrieving all records from the database.
+
+    Attributes:
+        _modeltype (Type): The type of the model, defaulting to `sqlmodel.SQLModel`.
+
+    Methods:
+        get_all(session: sqlmodel.Session) -> List['SQLDAO']:
+            Retrieves all records from the database for the given model type and returns
+            them as a list of SQLDAO instances.
+    """
+
+    _modeltype : Type = sqlmodel.SQLModel
+
+    @classmethod
+    def get_all(cls, session: sqlmodel.Session) -> List['SQLDAO']:
+        """
+        Retrieve all records from the database for the given model type and return them as a list of SQLDAO instances.
+
+        Args:
+            session (sqlmodel.Session): The database session to use for the query.
+
+        Returns:
+            List[SQLDAO]: A list of SQLDAO instances for the model type.
+
+        Raises:
+            TypeError: If `_modeltype` is not a subclass of `sqlmodel.SQLModel`.
+        """
+        if not issubclass(cls._modeltype, sqlmodel.SQLModel):
+            raise TypeError("_modeltype must be a subclass of sqlmodel.SQLModel")
+
+        db_results = session.query(cls._modeltype).all()
+        return [cls.from_model(result) for result in db_results]

joop/flask/__init__.py

@@ -0,0 +1,31 @@
+"""Flask application initialization module for joop.
+
+This is used for example, development, and testing purposes.
+This module initializes a Flask application and configures it with the joop Jinja2 environment.
+That is important. ^^^ We are not using the default Jinja2 env, and that is intentional.
+This is the place to register example Flask views to the application.
+
+Attributes:
+    app (Flask): The Flask application instance.
+
+Modules:
+"""
+
+from __future__ import absolute_import
+from flask import Flask
+from joop.web.j_env import joop_env
+from joop.flask.example import (
+    FlaskHello, FlaskName, FlaskTablePage
+)
+
+app = Flask(__name__)
+
+# Configure the Jinja2 environment for the Flask application
+# Important to do this and not use the default.
+app.jinja_env = joop_env
+
+# Register example views to the Flask application
+# ex. MyView.add_to_app(app)
+FlaskHello.add_to_app(app)
+FlaskName.add_to_app(app)
+FlaskTablePage.add_to_app(app)

joop/flask/example.py

@@ -0,0 +1,19 @@
+"""
+
+This is the default place to turn example or other View definitions into
+    flask-specific views.
+"""
+
+from joop.web.examples.view import (
+    NameView, HelloView
+)
+
+from joop.web.examples.table import MyTableWholePage
+
+from joop.flask.flask_view import FlaskView
+
+class FlaskHello(HelloView, FlaskView): pass
+
+class FlaskName(NameView, FlaskView): pass
+
+class FlaskTablePage(MyTableWholePage, FlaskView): pass

joop/flask/flask_view.py

@@ -0,0 +1,71 @@
+"""Flask view integration for joop.
+
+This module provides a base class for integrating joop views with Flask applications.
+
+Any regular joop View can do multiple inheritance with a FlaskView to result
+    in a class that can be used with Flask.
+
+Functionality include jinja env proxying.
+
+Classes:
+    FlaskView:
+        A base class for creating Flask-compatible views from joop View classes.
+"""
+
+from typing import Optional
+from flask import Flask, current_app
+
+from joop.web.view import View, Component
+
+class FlaskView(View):
+    """
+    A base class for creating Flask-compatible views from joop View classes.
+
+    This class provides methods to integrate joop views with Flask applications by
+    adding URL rules and accessing the Flask Jinja2 environment.
+
+    Use multiple inheritance to make your View a FlaskView ex.
+
+    `class FlaskHello(HelloView, FlaskView):`
+
+
+    Methods:
+        _add_to_app(app: Flask, view_func: callable):
+            Adds the view to a Flask application with the specified view function.
+
+        _get_jinja_env():
+            Retrieves the Jinja2 environment from the current Flask application context.
+    """
+
+    @classmethod
+    def _add_to_app(cls, app: Flask, view_func: callable):
+        """
+        Add the view to a Flask application with the specified view function.
+
+        Args:
+            app (Flask): The Flask application instance.
+            view_func (callable): The view function to associate with the URL rule.
+
+        This method registers a URL rule with the Flask application, associating it
+        with the specified view function and HTTP methods defined in the Endpoint.
+        """
+        app.add_url_rule(
+            rule=cls.Endpoint._url,  # URL rule as a string
+            endpoint=cls.Endpoint._name,  # Endpoint name
+            view_func=view_func,  # The view function to call
+            methods=cls.Endpoint._methods  # List of HTTP methods allowed
+        )
+    
+    @classmethod
+    def _get_jinja_env(cls):
+        """
+        Retrieve the Jinja2 environment from the current Flask application context.
+
+        Returns:
+            jinja2.Environment: The Jinja2 environment associated with the current
+            Flask application context.
+
+        This method allows joop views to access the Jinja2 environment configured
+        for the Flask application.
+        """
+        return current_app.jinja_env

joop/http/methods.py

@@ -0,0 +1,49 @@
+"""HTTP Methods Enumeration Module.
+
+joop uses its own HTTP method enum implementation for compatibility purposes with
+older versions of python, to provide a standardized way to
+represent and describe HTTP methods.
+
+Classes:
+    HttpMethod:
+        An enumeration of HTTP methods, each with a corresponding description.
+
+        Methods:
+            description() -> str:
+                Returns a description of the HTTP method.
+
+Usage:
+    - Use `HttpMethod` to refer to HTTP methods in a type-safe manner.
+    - Call the `description` method on an `HttpMethod` instance to get its description.
+
+"""
+
+from enum import Enum
+
+class HttpMethod(str, Enum):  # Changed from StrEnum to str + Enum for Python 3.10 compatibility
+    """Enumeration of HTTP methods with their descriptions."""
+
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    DELETE = "DELETE"
+    PATCH = "PATCH"
+    OPTIONS = "OPTIONS"
+    HEAD = "HEAD"
+    TRACE = "TRACE"
+    CONNECT = "CONNECT"
+
+    def description(self) -> str:
+        """Return a description of the HTTP method."""
+        descriptions = {
+            "GET": "Retrieve data from the server.",
+            "POST": "Submit data to the server.",
+            "PUT": "Update or create a resource on the server.",
+            "DELETE": "Delete a resource on the server.",
+            "PATCH": "Apply partial modifications to a resource.",
+            "OPTIONS": "Describe the communication options for the target resource.",
+            "HEAD": "Retrieve metadata about the resource without the body.",
+            "TRACE": "Perform a message loop-back test along the path to the target resource.",
+            "CONNECT": "Establish a tunnel to the server identified by the target resource."
+        }
+        return descriptions[self.value]

joop/tests/__init__.py

@@ -0,0 +1,5 @@
+"""Test suite catalog."""
+
+# from joop.tests.test_joop import TestJoop
+from joop.tests.test_web import TestHTMLComponent
+from joop.tests.test_view import TestView

joop/tests/test_joop.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python
+
+"""High-level test suite. Currently, verifies that the CLI works.."""
+
+
+import unittest
+from click.testing import CliRunner
+
+from joop.cli import main
+
+
+class TestJoop(unittest.TestCase):
+    """Tests for `joop` package."""
+
+    def setUp(self):
+        """Set up test fixtures, if any."""
+
+    def tearDown(self):
+        """Tear down test fixtures, if any."""
+
+    def test_001_command_line_interface(self):
+        """Test the CLI."""
+        runner = CliRunner()
+        result = runner.invoke(main)
+        assert result.exit_code == 0
+        assert 'Hello World' in result.output
+        help_result = runner.invoke(main, ['--help'])
+        assert help_result.exit_code == 0
+        assert '--help      Show this message and exit.' in help_result.output

joop/tests/test_templater.py

@@ -0,0 +1,31 @@
+"""Templater testing module for joop.
+
+This module instantiates a jinja templating engine for development and testing purposes.
+    It's not just restricted to automated testing.
+
+Classes:
+    BaseTestHTMLComponent:
+        A base class for testing HTML components.
+
+Variables:
+    environment:
+        A placeholder variable for the templating environment.
+
+Usage:
+    - Utilize the `environment` variable for templating-related operations.
+
+"""
+
+from joop.web.templater import EnvironmentFactory
+from jinja2 import FileSystemLoader
+from joop.web.j_env import set_joop_env
+
+from pathlib import Path
+
+WEB_TEMPLATES_ROOT = Path("../templates/examples/")
+
+environment = EnvironmentFactory.create_environment(
+        loader=FileSystemLoader(WEB_TEMPLATES_ROOT)
+    )
+
+set_joop_env(environment)

joop/tests/test_view.py

@@ -0,0 +1,46 @@
+"""Unit tests for joop Flask integration.
+
+This module contains unit tests for the Flask views in the joop project. It uses the
+unittest framework and Flask's test_client to test the functionality of the views.
+
+It borders on being an integration test, insofar as we are testing:
+* joop's views
+* joop's templater
+* joop's flask integration
+
+Classes:
+    TestView:
+        Test cases for the Flask views in the joop application.
+
+"""
+
+import unittest
+
+try:
+    from joop.flask import app
+    APP_AVAILABLE = app is not None
+except ImportError:
+    APP_AVAILABLE = False
+
+@unittest.skipIf(not APP_AVAILABLE, "joop.flask or app is not available")
+class TestView(unittest.TestCase):
+    """
+    Test cases for the Flask views in the joop application.
+
+    This test class uses the Flask test client to send requests to the application
+    and verify the responses.
+
+    Methods:
+        setUp():
+            Sets up the test client for the Flask application.
+
+        test_000_hello():
+            Tests the '/hello' endpoint to ensure it returns a 200 status code.
+    """
+
+    def setUp(self):
+                self.client = app.test_client()
+
+    def test_000_hello(self):
+        response = self.client.get('/hello') 
+        self.assertEqual(response.status_code, 200)