gamsapi 52.5.0__cp312-cp312-win_amd64.whl

gams/connect/agents/sqlwriter.py

@@ -0,0 +1,276 @@
+#
+# GAMS - General Algebraic Modeling System Python API
+#
+# Copyright (c) 2017-2026 GAMS Development Corp. <support@gams.com>
+# Copyright (c) 2017-2026 GAMS Software GmbH <support@gams.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+
+import gams.transfer as gt
+from gams.connect.agents.connectagent import ConnectAgent
+from gams.connect.agents._sqlconnectors import (
+    AccessConnector,
+    MySQLConnector,
+    PostgresConnector,
+    PyodbcConnector,
+    SQLAlchemyConnector,
+    SQLiteConnector,
+    SQLServerConnector,
+)
+from gams.connect.agents._sqlconnectors._databasehandler import ConnectionType
+from gams.connect.connectvalidator import ConnectValidator
+
+
+class SQLWriter(ConnectAgent):
+    def __init__(self, cdb, inst, agent_index):
+        super().__init__(cdb, inst, agent_index)
+        self._parse_options(self._inst)
+
+    def _parse_options(self, inst):
+        # global options
+        self._input_cnctn = inst["connection"]  # input db credentials/path thru user.
+        self._cnctn_type = inst["connectionType"]
+        self._connection_args = self._dict_get(inst, "connectionArguments", {})
+        self._ifExists = inst["ifExists"]
+        self._schema_name = inst["schemaName"]
+        self._to_sql_args = inst["toSQLArguments"]
+        self._trace = inst["trace"]
+        self._insertMethod = inst["insertMethod"]
+        self._unstack = inst["unstack"]
+        self._value_sub = inst["valueSubstitutions"]
+        self._dtype_map = inst["dTypeMap"]
+        self._col_encloser = inst["columnEncloser"]
+        self._skip_text = inst["skipText"]
+        self._fast = (
+            False if self._cnctn_type != ConnectionType.SQLITE.value else inst["fast"]
+        )  # NO effect for rest of the connectionTypes
+        self._small = (
+            False if self._cnctn_type != ConnectionType.SQLITE.value else inst["small"]
+        )  # NO effect for rest of the connectionTypes
+        self._symbols = inst["symbols"]  # symbol option
+        self._write_all = self._symbols == "all"
+        self._sqlitewrite_globalCommit = self._connection_args.pop(
+            "__globalCommit__", False
+        )
+        self._handler = self._get_handler(self._cnctn_type)
+
+    def _get_handler(
+        self, cnctn_type
+    ) -> (
+        SQLiteConnector
+        | SQLAlchemyConnector
+        | PyodbcConnector
+        | MySQLConnector
+        | PostgresConnector
+        | SQLServerConnector
+        | AccessConnector
+    ):
+        handlers = {
+            ConnectionType.SQLITE.value: SQLiteConnector,
+            ConnectionType.SQLALCHEMY.value: SQLAlchemyConnector,
+            ConnectionType.PYODBC.value: PyodbcConnector,
+            ConnectionType.MYSQL.value: MySQLConnector,
+            ConnectionType.POSTGRES.value: PostgresConnector,
+            ConnectionType.SQLSERVER.value: SQLServerConnector,
+            ConnectionType.ACCESS.value: AccessConnector,
+        }
+        handler_class = handlers[cnctn_type]
+
+        return handler_class(
+            error_callback=self._connect_error,
+            printLog_callback=self._cdb.print_log,
+            trace=self._trace,
+        )
+
+    def _open(self):
+        options = {
+            "_sqlitewrite_globalCommit": self._sqlitewrite_globalCommit,
+            "small": self._small,
+            "fast": self._fast,
+        }
+        self._handler.connect(
+            connection_details=self._input_cnctn,
+            connection_args=self._connection_args,
+            **options,
+        )
+
+    def execute(self):
+        if self._trace > 0:
+            self._log_instructions(self._inst, self._inst_raw)
+            self._describe_container(self._cdb.container, "Connect Container:")
+
+        self._handler.validate_insert_method(method=self._insertMethod)
+        self._open()
+
+        try:
+            self._handler.create_transaction()
+
+            if self._write_all:
+                self._symbols = []
+                sym_schema = self._cdb.load_schema(self)["symbols"]["oneof"][1][
+                    "schema"
+                ]["schema"]
+                v = ConnectValidator(sym_schema)
+                for name, sym in self._cdb.container.data.items():
+                    if type(sym) in [gt.Set, gt.Parameter]:
+                        sym_inst = v.validated({"name": name, "tableName": name})  # type: ignore
+                        if sym_inst is None:
+                            self._connect_error(
+                                f"Validation for symbol >{name}< failed: {v.errors}"  # type: ignore
+                            )
+                        sym_inst = v.normalize_of_rules(sym_inst)
+                        self._symbols.append(sym_inst)
+
+            symbols_raw = self._symbols.copy()
+            sym_list = []
+            for s in self._symbols:
+                sym_name = s["name"]
+                self._symbols_exist_cdb(sym_name, should_exist=True)
+                self._update_sym_inst(s, self._inst)
+                sym_list.append(s["name"])
+
+            pre_write_args = {
+                # only implemented for sqlite, pre_write_procedures must return the container
+                "container": self._cdb.container,
+                "directory": self._system_directory,
+                "sym_list": sym_list,
+            }
+            write_container = self._handler.pre_write_procedures(**pre_write_args)
+
+            for sym, sym_raw in zip(self._symbols, symbols_raw):
+                if self._trace > 0:
+                    self._log_instructions(
+                        sym, sym_raw, description=f"Write symbol >{sym['name']}<:"
+                    )
+
+                sym_name = sym["name"]
+                table_name = sym["tableName"]
+                schema = sym["schemaName"]
+                exists = sym["ifExists"]
+                unstack = sym["unstack"]
+                value_sub = sym["valueSubstitutions"]
+                dtype_map = self._dict_get(sym, "dTypeMap", {})
+                insertMethod = sym["insertMethod"]
+                skip_text = sym["skipText"]
+                self._handler.validate_insert_method(method=insertMethod)
+
+                if self._small and table_name == "UEL$":
+                    self._connect_error(
+                        "tableName >UEL$< is not allowed. >UEL$< is a preserved tableName with small set to >True<."
+                    )
+
+                gt_sym = write_container[sym_name]
+
+                if self._trace > 2:
+                    self._cdb.print_log(
+                        f"Connect Container symbol={sym_name}:\n {gt_sym.records}\n"  # type: ignore
+                    )
+
+                if not isinstance(gt_sym, gt.Set) and not isinstance(
+                    gt_sym, gt.Parameter
+                ):
+                    self._connect_error(
+                        f"Symbol type >{type(gt_sym)}< of symbol >{sym_name}< is not supported. Supported symbol types are set and parameter."
+                    )
+
+                dim = gt_sym.dimension
+                df = self._sym_records_no_none(gt_sym).copy(deep=True)
+                sym_type = "par" if isinstance(gt_sym, gt.Parameter) else "set"
+                value = "value" if sym_type == "par" else "element_text"
+
+                if value_sub:
+                    df = self._apply_value_substitutions(df, value_sub, sym_type)
+                    if self._trace > 2:
+                        self._cdb.print_log(f"After value substitution:\n{df}")
+
+                if unstack and dim > 0:
+                    if (
+                        sym_type == "set" and skip_text
+                    ):  # replace all element_text by Y when exporting a true table
+                        df.loc[:, value] = "Y"
+                    elif (
+                        sym_type == "set"
+                    ):  # replace empty element_text by Y when exporting a true table
+                        df.loc[df[value] == "", value] = "Y"
+                    cols = list(df.columns)
+                    if dim > 1:
+                        df = df.pivot(index=cols[0:-2], columns=cols[-2], values=value)
+                        df.reset_index(inplace=True, drop=False)
+                    elif len(df) > 0:
+                        df = df.set_index(cols[0]).T.reset_index(drop=True)
+                    else:
+                        self._connect_error(
+                            f"unstack: >{unstack}< on 1-dimensional symbol with empty DataFrame not allowed."
+                        )
+                    df.rename_axis(
+                        [None], axis=1, inplace=True
+                    )  # remove column index names
+                    if self._trace > 2:
+                        self._cdb.print_log(f"DataFrame after unstack:\n{df}")
+
+                elif dim > 0:
+                    df.sort_values(df.columns[:-1].tolist(), inplace=True)
+                    if self._trace > 2:
+                        self._cdb.print_log(f"DataFrame after sort:\n{df}")
+                    if sym_type == "set" and skip_text:
+                        df = df.drop(columns="element_text")
+
+                writeFunction_args = {
+                    "name": table_name,
+                    "schema": schema,
+                    "if_exists": exists,
+                    "insertMethod": insertMethod,
+                    "columnEncloser": self._col_encloser,
+                    "dtype_map": dtype_map,
+                    "toSQLArguments": self._dict_get(sym, "toSQLArguments", {}),
+                    "index": False,
+                }
+
+                dim_after_unstack = None
+                if self._small and dim > 0:
+                    dim_after_unstack = dim - 1 if unstack else dim
+                    col = df.columns[:dim_after_unstack]
+                    df[col] = df[col].astype("int64")
+                    writeFunction_args.update({"name": f"[{table_name}$]"})
+
+                self._handler.write_dataframe(df, writeFunction_args)
+
+                post_write_args = {
+                    "tableName": table_name,
+                    "dim_after_unstack": dim_after_unstack,
+                    "colList": df.columns.tolist(),
+                    "dim": dim,
+                }
+                self._handler.post_write_procedures(
+                    **post_write_args
+                )  # only implemented for sqlite
+
+                if not self._sqlitewrite_globalCommit:
+                    self._handler.commit()
+
+            if self._sqlitewrite_globalCommit:
+                self._handler.commit()
+
+        except Exception:
+            self._handler.rollback()
+            raise
+
+        finally:
+            self._handler.close()

gams/connect/connectdatabase.py

@@ -0,0 +1,275 @@
+#
+# GAMS - General Algebraic Modeling System Python API
+#
+# Copyright (c) 2017-2026 GAMS Development Corp. <support@gams.com>
+# Copyright (c) 2017-2026 GAMS Software GmbH <support@gams.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+
+import importlib
+import sys
+import weakref
+import yaml
+from gams.connect.agents.connectagent import ConnectAgent
+from gams.connect.connectvalidator import ConnectValidator
+from gams.connect.errors import GamsConnectException
+from gams.control import GamsWorkspace
+from gams.transfer import Container
+
+
+class ConnectDatabase(object):
+    """
+    A ConnectDatabase contains data in the form of a gams.transfer.Container instance.
+    Running the execute() method instantiates Connect agents that read, write, or modify
+    symbol data.
+
+    Parameters
+    ----------
+    system_directory : str
+        GAMS system directory to be used.
+    container : gams.transfer.Container, optional
+        A Container to be used by the ConnectDatabase, by default None. If omitted, the ConnectDatabase will instantiate a new and empty container.
+    ecdb : gams.core.embedded.ECGAMSDatabase, optional
+        When running in a GAMS context (e.g. embedded code), this can be used to allow connection to the embedded code GAMS database, by default None.
+    """
+
+    def __init__(self, system_directory, container=None, ecdb=None):
+        self._system_directory = system_directory
+        self._ecdb = ecdb
+        self._schema_cache = {}
+        self._ws = GamsWorkspace(system_directory=self._system_directory)
+        if container is None:
+            self._container = Container(system_directory=self._system_directory)
+        else:
+            self._container = container
+        if self._ecdb:
+            ecdb._cdb = self
+
+    def __del__(self):
+        pass
+
+    def print_log(self, msg, end="\n"):
+        """
+        Print msg to the GAMS log if avaiable, uses print() otherwise.
+
+        Parameters
+        ----------
+        msg : str
+            The message to be printed.
+        end : str, optional
+            String to be put after the message, by default "\n".
+        """
+        if self._ecdb:
+            self._ecdb.printLog(msg, end)
+        else:
+            print(msg, end=end)
+            sys.stdout.flush()
+
+    def _get_agent_class(self, agent_name):
+        # Try to load the agent module from 'gams.connect.agents'
+        try:
+            mod = importlib.import_module("gams.connect.agents." + agent_name.lower())
+            err = None
+        except ModuleNotFoundError as e:
+            err = e
+        if err:
+            try:
+                if (
+                    err.name != "gams.connect.agents." + agent_name.lower()
+                ):  # the connect agent module itself was found but an import in the source itself did fail
+                    raise GamsConnectException(str(err), traceback=True)
+                mod = importlib.import_module(agent_name.lower())
+                err = None
+            except ModuleNotFoundError as e:
+                err = e
+
+        # Try to retrieve the agent class from the found module
+        if not err:
+            try:
+                agent_class = vars(mod)[agent_name]
+            except KeyError as e:
+                err = e
+
+        # Compile error in case of previous errors
+        if err:
+            msg = f"Connect agent '{agent_name}' not found. The following agents are available: {', '.join(self._get_available_agents())}."
+            raise GamsConnectException(msg)
+
+        return agent_class
+
+    def _get_idx_str(self, agent_name, idx_list):
+        idx_str = f"{agent_name}"
+        if idx_list:
+            idx_str += f"({idx_list[0]})"
+            for i in idx_list[1:]:
+                idx_str = f"PythonCode({i})" + "->" + idx_str
+        return idx_str
+
+    def _execute(self, instructions, idx_list=[]):
+        if isinstance(instructions, list):
+            if all(isinstance(inst, dict) for inst in instructions):
+                inst_list = instructions
+            else:
+                raise GamsConnectException(
+                    "Invalid data type for instructions argument. Needs to be 'list of dict'."
+                )
+        elif isinstance(instructions, dict):
+            inst_list = [instructions]
+        else:
+            raise GamsConnectException(
+                f"Invalid data type for instructions argument. Needs to be 'dict' or 'list', but was '{type(instructions).__name__}'."
+            )
+
+        agent_instances = []
+        for idx, inst in enumerate(inst_list, start=1):
+            root = list(inst.keys())
+            if len(root) != 1:
+                raise GamsConnectException(
+                    f"Invalid agent definition with {len(root)} agent names instead of 1."
+                )
+            agent_name = root[0]
+            if not isinstance(agent_name, str):
+                raise GamsConnectException(
+                    f"Invalid data type for agent name. Needs to be 'str', but was '{type(agent_name).__name__}'."
+                )
+
+            inst = inst[agent_name]
+
+            agent_class = self._get_agent_class(agent_name)
+            if not issubclass(agent_class, ConnectAgent):
+                raise GamsConnectException(
+                    f"Agent class '{agent_name}' has to be derived from gams.connect.agents.connectagent.ConnectAgent",
+                    traceback=True,
+                ) 
+
+            agent_schema = self.load_schema(agent_class.__name__)
+            v = ConnectValidator(agent_schema)
+            if not v.validate(inst):
+                raise GamsConnectException(
+                    f"Validation of instructions for agent {self._get_idx_str(agent_name, [idx] + idx_list)} failed: {v.errors}"
+                )
+            agent_instance = agent_class(self, inst, [idx] + idx_list)
+            agent_instances.append(agent_instance)
+
+        for idx, agent in enumerate(agent_instances, start=1):
+            agent.setup_log()
+            try:
+                execute_return = agent.execute()
+            except GamsConnectException:
+                raise
+            except Exception as e:
+                e.add_note(self._get_idx_str(agent._agent_name, agent._agent_index) + " failed")
+                raise
+            agent.restore_log()
+
+            if (
+                type(agent).__name__ == "PythonCode" and execute_return
+            ):  # PythonCode generated instructions
+                self._execute(execute_return, [idx] + idx_list)
+
+    def execute(self, instructions):
+        """
+        Instantiates and executes one or multiple Connect agents.
+
+        Parameters
+        ----------
+        instructions : list, dict
+            The instructions to be used for instantiating and executing the agents. Use list for executnig multiple agents and dict for a single one.
+
+        Raises
+        ----------
+        GamsConnectException
+            If the instructions are invalid or if the specified agent could not be loaded.
+        """
+        self._execute(instructions)
+
+    @property
+    def container(self):
+        return self._container
+
+    @property
+    def ecdb(self):
+        return self._ecdb
+
+    @property
+    def system_directory(self):
+        return self._system_directory
+
+    def _get_available_agents(self):
+        try:
+            agents = []
+            with importlib.resources.as_file(
+                importlib.resources.files("gams.connect.agents") / "schema"
+            ) as schema_path:
+                for f in schema_path.rglob('*.yaml'):
+                    if f.is_file():
+                        agents.append(f.name.split(".")[0])
+            return agents
+        except:
+            return []
+
+    #def _get_close_agent(self, agent_name):
+    #    import difflib
+    #    agents = self._get_available_agents()
+    #    agents = {a.lower(): a for a in agents}  # use case-insensitive comparison since otherwise "csvwriter" -> "ExcelWriter" instead of "CSVWriter
+    #    m = difflib.get_close_matches(agent_name.lower(), agents.keys(), n=1, cutoff=0.7)
+    #    return agents[m[0]] if m else None
+
+    def load_schema(self, agent):
+        """
+        Returns the cerberus schema for a specific agent as Python data structure.
+
+        Parameters
+        ----------
+        agent : str, ConnectAgent
+            Either the name of the Connect agent or the ConnectAgent instance itself.
+
+        Returns
+        -------
+        dict
+            Python data structure to be used for validation to ensure correct format of instructions given to a Connect agent.
+        """
+
+        if isinstance(agent, str):
+            agent_name = agent
+        elif isinstance(agent, ConnectAgent):
+            agent_name = agent.__class__.__name__
+        else:
+            raise GamsConnectException(
+                f"Parameter 'agent' needs to be of type str or ConnectAgent, but was {type(agent)}."
+            )
+        with importlib.resources.as_file(
+            importlib.resources.files("gams.connect.agents") / "schema"
+        ) as schema_path:
+            schema_file = schema_path / (agent_name + ".yaml")
+            fstat = schema_file.stat()
+            mtime = fstat.st_mtime
+            size = fstat.st_size
+            if (
+                agent_name in self._schema_cache
+                and mtime == self._schema_cache[agent_name]["mtime"]
+                and size == self._schema_cache[agent_name]["size"]
+            ):
+                schema = self._schema_cache[agent_name]["schema"]
+            else:
+                schema = schema_file.read_text()
+                schema = yaml.safe_load(schema)
+                self._schema_cache[agent_name] = {"schema": schema, "mtime": mtime, "size": size}
+        return schema

gams/connect/connectvalidator.py

@@ -0,0 +1,93 @@
+#
+# GAMS - General Algebraic Modeling System Python API
+#
+# Copyright (c) 2017-2026 GAMS Development Corp. <support@gams.com>
+# Copyright (c) 2017-2026 GAMS Software GmbH <support@gams.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+
+from cerberus import Validator
+from cerberus.platform import Hashable
+
+
+class ConnectValidator(Validator):
+
+    def __init__(self, *args, **kwargs):
+        super(ConnectValidator, self).__init__(*args, **kwargs)
+
+    # Custom validator that does not consider null values when validating excludes rule
+    def _validate_excludes(self, excluded_fields, field, value):
+        """{'type': ('hashable', 'list'), 'schema': {'type': 'hashable'}}"""
+        if isinstance(excluded_fields, Hashable):
+            excluded_fields = [excluded_fields]
+
+        # get all fields from excluded_fields which values are not None
+        not_none_fields = [
+            ef
+            for ef in excluded_fields
+            # if self.document.get(ef) != self.schema[ef]["default"]
+            if self.document.get(ef) is not None
+        ]
+        # if value == self.schema[field]["default"]:
+        if value is None:  # None value is considered to be the same as missing
+            if (
+                not_none_fields
+            ):  # if all other fields are None or missing as well, we can skip validation
+                return
+
+        # if not_none_fields has values, then we want to get the default behavior for those fields only
+        super()._validate_excludes(not_none_fields, field, value)
+
+    def normalize_of_rules(self, document):
+        """
+        Perform normalization of 'anyof' and 'oneof' on the first
+        level of the document only. The implementation looks for 'anyof' and 'oneof'
+        in the schema and finds the first sub schema that matches. This needs to be
+        considered especially for 'anyof' since multiple sub schemas are allowed to
+        match. The determined sub schema will be used to perform the normalization.
+        :param document: the document to be normalized
+        :return: the normalized document
+        """
+
+        document_copy = dict(document)
+        for k, v in self.schema.items():
+            if document[k] is not None:
+                is_list = v.get("type") == "list"
+                of_rule = v
+                if is_list:
+                    of_rule = of_rule.get("schema", {})
+                of_rule = of_rule.get("anyof", of_rule.get("oneof"))
+                if of_rule is not None:
+                    document_copy[k] = []
+                    if is_list:
+                        doc_list = [{k: x} for x in document[k]]
+                    else:
+                        doc_list = [{k: document[k]}]
+                    for sub_doc in doc_list:
+                        for sub_schema in of_rule:
+                            new_schema = {k: sub_schema}
+                            v = ConnectValidator(new_schema)
+                            sub_doc_normalized = v.validated(sub_doc)
+                            if sub_doc_normalized is not None:
+                                if is_list:
+                                    document_copy[k].append(sub_doc_normalized[k])
+                                else:
+                                    document_copy[k] = sub_doc_normalized[k]
+        return document_copy

gams/connect/errors.py

@@ -0,0 +1,34 @@
+#
+# GAMS - General Algebraic Modeling System Python API
+#
+# Copyright (c) 2017-2026 GAMS Development Corp. <support@gams.com>
+# Copyright (c) 2017-2026 GAMS Software GmbH <support@gams.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+
+import sys
+
+
+class GamsConnectException(Exception):
+    def __init__(self, message, traceback=False):
+        super().__init__(message)
+        self.traceback = traceback
+        if not self.traceback:
+            sys.tracebacklimit = 0