testing async methods

basic_async_example.py

@@ -0,0 +1,59 @@
+from surrealdb import AsyncSurrealDB
+
+
+async def main():
+    """Example of how to use the SurrealDB client."""
+    async with AsyncSurrealDB("ws://localhost:8000") as db:
+        await db.sign_in("root", "root")
+        await db.use("test", "test")
+
+        print("Using methods")
+        print("create: ", await db.create(
+            "person",
+            {
+                "user": "me",
+                "pass": "safe",
+                "marketing": True,
+                "tags": ["python", "documentation"],
+            },
+        ))
+        print("read: ", await db.select("person"))
+        print("update: ", await db.update("person", {
+            "user": "you",
+            "pass": "very_safe",
+            "marketing": False,
+            "tags": ["Awesome"]
+        }))
+        print("delete: ", await db.delete("person"))
+
+        # You can also use the query method
+        # doing all of the above and more in SurrealQl
+
+        # In SurrealQL you can do a direct insert
+        # and the table will be created if it doesn't exist
+        print("Using justawait db.query")
+        print("create: ", await db.query("""
+        insert into person {
+            user: 'me',
+            pass: 'very_safe',
+            tags: ['python', 'documentation']
+        };
+        
+        """))
+        print("read: ", await db.query("select * from person"))
+
+        print("update: ", await db.query("""
+        update person content {
+            user: 'you',
+            pass: 'more_safe',
+            tags: ['awesome']
+        };
+        
+        """))
+        print("delete: ", await db.query("delete person"))
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(main())

examples/basic_async_example.py

@@ -1,62 +1,59 @@
 from surrealdb import AsyncSurrealDB
 
+
 async def main():
     """Example of how to use the SurrealDB client."""
-    db = AsyncSurrealDB("ws://localhost:8000/database/namespace")
-
-    await db.connect()
-
-    await db.signin({
-        "username": "root",
-        "password": "root",
-    })
-
-    print("Using methods")
-    print("create: " ,await db.create(
-        "person",
-        {
-            "user": "me",
-            "pass": "safe",
-            "marketing": True,
-            "tags": ["python", "documentation"],
-        },
-    ))
-    print("read: ", await db.select("person"))
-    print("update: ", await db.update("person", {
-        "user":"you",
-        "pass":"very_safe",
-        "marketing": False,
-        "tags": ["Awesome"]
-    }))
-    print("delete: ", await db.delete("person"))
-
-    # You can also use the query method 
-    # doing all of the above and more in SurrealQl
-
-    # In SurrealQL you can do a direct insert 
-    # and the table will be created if it doesn't exist
-    print("Using justawait db.query")
-    print("create: ", await db.query("""
-    insert into person {
-        user: 'me',
-        pass: 'very_safe',
-        tags: ['python', 'documentation']
-    };
-    
-    """))
-    print("read: ", await db.query("select * from person"))
-
-    print("update: ", await db.query("""
-    update person content {
-        user: 'you',
-        pass: 'more_safe',
-        tags: ['awesome']
-    };
-    
-    """))
-    print( "delete: ", await db.query("delete person"))
+    async with AsyncSurrealDB("ws://localhost:8000") as db:
+        await db.sign_in("root", "root")
+        await db.use("test", "test")
+
+        print("Using methods")
+        print("create: ", await db.create(
+            "person",
+            {
+                "user": "me",
+                "pass": "safe",
+                "marketing": True,
+                "tags": ["python", "documentation"],
+            },
+        ))
+        print("read: ", await db.select("person"))
+        print("update: ", await db.update("person", {
+            "user": "you",
+            "pass": "very_safe",
+            "marketing": False,
+            "tags": ["Awesome"]
+        }))
+        print("delete: ", await db.delete("person"))
+
+        # You can also use the query method
+        # doing all of the above and more in SurrealQl
+
+        # In SurrealQL you can do a direct insert
+        # and the table will be created if it doesn't exist
+        print("Using justawait db.query")
+        print("create: ", await db.query("""
+        insert into person {
+            user: 'me',
+            pass: 'very_safe',
+            tags: ['python', 'documentation']
+        };
+
+        """))
+        print("read: ", await db.query("select * from person"))
+
+        print("update: ", await db.query("""
+        update person content {
+            user: 'you',
+            pass: 'more_safe',
+            tags: ['awesome']
+        };
+
+        """))
+        print("delete: ", await db.query("delete person"))
+
 
 if __name__ == "__main__":
     import asyncio
 
-    asyncio.run(main())
+    asyncio.run(main())

surrealdb/async_surrealdb.py

@@ -20,11 +20,11 @@
 """
 
 import uuid
-from typing import Optional, TypeVar
+from typing import Optional, TypeVar, Union, List
 
 from surrealdb.connection.constants import DEFAULT_CONNECTION_URL
 from surrealdb.connection.factory import create_connection_factory
-
+from surrealdb.data import Table, RecordID, Patch
 
 _Self = TypeVar('_Self', bound='AsyncSurrealDB')
 
@@ -148,86 +148,99 @@ async def unset(self, name: str) -> _Self:
         await self.__connection.send('unset', name)
         return self
 
-    async def query(self):
+    async def select(self, what: Union[str, Table, RecordID]) -> Union[List[dict], dict]:
         """
-        queries the database.
+        Performs a select query on the database for a particular resource.
 
-        :param query: the query to run on the database
+        :param what: the resource to select from.
 
-        :return: None
+        :return: the result of the select
         """
-        pass
+        return await self.__connection.send('select', what)
 
-    async def create(self):
+    async def query(self, query: str, variables: dict = {}) -> List[dict]:
         """
-        Creates a new document in the database.
+        Queries sends a custom SurrealQL query.
 
-        :param name: the name of the document to create
-        :param data: the data to store in the document
+        :param query: The query to execute against SurrealDB. Queries are seperated by semicolons.
+        :param variables: A set of variables used by the query
 
-        :return: None
+        :return: An array of query results
         """
-        pass
+        return await self.__connection.send('query', query, variables)
 
-    async def select(self):
+    async def create(self, thing: Union[str, RecordID, Table], data: Union[List[dict], dict]):
         """
-        Performs a select query on the database for a particular resource.
+        Creates a record either with a random or specified ID
 
-        :param resource: the resource to select from
+        :param thing: The Table or Record ID to create. Passing just a table will result in a randomly generated ID
+        :param data: The data to store in the document
 
-        :return: the result of the select
+        :return: None
         """
-        pass
+        return await self.__connection.send('create', thing, data)
 
-    async def insert(self):
-        pass
+    async def insert(self, thing: Union[str, Table], data: Union[List[dict], dict]):
+        """
+        Inserts a record either with a random or specified ID.
+
+        :param thing: The table to insert in to
+        :param data: One or multiple record(s)
+        :return:
+        """
+        return await self.__connection.send('insert', thing, data)
 
-    async def patch(self):
+    async def patch(self, thing: Union[str, RecordID, Table], patches: List[Patch], diff: Optional[bool] = False):
         """
         Patches the given resource with the given data.
 
-        :param resource: the resource to update
-        :param data: the data to patch the resource with
-        :return: the updated resource such as an individual row or a list of rows
+        :param thing: The Table or Record ID to patch.
+        :param patches: An array of patches following the JSON Patch specification
+        :param diff: A boolean representing if just a diff should be returned.
+        :return: the patched resource such as a record/records or patches
         """
-        pass
+        if diff is None:
+            diff = False
+        return await self.__connection.send('insert', thing, patches, diff)
 
-    async def update(self):
+    async def update(self, thing: Union[str, RecordID, Table], data: dict):
         """
-        Updates the given resource with the given data.
+        Updates replaces either all records in a table or a single record with specified data
 
-        :param resource: the resource to update
-        :param data: the data to update the resource with
+        :param thing: The Table or Record ID to update.
+        :param data: The content for the record
         :return: the updated resource such as an individual row or a list of rows
         """
-        pass
+        return await self.__connection.send('update', thing, data)
 
-    async def upsert(self):
-        pass
+    async def upsert(self, thing: Union[str, RecordID, Table], data: dict):
+        """
+        Upsert replaces either all records in a table or a single record with specified data
+
+        :param thing: The Table or Record ID to upsert.
+        :param data: The content for the record
+        :return: the upsert-ed records such as an individual row or a list of rows
+        """
+        return await self.__connection.send('upsert', thing, data)
 
-    async def delete(self):
+    async def delete(self, thing: Union[str, RecordID, Table]) -> Union[List[dict], dict]:
         """
-        Deletes a document in the database.
+        Deletes either all records in a table or a single record.
 
-        :param name: the name of the document to delete
+        :param thing: The Table or Record ID to update.
 
         :return: the record or records that were deleted
         """
-        pass
+        return await self.__connection.send('delete', thing)
 
-    async def merge(self):
+    async def merge(self, thing: Union[str, RecordID, Table], data: dict) -> Union[List[dict], dict]:
         """
-        Merges the given resource with the given data.
+        Merge specified data into either all records in a table or a single record
 
-        :param resource: the resource to update
-        :param data: the data to merge the resource with
+        :param thing: The Table or Record ID to merge into.
+        :param data: The content for the record.
         :return: the updated resource such as an individual row or a list of rows
         """
-        pass
-
-    async def relate(self):
-        pass
+        return await self.__connection.send('update', thing, data)
 
-    async def insert_relation(self):
-        pass