Skip to content

Commit 326b19c

Browse files
Ce11anCe11an
authored
Merge branch 'surrealdb:main' into expose-bind-method
2 parents ba11e54 + ffefd8a commit 326b19c

19 files changed

+175
-2884
lines changed

‎README.md

Lines changed: 52 additions & 174 deletions
Original file line numberDiff line numberDiff line change
@@ -1,238 +1,116 @@
1-
<p align="center">
2-
<img width="300" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/icon.png" alt="SurrealDB Icon">
3-
</p>
4-
51
<br>
62

73
<p align="center">
8-
<a href="https://surrealdb.com#gh-dark-mode-only" target="_blank">
9-
<img width="300" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/white/logo.svg" alt="SurrealDB Logo">
10-
</a>
11-
<a href="https://surrealdb.com#gh-light-mode-only" target="_blank">
12-
<img width="300" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/black/logo.svg" alt="SurrealDB Logo">
13-
</a>
4+
<img width=120 src="https://raw.githubusercontent.com/surrealdb/icons/main/surreal.svg" />
5+
&nbsp;
6+
<img width=120 src="https://raw.githubusercontent.com/surrealdb/icons/main/python.svg" />
147
</p>
158

16-
<h3 align="center">
17-
<a href="https://surrealdb.com#gh-dark-mode-only" target="_blank">
18-
<img src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/white/text.svg" height="15" alt="SurrealDB">
19-
</a>
20-
<a href="https://surrealdb.com#gh-light-mode-only" target="_blank">
21-
<img src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/black/text.svg" height="15" alt="SurrealDB">
22-
</a>
23-
is the ultimate cloud <br> database for tomorrow's applications
24-
</h3>
25-
26-
<h3 align="center">Develop easier. &nbsp; Build faster. &nbsp; Scale quicker.</h3>
9+
<h3 align="center">The official SurrealDB SDK for Python.</h3>
2710

2811
<br>
2912

3013
<p align="center">
31-
<a href="https://github.com/surrealdb/surrealdb.py"><img src="https://img.shields.io/badge/status-beta-ff00bb.svg?style=flat-square"></a>
32-
&nbsp;
33-
<a href="https://surrealdb.com/docs/integration/libraries/python"><img src="https://img.shields.io/badge/docs-view-44cc11.svg?style=flat-square"></a>
34-
&nbsp;
35-
<a href="https://github.com/surrealdb/surrealdb.py"><img src="https://img.shields.io/badge/license-Apache_License_2.0-00bfff.svg?style=flat-square"></a>
36-
&nbsp;
37-
<a href="https://twitter.com/surrealdb"><img src="https://img.shields.io/badge/twitter-follow_us-1d9bf0.svg?style=flat-square"></a>
38-
&nbsp;
39-
<a href="https://dev.to/surrealdb"><img src="https://img.shields.io/badge/dev-join_us-86f7b7.svg?style=flat-square"></a>
14+
<a href="https://github.com/surrealdb/surrealdb.py"><img src="https://img.shields.io/badge/status-beta-ff00bb.svg?style=flat-square"></a>
15+
&nbsp;
16+
<a href="https://surrealdb.com/docs/integration/libraries/javascript"><img src="https://img.shields.io/badge/docs-view-44cc11.svg?style=flat-square"></a>
17+
&nbsp;
18+
<a href="https://pypi.org/project/surrealdb/"><img src="https://img.shields.io/pypi/v/surrealdb?style=flat-square"></a>
4019
&nbsp;
41-
<a href="https://www.linkedin.com/company/surrealdb/"><img src="https://img.shields.io/badge/linkedin-connect_with_us-0a66c2.svg?style=flat-square"></a>
20+
<a href="https://pypi.org/project/surrealdb/"><img src="https://img.shields.io/pypi/dm/surrealdb?style=flat-square"></a>
21+
&nbsp;
22+
<a href="https://pypi.org/project/surrealdb/"><img src="https://img.shields.io/pypi/pyversions/surrealdb?style=flat-square"></a>
4223
</p>
4324

4425
<p align="center">
45-
<a href="https://surrealdb.com/blog"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/blog.svg" alt="Blog"></a>
46-
&nbsp;
47-
<a href="https://github.com/surrealdb/surrealdb"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/github.svg" alt="Github "></a>
26+
<a href="https://surrealdb.com/discord"><img src="https://img.shields.io/discord/902568124350599239?label=discord&style=flat-square&color=5a66f6"></a>
4827
&nbsp;
49-
<a href="https://www.linkedin.com/company/surrealdb/"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/linkedin.svg" alt="LinkedIn"></a>
50-
&nbsp;
51-
<a href="https://twitter.com/surrealdb"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/twitter.svg" alt="Twitter"></a>
52-
&nbsp;
53-
<a href="https://www.youtube.com/channel/UCjf2teVEuYVvvVC-gFZNq6w"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/youtube.svg" alt="Youtube"></a>
54-
&nbsp;
55-
<a href="https://dev.to/surrealdb"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/dev.svg" alt="Dev"></a>
28+
<a href="https://twitter.com/surrealdb"><img src="https://img.shields.io/badge/twitter-follow_us-1d9bf0.svg?style=flat-square"></a>
5629
&nbsp;
57-
<a href="https://surrealdb.com/discord"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/discord.svg" alt="Discord"></a>
30+
<a href="https://www.linkedin.com/company/surrealdb/"><img src="https://img.shields.io/badge/linkedin-connect_with_us-0a66c2.svg?style=flat-square"></a>
5831
&nbsp;
59-
<a href="https://stackoverflow.com/questions/tagged/surrealdb"><img height="25" src="https://raw.githubusercontent.com/surrealdb/surrealdb/main/img/social/stack-overflow.svg" alt="StackOverflow"></a>
60-
32+
<a href="https://www.youtube.com/channel/UCjf2teVEuYVvvVC-gFZNq6w"><img src="https://img.shields.io/badge/youtube-subscribe-fc1c1c.svg?style=flat-square"></a>
6133
</p>
6234

6335
# surrealdb.py
6436

65-
The official SurrealDB library for Python.
66-
67-
[See the documentation here](https://surrealdb.com/docs/integration/libraries/python)
68-
69-
## Getting Started
70-
Below is a quick guide on how to get started with SurrealDB in Python.
71-
72-
### Running SurrealDB
73-
Before we can do anything, we need to download SurrealDB and start the server. The easiest, cleanest way to do this
74-
is with [Docker](https://www.docker.com/) abd [docker-compose](https://docs.docker.com/compose/) with the following
75-
docker-compose file:
76-
77-
```yaml
78-
version: '3'
79-
services:
80-
surrealdb:
81-
image: surrealdb/surrealdb
82-
command: start
83-
environment:
84-
- SURREAL_USER=root
85-
- SURREAL_PASS=root
86-
- SURREAL_LOG=trace
87-
ports:
88-
- 8000:8000
89-
```
90-
Here we are pulling the offical SurrealDB image from Docker Hub and starting it with the `start` command. We are also
91-
setting the environment variables `SURREAL_USER` and `SURREAL_PASS` to `root` and `SURREAL_LOG` to `trace`. This will
92-
allow us to connect to the database with the username `root` and password `root` and will set the log level to `trace`.
93-
Finally, we are exposing port `8000` so we can connect to the database.
37+
The official SurrealDB SDK for Python.
9438

95-
Now that we have everything up and running, we can move onto installing the Python library.
39+
## Documentation
9640

97-
### Installing the Python Library
41+
View the SDK documentation [here](https://surrealdb.com/docs/integration/libraries/python).
9842

99-
Right now the library is in beta, so you will need to install it from GitHub with Rust installed on your machine
100-
as Rust will be needed to compile part of the library. Installation for Rust can be found
101-
[here](https://www.rust-lang.org/tools/install). Once Rust is installed, you can install this library with the
102-
following command:
43+
## How to install
10344

104-
```bash
105-
pip install git+https://github.com/surrealdb/surrealdb.py@rust-no-runtime
45+
```sh
46+
pip install surrealdb
10647
```
10748

108-
Installation can take a while as it needs to compile the Rust code. If you want to use the python client in a Docker
109-
build in production you can use a two layered build which will use Rust to compile the library and then copy the
110-
compiled library into a new python image so your production image doesn't need to have Rust installed. Below is an
111-
example of a Dockerfile that will do this for a Flask application:
112-
113-
```dockerfile
114-
FROM rust:latest as builder
115-
116-
RUN apt-get update
117-
RUN apt install python3.9 -y
118-
RUN apt-get install -y python3-dev -y
119-
RUN apt-get install -y python3-pip -y
120-
RUN pip install --upgrade pip setuptools wheel
49+
## Getting started
12150

122-
RUN apt-get install libclang-dev -y
51+
### Running within synchronous code
12352

124-
# Set the working directory to /app
125-
WORKDIR /app
53+
> This example requires SurrealDB to be [installed](https://surrealdb.com/install) and running on port 8000.
12654
127-
# Copy the current directory contents into the container at /app
128-
ADD . /app
129-
130-
# install the python library locally
131-
RUN pip install ./surreal.py/
132-
133-
# or install the python library from github
134-
RUN pip install git+https://github.com/surrealdb/surrealdb.py@rust-no-runtime
135-
136-
# server build
137-
FROM python:3.9
138-
139-
RUN apt-get update \
140-
&& apt-get install -y python3-dev python3-pip \
141-
&& pip install --upgrade pip setuptools wheel \
142-
&& pip install flask gunicorn
143-
144-
WORKDIR /app
145-
146-
# copy the built python packages from the previous stage to the new image
147-
COPY --from=builder /usr/local/lib/python3.9/dist-packages /usr/local/lib/python3.9/site-packages
148-
149-
# copy the python server app code to the new image
150-
COPY --from=builder /app /app
151-
152-
# Run the python server using gunicorn
153-
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:5002", "--timeout", "900", "main:app"]
154-
```
155-
156-
You can change the python version and the `CMD` could change depending on your application. Now that we have our
157-
python application installing and running with SurrealDB, we can move onto using the python library.
158-
159-
### Using the blocking Python Library
160-
161-
We can then import the library and create the connection with the following code:
55+
Import the SDK and create the database connection:
16256

16357
```python
16458
from surrealdb import SurrealDB
16559

166-
connection = SurrealDB("ws://localhost:8000/database/namespace")
60+
db = SurrealDB("ws://localhost:8000/database/namespace")
16761
```
168-
Here, we can see that we defined the connection protocol as websocket using `ws://`. We then defined the host as
169-
`localhost` and the port as `8000`. Finally, we defined the database and namespace as `database` and `namespace`.
62+
63+
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`.
64+
65+
Finally, we defined the database and namespace as `database` and `namespace`.
17066
We need a database and namespace to connect to SurrealDB.
17167

172-
Now that we have our connection we need to signin using with the following code:
68+
Now that we have our connection we need to signin:
17369

17470
```python
175-
connection.signin({
71+
db.signin({
17672
"username": "root",
17773
"password": "root",
17874
})
17975
```
180-
For our getting started example we are now going to run some simple raw SurrealQL queries to create some users and
181-
then select them. We can then print the outcome of the query with the following code:
76+
We can now run our queries to create some users, select them and print the outcome.
18277

18378
```python
184-
connection.query("CREATE user:tobie SET name = 'Tobie';")
185-
connection.query("CREATE user:jaime SET name = 'Jaime';")
186-
outcome = connection.query("SELECT * FROM user;")
79+
db.query("CREATE user:tobie SET name = 'Tobie';")
80+
db.query("CREATE user:jaime SET name = 'Jaime';")
81+
outcome = db.query("SELECT * FROM user;")
18782
print(outcome)
18883
```
18984

190-
This will give you the following JSON output:
191-
192-
```json
193-
[
194-
{
195-
"id": "user:jaime",
196-
"name": "Jaime"
197-
},
198-
{
199-
"id": "user:tobie",
200-
"name": "Tobie"
201-
}
202-
]
203-
```
204-
205-
### Using the async Python Library
206-
207-
We can then import the library and create the connection with the following code:
208-
209-
```python
210-
from surrealdb import AsyncSurrealDB
85+
### Running within asynchronous code
21186

212-
connection = AsyncSurrealDB("ws://localhost:8000/database/namespace")
213-
await connection.connect()
214-
```
87+
> This example requires SurrealDB to be [installed](https://surrealdb.com/install) and running on port 8000.
21588
216-
Essentially the interface is exactly the same however, the functions are async. Below is a way to run the async code:
89+
The async methods work in the same way, with two main differences:
90+
- Inclusion of `async def / await`.
91+
- You need to call the connect method before signing in.
21792

21893
```python
21994
import asyncio
22095
from surrealdb import AsyncSurrealDB
22196

222-
22397
async def main():
224-
connection = AsyncSurrealDB("ws://localhost:8000/database/namespace")
225-
await connection.connect()
226-
await connection.signin({
98+
db = AsyncSurrealDB("ws://localhost:8000/database/namespace")
99+
await db.connect()
100+
await db.signin({
227101
"username": "root",
228102
"password": "root",
229103
})
230-
await connection.query("CREATE user:tobie SET name = 'Tobie';")
231-
await connection.query("CREATE user:jaime SET name = 'Jaime';")
232-
outcome = await connection.query("SELECT * FROM user;")
104+
await db.query("CREATE user:tobie SET name = 'Tobie';")
105+
await db.query("CREATE user:jaime SET name = 'Jaime';")
106+
outcome = await db.query("SELECT * FROM user;")
233107
print(outcome)
234108

235109

236110
# Run the main function
237111
asyncio.run(main())
238112
```
113+
114+
### Using Jupyter Notebooks
115+
116+
The Python SDK currently only supports the `AsyncSurrealDB` methods.

‎examples/basic_async_example.py

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
from surrealdb import AsyncSurrealDB
2+
3+
async def main():
4+
"""Example of how to use the SurrealDB client."""
5+
db = AsyncSurrealDB("ws://localhost:8000/database/namespace")
6+
7+
await db.connect()
8+
9+
await db.signin({
10+
"username": "root",
11+
"password": "root",
12+
})
13+
14+
print("Using methods")
15+
print("create: " ,await db.create(
16+
"person",
17+
{
18+
"user": "me",
19+
"pass": "safe",
20+
"marketing": True,
21+
"tags": ["python", "documentation"],
22+
},
23+
))
24+
print("read: ", await db.select("person"))
25+
print("update: ", await db.update("person", {
26+
"user":"you",
27+
"pass":"very_safe",
28+
"marketing": False,
29+
"tags": ["Awesome"]
30+
}))
31+
print("delete: ", await db.delete("person"))
32+
33+
# You can also use the query method
34+
# doing all of the above and more in SurrealQl
35+
36+
# In SurrealQL you can do a direct insert
37+
# and the table will be created if it doesn't exist
38+
print("Using justawait db.query")
39+
print("create: ", await db.query("""
40+
insert into person {
41+
user: 'me',
42+
pass: 'very_safe',
43+
tags: ['python', 'documentation']
44+
};
45+
46+
"""))
47+
print("read: ", await db.query("select * from person"))
48+
49+
print("update: ", await db.query("""
50+
update person content {
51+
user: 'you',
52+
pass: 'more_safe',
53+
tags: ['awesome']
54+
};
55+
56+
"""))
57+
print( "delete: ", await db.query("delete person"))
58+
59+
if __name__ == "__main__":
60+
import asyncio
61+
62+
asyncio.run(main())

0 commit comments

Comments
 (0)