erioon 0.1.5__py3-none-any.whl → 0.1.6__py3-none-any.whl

erioon/auth.py

@@ -0,0 +1,34 @@
+# Copyright 2025-present Erioon, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# Visit www.erioon.com/dev-docs for more information about the python SDK
+
+from erioon.client import ErioonClient
+
+def Auth(credential_string):
+    """
+    Authenticates a user using a colon-separated email:password string.
+
+    Parameters:
+    - credential_string (str): A string in the format "email:password"
+
+    Returns:
+    - ErioonClient instance: An instance representing the authenticated user.
+      If authentication fails, the instance will contain the error message.
+
+    Example usage:
+    >>> from erioon.auth import Auth
+    >>> client = Auth("<API_KEY>:<EMAIL>:<PASSWORD>")
+    >>> print(client)  # prints user_id if successful or error message if not
+    """
+    return ErioonClient(credential_string)

erioon/client.py

@@ -0,0 +1,118 @@
+# Copyright 2025-present Erioon, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# Visit www.erioon.com/dev-docs for more information about the python SDK
+
+import requests
+from erioon.database import Database
+
+class ErioonClient:
+    def __init__(self, credential_string, base_url="https://sdk.erioon.com"):
+        self.credential_string = credential_string
+        self.base_url = base_url
+        self.user_id = None
+        self.login_metadata = None
+
+        parts = credential_string.split(":")
+
+        if len(parts) == 1 and credential_string.startswith("erioon"):
+            self.api = credential_string
+            self.email = None
+            self.password = None
+        else:
+            if len(parts) == 2:
+                self.email, self.password = parts
+                self.api = None
+            else:
+                raise ValueError("Invalid credential format. Use 'erioon-xxxxx' or 'email:password'")
+
+        try:
+            self.login_metadata = self._login()
+            self._update_metadata_fields()
+        except Exception as e:
+            print(f"[ErioonClient] Initialization error: {e}")
+
+
+    def _login(self):
+        url = f"{self.base_url}/login"
+        payload = {"api_key": self.api, "email": self.email, "password": self.password}
+        headers = {"Content-Type": "application/json"}
+
+        response = requests.post(url, json=payload, headers=headers)
+        if response.status_code == 200:
+            data = response.json()
+            self.login_metadata = data
+            return data
+        else:
+            try:
+                msg = response.json().get("error", "Login failed")
+            except Exception:
+                msg = response.text
+            print(f"[ErioonClient] Login failed: {msg}")
+            raise RuntimeError(msg)
+
+    def _update_metadata_fields(self):
+        if self.login_metadata:
+            self.user_id = self.login_metadata.get("_id")
+            self.cluster = self.login_metadata.get("cluster")
+            self.database = self.login_metadata.get("database")
+            self.sas_tokens = self.login_metadata.get("sas_tokens", {})
+
+    def __getitem__(self, db_id):
+        if not self.user_id:
+            raise ValueError("Client not authenticated. Cannot access database.")
+
+        return self._get_database_info(db_id)
+
+    def _get_database_info(self, db_id):
+        payload = {"user_id": self.user_id, "db_id": db_id}
+        headers = {"Content-Type": "application/json"}
+        response = requests.post(f"{self.base_url}/db_info", json=payload, headers=headers)
+
+        if response.status_code == 200:
+            db_info = response.json()
+            sas_info = self.sas_tokens.get(db_id)
+            if not sas_info:
+                raise Exception(f"No SAS token info for database id {db_id}")
+
+            container_url = sas_info.get("container_url")
+            sas_token = sas_info.get("sas_token")
+
+            if not container_url or not sas_token:
+                raise Exception("Missing SAS URL components")
+
+            if not sas_token.startswith("?"):
+                sas_token = "?" + sas_token
+
+            sas_url = container_url.split("?")[0] + sas_token
+
+            return Database(
+                user_id=self.user_id,
+                metadata=db_info,
+                database=self.database,
+                cluster=self.cluster,
+                sas_url=sas_url
+            )
+        else:
+            try:
+                error_json = response.json()
+                error_msg = error_json.get("error", response.text)
+            except Exception:
+                error_msg = response.text
+            raise Exception(f"Failed to fetch database info: {error_msg}")
+
+    def __str__(self):
+        return self.user_id if self.user_id else "[ErioonClient] Unauthenticated"
+
+    def __repr__(self):
+        return f"<ErioonClient user_id={self.user_id}>" if self.user_id else "<ErioonClient unauthenticated>"

erioon/collection.py

@@ -0,0 +1,371 @@
+# Copyright 2025-present Erioon, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# Visit www.erioon.com/dev-docs for more information about the python SDK
+
+import json
+from urllib.parse import urlparse
+from erioon.read import handle_get_all, handle_find_one, handle_find_many, handle_count_records
+from erioon.create import handle_insert_one, handle_insert_many
+from erioon.delete import handle_delete_one, handle_delete_many
+from erioon.update import handle_update_one, handle_update_many, handle_replace_one
+from erioon.ping import handle_connection_ping
+
+class Collection:
+    def __init__(
+        self,
+        user_id,
+        db_id,
+        coll_id,
+        metadata,
+        database,
+        cluster,
+        sas_url,
+    ):
+        """
+        Initialize a Collection object that wraps Erioon collection access.
+
+        Args:
+            user_id (str): The authenticated user's ID.
+            db_id (str): The database ID.
+            coll_id (str): The collection ID.
+            metadata (dict): Metadata info about this collection (e.g., schema, indexing, etc.).
+            database (str): Name or ID of the database.
+            cluster (str): Cluster name or ID hosting the database.
+            sas_url (str): Full SAS URL used to access the storage container.
+        """
+        self.user_id = user_id
+        self.db_id = db_id
+        self.coll_id = coll_id
+        self.metadata = metadata
+        self.database = database
+        self.cluster = cluster
+
+        parsed_url = urlparse(sas_url.rstrip("/"))
+        container_name = parsed_url.path.lstrip("/").split("/")[0]
+        account_url = f"{parsed_url.scheme}://{parsed_url.netloc}"
+        sas_token = parsed_url.query
+        self.container_url = f"{account_url}/{container_name}?{sas_token}"
+
+    # PRINT ERIOON 
+    def _print_loading(self):
+        """Prints a loading message (likely for UX in CLI or SDK usage)."""
+        print("Erioon is loading...")
+
+    # CHECK READ / WRITE LICENCE
+    def _is_read_only(self):
+        """Check if the current database is marked as read-only."""
+        return self.database == "read"
+
+    # RESPONSE FOR ONLY WRITE
+    def _read_only_response(self):
+        """Standardized error response for blocked write operations."""
+        return "This user is not allowed to perform write operations.", 403
+
+    # GET ALL RECORDS OF A COLLECTION
+    def get_all(self, limit=1000000):
+        """
+        Fetch all records from the collection (up to a limit).
+        """
+        self._print_loading()
+        result, status_code = handle_get_all(
+            user_id=self.user_id,
+            db_id=self.db_id,
+            coll_id=self.coll_id,
+            limit=limit,
+            container_url=self.container_url,
+        )
+        return result
+
+    # FINDS A SPECIFIC RECORD OF A COLLECTION
+    def find_one(self, filters: dict | None = None):
+        """
+        Fetch a single record that matches specific key-value filters.
+        """
+        if self._is_read_only():
+            return self._read_only_response()
+
+        if filters is None:
+            filters = {}
+
+        search_criteria = [{k: v} for k, v in filters.items()]
+
+        result, status_code = handle_find_one(
+            user_id=self.user_id,
+            db_id=self.db_id,
+            coll_id=self.coll_id,
+            search_criteria=search_criteria,
+            container_url=self.container_url,
+        )
+        return result
+    
+    # FINDS MULTIPLE RECORDS OF A COLLECTION
+    def find_many(self, filters: dict | None = None, limit: int = 1000):
+        """
+        Fetch multiple records that match specific key-value filters.
+
+        Args:
+            filters (dict): Filters to match records.
+            limit (int): Maximum number of records to return (default: 1000).
+
+        Returns:
+            dict: Result from `handle_find_many()`
+        """
+        if self._is_read_only():
+            return self._read_only_response()
+
+        self._print_loading()
+
+        if filters is None:
+            filters = {}
+
+        if limit > 500_000:
+            raise ValueError("Limit of 500,000 exceeded")
+
+        search_criteria = [{k: v} for k, v in filters.items()]
+
+        result, status_code = handle_find_many(
+            user_id=self.user_id,
+            db_id=self.db_id,
+            coll_id=self.coll_id,
+            search_criteria=search_criteria,
+            limit=limit,
+            container_url=self.container_url,
+        )
+        return result
+
+    # INSERT A SINGLE RECORD IN A COLLECTION
+    def insert_one(self, record):
+        """
+        Insert a single record into the collection.
+        """
+        if self._is_read_only():
+            return self._read_only_response()
+        response, status = handle_insert_one(
+            user_id_cont=self.user_id,
+            database=self.db_id,
+            collection=self.coll_id,
+            record=record,
+            container_url=self.container_url,
+        )
+        if status == 200:
+            print("Insertion was successful.")
+        else:
+            print(f"Error inserting record: {response}")
+        return response, status
+
+    # INSERT MULTIPLE RECORDS INTO A COLLECTION
+    def insert_many(self, data):
+        """
+        Insert multiple records into the collection.
+
+        Args:
+            data (list): List of record dicts.
+
+        Returns:
+            tuple: (response message, HTTP status code)
+        """
+        if self._is_read_only():
+            return self._read_only_response()
+        self._print_loading()
+        response, status = handle_insert_many(
+            user_id_cont=self.user_id,
+            database=self.db_id,
+            collection=self.coll_id,
+            data=data,
+            container_url=self.container_url,
+        )
+        if status == 200:
+            print("Insertion of multiple records was successful.")
+        else:
+            print(f"Error inserting records: {response}")
+        return response, status
+
+    # DELETE A SINGLE RECORD BASED ON _ID OR KEY
+    def delete_one(self, record_to_delete):
+        """
+        Delete a single record based on its _id or nested key.
+        """
+        if self._is_read_only():
+            return self._read_only_response()
+        response, status = handle_delete_one(
+            user_id=self.user_id,
+            db_id=self.db_id,
+            coll_id=self.coll_id,
+            data_to_delete=record_to_delete,
+            container_url=self.container_url,
+        )
+        if status == 200:
+            print("Deletion was successful.")
+        else:
+            print(f"Error deleting record: {response}")
+        return response, status
+
+    # DELETE MANY RECORDS IN BATCHES
+    def delete_many(self, records_to_delete_list, batch_size=10):
+        """
+        Delete multiple records in batches.
+        """
+        if self._is_read_only():
+            return self._read_only_response()
+        self._print_loading()
+        response, status = handle_delete_many(
+            user_id=self.user_id,
+            db_id=self.db_id,
+            coll_id=self.coll_id,
+            data_to_delete_list=records_to_delete_list,
+            batch_size=batch_size,
+            container_url=self.container_url,
+        )
+        if status == 200:
+            print("Batch deletion was successful.")
+        else:
+            print(f"Error deleting records: {response}")
+        return response, status
+
+    # UPDATE A RECORD
+    def update_one(self, filter_query: dict, update_query: dict):
+        """
+        Update a record in-place by filtering and applying update logic.
+        """
+        if self._is_read_only():
+            return self._read_only_response()
+        response, status = handle_update_one(
+            user_id=self.user_id,
+            db_id=self.db_id,
+            coll_id=self.coll_id,
+            filter_query=filter_query,
+            update_query=update_query,
+            container_url=self.container_url,
+        )
+        if status == 200:
+            print("Update was successful.")
+        else:
+            print(f"Error updating record: {response}")
+        return response, status
+
+    # UPDATE MULTIPLE RECORDS
+    def update_many(self, update_tasks: list):
+        """
+        Update multiple records in-place by applying a list of filter + update operations.
+
+        Each item in `update_tasks` should be a dict:
+            {
+                "filter": { ... },
+                "update": {
+                    "$set": {...}, "$push": {...}, "$remove": [...]
+                }
+            }
+
+        Returns:
+            (dict, int): Summary response and HTTP status code.
+        """
+        if self._is_read_only():
+            return self._read_only_response()
+        self._print_loading()
+        
+        response, status = handle_update_many(
+            user_id=self.user_id,
+            db_id=self.db_id,
+            coll_id=self.coll_id,
+            update_tasks=update_tasks,
+            container_url=self.container_url,
+        )
+
+        if status == 200:
+            print(f"Successfully updated {response.get('success')}")
+        else:
+            print(f"Error updating records: {response}")
+
+        return response, status
+
+    # REPLACE A SINGLE RECORDS BASED ON THE FILTER QUERY
+    def replace_one(self, filter_query: dict, replacement: dict):
+        """
+        Replaces a single record matching `filter_query` with the full `replacement` document.
+
+        - If `_id` is **not** in the replacement, preserves the original `_id`.
+        - If `_id` **is** in the replacement, uses the new `_id`.
+
+        Args:
+            filter_query (dict): Must contain a single key-value pair.
+            replacement (dict): New record to replace the old one.
+
+        Returns:
+            (dict, int): Response message and HTTP status code.
+        """
+        if self._is_read_only():
+            return self._read_only_response()
+
+        response, status = handle_replace_one(
+            user_id=self.user_id,
+            db_id=self.db_id,
+            coll_id=self.coll_id,
+            filter_query=filter_query,
+            replacement=replacement,
+            container_url=self.container_url,
+        )
+
+        if status == 200:
+            print("Replacement was successful.")
+        else:
+            print(f"Error replacing record: {response}")
+
+        return response, status
+
+    # PING AND CHECK CONNECTION
+    def ping(self):
+        """
+        Health check / ping to verify collection accessibility.
+        """
+        self._print_loading()
+        response, status = handle_connection_ping(
+            user_id=self.user_id,
+            db_id=self.db_id,
+            coll_id=self.coll_id,
+            container_url=self.container_url,
+        )
+        if status == 200:
+            print("Connection ping successful.")
+        else:
+            print(f"Ping failed: {response}")
+        return response, status
+
+    # COUNT ALL THE RECORDS
+    def count_records(self) -> int:
+        """
+        Count the total number of documents in the collection (across all shards).
+
+        Returns:
+            int: Total document count.
+        """
+        if self._is_read_only():
+            return 0
+        self._print_loading()
+
+        count, status = handle_count_records(
+            user_id=self.user_id,
+            db_id=self.db_id,
+            coll_id=self.coll_id,
+            container_url=self.container_url,
+        )
+        return count
+
+
+    def __str__(self):
+        """Pretty print the collection metadata."""
+        return json.dumps(self.metadata, indent=4)
+
+    def __repr__(self):
+        """Simplified representation for debugging or introspection."""
+        return f"<Collection coll_id={self.coll_id}>"

erioon/create.py

@@ -0,0 +1,130 @@
+# Copyright 2025-present Erioon, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# Visit www.erioon.com/dev-docs for more information about the python SDK
+
+import uuid
+from erioon.functions import (
+    create_msgpack_file,
+    update_index_file_insert,
+    calculate_shard_number,
+    async_log,
+    is_duplicate_id
+)
+
+# INSERT ONE RECORD
+def handle_insert_one(user_id_cont, database, collection, record, container_url):
+    """
+    Insert a single record into the collection.
+
+    - If no '_id' provided, generate a new UUID.
+    - If provided '_id' is duplicate, generate a new one and update the record.
+    - Create or append the record in a shard file.
+    - Update index.json to map the record to the appropriate shard.
+    - Log success or errors asynchronously.
+
+    Args:
+        user_id_cont: User identifier.
+        database: Database name.
+        collection: Collection name.
+        record: Dict representing the record to insert.
+        container_url: Blob Storage container SAS URL.
+
+    Returns:
+        Tuple (response dict, status code) indicating success or failure.
+    """
+    try:
+        if "_id" not in record or not record["_id"]:
+            record["_id"] = str(uuid.uuid4())
+
+        rec_id = record["_id"]
+
+        if is_duplicate_id(user_id_cont, database, collection, rec_id, container_url):
+            new_id = str(uuid.uuid4())
+            record["_id"] = new_id
+            rec_id = new_id
+            msg = f"Record inserted successfully in {collection} with a new _id {rec_id} because the provided _id was already present."
+        else:
+            msg = f"Record inserted successfully in {collection} with _id {rec_id}"
+
+        async_log(user_id_cont, database, collection, "POST", "SUCCESS", msg, 1, container_url)
+
+        create_msgpack_file(user_id_cont, database, collection, record, container_url)
+
+        shard_number = calculate_shard_number(user_id_cont, database, collection, container_url)
+        update_index_file_insert(user_id_cont, database, collection, rec_id, shard_number, container_url)
+
+        return {"status": "OK", "message": msg, "record": record}, 200
+
+    except Exception as e:
+        error_msg = f"An error occurred during insert in {collection}: {str(e)}"
+        async_log(user_id_cont, database, collection,"POST", "ERROR", error_msg, 1, container_url)
+        return {"status": "KO", "message": "Failed to insert record.", "error": str(e)}, 500
+
+# INSERT MANY RECORDS
+def handle_insert_many(user_id_cont, database, collection, data, container_url):
+    """
+    Insert multiple records in bulk.
+
+    - `data` is a list of dicts, each representing a record.
+    - For each record:
+      - Ensure it has a unique _id (generate new UUID if missing or duplicate).
+      - Write the record to the appropriate shard.
+      - Update index.json with _id to shard mapping.
+    - Log the batch insert operation with details.
+    - Return aggregate success or failure response.
+
+    Args:
+        user_id_cont: User identifier.
+        database: Database name.
+        collection: Collection name.
+        data: List of record dicts.
+        container_url: Blob Storage container SAS URL.
+
+    Returns:
+        Tuple (response dict, status code) with summary of insert results.
+    """
+    insert_results = []
+    count = len(data)
+
+    try:
+        for record in data:
+            if "_id" not in record or not record["_id"]:
+                record["_id"] = str(uuid.uuid4())
+
+            rec_id = record["_id"]
+
+            if is_duplicate_id(user_id_cont, database, collection, rec_id, container_url):
+                new_id = str(uuid.uuid4())
+                record["_id"] = new_id
+                rec_id = new_id
+                msg = f"Inserted with new _id {rec_id} (original _id was already present)."
+            else:
+                msg = f"Inserted with _id {rec_id}."
+
+            create_msgpack_file(user_id_cont, database, collection, record, container_url)
+
+            shard_number = calculate_shard_number(user_id_cont, database, collection, container_url)
+            update_index_file_insert(
+                user_id_cont, database, collection, rec_id, shard_number, container_url
+            )
+
+            insert_results.append({"_id": rec_id, "message": msg})
+
+        async_log(user_id_cont, database, collection, "POST", "SUCCESS", insert_results, count, container_url)
+        return {"success": "Records inserted successfully", "details": insert_results}, 200
+
+    except Exception as e:
+        general_error_msg = f"Unexpected error during bulk insert: {str(e)}"
+        async_log(user_id_cont, database, collection, "POST", "ERROR", general_error_msg, 1, container_url)
+        return {"status": "KO", "message": general_error_msg}, 500