DOC-325: Add Python Docs

src/content/doc-sdk-python/concepts/_category_.json

@@ -0,0 +1,4 @@
+{
+    "sidebar_label": "Concepts",
+    "sidebar_position": 6
+}

src/content/doc-sdk-python/concepts/create-a-new-connection.mdx

@@ -0,0 +1,133 @@
+---
+sidebar_position: 1
+sidebar_label: Create a new connection
+title: Python | SDK | Create a new connection
+description: The SurrealDB SDK for Python enables simple and advanced querying of a remote or embedded database.
+---
+
+import Tabs from "@components/Tabs/Tabs.astro"
+import TabItem from "@components/Tabs/TabItem.astro"
+import Label from "@components/shared/Label.astro"
+
+# Create a new connection
+
+When creating a new connection to SurrealDB, you can choose to connect to a local or remote endpoint, specify a namespace and database pair to use, authenticate with an existing token, authenticate using a pair of credentials, or use advanced custom logic to prepare the connection to the database.
+
+First, you need to initialize a new instance of the `Surreal` or `AsyncSurreal` class and connect it to a database endpoint.
+
+
+## Related Methods and Properties
+
+While the `Surreal` class is the primary method to connect to SurrealDB, there are other methods that you can use while managing your connection.
+
+<table>
+	<thead>
+		<tr>
+			<th scope="col">Method</th>
+			<th scope="col">Description</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr>
+			<td scope="row" data-label="Method"><a href="#connect"> <code> Surreal / AsyncSurreal </code></a></td>
+			<td scope="row" data-label="Description">Establishes a persistent connection to the database</td>
+		</tr>
+        <tr>
+            <td scope="row" data-label="Method"><a href="#close"> <code> db.close() </code></a></td>
+            <td scope="row" data-label="Description">Closes the persistent connection to the database</td>
+        </tr>
+		<tr>
+			<td scope="row" data-label="Method"><a href="#use"> <code> db.use()</code></a></td>
+			<td scope="row" data-label="Description">Switch to a specific namespace and database</td>
+		</tr>
+	</tbody>
+</table>
+
+## `Surreal / AsyncSurreal`
+
+You can specify your connection protocol either as `http`, `https`, `ws`, or `wss`.
+
+### Example usage
+```python
+# Connect to a local endpoint with http protocol
+db = Surreal('http://127.0.0.1:8000')
+
+# Connect to a remote endpoint with ws protocol
+db = AsyncSurreal('wss://cloud.surrealdb.com')
+```
+
+### Effect of connection protocol on token & session duration
+
+The connection protocol you choose affects how authentication tokens and sessions work:
+
+With websockets connections (`ws://`, `wss://`) you open a single long-lived stateful connection where after the initial authentication, the session duration applies and if not specified, defaults to `NONE` meaning that the session never expires unless otherwise specified. 
+
+When you connect with a HTTP connection (`http://`, `https://`), every request you make is short-lived and stateless, requiring you to authenticate every request individually for which the token is used, creating a short lived session. Hence, the token duration which defaults to 1 hour applies.
+
+You can extend the session duration of a token or a session by setting the `DURATION` clause when creating a new access method with the [`DEFINE ACCESS METHOD`](/docs/surrealql/statements/define/access) statement or when defining a new user with the [`DEFINE USER`](/docs/surrealql/statements/define/user) statement. 
+
+Learn more about token and session duration in our [security best practices](/docs/surrealdb/reference-guide/security-best-practices#expiration) documentation.
+
+<br />
+
+## `.use()`
+
+Depending on the complexity of your use case, you can switch to a specific namespace and database using the `.use()` method. This is particularly useful if you want to switch to a different setup after connecting. You can also stay in the same namespace but switch to a different database. 
+
+Learn more about the `.use()` method [in the methods section](/docs/sdk/python/methods/use).
+
+### Example usage
+```python
+db.use(namespace='surrealdb', database='docs')
+```
+
+<br />
+
+## `.close()`
+
+The `.close()` method closes the persistent connection to the database. You should call this method when you are done with the connection to free up resources.
+
+
+### Example usage
+
+```python
+db.close()
+```
+
+## Context manager
+
+You can also use Python's context manger to automatically open and close a connection when exiting the context.
+
+## Putting it all together
+
+```python
+from surrealdb import Surreal
+
+# Without using a context manager
+db = Surreal('ws://localhost:8000')
+db.use('namespace', 'database')
+# Sign in and your code...
+db.close()
+
+# Using a context manager
+with Surreal('ws://localhost:8000') as db:
+    db.use('namespace', 'database')
+	# Sign in and your code...
+```
+
+The same applies when using Async
+
+```python
+from surrealdb import AsyncSurreal
+
+# Without using a context manager
+db = AsyncSurreal('ws://localhost:8000')
+await db.use('namespace', 'database')
+# Sign in and your code...
+await db.close()
+
+# Using a context manager
+async with AsyncSurreal('ws://localhost:8000') as db:
+    await db.use('namespace', 'database')
+	# Sign in and your code...
+```