Readme update (#124)

Author: remade

README.md

@@ -46,71 +46,173 @@ View the SDK documentation [here](https://surrealdb.com/docs/integration/librari
 pip install surrealdb
 ```
 
-## Getting started
+## Basic Usage
+> All examples assume SurrealDB is [installed](https://surrealdb.com/install) and running on port 8000.
+### Initialization
+To start using the database, create an instance of SurrealDB, connect to your SurrealDB server, and specify the
+namespace and database you wish to work with.
+```python
+from surrealdb import SurrealDB
 
-### Running within synchronous code
+# Connect to the database
+db = SurrealDB(url="ws://localhost:8080")
+db.connect()
+db.use("namespace", "database_name")
+```
 
-> This example requires SurrealDB to be [installed](https://surrealdb.com/install) and running on port 8000.
+### Using context manager
+The library supports Python’s context manager to manage connections automatically. 
+This ensures that connections are properly closed when the block of code finishes executing.
+```python
+from surrealdb import SurrealDB
 
-Import the SDK and create the database connection:
+with SurrealDB(url="ws://localhost:8080") as db:
+    db.use("namespace", "database_name")
+```
 
+### Using Async
+The AsyncSurrealDB supports asynchronous operations while retaining compatibility with synchronous workflows, 
+ensuring flexibility for any range of use cases. The APIs do not differ 
 ```python
-from surrealdb import SurrealDB
+from surrealdb import AsyncSurrealDB
+
+async with AsyncSurrealDB(url="ws://localhost:8080") as db:
+    await db.use("namespace", "database_name")
+```
+Without context manager:
+```python
+from surrealdb import AsyncSurrealDB
 
-db = SurrealDB("ws://localhost:8000/database/namespace")
+# Connect to the database
+db = AsyncSurrealDB(url="ws://localhost:8080")
+await db.connect()
+await db.use("namespace", "database_name")
 ```
 
-Here, we can see that we defined the connection protocol as WebSocket using `ws://`. We then defined the host as `localhost` and the port as `8000`.
+## Connection Engines
+There are 3 available connection engines you can use to connect to SurrealDb backend. It can be via Websocket, HTTP or
+through embedded database connections. The connection types are simply determined by the url scheme provided in 
+the connection url.
+
+### Via Websocket
+Websocket url can be `ws` or `wss` for secure connection. For example `ws://localhost:8000` and `wss://localhost:8000`.
+All functionalities are available via websockets.
+
+### Via HTTP
+HTTP url can be `http` or `https` for secure connection. For example `http://localhost:8000` and `https://localhost:8000`.
+There are some functions that are not available on RPC when using HTTP but are on Websocket. This includes all 
+live query/notification methods.
 
-Finally, we defined the database and namespace as `database` and `namespace`.
-We need a database and namespace to connect to SurrealDB. 
 
-Now that we have our connection we need to signin:
+### Using SurrealKV and Memory
+SurrealKV and In-Memory also do not support live notifications at this time. This would be updated in a later 
+release.
 
+For Surreal KV
 ```python
-db.signin({
-    "username": "root",
-    "password": "root",
-})
+from surrealdb import SurrealDB
+
+db = SurrealDB("surrealkv://path/to/dbfile.kv")
+```
+For Memory
+```python
+from surrealdb import SurrealDB
+
+db = SurrealDB("mem://")
+db = SurrealDB("memory://")
 ```
-We can now run our queries to create some users, select them and print the outcome.
 
+## Usage Examples
+### Insert and Retrieve Data
 ```python
-db.query("CREATE user:tobie SET name = 'Tobie';")
-db.query("CREATE user:jaime SET name = 'Jaime';")
-outcome = db.query("SELECT * FROM user;")
-print(outcome)
+from surrealdb import SurrealDB
+
+db = SurrealDB("ws://localhost:8080")
+db.connect()
+db.use("example_ns", "example_db")
+
+# Insert a record
+new_user = {"name": "Alice", "age": 30}
+inserted_record = db.insert("users", new_user)
+print(f"Inserted Record: {inserted_record}")
+
+# Retrieve the record
+retrieved_users = db.select("users")
+print(f"Retrieved Users: {retrieved_users}")
+
+db.close()
 ```
 
-### Running within asynchronous code
+### Perform a Custom Query
+```python
+from surrealdb import AsyncSurrealDB
 
-> This example requires SurrealDB to be [installed](https://surrealdb.com/install) and running on port 8000.
+async with AsyncSurrealDB(url="ws://localhost:8080") as db:
+    query = "SELECT * FROM users WHERE age > $min_age"
+    variables = {"min_age": 25}
 
-The async methods work in the same way, with two main differences:
-- Inclusion of `async def / await`.
-- You need to call the connect method before signing in.
+    results = await db.query(query, variables)
+    print(f"Query Results: {results}")
+```
+
+### Manage Authentication
+```python
+from surrealdb import SurrealDB
+
+with SurrealDB(url="ws://localhost:8080") as db:
+    # Sign up a new user
+    token = db.sign_up(username="new_user", password="secure_password")
+    print(f"New User Token: {token}")
+    
+    # Sign in as an existing user
+    token = db.sign_in(username="existing_user", password="secure_password")
+    print(f"Signed In Token: {token}")
+    
+    # Authenticate using a token
+    db.authenticate(token=token)
+    print("Authentication successful!")
+```
 
+### Live Query Notifications
 ```python
 import asyncio
-from surrealdb import AsyncSurrealDB
+from surrealdb.surrealdb import SurrealDB
+
+db = SurrealDB("ws://localhost:8080")
+db.connect()
+db.use("example_ns", "example_db")
+
+# Start a live query
+live_id = db.live("users")
+
+# Process live notifications
+notifications = db.live_notifications(live_id)
+
+async def handle_notifications():
+    while True:
+        notification = await notifications.get()
+        print(f"Live Notification: {notification}")
+
+# Run the notification handler
+asyncio.run(handle_notifications())
+```
+
+### Upserting Records
+```python
+from surrealdb.surrealdb import SurrealDB
+
+db = SurrealDB("ws://localhost:8080")
+db.connect()
+db.use("example_ns", "example_db")
+
+upsert_data = {"id": "user:123", "name": "Charlie", "age": 35}
+result = db.upsert("users", upsert_data)
+print(f"Upsert Result: {result}")
 
-async def main():
-    db = AsyncSurrealDB("ws://localhost:8000/database/namespace")
-    await db.connect()
-    await db.signin({
-        "username": "root",
-        "password": "root",
-    })
-    await db.query("CREATE user:tobie SET name = 'Tobie';")
-    await db.query("CREATE user:jaime SET name = 'Jaime';")
-    outcome = await db.query("SELECT * FROM user;")
-    print(outcome)
-
-
-# Run the main function
-asyncio.run(main())
+db.close()
 ```
 
-### Using Jupyter Notebooks
+## Contributing
+Contributions to this library are welcome! If you encounter issues, have feature requests, or 
+want to make improvements, feel free to open issues or submit pull requests.
 
-The Python SDK currently only supports the `AsyncSurrealDB` methods.