pandahub 0.3.16__zip → 0.4.0__zip

{pandahub-0.3.16 → pandahub-0.4.0}/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Change Log
 
+## [0.4.0]
+    - IMPROVED: pandapower 3.0 support
+
 ## [0.3.13]
     - FIXED: fetching integer index on empty collection
     - IMPROVED: context manager for mongo client /database / collection

{pandahub-0.3.16 → pandahub-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pandahub
-Version: 0.3.16
+Version: 0.4.0
 Summary: Data hub for pandapower and pandapipes networks based on MongoDB
 Author-email: Jan Ulffers <jan.ulffers@iee.fraunhofer.de>, Leon Thurner <leon.thurner@retoflow.de>, Jannis Kupka <jannis.kupka@retoflow.de>, Mike Vogt <mike.vogt@iee.fraunhofer.de>, Joschka Thurner <joschka.thurner@retoflow.de>, Alexander Scheidler <alexander.scheidler@iee.fraunhofer.de>
 License: Copyright (c) 2022 by University of Kassel, Fraunhofer Institute for Energy Economics
@@ -59,7 +59,7 @@ Provides-Extra: test
 Provides-Extra: all
 License-File: LICENSE
 
-[![pandapower](https://www.pandapower.org/images/pp.svg)](https://www.pandapower.org)         [![pandapipes](https://www.pandapipes.org/images/pp.svg)](https://www.pandapipes.org)
+from lib import get_mongo_client[![pandapower](https://www.pandapower.org/images/pp.svg)](https://www.pandapower.org)         [![pandapipes](https://www.pandapipes.org/images/pp.svg)](https://www.pandapipes.org)
 
 [![pandahub](https://badge.fury.io/py/pandahub.svg)](https://pypi.org/project/pandahub/) [![pandahub](https://img.shields.io/pypi/pyversions/pandahub.svg)](https://pypi.org/project/pandahub/) [![pandahub](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/e2nIEE/pandahub/blob/master/LICENSE)
 
@@ -75,3 +75,45 @@ Swagger UI is available at http://localhost:8002/docs.
 
 If you develop on the library and do not need the fastapi app, `docker compose up db -d` starts only the mongodb
 container.
+
+## MongoClient handling
+
+You can supply a mongodb connection string (or the host as connection string and user/password separately) either as arguments to PandaHub
+or by setting the following environment variables:
+
+* MONGODB_URL
+* MONGODB_USER (optional)
+* MONGODB_PASSWORD (optional)
+
+These values are then used as default arguments when creating a PandaHub object.
+
+By default, each instantiation of a PandaHub instance will create a new MongoClient instance. This is fine for interactive use or small scripts. To clean up the mongo client, call `ph.close()` on the instance once you are done with it.
+
+When running the pandahub API as a web application, provide database credentials through the environment variables and additionally set `PANDAHUB_GLOBAL_DB_CLIENT` to `true`.
+A single, global mongodb client instance per process will then be used for all PandaHub instantiations, as recommended by [pymongo](https://pymongo.readthedocs.io/en/stable/faq.html#how-does-connection-pooling-work-in-pymongo).
+
+You can use the following properties to access database resources from a PandaHub object:
+
+* *ph.project_db*: database of the activated project (e.g. `ph.project_db.net_bus.find().to_list()`)
+* *ph.mgmt_db*: the user_management database
+* *ph.users_collection*: the users collection from the management database
+* *ph.projects_collection*: the projects collection from the management database
+
+
+In case you want to access the database but do not need a PandaHub object, there are two convenience functions available:
+
+```python
+from pandahub.lib import get_mongo_client
+
+my_collection = get_mongo_client("db", "collection")
+docs = collection.find().to_list()
+```
+`PANDAHUB_GLOBAL_DB_CLIENT` is respected, you either get the global client or a fresh instance, in which case you are responsible for cleaning up the connection.
+
+```python
+from pandahub.lib import mongo_client
+
+with mongo_client("db", "my_collection") as collection:
+    docs = collection.find().to_list()
+```
+With the context manager, a new MongoClient is created (even if `PANDAHUB_GLOBAL_DB_CLIENT` is `true`) and closed on completion of the with block.

pandahub-0.4.0/README.md

@@ -0,0 +1,58 @@
+from lib import get_mongo_client[![pandapower](https://www.pandapower.org/images/pp.svg)](https://www.pandapower.org)         [![pandapipes](https://www.pandapipes.org/images/pp.svg)](https://www.pandapipes.org)
+
+[![pandahub](https://badge.fury.io/py/pandahub.svg)](https://pypi.org/project/pandahub/) [![pandahub](https://img.shields.io/pypi/pyversions/pandahub.svg)](https://pypi.org/project/pandahub/) [![pandahub](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/e2nIEE/pandahub/blob/master/LICENSE)
+
+pandahub is a data hub for pandapower and pandapipes networks based on MongoDB. It allows you to store pandapower and
+pandapipes networks as well as timeseries in a MongoDB. pandahub allows you to access the database directly through the PandaHub class,
+but also provides a REST-API based on FastAPI. Access through the API is managed with a user management implementation based on FastAPI Users.
+
+## Development
+`docker compose up -d` runs a mongodb container alongside a pandahub api instance with live reload available
+at http://localhost:8002. To connect to an existing database instead, set `MONGODB_URL` to the connection string through an environment variable / in you `.env` file.
+
+Swagger UI is available at http://localhost:8002/docs.
+
+If you develop on the library and do not need the fastapi app, `docker compose up db -d` starts only the mongodb
+container.
+
+## MongoClient handling
+
+You can supply a mongodb connection string (or the host as connection string and user/password separately) either as arguments to PandaHub
+or by setting the following environment variables:
+
+* MONGODB_URL
+* MONGODB_USER (optional)
+* MONGODB_PASSWORD (optional)
+
+These values are then used as default arguments when creating a PandaHub object.
+
+By default, each instantiation of a PandaHub instance will create a new MongoClient instance. This is fine for interactive use or small scripts. To clean up the mongo client, call `ph.close()` on the instance once you are done with it.
+
+When running the pandahub API as a web application, provide database credentials through the environment variables and additionally set `PANDAHUB_GLOBAL_DB_CLIENT` to `true`.
+A single, global mongodb client instance per process will then be used for all PandaHub instantiations, as recommended by [pymongo](https://pymongo.readthedocs.io/en/stable/faq.html#how-does-connection-pooling-work-in-pymongo).
+
+You can use the following properties to access database resources from a PandaHub object:
+
+* *ph.project_db*: database of the activated project (e.g. `ph.project_db.net_bus.find().to_list()`)
+* *ph.mgmt_db*: the user_management database
+* *ph.users_collection*: the users collection from the management database
+* *ph.projects_collection*: the projects collection from the management database
+
+
+In case you want to access the database but do not need a PandaHub object, there are two convenience functions available:
+
+```python
+from pandahub.lib import get_mongo_client
+
+my_collection = get_mongo_client("db", "collection")
+docs = collection.find().to_list()
+```
+`PANDAHUB_GLOBAL_DB_CLIENT` is respected, you either get the global client or a fresh instance, in which case you are responsible for cleaning up the connection.
+
+```python
+from pandahub.lib import mongo_client
+
+with mongo_client("db", "my_collection") as collection:
+    docs = collection.find().to_list()
+```
+With the context manager, a new MongoClient is created (even if `PANDAHUB_GLOBAL_DB_CLIENT` is `true`) and closed on completion of the with block.

{pandahub-0.3.16 → pandahub-0.4.0}/pandahub/api/internal/settings.py

@@ -58,3 +58,4 @@ DEBUG = settings_bool("DEBUG", default=False)
 PANDAHUB_SERVER_URL = get_os_env("PANDAHUB_SERVER_URL", "0.0.0.0")
 PANDAHUB_SERVER_PORT = int(get_os_env('PANDAHUB_SERVER_PORT', 8002))
 WORKERS = int(get_os_env('WORKER', 2))
+PANDAHUB_GLOBAL_DB_CLIENT = settings_bool("PANDAHUB_GLOBAL_DB_CLIENT", default=False)

{pandahub-0.3.16 → pandahub-0.4.0}/pandahub/lib/PandaHub.py

@@ -27,19 +27,19 @@ import pandapower as pp
 import pandapower.io_utils as io_pp
 
 from pandahub.api.internal.settings import MONGODB_URL, MONGODB_USER, MONGODB_PASSWORD, MONGODB_GLOBAL_DATABASE_URL, \
-    MONGODB_GLOBAL_DATABASE_USER, MONGODB_GLOBAL_DATABASE_PASSWORD, CREATE_INDEXES_WITH_PROJECT
+    MONGODB_GLOBAL_DATABASE_USER, MONGODB_GLOBAL_DATABASE_PASSWORD, CREATE_INDEXES_WITH_PROJECT, PANDAHUB_GLOBAL_DB_CLIENT
 from pandahub.lib.database_toolbox import (
     create_timeseries_document,
     convert_timeseries_to_subdocuments,
     convert_element_to_dict,
-    get_mongo_client,
     json_to_object,
     serialize_object_data,
     get_dtypes,
     decompress_timeseries_data,
     convert_geojsons,
-    get_metadata_for_timeseries_collections
+    get_metadata_for_timeseries_collections,
 )
+from pandahub.lib import get_mongo_client
 from pandahub.lib.mongodb_indexes import MONGODB_INDEXES
 
 logger = logging.getLogger(__name__)
@@ -102,7 +102,11 @@ class PandaHub:
     ):
         self._datatypes = datatypes
         self.mongodb_indexes = mongodb_indexes
-        self.mongo_client = get_mongo_client(connection_url, connection_user, connection_password)
+        self.mongo_client = get_mongo_client(
+            connection_url=connection_url,
+            connection_user=connection_user,
+            connection_password=connection_password,
+        )
         self.mongo_client_global_db = None
         self.active_project = None
         self.user_id = user_id
@@ -117,6 +121,27 @@ class PandaHub:
         if check_server_available:
             self.server_is_available()
 
+
+    @property
+    def project_db(self) -> Database:
+        """Get the database of the current active project"""
+        return self.get_project_database()
+
+    @property
+    def mgmt_db(self) -> Database:
+        """Get the user_management database"""
+        return self.mongo_client["user_management"]
+
+    @property
+    def users_collection(self) -> Collection:
+        """Get the users collection"""
+        return self.mongo_client["user_management"]["users"]
+
+    @property
+    def projects_collection(self) -> Collection:
+        """Get the projects collection"""
+        return self.mongo_client["user_management"]["projects"]
+
     # -------------------------
     # Database connection checks
     # -------------------------
@@ -150,6 +175,12 @@ class PandaHub:
         except ServerSelectionTimeoutError as e:
             return "connection timeout"
 
+    def close(self, force=False):
+        """Close the database connection."""
+        if PANDAHUB_GLOBAL_DB_CLIENT and not force:
+            msg = "Closing the global MongoClient instance will break all subsequent database connections. If this is intentional, use force=True"
+            raise PandaHubError(msg)
+        self.mongo_client.close()
     # -------------------------
     # Permission check
     # -------------------------
@@ -272,7 +303,7 @@ class PandaHub:
         if realm is not None:
             filter_dict["realm"] = realm
         db = self.mongo_client["user_management"]
-        projects = list(db["projects"].find(filter_dict))
+        projects = db["projects"].find(filter_dict).to_list()
         return [
             {
                 "id": str(p["_id"]),
@@ -401,8 +432,7 @@ class PandaHub:
         return project is not None
 
     def _get_project_document(self, filter_dict: dict) -> Optional[dict]:
-        project_collection = self.mongo_client["user_management"].projects
-        projects = list(project_collection.find(filter_dict))
+        projects = self.projects_collection.find(filter_dict).to_list()
         if len(projects) == 0:  # project doesn't exist
             return None
         if len(projects) > 1:
@@ -437,8 +467,12 @@ class PandaHub:
         -------
         pymongo.database.Database
         """
+        if self.active_project is None:
+            msg = "Can not access project database - no project active!"
+            raise PandaHubError(msg)
+        project_id = str(self.active_project["_id"])
         if collection is None:
-            return self.mongo_client[str(self.active_project["_id"])]
+            return self.mongo_client[project_id]
         logger.warning(f"Passing a collection to get_project_database is deprecated. Use get_project_collection instead!")
         return self.get_project_collection(collection)
 
@@ -487,8 +521,6 @@ class PandaHub:
         list
             network ids
         """
-        if not self.active_project:
-            raise PandaHubError("No project activated!")
         return self.get_project_collection("_networks").find({}, {"_id:": 1}).distinct("_id")
 
     def get_project_version(self):
@@ -503,7 +535,7 @@ class PandaHub:
             return
 
         if version.parse(self.get_project_version()) < version.parse("0.2.3"):
-            db = self._get_project_database()
+            db = self.project_db
             all_collection_names = db.list_collection_names()
             old_net_collections = [
                 name
@@ -516,9 +548,7 @@ class PandaHub:
             for element in old_net_collections:
                 db[element].rename(self._collection_name_of_element(element))
             # for all networks
-            for d in list(
-                db["_networks"].find({}, projection={"sector": 1, "data": 1})
-            ):
+            for d in db["_networks"].find({}, projection={"sector": 1, "data": 1}).to_list():
                 # load old format
                 if d.get("sector", "power") == "power":
                     data = dict(
@@ -729,7 +759,7 @@ class PandaHub:
             self.set_active_project_by_id(project_id)
         self.check_permission("read")
         db = self._get_project_database()
-        return list(db["_networks"].find())
+        return db["_networks"].find().to_list()
 
 
     def get_network_by_name(
@@ -1241,11 +1271,11 @@ class PandaHub:
         proj = {"net": 0}
         if not load_area:
             proj["area_geojson"] = 0
-        nets = pd.DataFrame(list(db.find(fi, projection=proj)))
+        nets = pd.DataFrame(db.find(fi, projection=proj)).to_list()
         return nets
 
     def _get_net_id_from_name(self, name, db):
-        metadata = list(db["_networks"].find({"name": name}))
+        metadata = db["_networks"].find({"name": name}).to_list()
         if len(metadata) > 1:
             msg = (f"Multiple networks with the name {metadata[0]['name']} found in the database. "
                    f"Use the corresponding function which selects the network by net_id instead.")
@@ -1302,9 +1332,7 @@ class PandaHub:
             else:
                 filter_dict = {**filter_dict, **filter}
 
-        data = list(
-            db[self._collection_name_of_element(element_type)].find(filter_dict)
-        )
+        data = db[self._collection_name_of_element(element_type)].find(filter_dict).to_list()
         if len(data) == 0:
             return
         if dtypes is None:
@@ -1344,17 +1372,12 @@ class PandaHub:
         if project_id:
             self.set_active_project_by_id(project_id)
         self.check_permission("write")
-        db = self._get_project_database()
 
         collection = self._collection_name_of_element(element_type)
         dtypes = self._datatypes.get(element_type)
 
         variant_filter = self.get_variant_filter(variant)
-        documents = list(
-            db[collection].find(
-                {"index": element_index, "net_id": net_id, **variant_filter}
-            )
-        )
+        documents = self.projects_collection[collection].find({"index": element_index, "net_id": net_id, **variant_filter}).to_list()
         if len(documents) == 1:
             document = documents[0]
         else:
@@ -1446,7 +1469,7 @@ class PandaHub:
             **self.get_variant_filter(variant),
         }
 
-        deletion_targets = list(db[collection].find(element_filter))
+        deletion_targets = db[collection].find(element_filter).to_list()
         if not deletion_targets:
             return []
 
@@ -1554,7 +1577,7 @@ class PandaHub:
             value = dtypes[parameter](value)
         collection = self._collection_name_of_element(element_type)
 
-        js = list(db[collection].find({"index": element_index, "net_id": net_id}))[0]
+        js = db[collection].find({"index": element_index, "net_id": net_id}).to_list(1)
         obj = json_to_object(js["object"])
         setattr(obj, parameter, value)
         db[collection].update_one(
@@ -2419,7 +2442,7 @@ class PandaHub:
             if not include_metadata:
                 pipeline.append({"$project": {"timeseries_data": 1,
                                               "num_timestamps": 1}})
-        data = list(db[collection_name].aggregate(pipeline))
+        data = db[collection_name].aggregate(pipeline).to_list()
         if len(data) == 0:
             raise PandaHubError("no documents matching the provided filter found", 404)
         elif len(data) > 1:
@@ -2532,7 +2555,7 @@ class PandaHub:
                 pipeline.append({"$match": {"$and": match_filter}})
             projection = {"$project": {"timeseries_data": 0}}
             pipeline.append(projection)
-        metadata = list(db[collection_name].aggregate(pipeline))
+        metadata = db[collection_name].aggregate(pipeline).to_list()
         df_metadata = pd.DataFrame(metadata)
         if len(df_metadata):
             df_metadata.set_index("_id", inplace=True)
@@ -3086,7 +3109,7 @@ class PandaHub:
         global_database=False,
     ):
         db = self._get_project_or_global_db(project_id, global_database)
-        collections = list(db.list_collections(filter={"name": collection_name}))
+        collections = db.list_collections(filter={"name": collection_name}).to_list()
         return len(collections) == 1 and collections[0]["type"] == "timeseries"
 
     def _get_project_or_global_db(self, project_id=None, global_database=False):

pandahub-0.4.0/pandahub/lib/__init__.py

@@ -0,0 +1 @@
+from pandahub.lib.mongo_client import mongo_client, get_mongo_client

{pandahub-0.3.16 → pandahub-0.4.0}/pandahub/lib/database_toolbox.py

@@ -1,14 +1,8 @@
 # -*- coding: utf-8 -*-
-from contextlib import contextmanager
-from collections.abc import Iterator
 
 import numpy as np
 import pandas as pd
-from pymongo import MongoClient
-from pymongo.database import Database
-from pymongo.collection import Collection
 
-from pandahub.api.internal.settings import MONGODB_URL, MONGODB_USER, MONGODB_PASSWORD
 from pandahub.lib.datatypes import DATATYPES
 import base64
 import hashlib
@@ -428,55 +422,6 @@ def migrate_userdb_to_beanie(ph):
                  {'$out': 'users'}]
     userdb.aggregate(migration)
 
-def get_mongo_client(connection_url: str = MONGODB_URL, connection_user: str = MONGODB_USER,
-                     connection_password: str = MONGODB_PASSWORD) -> MongoClient:
-    mongo_client_args = {
-        "host": connection_url,
-        "uuidRepresentation": "standard",
-        "connect": False,
-    }
-    if connection_user:
-        mongo_client_args |= {
-            "username": connection_user,
-            "password": connection_password,
-        }
-    return MongoClient(**mongo_client_args)
-
-@contextmanager
-def mongo_client(database: str | None = None, collection: str | None = None, connection_url: str = MONGODB_URL,
-                 connection_user: str = MONGODB_USER, connection_password: str = MONGODB_PASSWORD) -> Iterator[MongoClient | Database | Collection]:
-    """Contextmanager for pymongo MongoClient / Database / Collection with close after use.
-
-    Parameters
-    ----------
-    database: str or None
-        The database to connect to
-    collection: str or None
-        The collection to connect to
-    connection_url: str or None
-        Defaults to MONGODB_URL env var
-    connection_user: str or None
-        Defaults to MONGODB_USER env var
-    connection_password: str or None
-        Defaults to MONGODB_PASSWORD env var
-
-    Returns
-    -------
-        Contextmanager yielding MongoClient / Database / Collection
-    """
-    if collection is not None and database is None:
-        raise ValueError("Must specify database to access a collection!")
-    client = get_mongo_client(connection_url, connection_user, connection_password)
-    try:
-        if database is not None and collection is not None:
-            yield client[database][collection]
-        elif database is not None:
-            yield client[database]
-        else:
-            yield client
-    finally:
-        client.close()
-
 
 def get_metadata_for_timeseries_collections(db, data_type=None, net_id=None, element_type=None, element_index=None, **kwargs):
         if element_type is None:

{pandahub-0.3.16 → pandahub-0.4.0}/pandahub/lib/datatypes.py

@@ -7,7 +7,8 @@ DATATYPES = {
         "zone": str,
         "in_service": bool,
         "max_vm_pu": float,
-        "min_vm_pu": float
+        "min_vm_pu": float,
+        "geo": object
     },
     "load": {
         "name": str,
@@ -95,7 +96,8 @@ DATATYPES = {
         "type": str,
         "in_service": bool,
         "max_loading_percent": float,
-        "std_type": str
+        "std_type": str,
+        "geo": object
     },
     "trafo": {
         "name": str,
@@ -306,12 +308,4 @@ DATATYPES = {
         'initial_run': bool,
         "recycle": str
     },
-    "line_geodata": {
-        "coords": object
-    },
-    "bus_geodata": {
-        "x": float,
-        "y": float,
-        "coords": object
-    },
 }

pandahub-0.4.0/pandahub/lib/mongo_client.py

@@ -0,0 +1,78 @@
+from contextlib import contextmanager
+from typing import Iterator
+
+from pymongo import MongoClient
+from pymongo.synchronous.collection import Collection
+from pymongo.synchronous.database import Database
+
+from pandahub.api.internal.settings import PANDAHUB_GLOBAL_DB_CLIENT, MONGODB_URL, MONGODB_USER, MONGODB_PASSWORD
+
+def _get_mongo_client(connection_url: str = MONGODB_URL, connection_user: str = MONGODB_USER,
+                     connection_password: str = MONGODB_PASSWORD) -> MongoClient:
+    mongo_client_args = {
+        "host": connection_url,
+        "uuidRepresentation": "standard",
+        "connect": False,
+    }
+    if connection_user:
+        mongo_client_args |= {
+            "username": connection_user,
+            "password": connection_password,
+        }
+    return MongoClient(**mongo_client_args)
+
+if PANDAHUB_GLOBAL_DB_CLIENT:
+    _global_mongo_client = _get_mongo_client(connection_url=MONGODB_URL, connection_user = MONGODB_USER, connection_password = MONGODB_PASSWORD)
+else:
+    _global_mongo_client = None
+
+
+def get_mongo_client(database: str | None = None, collection: str | None = None, connection_url: str = MONGODB_URL, connection_user: str = MONGODB_USER,
+                     connection_password: str = MONGODB_PASSWORD) -> Iterator[MongoClient | Database | Collection]:
+    if collection is not None and database is None:
+        raise ValueError("Must specify database to access a collection!")
+    if _global_mongo_client is None:
+        client = _get_mongo_client(connection_url, connection_user, connection_password)
+    else:
+        client = _global_mongo_client
+    return _get_db_or_coll(client, database, collection)
+
+
+@contextmanager
+def mongo_client(database: str | None = None, collection: str | None = None, connection_url: str = MONGODB_URL,
+                 connection_user: str = MONGODB_USER, connection_password: str = MONGODB_PASSWORD) -> Iterator[MongoClient | Database | Collection]:
+    """Contextmanager for pymongo MongoClient / Database / Collection with close after use.
+
+    Parameters
+    ----------
+    database: str or None
+        The database to connect to
+    collection: str or None
+        The collection to connect to
+    connection_url: str or None
+        Defaults to MONGODB_URL env var
+    connection_user: str or None
+        Defaults to MONGODB_USER env var
+    connection_password: str or None
+        Defaults to MONGODB_PASSWORD env var
+
+    Returns
+    -------
+        Contextmanager yielding MongoClient / Database / Collection
+    """
+    if collection is not None and database is None:
+        raise ValueError("Must specify database to access a collection!")
+    client = _get_mongo_client(connection_url, connection_user, connection_password)
+    try:
+        yield _get_db_or_coll(client, database, collection)
+    finally:
+        client.close()
+
+
+def _get_db_or_coll(client: MongoClient, database: str | None = None, collection: str | None = None) -> Iterator[MongoClient | Database | Collection]:
+    if database is not None and collection is not None:
+        return client[database][collection]
+    elif database is not None:
+        return client[database]
+    else:
+        return client

{pandahub-0.3.16 → pandahub-0.4.0}/pandahub.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pandahub
-Version: 0.3.16
+Version: 0.4.0
 Summary: Data hub for pandapower and pandapipes networks based on MongoDB
 Author-email: Jan Ulffers <jan.ulffers@iee.fraunhofer.de>, Leon Thurner <leon.thurner@retoflow.de>, Jannis Kupka <jannis.kupka@retoflow.de>, Mike Vogt <mike.vogt@iee.fraunhofer.de>, Joschka Thurner <joschka.thurner@retoflow.de>, Alexander Scheidler <alexander.scheidler@iee.fraunhofer.de>
 License: Copyright (c) 2022 by University of Kassel, Fraunhofer Institute for Energy Economics
@@ -59,7 +59,7 @@ Provides-Extra: test
 Provides-Extra: all
 License-File: LICENSE
 
-[![pandapower](https://www.pandapower.org/images/pp.svg)](https://www.pandapower.org)         [![pandapipes](https://www.pandapipes.org/images/pp.svg)](https://www.pandapipes.org)
+from lib import get_mongo_client[![pandapower](https://www.pandapower.org/images/pp.svg)](https://www.pandapower.org)         [![pandapipes](https://www.pandapipes.org/images/pp.svg)](https://www.pandapipes.org)
 
 [![pandahub](https://badge.fury.io/py/pandahub.svg)](https://pypi.org/project/pandahub/) [![pandahub](https://img.shields.io/pypi/pyversions/pandahub.svg)](https://pypi.org/project/pandahub/) [![pandahub](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/e2nIEE/pandahub/blob/master/LICENSE)
 
@@ -75,3 +75,45 @@ Swagger UI is available at http://localhost:8002/docs.
 
 If you develop on the library and do not need the fastapi app, `docker compose up db -d` starts only the mongodb
 container.
+
+## MongoClient handling
+
+You can supply a mongodb connection string (or the host as connection string and user/password separately) either as arguments to PandaHub
+or by setting the following environment variables:
+
+* MONGODB_URL
+* MONGODB_USER (optional)
+* MONGODB_PASSWORD (optional)
+
+These values are then used as default arguments when creating a PandaHub object.
+
+By default, each instantiation of a PandaHub instance will create a new MongoClient instance. This is fine for interactive use or small scripts. To clean up the mongo client, call `ph.close()` on the instance once you are done with it.
+
+When running the pandahub API as a web application, provide database credentials through the environment variables and additionally set `PANDAHUB_GLOBAL_DB_CLIENT` to `true`.
+A single, global mongodb client instance per process will then be used for all PandaHub instantiations, as recommended by [pymongo](https://pymongo.readthedocs.io/en/stable/faq.html#how-does-connection-pooling-work-in-pymongo).
+
+You can use the following properties to access database resources from a PandaHub object:
+
+* *ph.project_db*: database of the activated project (e.g. `ph.project_db.net_bus.find().to_list()`)
+* *ph.mgmt_db*: the user_management database
+* *ph.users_collection*: the users collection from the management database
+* *ph.projects_collection*: the projects collection from the management database
+
+
+In case you want to access the database but do not need a PandaHub object, there are two convenience functions available:
+
+```python
+from pandahub.lib import get_mongo_client
+
+my_collection = get_mongo_client("db", "collection")
+docs = collection.find().to_list()
+```
+`PANDAHUB_GLOBAL_DB_CLIENT` is respected, you either get the global client or a fresh instance, in which case you are responsible for cleaning up the connection.
+
+```python
+from pandahub.lib import mongo_client
+
+with mongo_client("db", "my_collection") as collection:
+    docs = collection.find().to_list()
+```
+With the context manager, a new MongoClient is created (even if `PANDAHUB_GLOBAL_DB_CLIENT` is `true`) and closed on completion of the with block.

{pandahub-0.3.16 → pandahub-0.4.0}/pandahub.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ pandahub/lib/PandaHub.py
 pandahub/lib/__init__.py
 pandahub/lib/database_toolbox.py
 pandahub/lib/datatypes.py
+pandahub/lib/mongo_client.py
 pandahub/lib/mongodb_indexes.py
 pandahub/lib/timeseries/__init__.py
 pandahub/lib/timeseries/output_writer_mongodb.py

{pandahub-0.3.16 → pandahub-0.4.0}/pandahub.egg-info/requires.txt

@@ -2,9 +2,9 @@ uvicorn>=0.24.0
 fastapi-users[beanie]>=12.0
 fastapi>=0.104.0
 fastapi-mail>=1.4.1
-pandapower~=2.14
+pandapower>=3.0
 pandapipes>=0.7.0
-pymongo
+pymongo>=4.9
 pydantic
 simplejson
 requests

{pandahub-0.3.16 → pandahub-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pandahub"
-version = "0.3.16"  # File format version '__format_version__' is tracked in __init__.py
+version = "0.4.0"  # File format version '__format_version__' is tracked in __init__.py
 authors=[
     { name = "Jan Ulffers", email = "jan.ulffers@iee.fraunhofer.de" },
     { name = "Leon Thurner", email = "leon.thurner@retoflow.de" },

{pandahub-0.3.16 → pandahub-0.4.0}/requirements.txt

@@ -2,9 +2,9 @@ uvicorn>=0.24.0
 fastapi-users[beanie]>=12.0
 fastapi>=0.104.0
 fastapi-mail>=1.4.1
-pandapower~=2.14
+pandapower>=3.0
 pandapipes>=0.7.0
-pymongo
+pymongo>=4.9
 pydantic
 simplejson
 requests

pandahub-0.3.16/README.md

@@ -1,16 +0,0 @@
-[![pandapower](https://www.pandapower.org/images/pp.svg)](https://www.pandapower.org)         [![pandapipes](https://www.pandapipes.org/images/pp.svg)](https://www.pandapipes.org)
-
-[![pandahub](https://badge.fury.io/py/pandahub.svg)](https://pypi.org/project/pandahub/) [![pandahub](https://img.shields.io/pypi/pyversions/pandahub.svg)](https://pypi.org/project/pandahub/) [![pandahub](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/e2nIEE/pandahub/blob/master/LICENSE)
-
-pandahub is a data hub for pandapower and pandapipes networks based on MongoDB. It allows you to store pandapower and
-pandapipes networks as well as timeseries in a MongoDB. pandahub allows you to access the database directly through the PandaHub class,
-but also provides a REST-API based on FastAPI. Access through the API is managed with a user management implementation based on FastAPI Users.
-
-## Development
-`docker compose up -d` runs a mongodb container alongside a pandahub api instance with live reload available
-at http://localhost:8002. To connect to an existing database instead, set `MONGODB_URL` to the connection string through an environment variable / in you `.env` file.
-
-Swagger UI is available at http://localhost:8002/docs.
-
-If you develop on the library and do not need the fastapi app, `docker compose up db -d` starts only the mongodb
-container.