velocity-python 0.0.31__py3-none-any.whl → 0.0.32__py3-none-any.whl

velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.0.31"
+__version__ = version = "0.0.32"
 
 from . import aws
 from . import db

velocity/aws/handlers/response.py

@@ -1,17 +1,20 @@
-from velocity.misc.format import to_json
 import sys
 import traceback
+from typing import Any, Dict, List, Optional, Union
+from velocity.misc.format import to_json
 from support.app import DEBUG
 
 
-variants = ["success", "error", "warning", "info"]
+class Response:
+    """Class to manage and structure HTTP responses with various actions and custom headers."""
 
+    VALID_VARIANTS = {"success", "error", "warning", "info"}
 
-class Response:
     def __init__(self):
-        self.actions = []
-        self.body = {"actions": self.actions}
-        self.raw = {
+        """Initialize the Response object with default status, headers, and an empty actions list."""
+        self.actions: List[Dict[str, Any]] = []
+        self.body: Dict[str, Any] = {"actions": self.actions}
+        self.raw: Dict[str, Any] = {
             "statusCode": 200,
             "body": "{}",
             "headers": {
@@ -22,118 +25,266 @@ class Response:
             },
         }
 
-    def render(self):
+    def render(self) -> Dict[str, Any]:
+        """
+        Finalize the response body as JSON and return the complete response dictionary.
+
+        Returns:
+            Dict[str, Any]: The complete HTTP response with headers, status code, and JSON body.
+        """
         self.raw["body"] = to_json(self.body)
         return self.raw
 
-    def alert(self, message, title="Notification"):
+    def alert(self, message: str, title: str = "Notification") -> "Response":
+        """
+        Add an alert action to the response.
+
+        Args:
+            message (str): The alert message.
+            title (str): Title for the alert. Defaults to "Notification".
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
         self.actions.append(
             {
                 "action": "alert",
-                "payload": {
-                    "title": title,
-                    "message": message,
-                },
+                "payload": {"title": title, "message": message},
             }
         )
         return self
 
-    def toast(self, message, variant="success"):
+    def toast(self, message: str, variant: str = "success") -> "Response":
+        """
+        Add a toast notification action to the response with a specified variant.
+
+        Args:
+            message (str): The message to display in the toast.
+            variant (str): The style variant of the toast (e.g., "success", "error"). Must be one of VALID_VARIANTS.
+
+        Raises:
+            ValueError: If the variant is not one of VALID_VARIANTS.
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
         variant = variant.lower()
-        if variant not in variants:
-            raise Exception(f"Notistack variant {variant} not in {variants}")
+        if variant not in self.VALID_VARIANTS:
+            raise ValueError(
+                f"Notistack variant '{variant}' not in {self.VALID_VARIANTS}"
+            )
         self.actions.append(
             {
                 "action": "toast",
-                "payload": {
-                    "options": {
-                        "variant": variant,
-                    },
-                    "message": message,
-                },
+                "payload": {"options": {"variant": variant}, "message": message},
             }
         )
         return self
 
-    def load_object(self, payload):
+    def load_object(self, payload: Dict[str, Any]) -> "Response":
+        """
+        Add a load-object action to the response with a specified payload.
+
+        Args:
+            payload (Dict[str, Any]): The data to load into the response.
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
         self.actions.append({"action": "load-object", "payload": payload})
         return self
 
-    def update_store(self, payload):
+    def update_store(self, payload: Dict[str, Any]) -> "Response":
+        """
+        Add an update-store action to the response with a specified payload.
+
+        Args:
+            payload (Dict[str, Any]): The data to update the store with.
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
         self.actions.append({"action": "update-store", "payload": payload})
         return self
 
-    def file_download(self, payload):
+    def file_download(self, payload: Dict[str, Any]) -> "Response":
+        """
+        Add a file-download action to the response with a specified payload.
+
+        Args:
+            payload (Dict[str, Any]): The data for file download details.
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
         self.actions.append({"action": "file-download", "payload": payload})
         return self
 
-    def status(self, code=None):
-        if code:
+    def status(self, code: Optional[int] = None) -> int:
+        """
+        Get or set the status code of the response.
+
+        Args:
+            code (Optional[int]): The HTTP status code to set. If None, returns the current status code.
+
+        Returns:
+            int: The current status code.
+        """
+        if code is not None:
             self.raw["statusCode"] = int(code)
         return self.raw["statusCode"]
 
-    def headers(self, headers=None):
+    def headers(self, headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        """
+        Get or update the headers of the response.
+
+        Args:
+            headers (Optional[Dict[str, str]]): A dictionary of headers to add or update.
+
+        Returns:
+            Dict[str, str]: The current headers after updates.
+        """
         if headers:
-            new = {}
-            for key in headers.keys():
-                new["-".join(w.capitalize() for w in key.split("-"))] = headers[key]
-            self.raw["headers"].update(new)
+            formatted_headers = {
+                self._format_header_key(k): v for k, v in headers.items()
+            }
+            self.raw["headers"].update(formatted_headers)
         return self.raw["headers"]
 
-    def set_status(self, code):
+    def set_status(self, code: int) -> "Response":
+        """
+        Set the HTTP status code of the response.
+
+        Args:
+            code (int): The status code to set.
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
         self.status(code)
         return self
 
-    def set_headers(self, headers):
+    def set_headers(self, headers: Dict[str, str]) -> "Response":
+        """
+        Set custom headers for the response.
+
+        Args:
+            headers (Dict[str, str]): The headers to add or update.
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
         self.headers(headers)
         return self
 
-    def set_body(self, body):
+    def set_body(self, body: Dict[str, Any]) -> "Response":
+        """
+        Update the body of the response with new data.
+
+        Args:
+            body (Dict[str, Any]): The body data to update.
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
         self.body.update(body)
         return self
 
-    def exception(self):
-        t, v, tb = sys.exc_info()
+    def exception(self) -> None:
+        """
+        Capture and format the current exception details and set a 500 status code.
+        Includes traceback information if DEBUG mode is enabled.
+        """
+        exc_type, exc_value, tb = sys.exc_info()
         self.set_status(500)
         self.set_body(
             {
                 "python_exception": {
-                    "type": str(t),
-                    "value": str(v),
+                    "type": str(exc_type),
+                    "value": str(exc_value),
                     "traceback": traceback.format_exc() if DEBUG else None,
                     "tb": traceback.format_tb(tb) if DEBUG else None,
                 }
             }
         )
 
-    def console(self, message, title="Notification"):
+    def console(self, message: str, title: str = "Notification") -> "Response":
+        """
+        Add a console log action to the response.
+
+        Args:
+            message (str): The console message.
+            title (str): Title for the console message. Defaults to "Notification".
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
         self.actions.append(
             {
                 "action": "console",
-                "payload": {
-                    "title": title,
-                    "message": message,
-                },
+                "payload": {"title": title, "message": message},
             }
         )
         return self
 
-    def redirect(self, location):
+    def redirect(self, location: str) -> "Response":
+        """
+        Add a redirect action to the response with the target location.
+
+        Args:
+            location (str): The URL to redirect to.
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
         self.actions.append({"action": "redirect", "payload": {"location": location}})
         return self
 
-    def signout(self, location):
-        self.actions.append(
-            {
-                "action": "signout",
-            }
-        )
+    def signout(self) -> "Response":
+        """
+        Add a signout action to the response.
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
+        self.actions.append({"action": "signout"})
         return self
 
-    def set_table(self, payload):
+    def set_table(self, payload: Dict[str, Any]) -> "Response":
+        """
+        Add a set-table action to the response with the specified payload.
+
+        Args:
+            payload (Dict[str, Any]): The table data to set.
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
         self.actions.append({"action": "set-table", "payload": payload})
         return self
 
-    def set_repo(self, payload):
+    def set_repo(self, payload: Dict[str, Any]) -> "Response":
+        """
+        Add a set-repo action to the response with the specified payload.
+
+        Args:
+            payload (Dict[str, Any]): The repository data to set.
+
+        Returns:
+            Response: The current Response object, allowing method chaining.
+        """
         self.actions.append({"action": "set-repo", "payload": payload})
         return self
+
+    @staticmethod
+    def _format_header_key(key: str) -> str:
+        """
+        Format HTTP headers to be in a title-cased format.
+
+        Args:
+            key (str): The header key to format.
+
+        Returns:
+            str: The formatted header key.
+        """
+        return "-".join(word.capitalize() for word in key.split("-"))

velocity/misc/conv/iconv.py

@@ -1,32 +1,33 @@
+# iconv.py
 import re
 import codecs
-import decimal as _decimal
+from decimal import Decimal, ROUND_HALF_UP
 from email.utils import parseaddr
 from datetime import datetime
+from typing import Optional, Union, Callable
 
+# Convert data to SQL format for storage
 
-def none(data):
-    if data == "":
-        return None
-    if data == "null":
-        return None
-    if data == "@NULL":
-        return None
-    return data
+
+def none(data: str) -> Optional[str]:
+    """Converts various 'null' representations to None."""
+    return None if data in ("", "null", "None", "@NULL") else data
 
 
-def phone(data):
-    if data == "None":
+def phone(data: str) -> Optional[str]:
+    """Extracts a 10-digit phone number or returns None if invalid."""
+    if data in ("None", None):
         return None
-    if not data:
-        return data
-    return re.search(r"\d{10}$", re.sub("[^0-9]", "", data)).group()
+    cleaned_data = re.sub(r"[^0-9]", "", data)
+    match = re.search(r"\d{10}$", cleaned_data)
+    return match.group() if match else None
 
 
-def day_of_week(data):
+def day_of_week(data: str) -> Optional[int]:
+    """Converts day of the week to an integer representation."""
     if not data:
-        return data
-    return {
+        return None
+    days = {
         "monday": 1,
         "tuesday": 2,
         "wednesday": 3,
@@ -41,174 +42,137 @@ def day_of_week(data):
         "fri": 5,
         "sat": 6,
         "sun": 7,
-    }[data.lower()]
-
+    }
+    return days.get(data.lower())
 
-def date(*args, **kwds):
-    kwds.setdefault("fmt", "%Y-%m-%d")
 
-    def _(param):
-        if isinstance(param, str):
-            return datetime.strptime(param, kwds["fmt"]).date()
-        else:
-            return param
-
-    if args and args[0]:
-        return _(args[0])
-    return _
+def date(data: str, fmt: str = "%Y-%m-%d") -> Optional[datetime.date]:
+    """Parses a date string into a date object using the specified format."""
+    try:
+        return datetime.strptime(data, fmt).date()
+    except (ValueError, TypeError):
+        return None
 
 
-def time(*args, **kwds):
-    kwds.setdefault("fmt", "%X")
+def time(data: str, fmt: str = "%X") -> Optional[datetime.time]:
+    """Parses a time string into a time object using the specified format."""
+    try:
+        return datetime.strptime(data, fmt).time()
+    except (ValueError, TypeError):
+        return None
 
-    def _(param):
-        if isinstance(param, str):
-            return datetime.strptime(param, kwds["fmt"]).time()
-        else:
-            return param
 
-    if args and args[0]:
-        return _(args[0])
-    return _
+def timestamp(data: str, fmt: str = "%c") -> Optional[datetime]:
+    """Parses a timestamp string into a datetime object using the specified format."""
+    try:
+        return datetime.strptime(data, fmt)
+    except (ValueError, TypeError):
+        return None
 
 
-def timestamp(*args, **kwds):
-    kwds.setdefault("fmt", "%c")
+def email(data: str) -> Optional[str]:
+    """Validates and returns an email address if properly formatted."""
+    if not data or data.lower() == "none":
+        return None
+    data = data.strip().lower()
+    email_address = parseaddr(data)[1]
+    if "@" in email_address and "." in email_address.split("@")[1]:
+        return email_address
+    raise ValueError("Invalid email format")
 
-    def _(param):
-        if isinstance(param, str):
-            return datetime.strptime(param, kwds["fmt"])
-        else:
-            return param
 
-    if args and args[0]:
-        return _(args[0])
-    return _
+def integer(data: str) -> int:
+    """Converts a string to an integer, removing non-numeric characters."""
+    return int(re.sub(r"[^0-9\.-]", "", data))
 
 
-def email(data):
-    if not data:
-        return None
-    if data == "None":
-        return None
-    data = data.strip().lower()
-    if "@" not in data:
-        raise Exception()
-    email = parseaddr(data)[1]
-    mailbox, domain = email.split("@")
-    if "." in domain:
-        if len(domain.split(".")[1]) < 1:
-            raise Exception()
-    else:
-        raise Exception()
-    return data
-
-
-def integer(data):
-    return int(re.sub("[^0-9\.-]", "", str(data)))
-
-
-def boolean(data):
-    if isinstance(data, str):
-        if data.lower() in ["false", "", "f", "off", "no"]:
-            return False
+def boolean(data: Union[str, bool]) -> bool:
+    """Converts various string representations to a boolean."""
+    if isinstance(data, str) and data.lower() in ["false", "", "f", "off", "no"]:
+        return False
     return bool(data)
 
 
-def rot13(data):
+def rot13(data: str) -> str:
+    """Encodes a string using ROT13."""
     return codecs.encode(data, "rot13")
 
 
-def pointer(data):
-    if data == "@new":
-        return data
-    if data == "":
-        return None
-    if data == None:
-        return None
-    if data == "@NULL":
+def pointer(data: Union[str, None]) -> Optional[int]:
+    """Converts a pointer to an integer, or returns None for null values."""
+    if data in ("@new", "", "@NULL", None):
         return None
     return int(data)
 
 
-def money(data):
-    if data == "None":
+def money(data: str) -> Optional[Decimal]:
+    """Converts a monetary string to a Decimal, removing non-numeric characters."""
+    if data in ("None", None):
         return None
-    if not data:
-        return data
-    return _decimal.Decimal(re.sub("[^0-9\.-]", "", str(data)))
+    return Decimal(re.sub(r"[^0-9\.-]", "", data))
+
 
+def round_to(
+    precision: int, data: Optional[Union[str, float, Decimal]] = None
+) -> Union[Decimal, Callable[[Union[str, float, Decimal]], Decimal]]:
+    """Rounds a number to a specified precision."""
 
-def round(precision, data=None):
-    def function(data):
-        if data == "None":
+    def function(value):
+        if value in ("None", None):
             return None
-        if not data:
-            return data
-        if isinstance(data, str):
-            data = re.sub("[^0-9\.-]", "", data)
-        return _decimal.Decimal(data).quantize(
-            _decimal.Decimal(10) ** -precision, rounding=_decimal.ROUND_HALF_UP
+        if isinstance(value, str):
+            value = re.sub(r"[^0-9\.-]", "", value)
+        return Decimal(value).quantize(
+            Decimal(10) ** -precision, rounding=ROUND_HALF_UP
         )
 
-    if data == None:
-        return function
-    return function(data)
+    return function(data) if data is not None else function
 
 
-def decimal(data):
-    if data == "None":
+def decimal(data: str) -> Optional[Decimal]:
+    """Converts a numeric string to a Decimal, removing non-numeric characters."""
+    if data in ("None", None):
         return None
-    if not data:
-        return data
-    return _decimal.Decimal(re.sub("[^0-9\.-]", "", str(data)))
+    return Decimal(re.sub(r"[^0-9\.-]", "", data))
 
 
-def ein(data):
-    if data == "None":
+def ein(data: str) -> Optional[str]:
+    """Validates and returns a 9-digit EIN, or None if invalid."""
+    if data in ("None", None):
         return None
-    if not data:
-        return data
-    return re.search(r"^\d{9}$", re.sub("[^0-9]", "", data)).group()
+    cleaned_data = re.sub(r"[^0-9]", "", data)
+    match = re.fullmatch(r"\d{9}", cleaned_data)
+    return match.group() if match else None
 
 
-def list(data):
+def to_list(data: Union[str, list]) -> Optional[list]:
+    """Converts a string or single element into a list representation."""
     if data in (None, "None"):
         return None
-    if isinstance(data, str):
-        if data[0] == "[":
-            return data
-    if not isinstance(data, list):
-        data = [data]
-    return repr(data)
+    if isinstance(data, str) and data.startswith("["):
+        return eval(data)  # Assuming the input string is a list string
+    return [data] if not isinstance(data, list) else data
+
 
+def title(data: str) -> str:
+    """Converts a string to title case."""
+    return "" if data in (None, "None") else str(data).title()
 
-def title(data):
-    if data == None:
-        return ""
-    if data == "None":
-        return ""
-    return str(data).title()
 
+def lower(data: str) -> str:
+    """Converts a string to lowercase."""
+    return "" if data in (None, "None") else str(data).lower()
 
-def lower(data):
-    if data == None:
-        return ""
-    if data == "None":
-        return ""
-    return str(data).lower()
 
+def upper(data: str) -> str:
+    """Converts a string to uppercase."""
+    return "" if data in (None, "None") else str(data).upper()
 
-def upper(data):
-    if data == None:
-        return ""
-    if data == "None":
-        return ""
-    return str(data).upper()
 
+def padding(length: int, char: str = " ") -> Callable[[str], Optional[str]]:
+    """Pads a string to the specified length with a given character."""
 
-def padding(length, char):
-    def inner(data):
+    def inner(data: str) -> Optional[str]:
         if data in [None, "None", ""]:
             return None
         return str(data).rjust(length, char)
@@ -216,7 +180,6 @@ def padding(length, char):
     return inner
 
 
-def string(data):
-    if data == "":
-        return None
-    return str(data)
+def string(data: str) -> Optional[str]:
+    """Converts an empty string to None, otherwise returns the string itself."""
+    return None if data == "" else str(data)