vtlengine 1.4.0rc2__py3-none-any.whl

vtlengine/DataTypes/_time_checking.py

@@ -0,0 +1,135 @@
+import calendar
+import re
+from datetime import date, datetime
+
+from vtlengine.DataTypes.TimeHandling import TimePeriodHandler
+from vtlengine.Exceptions import InputValidationException
+
+
+def check_date(value: str) -> str:
+    """
+    Check if the date is in the correct format.
+    """
+    # Remove all whitespaces
+    value = value.strip()
+    try:
+        if len(value) == 9 and value[7] == "-":
+            value = value[:-1] + "0" + value[-1]
+        date_value = date.fromisoformat(value)
+    except ValueError as e:
+        if "is out of range" in str(e):
+            raise InputValidationException(f"Date {value} is out of range for the month.")
+        if "month must be in 1..12" in str(e):
+            raise InputValidationException(
+                f"Date {value} is invalid. Month must be between 1 and 12."
+            )
+        raise InputValidationException(
+            f"Date {value} is not in the correct format. Use YYYY-MM-DD."
+        )
+
+    # Check date is between 1900 and 9999
+    if not 1800 <= date_value.year <= 9999:
+        raise InputValidationException(
+            f"Date {value} is invalid. Year must be between 1900 and 9999."
+        )
+
+    return date_value.isoformat()
+
+
+def dates_to_string(date1: date, date2: date) -> str:
+    date1_str = date1.strftime("%Y-%m-%d")
+    date2_str = date2.strftime("%Y-%m-%d")
+    return f"{date1_str}/{date2_str}"
+
+
+date_pattern = r"\d{4}[-][0-1]?\d[-][0-3]?\d"
+year_pattern = r"\d{4}"
+month_pattern = r"\d{4}[-][0-1]?\d"
+time_pattern = r"^" + date_pattern + r"/" + date_pattern + r"$"
+
+
+def check_time(value: str) -> str:
+    value = value.strip()
+    year_result = re.fullmatch(year_pattern, value)
+    if year_result is not None:
+        date1_time = datetime.strptime(value, "%Y")
+        date2_time = date1_time.replace(day=31, month=12)
+        return dates_to_string(date1_time, date2_time)
+    month_result = re.fullmatch(month_pattern, value)
+    if month_result is not None:
+        date1_time = datetime.strptime(value, "%Y-%m")
+        last_month_day = calendar.monthrange(date1_time.year, date1_time.month)[1]
+        date2_time = date1_time.replace(day=last_month_day)
+        return dates_to_string(date1_time, date2_time)
+    time_result = re.fullmatch(time_pattern, value)
+    if time_result is not None:
+        time_list = value.split("/")
+        if time_list[0] > time_list[1]:
+            raise ValueError("Start date is greater than end date.")
+        return value
+    raise ValueError(
+        "Time is not in the correct format. Use YYYY-MM-DD/YYYY-MM-DD or YYYY or YYYY-MM."
+    )
+
+
+day_period_pattern = r"^\d{4}[-][0-1]?\d[-][0-3]?\d$"
+month_period_pattern = r"^\d{4}[-][0-1]?\d$"
+year_period_pattern = r"^\d{4}$"
+period_pattern = (
+    r"^\d{4}[A]$|^\d{4}[S][1-2]$|^\d{4}[Q][1-4]$|^\d{4}[M]"
+    r"[0-1]?\d$|^\d{4}[W][0-5]?\d$|^\d{4}[D][0-3]?[0-9]?\d$"
+)
+
+# Related with gitlab issue #440, we can say that period pattern
+# matches with our internal representation (or vtl user manual)
+# and further_options_period_pattern matches
+# with other kinds of inputs that we have to accept for the period.
+further_options_period_pattern = (
+    r"\d{4}-\d{2}-\d{2}|^\d{4}-D[0-3]\d\d$|^\d{4}-W([0-4]"
+    r"\d|5[0-3])|^\d{4}-(0[1-9]|1[0-2]|M(0[1-9]|1[0-2]|[1-9]))$|^"
+    r"\d{4}-Q[1-4]$|^\d{4}-S[1-2]$|^\d{4}-A1$"
+)
+
+
+def check_time_period(value: str) -> str:
+    if isinstance(value, int):
+        value = str(value)
+    value = value.strip()
+
+    match = re.fullmatch(r"^(\d{4})-(\d{2})$", value)
+    if match:
+        value = f"{match.group(1)}-M{match.group(2)}"
+
+    period_result = re.fullmatch(period_pattern, value)
+    if period_result is not None:
+        result = TimePeriodHandler(value)
+        return str(result)
+
+    # We allow the user to input the time period in different formats.
+    # See gl-440 or documentation in time period tests.
+    further_options_period_result = re.fullmatch(further_options_period_pattern, value)
+    if further_options_period_result is not None:
+        result = TimePeriodHandler(value)
+        return str(result)
+
+    year_result = re.fullmatch(year_period_pattern, value)
+    if year_result is not None:
+        year = datetime.strptime(value, "%Y")
+        year_period_wo_A = str(year.year)
+        return year_period_wo_A
+        # return year_period
+
+    month_result = re.fullmatch(month_period_pattern, value)
+    if month_result is not None:
+        month = datetime.strptime(value, "%Y-%m")
+        month_period = month.strftime("%YM%m")
+        result = TimePeriodHandler(month_period)
+        return str(result)
+
+    # TODO: Do we use this?
+    day_result = re.fullmatch(day_period_pattern, value)
+    if day_result is not None:
+        day = datetime.strptime(value, "%Y-%m-%d")
+        day_period = day.strftime("%YD%-j")
+        return day_period
+    raise ValueError

vtlengine/Exceptions/__exception_file_generator.py

@@ -0,0 +1,96 @@
+from pathlib import Path
+from typing import Any, Dict
+
+output_filepath = Path(__file__).parent.parent.parent.parent / "Docs" / "error_messages.rst"
+
+
+def generate_errors_rst(file_path: Path, messages: Dict[str, Any]) -> None:
+    """
+    Generates an RST file with a grid of error codes, messages, and descriptions.
+    """
+
+    def sort_key(code: str) -> Any:
+        return tuple(int(part) for part in code.split("-"))
+
+    def escape_for_sphinx(text: str) -> str:
+        """
+        Scapes placeholders for Sphinx formatting.
+        """
+        placeholders = ["{type}", "{type_}", "{format}", "{format_}", "{param}", "{op}", "{value}"]
+        for ph in placeholders:
+            text = text.replace(ph, f"``{ph}``")
+        return text
+
+    path = Path(file_path)
+    lines = []
+    lines.append("Error Messages")
+    lines.append("################")
+    lines.append("")
+    lines.append(
+        "This document provides a complete list of all error messages generated by the VTL engine. "
+        "Each entry includes the error code, the corresponding message, and a brief description "
+        "to help users to understand the cause of the issue."
+    )
+    lines.append("")
+    lines.append("The following legend explains the error code patterns used in the VTL engine:")
+    lines.append("")
+    category_header = "Category"
+    pattern_header = "Pattern"
+    legend_rows = [
+        ("INPUT ERRORS", "0-1-X-X = Input Validation Errors\n"),
+        ("", "0-2-X-X = JSON Schema Errors\n"),
+        ("", "0-3-X-X = DataLoad Errors"),
+        ("SEMANTIC ERRORS", "1-1-X-X = Operators Semantic Errors\n"),
+        ("", "1-2-X-X = Semantic Analyzer Errors\n"),
+        ("", "1-3-X-X = AST Errors"),
+        ("RUNTIME ERRORS", "2-X-X-X = RunTime Operator Errors"),
+    ]
+
+    max_cat = max(len(category_header), max(len(row[0]) for row in legend_rows))
+    max_pat = max(len(pattern_header), max(len(row[1]) for row in legend_rows))
+    sep_legend = f"{'=' * max_cat}  {'=' * max_pat}"
+
+    lines.append(sep_legend)
+    lines.append(f"{category_header.ljust(max_cat)}  {pattern_header.ljust(max_pat)}")
+    lines.append(sep_legend)
+    for cat, pat in legend_rows:
+        lines.append(f"{cat.ljust(max_cat)}  {pat.ljust(max_pat)}")
+    lines.append(sep_legend)
+    lines.append("")
+    lines.append("The following table contains all available error codes:")
+    lines.append("")
+    headers = ["Code", "Message", "Description"]
+    max_lengths = [len(h) for h in headers]
+
+    for code, info in messages.items():
+        if isinstance(info, dict):
+            message = escape_for_sphinx(info.get("message", ""))
+            description = escape_for_sphinx(info.get("description", ""))
+        else:
+            message = escape_for_sphinx(str(info))
+            description = ""
+        max_lengths[0] = max(max_lengths[0], len(code))
+        max_lengths[1] = max(max_lengths[1], len(message))
+        max_lengths[2] = max(max_lengths[2], len(description))
+
+    sep = "  ".join("=" * length for length in max_lengths)
+    lines.append(sep)
+    header_line = "  ".join(h.ljust(max_lengths[i]) for i, h in enumerate(headers))
+    lines.append(header_line)
+    lines.append(sep)
+
+    for code in sorted(messages.keys(), key=sort_key):
+        info = messages[code]
+        if isinstance(info, dict):
+            message = escape_for_sphinx(info.get("message", ""))
+            description = escape_for_sphinx(info.get("description", ""))
+        else:
+            message = escape_for_sphinx(str(info))
+            description = ""
+        row = "  ".join(s.ljust(max_lengths[i]) for i, s in enumerate([code, message, description]))
+        lines.append(row)
+
+    lines.append(sep)
+
+    path.write_text("\n".join(lines), encoding="utf-8")
+    print(f"RST generated in {path}")

vtlengine/Exceptions/__init__.py

@@ -0,0 +1,159 @@
+"""
+Exceptions.exceptions.py
+========================
+
+Description
+-----------
+All exceptions exposed by the Vtl engine.
+"""
+
+from typing import Any, List, Optional
+
+from vtlengine.Exceptions.messages import centralised_messages
+
+dataset_output = None
+
+
+class VTLEngineException(Exception):
+    """Base class for exceptions in this module."""
+
+    def __init__(
+        self,
+        message: str,
+        lino: Optional[str] = None,
+        colno: Optional[str] = None,
+        code: Optional[str] = None,
+    ) -> None:
+        if code is not None:
+            super().__init__(message, code)
+        else:
+            super().__init__(message)
+        self.lino = lino
+        self.colno = colno
+
+    @property
+    def pos(self) -> List[Optional[str]]:
+        """ """
+
+        return [self.lino, self.colno]
+
+
+class SemanticError(VTLEngineException):
+    """ """
+
+    output_message = " Please check transformation with output Dataset "
+    comp_code = None
+
+    def __init__(self, code: str, comp_code: Optional[str] = None, **kwargs: Any) -> None:
+        if dataset_output:
+            message = (
+                centralised_messages[code]["message"].format(**kwargs)
+                + self.output_message
+                + str(dataset_output)
+            )
+        else:
+            message = centralised_messages[code]["message"].format(**kwargs)  # type: ignore[index]
+
+        super().__init__(message, None, None, code)
+
+        if comp_code:
+            self.comp_code = comp_code
+
+
+class RunTimeError(VTLEngineException):
+    output_message = " Please check transformation with output Dataset "
+    comp_code = None
+
+    def __init__(
+        self,
+        code: str,
+        comp_code: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        message = centralised_messages[code]["message"].format(**kwargs)  # type: ignore[index]
+        if dataset_output:
+            message += self.output_message + str(dataset_output)
+
+        super().__init__(message, None, None, code)
+
+        if comp_code:
+            self.comp_code = comp_code
+
+
+class InputValidationException(VTLEngineException):
+    """ """
+
+    def __init__(
+        self,
+        message: str = "default_value",
+        lino: Optional[str] = None,
+        colno: Optional[str] = None,
+        code: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        if code is not None:
+            message = centralised_messages[code]["message"].format(**kwargs)  # type: ignore[index]
+            super().__init__(message, lino, colno, code)
+        else:
+            super().__init__(message, lino, colno)
+
+
+def check_key(field: str, dict_keys: Any, key: str) -> None:
+    if key not in dict_keys:
+        closest_key = find_closest_key(dict_keys, key)
+        message_append = f". Did you mean {closest_key}?" if closest_key else ""
+        raise SemanticError("0-1-1-13", field=field, key=key, closest_key=message_append)
+
+
+def find_closest_key(dict_keys: Any, key: str) -> Optional[str]:
+    closest_key = None
+    max_distance = 3
+    min_distance = float("inf")
+
+    for dict_key in dict_keys:
+        distance = key_distance(key, dict_key)
+        if distance < min_distance:
+            min_distance = distance
+            closest_key = dict_key
+
+    if min_distance <= max_distance:
+        return closest_key
+    return None
+
+
+def key_distance(key: str, objetive: str) -> int:
+    dp = [[0] * (len(objetive) + 1) for _ in range(len(key) + 1)]
+
+    for i in range(len(key) + 1):
+        dp[i][0] = i
+    for j in range(len(objetive) + 1):
+        dp[0][j] = j
+
+    for i in range(1, len(key) + 1):
+        for j in range(1, len(objetive) + 1):
+            cost = 0 if key[i - 1] == objetive[j - 1] else 1
+            dp[i][j] = min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost)
+
+    return dp[-1][-1]
+
+
+class DataLoadError(VTLEngineException):
+    output_message = " Please check loaded file"
+    comp_code: Optional[str] = None
+
+    def __init__(
+        self,
+        code: str,
+        comp_code: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        message = centralised_messages[code]["message"].format(**kwargs)  # type: ignore[index]
+        if dataset_output:
+            message += self.output_message + " " + str(dataset_output)
+        else:
+            message += self.output_message
+
+        super().__init__(message, None, None, code)
+
+        if comp_code:
+            self.comp_code = comp_code