DataOpsHub 6.2.0__py3-none-any.whl

DataOpsHub/data_entry_forms/validators/form_field_validations.py

@@ -0,0 +1,513 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Full-Stack Form Field Validation Module
+
+This module provides comprehensive validation functionality for form fields in full-stack applications.
+It combines backend-oriented validation with frontend-friendly features for user registration and other forms.
+"""
+
+#----------------#
+# Import modules # 
+#----------------#
+
+from email_validator import validate_email, EmailNotValidError
+
+#------------------------#
+# Import project modules #
+#------------------------#
+
+from DataOpsHub import (
+    INVALID_AGE_ERROR,
+    INVALID_DATE_FORMAT_ERROR,
+    INVALID_DATE_RANGE_ERROR,
+    INVALID_DATE_RANGE_FORMAT_ERROR,
+    INVALID_EMAIL_ERROR,
+    INVALID_FIRST_NAME_ERROR,
+    INVALID_FIRST_SURNAME_ERROR,
+    INVALID_ID_FORMAT_ERROR,
+    INVALID_ID_TYPE_ERROR,
+    INVALID_PASSWORD_ERROR,
+    INVALID_SECOND_SURNAME_ERROR,
+    INVALID_TEL_ERROR,
+    INVALID_TEL_SEARCH_VALUE,
+    MISSING_DATE_VALUES_ERROR,
+    USER_EXISTS_ERROR
+)
+
+from pygenutils.strings.string_handler import find_substring_index
+from pygenutils.time_handling.time_formatters import parse_time_string
+
+#------------------#
+# Define functions #
+#------------------#
+
+# General validation functions #
+#------------------------------#
+
+def validate_field(field_name, field_value, reg_exp_dict, err_str_list):
+    """
+    Validates a field based on the provided regular expression and error string.
+
+    Parameters
+    ----------
+    field_name : str
+        The name of the field being validated.
+    field_value : str
+        The value of the field to validate.
+    reg_exp_dict : dict
+        A dictionary of field names and their corresponding regular expressions.
+    err_str_list : list
+        A list of error messages corresponding to the fields.
+    
+    Returns
+    -------
+    dict
+        A dictionary with `has_error` (bool) and `error_msg` (str).
+    """
+    # Special handling for complex validations
+    if field_name == FIELD_NAME_LIST_ENG[0]:  # email
+        return validate_email_field(field_value)
+    elif field_name == FIELD_NAME_LIST_ENG[-1]:  # age
+        return validate_age_field(field_value)
+    elif field_name == 'id':  # ID validation
+        return validate_id_field(field_value, INVALID_ID_FORMAT_ERROR, INVALID_ID_TYPE_ERROR)
+    
+    # Default validation using regular expressions
+    has_error = find_substring_index(
+        field_value.strip() if field_name != FIELD_NAME_LIST_ENG[4] else field_value,
+        reg_exp_dict[field_name],
+        advanced_search=True
+    ) == -1
+    
+    error_msg = err_str_list[FIELD_NAME_LIST_ENG.index(field_name)] if has_error else ""
+    return {"has_error": has_error, "error_msg": error_msg}
+
+
+def generate_error_dict(request_form, reg_exp_dict, err_str_list):
+    """
+    Generates an error dictionary for all form fields.
+
+    Parameters
+    ----------
+    request_form : dict
+        A dictionary containing form field data (usually from Flask `request.form`).
+    reg_exp_dict : dict
+        A dictionary of field names and their corresponding regular expressions.
+    err_str_list : list
+        A list of error messages corresponding to the fields.
+    
+    Returns
+    -------
+    dict
+        A dictionary where each key is a field name and each value contains
+        `has_error` (bool) and `error_msg` (str).
+    """
+    return {
+        field_name: validate_field(
+            field_name,
+            request_form.get(field_name),
+            reg_exp_dict,
+            err_str_list,
+        )
+        for field_name in FIELD_NAME_LIST_ENG
+    }
+
+
+def generate_error_dict_nonempty(request_form, reg_exp_dict, err_str_list, exclude_fields=None):
+    """
+    Generates an error dictionary for all non-empty form fields.
+
+    Parameters
+    ----------
+    request_form : dict
+        A dictionary containing form field data (usually from Flask `request.form`).
+    reg_exp_dict : dict
+        A dictionary of field names and their corresponding regular expressions.
+    err_str_list : list
+        A list of error messages corresponding to the fields.
+    exclude_fields : list
+        A list of field names to exclude from validation.
+
+    Returns
+    -------
+    dict
+        A dictionary where each key is a field name and each value contains
+        `has_error` (bool) and `error_msg` (str).
+    """
+    if exclude_fields is None:
+        exclude_fields = []
+    elif exclude_fields and not isinstance(exclude_fields, list):
+        exclude_fields = [exclude_fields]
+
+    err_dict = {
+        field_name: validate_field(
+            field_name,
+            request_form.get(field_name),
+            reg_exp_dict,
+            err_str_list,
+        )
+        for field_name in FIELD_NAME_LIST_ENG 
+        if request_form.get(field_name) and field_name not in exclude_fields
+    }
+    return err_dict
+
+
+# Specific validation functions #
+#------------------------------#
+
+def verify_spanish_dni(dni: str) -> bool:
+    """
+    Verify the validity of a Spanish DNI (Documento Nacional de Identidad).
+    
+    Parameters
+    ----------
+    dni : str
+        The DNI (ID card) to be verified.
+        
+    Returns
+    -------
+    bool
+        True if the DNI is valid, False otherwise.
+    """
+    if len(dni) != 9:
+        return False
+
+    digits = dni[:-1]
+    control_letter = dni[-1].upper()
+
+    if not digits.isdigit():
+        return False
+
+    letters = "TRWAGMYFPDXBNJZSQVHLCKE"
+    calculated_letter = letters[int(digits) % 23]
+
+    return calculated_letter == control_letter
+
+def validate_id_field(value, invalid_val_err_str, empty_val_err_str):
+    """
+    Validate if the ID follows the required format (3-10 characters, alphanumeric with hyphens).
+
+    Parameters
+    ----------
+    value : str
+        The ID value to validate.
+    invalid_val_err_str : str
+        The error message for invalid ID format.
+    empty_val_err_str : str
+        The error message for empty ID values.
+
+    Returns
+    -------
+    dict
+        A dictionary with the error message, if any, stored under the key `error_msg` (str).
+    """
+    try:
+        if not isinstance(value, str):
+            return {"error_msg": empty_val_err_str}
+        
+        # First check if it's a Spanish DNI
+        if len(value) == 9 and value[-1].isalpha():
+            if not verify_spanish_dni(value):
+                return {"error_msg": invalid_val_err_str}
+            return {"error_msg": ""}
+        
+        # If not a DNI, check the standard ID pattern
+        pattern_match_index = find_substring_index(value, ID_PATTERN, advanced_search=True)
+        if pattern_match_index == -1:
+            return {"error_msg": invalid_val_err_str}
+            
+        return {"error_msg": ""}
+    except (ValueError, TypeError):
+        return {"error_msg": empty_val_err_str}
+
+def validate_date_range(min_value, max_value):
+    """
+    Validate date range values, always including both edges of the range.
+
+    Parameters
+    ----------
+    min_value : str
+        Start date in format 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM'.
+        If only date is provided, time defaults to 00:00.
+    max_value : str
+        End date in format 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM'.
+        If only date is provided, time defaults to 23:59.
+
+    Returns
+    -------
+    dict
+        A dictionary with the error message, if any, stored under the key `error_msg` (str).
+        If multiple errors are found, they will be combined with semicolons.
+    """
+    errors = []
+    min_date = None
+    max_date = None
+    min_value_error = False
+    max_value_error = False
+    
+    # Try parsing min_value
+    try:
+        # Try parsing with time first
+        try:
+            min_date = parse_time_string(min_value, '%Y-%m-%d %H:%M')
+        except ValueError:
+            # If that fails, try date-only format and set time to 00:00
+            try:
+                min_date = parse_time_string(min_value, '%Y-%m-%d')
+                min_date = min_date.replace(hour=0, minute=0)
+            except ValueError:
+                min_value_error = True
+    except Exception:
+        min_value_error = True
+    
+    # Try parsing max_value
+    try:
+        # Try parsing with time first
+        try:
+            max_date = parse_time_string(max_value, '%Y-%m-%d %H:%M')
+        except ValueError:
+            # If that fails, try date-only format and set time to 23:59
+            try:
+                max_date = parse_time_string(max_value, '%Y-%m-%d')
+                max_date = max_date.replace(hour=23, minute=59)
+            except ValueError:
+                max_value_error = True
+    except Exception:
+        max_value_error = True
+    
+    # Create consolidated error messages for date format issues
+    if min_value_error and max_value_error:
+        errors.append(f"Invalid date format for min_value and max_value. {INVALID_DATE_FORMAT_ERROR}")
+    elif min_value_error:
+        errors.append(f"Invalid date format for min_value: '{min_value}'. {INVALID_DATE_FORMAT_ERROR}")
+    elif max_value_error:
+        errors.append(f"Invalid date format for max_value: '{max_value}'. {INVALID_DATE_FORMAT_ERROR}")
+    
+    # If both dates are valid, check if min_date is greater than max_date
+    if min_date and max_date and min_date > max_date:
+        errors.append(INVALID_DATE_RANGE_ERROR)
+    
+    # Return all errors at once if any were found
+    if errors:
+        return {"error_msg": "; ".join(errors)}
+
+    return {"error_msg": ""}
+
+def validate_email_field(email):
+    """
+    Validates and normalizes an email address.
+
+    Parameters
+    ----------
+    email: str
+        The email address to validate.
+    
+    Returns
+    -------
+    dict
+        A dictionary with `has_error` (bool) and `error_msg` (str).
+    """
+    try:
+        validate_email(email)
+        return {"has_error": False, "error_msg": ""}
+    except EmailNotValidError as e:
+        return {"has_error": True, "error_msg": f"{INVALID_EMAIL_ERROR}: {str(e)}"}
+
+def validate_age_field(age):
+    """
+    Validate if the age is within the range [14-120].
+
+    Parameters
+    ----------
+    age : str
+        The age input value as a string.
+
+    Returns
+    -------
+    dict
+        A dictionary with `has_error` (bool) and `error_msg` (str).
+    """
+    if not (age.isdigit() and 14 <= int(age) <= 110):
+        return {"has_error": True, "error_msg": INVALID_AGE_ERROR}
+    return {"has_error": False, "error_msg": ""}
+
+# Hybrid validation functions #
+#----------------------------#
+
+def validate_form_with_json(form_data, json_data=None):
+    """
+    Validates both form data and JSON data in a full-stack context.
+    
+    This function combines the backend-oriented JSON validation with
+    the frontend-oriented form validation.
+
+    Parameters
+    ----------
+    form_data : dict
+        Form data from a web form (e.g., Flask request.form).
+    json_data : dict, optional
+        JSON data for API validation.
+
+    Returns
+    -------
+    dict
+        A dictionary with validation results for both form and JSON data.
+    """
+    results = {
+        "form_validation": {},
+        "json_validation": {}
+    }
+    
+    # Validate form data if provided
+    if form_data:
+        results["form_validation"] = generate_error_dict(
+            form_data, 
+            REG_EXP_DICT, 
+            ERR_STR_LIST
+        )
+    
+    # Validate JSON data if provided
+    if json_data:
+        results["json_validation"] = generate_json_validation_response(json_data)
+    
+    return results
+
+def generate_json_validation_response(json_data):
+    """
+    Generates a validation response for medical data fields from JSON input.
+
+    Parameters
+    ----------
+    json_data : dict
+        The JSON data containing medical measurements to validate.
+        Expected fields are:
+        - id (str)
+        - created_at (dict with min_value and max_value)
+
+    Returns
+    -------
+    dict
+        JSON-formatted validation response for each field:
+        {
+            "field_name": {
+                "error_msg": str
+            }
+        }
+    """
+    validation_results = {}
+    
+    for field_name, field_specs_dict in json_data.items():
+        if field_name == 'created_at':
+            # Validate date range format and values
+            if not isinstance(field_specs_dict, dict):
+                validation_results[field_name] = {"error_msg": INVALID_DATE_RANGE_FORMAT_ERROR}
+                continue
+                
+            min_value = field_specs_dict.get("min_value")
+            max_value = field_specs_dict.get("max_value")
+            
+            if not min_value or not max_value:
+                validation_results[field_name] = {"error_msg": MISSING_DATE_VALUES_ERROR}
+                continue
+                
+            validation_results[field_name] = validate_date_range(min_value, max_value)
+        elif field_name == 'id':
+            validation_results[field_name] = validate_id_field(field_specs_dict, INVALID_ID_FORMAT_ERROR, INVALID_ID_TYPE_ERROR)
+    
+    return validation_results
+
+#--------------------------#
+# Parameters and constants #
+#--------------------------#
+
+# Field name keywords #
+#--------------------#
+
+# User registration fields
+FIELD_NAME_LIST_ENG = [
+    "email",
+    "first_name",
+    "first_surname",
+    "second_surname",
+    "password",
+    "tel",
+    "age"
+]
+
+FIELD_NAME_LIST_ESP = [
+    "Correo electrónico",
+    "Nombre",
+    "Primer apellido",
+    "Segundo apellido",
+    "Contraseña",
+    "Teléfono",
+    "Edad"
+]
+
+DROPDOWN_ID_LIST = [f"{field}_dropdown" for field in FIELD_NAME_LIST_ENG]
+FIELD_NAME_SEARCH_LIST = [f"{field}_search_value" for field in FIELD_NAME_LIST_ENG]
+
+# Fields that can be used for filtering (WHERE clauses)
+FILTERABLE_FIELDS = ["id", "created_at"]
+
+# Fields to display in the response (SELECT clauses)
+DISPLAYABLE_FIELDS = ["hl7_v2"]
+
+# Pretty names for documentation
+FIELD_NAME_LIST_PRETTY = [
+    "ID",
+    "Age",
+    "Body Temperature",
+    "Blood Pressure",
+    "Leucocyte Count",
+    "Neutrophil Count",
+    "Lymphocyte Count",
+    "Monocyte Count",
+    "User Registration Date",
+    "HL7 v2.X"
+]
+
+# ID validation regex pattern
+ID_PATTERN = r'^P[0-9]{3}$'
+
+# Create lists of error messages for backward compatibility
+ERR_STR_LIST = [
+    INVALID_EMAIL_ERROR,
+    INVALID_FIRST_NAME_ERROR,
+    INVALID_FIRST_SURNAME_ERROR,
+    INVALID_SECOND_SURNAME_ERROR,
+    INVALID_PASSWORD_ERROR,
+    INVALID_TEL_ERROR,
+    INVALID_AGE_ERROR,
+    USER_EXISTS_ERROR
+]
+
+ERR_STR_LIST_SEARCH = ERR_STR_LIST.copy()
+INVALID_TEL_SEARCH_VALUE = INVALID_TEL_SEARCH_VALUE
+
+# Regular expressions #
+#---------------------#
+
+REG_EXP_DICT = {
+    FIELD_NAME_LIST_ENG[1]: r"^[a-zá-úà-ùâ-ûä-üA-ZÁ-ÚÀ-ÙÂ-ÛÄ-ÜçñÇÑ\s-]{3,}$",
+    FIELD_NAME_LIST_ENG[2]: r"^[a-zá-úà-ùâ-ûä-üA-ZÁ-ÚÀ-ÙÂ-ÛÄ-ÜçñÇÑ\s'-]{3,}$",
+    FIELD_NAME_LIST_ENG[3]: r"^[a-zá-úà-ùâ-ûä-üA-ZÁ-ÚÀ-ÙÂ-ÛÄ-ÜçñÇÑ\s'-]{3,}$",
+    FIELD_NAME_LIST_ENG[4]: r"^(?=.{8,})(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[_\W]).+$",
+    FIELD_NAME_LIST_ENG[5]: r"^(\+[1-9][0-9]{1,2} [0-9]{3} [0-9]{3} [0-9]{3}|\+[1-9]{1}-[0-9]{3} [0-9]{3} [0-9]{3} [0-9]{3}|[0-9]{3} [0-9]{3} [0-9]{3})$",
+}
+
+REG_EXP_DICT_SEARCH = {
+    FIELD_NAME_LIST_ENG[1]: r"^[a-zá-úà-ùâ-ûä-üA-ZÁ-ÚÀ-ÙÂ-ÛÄ-ÜçñÇÑ\s%-]*$",
+    FIELD_NAME_LIST_ENG[2]: r"^[a-zá-úà-ùâ-ûä-üA-ZÁ-ÚÀ-ÙÂ-ÛÄ-ÜçñÇÑ\s%-]*$",
+    FIELD_NAME_LIST_ENG[3]: r"^[a-zá-úà-ùâ-ûä-üA-ZÁ-ÚÀ-ÙÂ-ÛÄ-ÜçñÇÑ\s%-]*$",
+    FIELD_NAME_LIST_ENG[5]: r"^\+[0-9\s]*$",
+}
+
+# Validation mapping #
+FIELD_VALIDATORS = {
+    "id": lambda x: validate_id_field(x, INVALID_ID_FORMAT_ERROR, INVALID_ID_TYPE_ERROR),
+    "email": validate_email_field,
+    "age": validate_age_field
+} 

DataOpsHub/databases/__init__.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# DataOpsHub/databases/__init__.py
+
+# Define what should be available when using 'from DataOpsHub.databases import *'
+__all__ = [
+    'database_handler',
+    'upload_data'
+]