vtlengine 1.0.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

vtlengine/API/__init__.py

@@ -1,32 +1,45 @@
 from pathlib import Path
-from typing import Any, Union, List, Optional
-
-from antlr4 import CommonTokenStream, InputStream
-from antlr4.error.ErrorListener import ErrorListener
-
-from vtlengine.API._InternalApi import load_vtl, load_datasets, load_value_domains, \
-    load_external_routines, \
-    load_datasets_with_data, _return_only_persistent_datasets, _check_output_folder
+from typing import Any, Union, List, Optional, Dict
+
+import pandas as pd
+from antlr4 import CommonTokenStream, InputStream  # type: ignore[import-untyped]
+from antlr4.error.ErrorListener import ErrorListener  # type: ignore[import-untyped]
+
+from vtlengine.API._InternalApi import (
+    load_vtl,
+    load_datasets,
+    load_value_domains,
+    load_external_routines,
+    load_datasets_with_data,
+    _return_only_persistent_datasets,
+    _check_output_folder,
+)
 from vtlengine.AST import Start
 from vtlengine.AST.ASTConstructor import ASTVisitor
 from vtlengine.AST.DAG import DAGAnalyzer
 from vtlengine.AST.Grammar.lexer import Lexer
 from vtlengine.AST.Grammar.parser import Parser
 from vtlengine.Interpreter import InterpreterAnalyzer
-from vtlengine.files.output import TimePeriodRepresentation, \
-    format_time_period_external_representation
+from vtlengine.files.output._time_period_representation import (
+    format_time_period_external_representation,
+    TimePeriodRepresentation,
+)
 
+pd.options.mode.chained_assignment = None
 
-class __VTLSingleErrorListener(ErrorListener):
-    """
 
-    """
+class __VTLSingleErrorListener(ErrorListener):  # type: ignore[misc]
+    """ """
 
-    def syntaxError(self, recognizer, offendingSymbol, line, column, msg, e):
-        raise Exception(f"Not valid VTL Syntax \n "
-                        f"offendingSymbol: {offendingSymbol} \n "
-                        f"msg: {msg} \n "
-                        f"line: {line}")
+    def syntaxError(
+        self, recognizer: Any, offendingSymbol: str, line: str, column: str, msg: str, e: Any
+    ) -> None:
+        raise Exception(
+            f"Not valid VTL Syntax \n "
+            f"offendingSymbol: {offendingSymbol} \n "
+            f"msg: {msg} \n "
+            f"line: {line}"
+        )
 
 
 def _lexer(text: str) -> CommonTokenStream:
@@ -52,6 +65,15 @@ def _parser(stream: CommonTokenStream) -> Any:
 def create_ast(text: str) -> Start:
     """
     Function that creates the AST object.
+
+    Args:
+        text: Vtl string expression that will be used to create the AST object.
+
+    Returns:
+        The ast object.
+
+    Raises:
+        Exception: When the vtl syntax expression is wrong.
     """
     stream = _lexer(text)
     cst = _parser(stream)
@@ -61,10 +83,12 @@ def create_ast(text: str) -> Start:
     return ast
 
 
-def semantic_analysis(script: Union[str, Path],
-                      data_structures: Union[dict, Path, List[Union[dict, Path]]],
-                      value_domains: Union[dict, Path] = None,
-                      external_routines: Union[str, Path] = None):
+def semantic_analysis(
+    script: Union[str, Path],
+    data_structures: Union[Dict[str, Any], Path, List[Union[Dict[str, Any], Path]]],
+    value_domains: Optional[Union[Dict[str, Any], Path]] = None,
+    external_routines: Optional[Union[Dict[str, Any], Path]] = None,
+) -> Any:
     """
     Checks if the vtl operation can be done.To do that, it generates the AST with the vtl script
     given and also reviews if the data structure given can fit with it.
@@ -85,9 +109,9 @@ def semantic_analysis(script: Union[str, Path],
 
     - Vtl script: The expression that shows the operation to be done.
 
-    - Data Structure: Json file that contains the structure and the name for the dataset(s) \
-    (and/or scalar) about the datatype (String, integer or number) and \
-    the role (Measure or Identifier) each data has.
+    - Data Structure: JSON file that contains the structure and the name for the dataset(s) \
+    (and/or scalar) about the datatype (String, integer or number), \
+    the role (Identifier, Attribute or Measure) and the nullability each component has.
 
     - Value domains: Collection of unique values on the same datatype.
 
@@ -95,16 +119,19 @@ def semantic_analysis(script: Union[str, Path],
 
     This function has the following params:
 
-    :param script: String or Path of the vtl expression.
-
-    :param data_structures: Dict or Path (file or folder), \
-    or List of Dicts or Paths with the data structures JSON files.
-
-    :param value_domains: Dict or Path of the value domains JSON files. (default: None)
+    Args:
+        script: String or Path of the vtl expression.
+        data_structures: Dict or Path (file or folder), \
+        or List of Dicts or Paths with the data structures JSON files.
+        value_domains: Dict or Path of the value domains JSON files. (default: None)
+        external_routines: String or Path of the external routines SQL files. (default: None)
 
-    :param external_routines: String or Path of the external routines SQL files. (default: None)
+    Returns:
+        The computed datasets.
 
-    :return: The computed datasets.
+    Raises:
+        Exception: If the files have the wrong format, or they do not exist, \
+        or their Paths are invalid.
     """
     # AST generation
     vtl = load_vtl(script)
@@ -122,19 +149,24 @@ def semantic_analysis(script: Union[str, Path],
         ext_routines = load_external_routines(external_routines)
 
     # Running the interpreter
-    interpreter = InterpreterAnalyzer(datasets=structures, value_domains=vd,
-                                      external_routines=ext_routines,
-                                      only_semantic=True)
-    result = interpreter.visit(ast)
+    interpreter = InterpreterAnalyzer(
+        datasets=structures, value_domains=vd, external_routines=ext_routines, only_semantic=True
+    )
+    with pd.option_context("future.no_silent_downcasting", True):
+        result = interpreter.visit(ast)
     return result
 
 
-def run(script: Union[str, Path], data_structures: Union[dict, Path, List[Union[dict, Path]]],
-        datapoints: Union[dict, str, Path, List[Union[str, Path]]],
-        value_domains: Union[dict, Path] = None, external_routines: Union[str, Path] = None,
-        time_period_output_format: str = "vtl",
-        return_only_persistent=False,
-        output_folder: Optional[Union[str, Path]] = None):
+def run(
+    script: Union[str, Path],
+    data_structures: Union[Dict[str, Any], Path, List[Union[Dict[str, Any], Path]]],
+    datapoints: Union[Dict[str, Any], str, Path, List[Union[str, Path]]],
+    value_domains: Optional[Union[Dict[str, Any], Path]] = None,
+    external_routines: Optional[Union[str, Path]] = None,
+    time_period_output_format: str = "vtl",
+    return_only_persistent: bool = False,
+    output_folder: Optional[Union[str, Path]] = None,
+) -> Any:
     """
     Run is the main function of the ``API``, which mission is to ensure the vtl operation is ready
     to be performed.
@@ -144,7 +176,7 @@ def run(script: Union[str, Path], data_structures: Union[dict, Path, List[Union[
 
     The data structure information is contained in the JSON file given,
     and establish the datatype (string, integer or number),
-    and the role that each component is going to have (Identifier or Measure).
+    and the role that each component is going to have (Identifier, Attribute or Measure).
     It can be a dictionary or a path to the JSON file or folder that contains it.
 
     Moreover, a csv file with the data to operate with is going to be loaded.
@@ -186,10 +218,9 @@ def run(script: Union[str, Path], data_structures: Union[dict, Path, List[Union[
 
     - Vtl script: The expression that shows the operation to be done.
 
-    - Data Structure: \
-    JSON file that contains the structure and the name for the dataset(s) (and/or scalar) \
-    about the datatype (String, integer or number) and the role (Identifier, Attribute or Measure)
-    each component has.
+    - Data Structure: JSON file that contains the structure and the name for the dataset(s) \
+    (and/or scalar) about the datatype (String, integer or number), \
+    the role (Identifier, Attribute or Measure) and the nullability each component has.
 
     - Data point: Pointer to the data. It will be loaded as a `Pandas Dataframe \
     <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html>`_.
@@ -200,26 +231,33 @@ def run(script: Union[str, Path], data_structures: Union[dict, Path, List[Union[
 
     This function has the following params:
 
-    :param script: String or Path with the vtl expression.
+    Args:
+        script: String or Path with the vtl expression.
+
+        data_structures: Dict, Path or a List of Dicts or Paths with the data structures.
+
+        datapoints: Dict, Path, S3 URI or List of S3 URIs or Paths with data.
 
-    :param data_structures: Dict, Path or a List of Dicts or Paths with the data structures.
+        value_domains: Dict or Path of the value domains JSON files. (default:None)
 
-    :param datapoints: Dict, Path, S3 URI or List of S3 URIs or Paths with data.
+        external_routines: String or Path of the external routines SQL files. (default: None)
 
-    :param value_domains: Dict or Path of the value domains JSON files. (default:None)
+        time_period_output_format: String with the possible values \
+        ("sdmx_gregorian", "sdmx_reporting", "vtl") for the representation of the \
+        Time Period components.
 
-    :param external_routines: String or Path of the external routines SQL files. (default: None)
+        return_only_persistent: If True, run function will only return the results of \
+        Persistent Assignments. (default: False)
 
-    :param time_period_output_format: String with the possible values \
-    ("sdmx_gregorian", "sdmx_reporting", "vtl") for the representation of the \
-    Time Period components.
+        output_folder: Path or S3 URI to the output folder. (default: None)
 
-    :param return_only_persistent: If True, run function will only return the results of \
-    Persistent Assignments. (default: False)
 
-    :param output_folder: Path or S3 URI to the output folder. (default: None)
+    Returns:
+       The datasets are produced without data if the output folder is defined.
 
-    :return: The datasets are produced without data if the output folder is defined.
+    Raises:
+        Exception: If the files have the wrong format, or they do not exist, \
+        or their Paths are invalid.
 
     """
     # AST generation
@@ -248,13 +286,17 @@ def run(script: Union[str, Path], data_structures: Union[dict, Path, List[Union[
         _check_output_folder(output_folder)
 
     # Running the interpreter
-    interpreter = InterpreterAnalyzer(datasets=datasets, value_domains=vd,
-                                      external_routines=ext_routines,
-                                      ds_analysis=ds_analysis,
-                                      datapoints_paths=path_dict,
-                                      output_path=output_folder,
-                                      time_period_representation=time_period_representation)
-    result = interpreter.visit(ast)
+    interpreter = InterpreterAnalyzer(
+        datasets=datasets,
+        value_domains=vd,
+        external_routines=ext_routines,
+        ds_analysis=ds_analysis,
+        datapoints_paths=path_dict,
+        output_path=output_folder,
+        time_period_representation=time_period_representation,
+    )
+    with pd.option_context("future.no_silent_downcasting", True):
+        result = interpreter.visit(ast)
 
     # Applying time period output format
     if output_folder is None: