awaredb 0.1.0__tar.gz

awaredb-0.1.0/AwareDB/__init__.py

@@ -0,0 +1 @@
+from .api import AwareDB

awaredb-0.1.0/AwareDB/api.py

@@ -0,0 +1,282 @@
+from pathlib import Path
+from typing import Any, Dict, List, Union
+
+import json
+import requests
+
+
+class AwareDB:
+    """
+    Python API to interact with AwareDB.
+    """
+
+    # pylint: disable=too-many-arguments
+    def __init__(
+        self,
+        db: str,
+        token=None,
+        user: str = None,
+        password: str = None,
+        host: str = None,
+    ):
+        """
+        :param db: Name of the database to connect to
+        :type db: str
+        :param user: Username of the database to connect to
+        :type user: str
+        :param pass: Password of the database to connect to
+        :type pass: str
+        :param host: Host of the database to connect to
+        :type host: str
+        :param token: Token of the database to connect to
+        :type token: str
+        """
+        self.host = host or "https://aware-db.com"
+        self.db = db
+        self.user = user
+        self.password = password
+        self.token = token
+
+        # Check if token or user and pass are provided
+        if not token and not (user and password):
+            raise ValueError("Database token or username and password are required")
+
+        # If token is not provided, get it from the server
+        if not self.token:
+            self.token = self._get_token(user=user, password=password)
+
+        # Check if connection is valid
+        if not self._check_connection():
+            raise ValueError("Unable to connect to database")
+
+    # -------------------------------------------------------------------------
+    # Login and connection methods
+    # -------------------------------------------------------------------------
+
+    def _check_connection(self):
+        """
+        Check if token is valid and if database exists.
+        """
+        return self._request("check") == {"connected": True}
+
+    def _get_token(self, user: str = None, password: str = None):
+        """
+        Get a token from the server with the provided username and password.
+        """
+        response = requests.post(
+            f"{self.host}/rest/auth/token/login/",
+            json={"username": user, "password": password},
+            timeout=30,
+        )
+        return response.json().get("token")
+
+    # -------------------------------------------------------------------------
+    # Read database commands
+    # -------------------------------------------------------------------------
+
+    def get(
+        self,
+        path: str,
+        states: List[str] = None,
+    ) -> Any:
+        """
+        Returns the value of a specific path from nodes in the database
+
+        :param path: Path to get from the database.
+        :type path: str
+        :param states: List of states from which data should be retrieved.
+        :type states: List[str]
+        :return: Value of the path
+        :rtype: Any
+        """
+        data = {"path": path, "states": states or []}
+        return self._request("get", data)
+
+    def query(
+        self,
+        nodes: List[str] = None,
+        conditions: List[str] = None,
+        properties: List[str] = None,
+        states: List[str] = None,
+        show_abstract: bool = False,
+    ) -> List[Dict[str, Any]]:
+        """
+        Returns a list of nodes based on the input.
+
+        :param nodes: List of ids, uids and names from nodes to fetch. Defaults to all.
+        :type nodes: List[str]
+        :param conditions: A list of conditions that validates if node should be retrieved.
+        :type conditions: List[str]
+        :param properties: A list of properties that should be retrieve. Defaults to all.
+        :type properties: List[str]
+        :param states: List of states from which data should be retrieved.
+        :type states: List[str]
+        :param show_abstract: If abstract nodes should be retrieved. Defaults to False.
+        :type show_abstract: bool
+        :return: Value of the path
+        :rtype: Dict[str, Any]
+        """
+        data = {
+            "nodes": nodes or ["*"],
+            "conditions": conditions or [],
+            "properties": properties or [],
+            "states": states or [],
+            "show_abstract": show_abstract,
+        }
+        return self._request("query", data)
+
+    def calculate(
+        self,
+        formula: Union[str, List[str]],
+        states: List[str] = None,
+    ) -> Union[Any, List[Any]]:
+        """
+        Calculates a formula on the database.
+
+        If only one formula is passed, the response will result of the calculation.
+        If multiple formulas are passed, the response will be a list of results.
+
+        :param formula: Formula to calculate
+        :type formula: Union[str, List[str]]
+        :return: Value of the formula
+        :rtype: Union[Dict[str, Any], List[Dict[str, Any]]]
+        """
+        data = {"formula": formula, states: states or []}
+        return self._request("calculate", data)
+
+    def what_if(
+        self,
+        changes: Dict[str, Any],
+        states: List[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Returns the impacts of changes without saving them on database.
+
+        :param changes: A dictionary where keys represents paths and values the new values.
+        :type changes: Dict[str, Any]
+        :param states: List of states from which data should be retrieved.
+        :type states: List[str]
+        :return: Dictionary with the impacts of the changes.
+        :rtype: Dict[str, Any]
+        """
+        data = {"changes": changes, states: states or []}
+        return self._request("what-if", data)
+
+    # -------------------------------------------------------------------------
+    # Write database commands
+    # -------------------------------------------------------------------------
+
+    def update(
+        self,
+        data: Union[Dict[str, Any], List[Dict[str, Any]]],
+        partial: bool = False,
+    ) -> List[Dict[str, Any]]:
+        """
+        Updates nodes on the database.
+
+        :param data: List of nodes, relations and relation types to created or update.
+        :type data: List[Dict[str, Any]]
+        :param partial: Updates only passed properties for exiting data. Defaults to False.
+        :type partial: bool
+        :return: List of updated nodes, relations and relation types.
+        :rtype: List[Dict[str, Any]]
+        """
+        data = {"data": data, "partial": partial}
+        return self._request("update", data)
+
+    def remove(self, ids: List[str]) -> None:
+        """
+        Removes specific nodes, relations and relation types from database.
+
+        :param ids: List of ids from nodes, relations and relation types to remove.
+        :type ids: List[str]
+        """
+        data = {"ids": ids}
+        return self._request("remove", data)
+
+    def flush(self) -> None:
+        """
+        Removes all nodes, relations and relation types from database.
+        """
+        return self._request("flush")
+
+    # -------------------------------------------------------------------------
+    # Generic methods to handle command requests
+    # -------------------------------------------------------------------------
+
+    def _request(self, command: str, data: Dict[str, Any] = None) -> Any:
+        """
+        Run a command on the server
+
+        :param command: Command to execute on the server.
+        :type command: str
+        :param data: Data to send to the server as part of the command.
+        :type data: Dict[str, Any]
+        :return: Servers response
+        :rtype: Any
+        """
+        url = f"{self.host}/rest/db/{self.db}/{command}/"
+        response = requests.post(
+            url,
+            json=data or {},
+            headers={"Authorization": f"Token {self.token}"},
+            timeout=180,
+        )
+        if response.status_code == 400:
+            raise ValueError("Invalid request", response.json())
+        if response.status_code != 200:
+            raise ValueError("Invalid request", response.content)
+        return response.json().get("data")
+
+    # -------------------------------------------------------------------------
+    # Load and save database methods
+    # -------------------------------------------------------------------------
+
+    def load(self, filepath: str, recursive: bool = False, flush: bool = False):
+        """
+        Load a file or folder of JSONs into the database.
+        """
+        path = Path(filepath)
+
+        # If path is invalid, theres nothing to load
+        if not path.exists():
+            raise ValueError(f"Path {path} does not exist.")
+
+        # If flush is True, remove all data from database
+        if flush:
+            self.flush()
+
+        # Gather data to be loaded
+        data = []
+        if path.is_dir():
+            self._load_folder(data, path, recursive)
+        else:
+            self._load_file(data, path)
+
+        # Upload data to database
+        self.update(data)
+
+    def _load_folder(
+        self, data: List[Dict[str, Any]], path: Path, recursive: bool = False
+    ):
+        """
+        Loads a folder of JSONs into list of data to be loaded.
+        """
+        for file in path.iterdir():
+            if file.is_dir():
+                if recursive:
+                    self._load_folder(data, file, recursive=recursive)
+            elif file.suffix.lower() == ".json":
+                self._load_file(data, file)
+
+    def _load_file(self, data: List[Dict[str, Any]], path: Path):
+        """
+        Loads a JSON file into a list of data to be loaded.
+        """
+        with open(path, "r", encoding="utf-8") as f:
+            content = json.load(f)
+
+        if isinstance(content, list):
+            data.extend(content)
+        else:
+            data.append(content)

awaredb-0.1.0/AwareDB.egg-info/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.1
+Name: awaredb
+Version: 0.1.0
+Summary: AwareDB: data modularity, simplified. Python API.
+Home-page: https://github.com/nelsonmonteiro/awaredb-python-api
+Download-URL: https://github.com/nelsonmonteiro/awaredb-python-api/archive/v_0_1_1.tar.gz
+Author: Nelson Monteiro
+Author-email: nelson@aware-db.com
+License: MIT
+Keywords: AwareDB,modularity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Database :: Front-Ends
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+License-File: LICENSE

awaredb-0.1.0/AwareDB.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+setup.cfg
+setup.py
+AwareDB/__init__.py
+AwareDB/api.py
+AwareDB.egg-info/PKG-INFO
+AwareDB.egg-info/SOURCES.txt
+AwareDB.egg-info/dependency_links.txt
+AwareDB.egg-info/requires.txt
+AwareDB.egg-info/top_level.txt
+awaredb/__init__.py
+awaredb/api.py
+awaredb.egg-info/PKG-INFO
+awaredb.egg-info/SOURCES.txt
+awaredb.egg-info/dependency_links.txt
+awaredb.egg-info/requires.txt
+awaredb.egg-info/top_level.txt

awaredb-0.1.0/AwareDB.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

awaredb-0.1.0/AwareDB.egg-info/requires.txt

@@ -0,0 +1 @@
+requests

awaredb-0.1.0/AwareDB.egg-info/top_level.txt

@@ -0,0 +1 @@
+awaredb

awaredb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Nelson Monteiro
+
+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.

awaredb-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.1
+Name: awaredb
+Version: 0.1.0
+Summary: AwareDB: data modularity, simplified. Python API.
+Home-page: https://github.com/nelsonmonteiro/awaredb-python-api
+Download-URL: https://github.com/nelsonmonteiro/awaredb-python-api/archive/v_0_1_1.tar.gz
+Author: Nelson Monteiro
+Author-email: nelson@aware-db.com
+License: MIT
+Keywords: AwareDB,modularity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Database :: Front-Ends
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+License-File: LICENSE

awaredb-0.1.0/README.md

@@ -0,0 +1,362 @@
+# AwareDB: Python API
+
+This is a simple plugin to execute commands on AwareDB. For more information about AwareDB, read [here the full documentation](https://docs.aware-db.com/).
+
+## About AwareDB
+
+AwareDB aims to revolutionize the traditional approach to data by introducing the principle
+of **modularity** directly into the **data structure**. While modularity is a well-established
+concept in computer science, primarily applied to programming and infrastructure, the realm
+of data has remained predominantly static and non-modular,tightly bound to the code
+that governs it.
+
+Our innovative approach introduces a groundbreaking concept wherein data becomes **self-aware**.
+Individual pieces of data can seamlessly **connect**, **reference one another** through direct links
+or employ **mathematical** and **logical operations**. Notably, alterations to one node trigger
+**automatic cascading impacts** throughout the system, all achieved without the need for
+additional code.
+
+This marks a paradigm shift in data management, empowering a dynamic,
+interconnected, and **self-aware data environment**.
+
+## Installation
+
+```bash
+$ pip install awaredb
+```
+
+## Quick start
+
+```python
+
+from awaredb import AwareDB
+
+# Using token
+awaredb = AwareDB(db="<my_db>", token="<my_token>")
+
+# Using username and password
+awaredb = AwareDB(db="<my_db>", user="<username>", password="<my_password>")
+```
+
+## Read commands
+
+#### calculate
+
+Execute calculations using existing nodes in the database.
+
+Params:
+* `formula`: A singular formula or a list of formulas to be computed.
+* `states`: A list specifying the active states used during calculations.
+
+Example of a call:
+
+```python
+awaredb.calculate(
+  formula="${car.power} * 2",
+  states=["car.model.x"],
+)
+
+# Example of response:
+Output: "500 hp"
+```
+
+### get
+
+Returns the value of a specific path from nodes in the database.
+
+Params:
+* `path`: A single path to be retrieved.
+* `states`: A list of states from which data should be retrieved.
+
+Example of a call:
+
+```python
+awaredb.get(path="car.power", states=[car.model.x])
+
+# Example of a calculate response
+Output: "250 hp"
+```
+
+
+### query
+
+Returns a list of nodes based on the input.
+
+Params:
+* `nodes`: List of ids, uids and names from existing nodes.
+* `conditions`: A list of conditions that validates if node should be retrieved.
+* `properties`: A list of properties that should be retrieve. Defaults to all.
+* `states`: A list of states from which data should be retrieved.
+* `show_abstract`: If abstract nodes should be retrieved. Defaults to False.
+
+Note: To retrieve all nodes, use `'*'` as `nodes` value.
+
+
+Example of a call:
+
+```python
+awaredb.query(
+  nodes=["employee"],
+  conditions=["${node.salary.gross} > 60000"],
+)
+
+# Example of a calculate response
+Output: [
+  {
+    "id": "7037a8a5-ac2f-4a65-a913-ab1e631fda76"
+    "node_type": "employee",
+    "name": "John Doe",
+    "salary": {
+      "gross": "80000"
+    },
+    "value": {
+      "salary": {
+        "gross": "80000",
+        "net": "56000"
+      }
+    }
+  },
+  {
+    "id": "7037a8a5-ac2f-4a65-a913-ab1e631fda77"
+    "node_type": "employee",
+    "name": "Jane Doe",
+    "salary": {
+      "gross": "100000"
+    },
+    "value": {
+      "salary": {
+        "gross": "100000",
+        "net": "70000"
+      }
+    }
+  }
+]
+```
+
+
+### what_if
+
+Allows to return the impacts of changes without saving them on database.
+
+Params:
+* `change`: A dictionary where keys represents paths and values the new values.
+* `states`: A list of states from which data should be retrieved.
+
+Example of a call:
+
+```python
+awaredb.what_if(
+  changes={"battery.capacity": "55 kWh"},
+  states=["car.performance"],
+)
+
+# Example of a calculate response
+Output: {
+  "battery.capacity": "55 kWh",
+  "car.range": "180 km"
+}
+```
+
+
+## Write commands
+
+
+### flush
+
+Deletes all data currently on database.
+
+Example of a call:
+
+```python
+awaredb.flush()
+```
+
+### remove
+
+Removes specific nodes and relations from database.
+
+Params:
+* `ids`: List of ids from nodes and relations to be deleted.
+
+Example of a call:
+```python
+awaredb.remove(ids=[
+  "7037a8a5-ac2f-4a65-a913-ab1e631fda76",
+  "7037a8a5-ac2f-4a65-a913-ab1e631fda77",
+])
+```
+
+### update
+
+Add and/or updates nodes, relations and relation types from a database.
+
+Params:
+* `data`: List of nodes, relations and relation types to created or update.
+* `partial`: Updates only passed properties for exiting data. Defaults to False.
+
+Example of a call:
+
+```python
+awaredb.update(data=[
+  {
+    "name": "Fan",
+    "mode": {
+      "states": {
+        "off": ["this.engine.mode.off", "this.lights.status.off"],
+        "low": ["this.engine.mode.low", "this.lights.status.on"],
+        "mid": ["this.engine.mode.mid", "this.lights.status.on"],
+        "high": ["this.engine.mode.high", "this.lights.status.on"]
+      }
+    },
+    "power": "=sum(${this.children.power})",
+    "engine": {
+      "mode": {"states": ["off", "low", "mid", "high"]},
+      "power": {
+        "linked-to": "${this.engine.mode}",
+        "cases": [
+          ["low", "10 W"],
+          ["mid", "20 W"],
+          ["high", "30 W"],
+          ["default", "0 W"]
+        ]
+      },
+      "speed": "=10 rpm * (${this.engine.power} / 1 W)"
+    },
+    "lights": {
+      "status": {"states": ["off", "on"]},
+      "power": {
+        "linked-to": "this.lights.status",
+        "cases": [
+          ["off", "0 W"],
+          ["on", "5 W"]
+        ]
+      }
+    }
+  }
+])
+
+# Example of a calculate response
+Output: [
+    {
+      "name": "Fan",
+      "mode": {
+        "states": {
+          "off": ["this.engine.mode.off", "this.lights.status.off"],
+          "low": ["this.engine.mode.low", "this.lights.status.on"],
+          "mid": ["this.engine.mode.mid", "this.lights.status.on"],
+          "high": ["this.engine.mode.high", "this.lights.status.on"]
+        }
+      },
+      "power": "=sum(${this.children.power})",
+      "engine": {
+        "mode": {"states": ["off", "low", "mid", "high"]},
+        "power": {
+          "linked-to": "${this.engine.mode}",
+          "cases": [
+            ["low", "10 W"],
+            ["mid", "20 W"],
+            ["high", "30 W"],
+            ["default", "0 W"]
+          ]
+        },
+        "speed": "=10 rpm * (${this.engine.power} / 1 W)"
+      },
+      "lights": {
+        "status": {"states": ["off", "on"]},
+        "power": {
+          "linked-to": "this.lights.status",
+          "cases": [
+            ["off", "0 W"],
+            ["on", "5 W"]
+          ]
+        }
+      }
+      "value": {
+        "mode": {
+          "states": {
+            "off": ["this.engine.mode.off", "this.lights.status.off"],
+            "low": ["this.engine.mode.low", "this.lights.status.on"],
+            "mid": ["this.engine.mode.mid", "this.lights.status.on"],
+            "high": ["this.engine.mode.high", "this.lights.status.on"]
+          }
+        },
+        "power": {
+            "linked-to": "this.engine.mode",
+            "cases": [
+                [
+                    "low",
+                    {
+                        "linked-to": "this.lights.status",
+                        "cases": [
+                            ["off", "10.0 W"],
+                            ["on", "15.0 W"],
+                        ],
+                    },
+                ],
+                [
+                    "mid",
+                    {
+                        "linked-to": "this.lights.status",
+                        "cases": [
+                            ["off", "20.0 W"],
+                            ["on", "25.0 W"],
+                        ],
+                    },
+                ],
+                [
+                    "high",
+                    {
+                        "linked-to": "this.lights.status",
+                        "cases": [
+                            ["off", "30.0 W"],
+                            ["on", "35.0 W"],
+                        ],
+                    },
+                ],
+                [
+                    "default",
+                    {
+                        "linked-to": "this.lights.status",
+                        "cases": [
+                            ["off", "0.0 W"],
+                            ["on", "5.0 W"],
+                        ],
+                    },
+                ],
+            ],
+        },
+        "engine": {
+          "mode": {"states": ["off", "low", "mid", "high"]},
+          "power": {
+            "linked-to": "${this.engine.mode}",
+            "cases": [
+              ["low", "10 W"],
+              ["mid", "20 W"],
+              ["high", "30 W"],
+              ["default", "0 W"]
+            ]
+          },
+          "speed": {
+              "linked-to": "this.engine.mode",
+              "cases": [
+                  ["low", "100.0 rpm"],
+                  ["mid", "200.0 rpm"],
+                  ["high", "300.0 rpm"],
+                  ["default", "0.0 rpm"],
+              ],
+          }
+        },
+        "lights": {
+          "status": {"states": ["off", "on"]},
+          "power": {
+            "linked-to": "this.lights.status",
+            "cases": [
+              ["off", "0 W"],
+              ["on", "5 W"]
+            ]
+          }
+        }
+      }
+    }
+  ]
+```

awaredb-0.1.0/setup.cfg

@@ -0,0 +1,7 @@
+[metadata]
+description_file = README.md
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

awaredb-0.1.0/setup.py

@@ -0,0 +1,29 @@
+from setuptools import setup
+
+setup(
+    name="awaredb",
+    packages=["awaredb"],
+    version="0.1.0",
+    license="MIT",
+    description="AwareDB: data modularity, simplified. Python API.",
+    author="Nelson Monteiro",
+    author_email="nelson@aware-db.com",
+    url="https://github.com/nelsonmonteiro/awaredb-python-api",
+    download_url="https://github.com/nelsonmonteiro/awaredb-python-api/archive/v_0_1_1.tar.gz",
+    keywords=["AwareDB", "modularity"],
+    install_requires=[
+        "requests",
+    ],
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "Topic :: Database :: Front-Ends",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+    ],
+)