initial commit with nocodb python client library

Author: elchicodepython

LICENSE

@@ -0,0 +1,7 @@
+Copyright 2022 Samuel López Saura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,97 @@
+# NocoDB Python Client
+
+NocoDB is a great Airtable alternative. This client allows python developers
+to use NocoDB API in a simple way.
+
+## Usage
+
+### Client configuration
+```python
+from nocodb.nocodb import NocoDBProject, APIToken, JWTAuthToken
+from nocodb.filters import InFilter, EqFilter
+from nocodb.infra.requests_client import NocoDBRequestsClient
+
+
+# Usage with API Token
+client = NocoDBRequestsClient(
+        # Your API Token retrieved from NocoDB conf
+        APIToken("YOUR-API-TOKEN"),
+        # Your nocodb root path
+        "http://localhost:8080"
+)
+
+# Usage with JWT Token
+client = NocoDBRequestsClient(
+        # Your API Token retrieved from NocoDB conf
+        JWTAuthToken("your.jwt.token"),
+        # Your nocodb root path
+        "http://localhost:8080"
+)
+```
+
+### Project selection
+```python
+# Be very carefull with org, project_name and table names
+# weird errors from nocodb can arrive if they are wrong
+# example: id is not defined...
+# probably they will fix that in a future release.
+project = NocoDBProject(
+        "noco", # org name. noco by default
+        "myproject" # project name. Case sensitive!!
+)
+
+```
+
+### Table rows operations
+```python
+table_name = "tablename"
+
+# Retrieve a page of rows from a table
+table_rows = client.table_row_list(project, table_name)
+
+# Retrieve the first 10000 rows
+table_rows = client.table_row_list(project, table_name, params={'limit': 10000})
+
+# Skip 100 rows
+table_rows = client.table_row_list(project, table_name, params={'offset': 100})
+
+# Filter the query
+# Currently only one filter at a time is allowed. I don't know how to join
+# multiple conditions in nocodb dsl. If you know how please let me know :).
+table_rows = client.table_row_list(project, table_name, InFilter("name", "sam"))
+table_rows = client.table_row_list(project, table_name, filter_obj=EqFilter("Id", 100))
+
+# Retrieve a single row
+row_id = 10
+row = client.table_row_detail(project, table_name, row_id)
+
+# Create a new row
+row_info = {
+    "name": "my thoughts",
+    "content": "i'm going to buy samuel a beer because i love this module",
+    "mood": ":)"
+}
+client.table_row_create(project, table_name, row_info)
+
+# Update a row
+row_id = 2
+row_info = {
+    "content": "i'm going to buy samuel a new car because i love this module",
+}
+client.table_row_update(project, table_name, row_id, row_info)
+
+# Delete a row (only if you've already bought me a beer)
+client.table_row_delete(project, table_name, row_id)
+```
+
+## Author notes
+
+I created this package to bootstrap some personal projects and I hope it
+will help other developers from the python community. It's not completed but
+it has what I needed: A full CRUD with some filters.
+
+Feel free to add new capabilities by creating a new MR.
+
+## Contributors
+
+- Samuel López Saura

nocodb/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

nocodb/api.py

@@ -0,0 +1,56 @@
+from enum import Enum
+from .nocodb import NocoDBProject
+
+
+class NocoDBAPIUris(Enum):
+    V1_DB_DATA_PREFIX = "api/v1/db/data"
+
+
+class NocoDBAPI:
+    def __init__(self, base_uri: str):
+        self.__base_data_uri = (
+            f"{base_uri}/{NocoDBAPIUris.V1_DB_DATA_PREFIX.value}"
+        )
+
+    def get_table_uri(self, project: NocoDBProject, table: str) -> str:
+        return "/".join(
+            (
+                self.__base_data_uri,
+                project.org_name,
+                project.project_name,
+                table,
+            )
+        )
+
+    def get_row_detail_uri(
+        self, project: NocoDBProject, table: str, row_id: int
+    ):
+        return "/".join(
+            (
+                self.__base_data_uri,
+                project.org_name,
+                project.project_name,
+                table,
+                str(row_id),
+            )
+        )
+
+    def get_nested_relations_rows_list_uri(
+        self,
+        project: NocoDBProject,
+        table: str,
+        relation_type: str,
+        row_id: int,
+        column_name: str,
+    ) -> str:
+        return "/".join(
+            (
+                self.__base_data_uri,
+                project.org_name,
+                project.project_name,
+                table,
+                str(row_id),
+                relation_type,
+                column_name,
+            )
+        )

nocodb/filters.py

@@ -0,0 +1,19 @@
+from .nocodb import WhereFilter
+
+
+class InFilter(WhereFilter):
+    def __init__(self, column_name: str, value: str):
+        self.__column_name = column_name
+        self.__value = value
+
+    def get_where(self) -> str:
+        return f"({self.__column_name},like,%{self.__value}%)"
+
+
+class EqFilter(WhereFilter):
+    def __init__(self, column_name: str, value: str):
+        self.__column_name = column_name
+        self.__value = value
+
+    def get_where(self) -> str:
+        return f"({self.__column_name},eq,{self.__value})"

nocodb/infra/__init__.py

@@ -0,0 +1,78 @@
+from typing import Optional
+from ..nocodb import (
+    NocoDBClient,
+    NocoDBProject,
+    AuthToken,
+    WhereFilter,
+)
+from ..api import NocoDBAPI
+from ..utils import get_query_params
+
+import requests
+
+
+class NocoDBRequestsClient(NocoDBClient):
+    def __init__(self, auth_token: AuthToken, base_uri: str):
+        self.__session = requests.Session()
+        self.__session.headers.update(
+            auth_token.get_header(),
+        )
+        self.__session.headers.update({"Content-Type": "application/json"})
+        self.__api_info = NocoDBAPI(base_uri)
+
+    def table_row_list(
+        self,
+        project: NocoDBProject,
+        table: str,
+        filter_obj: Optional[WhereFilter] = None,
+        params: Optional[dict] = None,
+    ) -> dict:
+
+        response = self.__session.get(
+            self.__api_info.get_table_uri(project, table),
+            params=get_query_params(filter_obj, params),
+        )
+        return response.json()
+
+    def table_row_create(
+        self, project: NocoDBProject, table: str, body: dict
+    ) -> dict:
+        return self.__session.post(
+            self.__api_info.get_table_uri(project, table), json=body
+        ).json()
+
+    def table_row_detail(
+        self, project: NocoDBProject, table: str, row_id: int
+    ) -> dict:
+        return self.__session.get(
+            self.__api_info.get_row_detail_uri(project, table, row_id),
+        ).json()
+
+    def table_row_update(
+        self, project: NocoDBProject, table: str, row_id: int, body: dict
+    ) -> dict:
+        return self.__session.patch(
+            self.__api_info.get_row_detail_uri(project, table, row_id),
+            json=body,
+        ).json()
+
+    def table_row_delete(
+        self, project: NocoDBProject, table: str, row_id: int
+    ) -> int:
+        return self.__session.delete(
+            self.__api_info.get_row_detail_uri(project, table, row_id),
+        ).json()
+
+    def table_row_nested_relations_list(
+        self,
+        project: NocoDBProject,
+        table: str,
+        relation_type: str,
+        row_id: int,
+        column_name: str,
+    ) -> dict:
+        return self.__session.get(
+            self.__api_info.get_nested_relations_rows_list_uri(
+                project, table, relation_type, row_id, column_name
+            )
+        ).json()

nocodb/infra/requests_client.py

@@ -0,0 +1,91 @@
+from abc import ABC, abstractmethod
+
+
+"""
+License MIT
+
+Copyright 2022 Samuel López Saura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+
+class AuthToken(ABC):
+    @abstractmethod
+    def get_header(self) -> dict:
+        pass
+
+
+class APIToken:
+    def __init__(self, token: str):
+        self.__token = token
+
+    def get_header(self) -> dict:
+        return {"xc-token": self.__token}
+
+
+class JWTAuthToken:
+    def __init__(self, token: str):
+        self.__token = token
+
+    def get_header(self) -> dict:
+        return {"xc-auth": self.__token}
+
+
+class WhereFilter(ABC):
+    @abstractmethod
+    def get_where(self) -> str:
+        pass
+
+
+"""This could be great but actually I don't know how to join filters in the
+NocoDB DSL. I event don't know if this is possible through the current API.
+I hope they add docs about it soon.
+
+class NocoDBWhere:
+
+    def __init__(self):
+        self.__filter_array: List[WhereFilter] = []
+
+    def add_filter(self, where_filter: WhereFilter) -> NocoDBWhere:
+        self.__filter_array.append(
+                where_filter
+        )
+        return self
+
+    def get_where(self) -> str:
+        return '&'.join([filter_.get_where() for filter_ in self.__filter_array])
+
+    def __str__(self):
+        return f'Where: "{self.get_where()}"'
+"""
+
+
+class NocoDBProject:
+    def __init__(self, org_name: str, project_name: str):
+        self.project_name = project_name
+        self.org_name = org_name
+
+
+class NocoDBClient:
+    @abstractmethod
+    def table_row_list(
+        self, project: NocoDBProject, table: str, filter_obj=None, params=None
+    ) -> dict:
+        pass

nocodb/nocodb.py

@@ -0,0 +1,5 @@
+def get_query_params(filter_obj, params) -> dict:
+    query_params = params or {}
+    if filter_obj:
+        query_params["where"] = filter_obj.get_where()
+    return query_params