contiguity · lemonyte · Sep 29, 2024 · Sep 29, 2024 · Sep 29, 2024 · Oct 1, 2024
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,5 @@
+.vscode/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
    hooks:
      - id: check-added-large-files
      - id: check-case-conflict
@@ -11,12 +11,12 @@ repos:
        args: [--markdown-linebreak-ext=md]

  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.8
+    rev: v0.6.9
    hooks:
      - id: ruff
      - id: ruff-format

  - repo: https://github.com/RobertCraigie/pyright-python
-    rev: v1.1.382.post1
+    rev: v1.1.384
    hooks:
      - id: pyright
diff --git a/README.md b/README.md
@@ -23,13 +23,13 @@ db = connect("your-api-key", "your-project-id")
 You can get an API key by fetching it in the [dashboard](https://base.contiguity.co), and a project ID is given to you when creating a project.

 ## <img src="https://avatars.githubusercontent.com/u/47275976?s=280&v=4" alt="Deta Logo" style="vertical-align: middle;" height="30"> For those moving from Deta Space <img src="https://avatars.githubusercontent.com/u/47275976?s=280&v=4" alt="Deta Logo" style="vertical-align: middle;" height="30">
-Contiguity Base is a one-to-one replacement for the old Deta Base API, Deta Base JavaScript SDK, Deta Base Python SDK, and Deta Base Go SDK. The only thing that has changed is initialization. 
+Contiguity Base is a one-to-one replacement for the old Deta Base API, Deta Base JavaScript SDK, Deta Base Python SDK, and Deta Base Go SDK. The only thing that has changed is initialization.

 Instead of `deta = Deta(project_key)`, you'll use `db = connect(api_key, project_id)`

 The rest stays the same, because at Contiguity, we think it's crazy for a cloud provider to give you 45 days to move dozens of apps from their proprietary database.

-If you're transitioning from Deta Space to Contiguity, welcome! 
+If you're transitioning from Deta Space to Contiguity, welcome!

 ## Creating your first "base" 📊

@@ -129,15 +129,15 @@ results = my_base.fetch({

 ```python
 {
-  "age": 22, 
+  "age": 22,
  "name": "Sarah"
 }
 ```

 - **Hierarchical**  
 ```python
 {
-  "user.profile.age": 22, 
+  "user.profile.age": 22,
  "user.profile.name": "Sarah"
 }
 ```
@@ -152,8 +152,8 @@ results = my_base.fetch({
 - **Nested Object**  
 ```python
 {
-  "time": { 
-    "day": "Tuesday", 
+  "time": {
+    "day": "Tuesday",
    "hour": "08:00"
  }
 }

diff --git a/api.md b/api.md
@@ -0,0 +1,189 @@
+# Base API
+
+## GET /items/{key}
+
+SDK method: `get(key: str) -> Item`
+
+Response `200`:
+Returns a single item.
+
+```json
+{
+    "key": "foo",
+    "field1": "bar"
+    // ...other item fields
+}
+```
+
+Response `404`:
+Key does not exist.
+
+```text
+No content
+```
+
+## DELETE /items/{key}
+
+SDK method: `delete(key: str) -> None`
+
+Response `204`:
+Returns nothing.
+
+```text
+No content
+```
+
+## POST /items
+
+SDK method: `insert(item: Item) -> Item`
+
+Request body:
+
+```json
+{
+    "item": {
+        "key": "foo",
+        "field1": "bar",
+        // ...other item fields
+        "__expires": 1727765807 // optional Unix timestamp
+    }
+}
+```
+
+Response `201`:
+Returns a list of items.
+
+```json
+[
+    {
+        "key": "foo",
+        "field1": "bar"
+        // ...other item fields
+    }
+    // ...other items
+]
+```
+
+Response `409`:
+Key already exists.
+
+```text
+No content
+```
+
+## PUT /items
+
+SDK method: `put(items: Item[]) -> Item[]`
+
+Request body:
+
+```json
+{
+    "items": [
+        {
+            "key": "foo",
+            "field1": "bar",
+            // ...other item fields
+            "__expires": 1727765807 // optional Unix timestamp
+        }
+        // ...other items
+    ]
+}
+```
+
+Response `201`:
+Returns a list of items.
+
+```json
+[
+    {
+        "key": "foo",
+        "field1": "bar"
+        // ...other item fields
+    }
+    // ...other items
+]
+```
+
+## PATCH /items/{key}
+
+SDK method: `update(updates: Mapping, key: str) -> Item`
+
+Request body:
+
+```json
+{
+    "set": {
+        "field1": "bar",
+        // ...other item fields
+        "__expires": 1727765807 // optional Unix timestamp
+    },
+    "increment": {
+        "field2": 1,
+        "field3": -2
+    },
+    "append": {
+        "field4": ["baz"]
+    },
+    "prepend": {
+        "field5": ["foo", "bar"]
+    },
+    "delete": ["field6"]
+}
+```
+
+Response `200`:
+Returns a single item.
+
+```json
+{
+    "key": "foo",
+    "field1": "bar"
+    // ...other item fields
+}
+```
+
+Response `404`:
+Key does not exist.
+
+```text
+No content
+```
+
+## GET /query
+
+SDK method: `fetch(*query: Query) -> Item[]`
+
+Request body:
+
+```json
+{
+    "limit": 10,
+    "last_key": "foo",
+    "query": [
+        {
+            "field1": "foo",
+            "field4?contains": "bar"
+            // multiple conditions are ANDed
+        },
+        {
+            "field3?gt": 2
+        }
+        // multiple queries are ORed
+    ]
+}
+```
+
+Response `200`:
+Returns a list of items.
+
+```json
+[
+    {
+        "key": "foo",
+        "field1": "bar"
+        // ...other item fields
+    }
+    // ...other items
+]
+```
diff --git a/examples/__init__.py b/examples/__init__.py
diff --git a/examples/basic_usage.py b/examples/basic_usage.py
@@ -1,44 +1,40 @@
-from contiguity_base import connect
-
-# Initialize the Contiguity client
-db = connect("api-key", "project-id")
-
-# Create a Base instance
-my_base = db.Base("randomBase9000")
-
-# Helper function to print results
-def print_result(operation, result):
-    print(f"{operation} result: {result}")
-    if result is None:
-        print(f"Warning: {operation} operation failed!")
-
-# Put an item with a specific key
-result1 = my_base.put({"value": "Hello world!"}, "my-key-py")
-print_result("Put", result1)
-
-# Insert an item with a specific key
-result2 = my_base.insert({"name": "John Doe", "age": 30}, "john-doe-py")
-print_result("Insert", result2)
-
-# Insert an item with a specific key and expireIn
-result3 = my_base.insert({"name": "Jane Doe", "age": 28}, "jane-doe-py", expire_in=3600)
-print_result("Insert with expireIn", result3)
-
-# Get an item
-get_result = my_base.get("john-doe-py")
-print_result("Get", get_result)
-
-# Update an item
-update_result = my_base.update({"age": 31}, "john-doe-py")
-print_result("Update", update_result)
-
-# Fetch items
-try:
-    fetch_result = my_base.fetch({"age": {"$gt": 25}}, limit=10)
-    print_result("Fetch", fetch_result)
-except Exception as e:
-    print(f"Fetch operation failed: {str(e)}")
-
-# Delete an item
-delete_result = my_base.delete("jane-doe-py")
-print_result("Delete", delete_result)
+# ruff: noqa: T201
+from contiguity_base import Base
+
+# Create a Base instance.
+db = Base("my-base")
+
+# Put an item with a specific key.
+put_result = db.put({"key": "foo", "value": "Hello world!"})
+print("Put result:", put_result)
+
+# Put multiple items.
+put_result = db.put({"key": "bar", "value": "Bar"}, {"key": "baz", "value": "Baz"})
+print("Put many result:", put_result)
+
+# Insert an item with a specific key.
+insert_result = db.insert({"key": "john-doe", "name": "John Doe", "age": 30})
+print("Insert result:", insert_result)
+
+# Insert an item with a specific key that expires in 1 hour.
+expiring_insert_result = db.insert({"key": "jane-doe", "name": "Jane Doe", "age": 28}, expire_in=3600)
+print("Insert with expiry result:", expiring_insert_result)
+
+# Get an item using a key.
+get_result = db.get("foo")
+print("Get result:", get_result)
+
+# Update an item.
+update_result = db.update({"age": db.util.increment(2), "name": "Mr. Doe"}, key="john-doe")
+print("Update result:", update_result)
+
+# Query items.
+query_result = db.query({"age?gt": 25}, limit=10)
+print("Query result:", query_result)
+
+# Delete an item.
+db.delete("jane-doe-py")
+
+# Delete all items.
+for item in db.query().items:
+    db.delete(str(item["key"]))