Merge branch 'develop' into bugfix-469-add_missing_column_to_table

.pre-commit-config.yaml

@@ -3,4 +3,4 @@ repos:
     rev: 22.6.0
     hooks:
       - id: black
-        language_version: python3.10
+        language_version: python3.10

CHANGELOG.md

@@ -10,10 +10,14 @@ and the versioning aims to respect [Semantic Versioning](http://semver.org/spec/
 ### Added
 - User-defined output path for csv, xml, database [#402](https://github.com/OpenEnergyPlatform/open-MaStR/pull/402)
 - Add date=existing parameter to Mastr.download [#452](https://github.com/OpenEnergyPlatform/open-MaStR/pull/452)
-- Adapt column names to the API web service update [#472](https://github.com/OpenEnergyPlatform/open-MaStR/pull/472)
+- Replace values in ArtDerFlaecheIds with their entries from katalogwerte [#464](https://github.com/OpenEnergyPlatform/open-MaStR/pull/464)
+- Add a Mastr.translate method for english translation [##471](https://github.com/OpenEnergyPlatform/open-MaStR/pull/471)
+
 ### Changed
 - Using sphinx version <7 to build documentation [#454](https://github.com/OpenEnergyPlatform/open-MaStR/pull/454)
 - Get missing column names in xml download in a robust way [#470](https://github.com/OpenEnergyPlatform/open-MaStR/pull/470)
+- Adapt column names to the API web service update [#472](https://github.com/OpenEnergyPlatform/open-MaStR/pull/472)
+- 
 ### Removed
 - Delete `on push` for github workflow [#445](https://github.com/OpenEnergyPlatform/open-MaStR/pull/445)
 

environment.yml

@@ -1,6 +1,6 @@
-name: py38_open_mastr
+name: py310_open_mastr
 channels:
     - conda-forge
     - defaults
 dependencies:
-    - python=3.8
+    - python=3.10

open_mastr/mastr.py

@@ -1,4 +1,5 @@
 import os
+from sqlalchemy import inspect, create_engine
 
 # import xml dependencies
 from open_mastr.xml_download.utils_download_bulk import download_xml_Mastr
@@ -35,6 +36,8 @@
 # import initialize_database dependencies
 from open_mastr.utils.helpers import (
     create_database_engine,
+    rename_table,
+    create_translated_database_engine,
 )
 
 # constants
@@ -62,16 +65,28 @@ class Mastr:
     ------------
         engine: {'sqlite', sqlalchemy.engine.Engine}, optional
             Defines the engine of the database where the MaStR is mirrored to. Default is 'sqlite'.
+
+        connect_to_translated_db: boolean, optional
+            Allows connection to an existing translated database. Default is 'False'.
+            Only for 'sqlite'-type engines.
     """
 
-    def __init__(self, engine="sqlite") -> None:
+    def __init__(self, engine="sqlite", connect_to_translated_db=False) -> None:
+
         validate_parameter_format_for_mastr_init(engine)
+
         self.output_dir = get_output_dir()
         self.home_directory = get_project_home_dir()
         self._sqlite_folder_path = os.path.join(self.output_dir, "data", "sqlite")
         os.makedirs(self._sqlite_folder_path, exist_ok=True)
 
-        self.engine = create_database_engine(engine, self.output_dir)
+        self.is_translated = connect_to_translated_db
+        if connect_to_translated_db:
+            self.engine = create_translated_database_engine(
+                engine, self._sqlite_folder_path
+            )
+        else:
+            self.engine = create_database_engine(engine, self.home_directory)
 
         print(
             f"Data will be written to the following database: {self.engine.url}\n"
@@ -192,6 +207,13 @@ def download(
             "location_elec_generation", "location_elec_consumption", "location_gas_generation",
             "location_gas_consumption". Defaults to all.
         """
+
+        if self.is_translated:
+            raise TypeError(
+                "you are currently connected to a translated database\n"
+                "a translated database cannot be further altered\n"
+                "translate a new database to replace the current one"
+            )
 
         validate_parameter_format_for_download_method(
             method=method,
@@ -365,3 +387,59 @@ def to_csv(
         # FIXME: Currently metadata is only created for technology data, Fix in #386
         # Configure and save data package metadata file along with data
         # save_metadata(data=technologies_to_export, engine=self.engine)
+
+    def translate(self) -> None:
+        """
+        A database can be translated only once.
+
+        Deletes translated versions of the currently connected database.
+
+        Translates currently connected database,renames it with '-translated'
+        suffix and updates self.engine's path accordingly.
+
+        !!! example
+            ```python
+
+            from open_mastr import Mastr
+            import pandas as pd
+
+            db = Mastr()
+            db.download(data='biomass')
+            db.translate()
+
+            df = pd.read_sql(table='biomass_extended', con=db.engine)
+            print(df.head(10))
+            ```
+
+        """
+
+        if "sqlite" not in self.engine.dialect.name:
+            raise ValueError("engine has to be of type 'sqlite'")
+        if self.is_translated:
+            raise TypeError("the currently connected database is already translated")
+
+        inspector = inspect(self.engine)
+        old_path = r"{}".format(self.engine.url.database)
+        new_path = old_path[:-3] + "-translated.db"
+
+        if os.path.exists(new_path):
+            try:
+                os.remove(new_path)
+            except Exception as e:
+                print(f"An error occurred: {e}")
+
+            print("Replacing previous version of the translated database...")
+
+        for table in inspector.get_table_names():
+            rename_table(table, inspector.get_columns(table), self.engine)
+
+        self.engine.dispose()
+
+        try:
+            os.rename(old_path, new_path)
+            print(f"Database '{old_path}' changed to '{new_path}'")
+        except Exception as e:
+            print(f"An error occurred: {e}")
+
+        self.engine = create_engine(f"sqlite:///{new_path}")
+        self.is_translated = True