reachcollective-utils 0.1.0__tar.gz

reachcollective_utils-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.3
+Name: reachcollective-utils
+Version: 0.1.0
+Summary: Utilities for developing RESTful API, Open API projects with FastAPI and Python
+Author: Juan Minaya
+Author-email: minayaleon@gmail.com
+Requires-Python: >=3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: fastapi[standard] (>=0.115.8,<0.116.0)
+Requires-Dist: pydantic (>=2.10.6,<3.0.0)
+Requires-Dist: sqlmodel (>=0.0.22,<0.0.23)
+Description-Content-Type: text/markdown
+
+# ReachCollective / APIs / Utils
+
+# Requirements
+- sqlmodel (>=0.0.22,<0.0.23)
+- fastapi (>=0.115.8,<0.116.0)
+- pydantic (>=2.10.6,<3.0.0)
+
+# Installation
+
+### Poetry
+```
+poetry add reachcollective-utils
+
+```
+### Pip
+```
+pip install reachcollective-utils
+```
+
+# Examples
+
+## DataGrid
+List and paginate data from a model, accepting filters, sorting, and relationships
+
+### 1. Modify models
+Add `to_dcit()` function to each SQL Model, `to_dcit()` gets relationships.
+
+```python
+
+class Post(SQLModel, table=True):
+    __tablename__ = "posts"
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str | None
+    status: str | None
+    comments: list["Comment"] | None = Relationship(back_populates="post", sa_relationship_kwargs={"lazy": "raise"})
+
+    def to_dict(self, *args, **kwargs):
+        data = super().model_dump(*args, **kwargs)
+        if 'comments' in self.__dict__:
+            data['comments'] = []
+            if self.quota_groups:
+                data['comments'] = [quota_group.to_dict(*args, **kwargs) for quota_group in self.quota_groups]
+
+        return data
+
+
+class Comment(SQLModel, table=True):
+    __tablename__ = "comments"
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    description: str | None
+    post: Optional["Survey"] = Relationship(back_populates="comments", sa_relationship_kwargs={"lazy": "raise"})
+
+    def to_dict(self, *args, **kwargs):
+        data = super().model_dump(*args, **kwargs)
+        if 'post' in self.__dict__:
+            data['post'] = {}
+            if self.survey:
+                data['post'] = self.survey.model_dump(*args, **kwargs)
+
+        return data
+ ```
+
+### 2. Basic use
+```python
+# URL: /posts?sort=-created&filter[status]=active&view=paginate
+
+
+from app.models import Post
+from reachcollective.utils import DataGrid
+
+@router.get('/posts', status_code=HTTPStatus.OK)
+async def list_(
+    request: Request,
+    db: AsyncSession = Depends(get_session)
+):
+    return await DataGrid(db, Post, request).init().get()
+```
+
+### 2. Custom filters
+```python
+# URL: /posts?sort=-created&filter[status]=active&filter[name]=demo&view=paginate
+
+
+from app.models import Post
+from reachcollective.utils import DataGrid
+
+@router.get('/posts', status_code=HTTPStatus.OK)
+async def list_(
+    request: Request,
+    db: AsyncSession = Depends(get_session)
+):
+    datagrid = DataGrid(db, Post, request)
+    datagrid.qp.filters.personalize = ['name']
+    datagrid.init()
+
+    for key, value in datagrid.params['filters']['customize'].items():
+        match key:
+            case 'name':
+                datagrid.qb.stmt = datagrid.qb.stmt.where(Post.name.ilike(f'%{value}%'))
+
+    return await datagrid.get()
+ ```
+
+### 3. Result
+```json
+{
+  "current_page": 1,
+  "data": [
+    {
+      "description": "",
+      "id": "18a6ac49-cb2f-41c7-ac14-ff5360210c65",
+      "name": "demo",
+      "status": "active"
+    },
+    {
+      "id": "81f08423-288f-4e74-bcbb-edf5ef37f1fe",
+      "name": "demo",
+      "status": "active"
+    },
+    {
+      "d": "a017c74f-f0bb-4f65-9faf-36581812bbe7",
+      "name": "Test 4",
+      "status": "active"
+    }
+  ],
+  "total": 683,
+  "per_page": 15,
+  "total_pages": 46
+}
+```

reachcollective_utils-0.1.0/README.md

@@ -0,0 +1,132 @@
+# ReachCollective / APIs / Utils
+
+# Requirements
+- sqlmodel (>=0.0.22,<0.0.23)
+- fastapi (>=0.115.8,<0.116.0)
+- pydantic (>=2.10.6,<3.0.0)
+
+# Installation
+
+### Poetry
+```
+poetry add reachcollective-utils
+
+```
+### Pip
+```
+pip install reachcollective-utils
+```
+
+# Examples
+
+## DataGrid
+List and paginate data from a model, accepting filters, sorting, and relationships
+
+### 1. Modify models
+Add `to_dcit()` function to each SQL Model, `to_dcit()` gets relationships.
+
+```python
+
+class Post(SQLModel, table=True):
+    __tablename__ = "posts"
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str | None
+    status: str | None
+    comments: list["Comment"] | None = Relationship(back_populates="post", sa_relationship_kwargs={"lazy": "raise"})
+
+    def to_dict(self, *args, **kwargs):
+        data = super().model_dump(*args, **kwargs)
+        if 'comments' in self.__dict__:
+            data['comments'] = []
+            if self.quota_groups:
+                data['comments'] = [quota_group.to_dict(*args, **kwargs) for quota_group in self.quota_groups]
+
+        return data
+
+
+class Comment(SQLModel, table=True):
+    __tablename__ = "comments"
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    description: str | None
+    post: Optional["Survey"] = Relationship(back_populates="comments", sa_relationship_kwargs={"lazy": "raise"})
+
+    def to_dict(self, *args, **kwargs):
+        data = super().model_dump(*args, **kwargs)
+        if 'post' in self.__dict__:
+            data['post'] = {}
+            if self.survey:
+                data['post'] = self.survey.model_dump(*args, **kwargs)
+
+        return data
+ ```
+
+### 2. Basic use
+```python
+# URL: /posts?sort=-created&filter[status]=active&view=paginate
+
+
+from app.models import Post
+from reachcollective.utils import DataGrid
+
+@router.get('/posts', status_code=HTTPStatus.OK)
+async def list_(
+    request: Request,
+    db: AsyncSession = Depends(get_session)
+):
+    return await DataGrid(db, Post, request).init().get()
+```
+
+### 2. Custom filters
+```python
+# URL: /posts?sort=-created&filter[status]=active&filter[name]=demo&view=paginate
+
+
+from app.models import Post
+from reachcollective.utils import DataGrid
+
+@router.get('/posts', status_code=HTTPStatus.OK)
+async def list_(
+    request: Request,
+    db: AsyncSession = Depends(get_session)
+):
+    datagrid = DataGrid(db, Post, request)
+    datagrid.qp.filters.personalize = ['name']
+    datagrid.init()
+
+    for key, value in datagrid.params['filters']['customize'].items():
+        match key:
+            case 'name':
+                datagrid.qb.stmt = datagrid.qb.stmt.where(Post.name.ilike(f'%{value}%'))
+
+    return await datagrid.get()
+ ```
+
+### 3. Result
+```json
+{
+  "current_page": 1,
+  "data": [
+    {
+      "description": "",
+      "id": "18a6ac49-cb2f-41c7-ac14-ff5360210c65",
+      "name": "demo",
+      "status": "active"
+    },
+    {
+      "id": "81f08423-288f-4e74-bcbb-edf5ef37f1fe",
+      "name": "demo",
+      "status": "active"
+    },
+    {
+      "d": "a017c74f-f0bb-4f65-9faf-36581812bbe7",
+      "name": "Test 4",
+      "status": "active"
+    }
+  ],
+  "total": 683,
+  "per_page": 15,
+  "total_pages": 46
+}
+```

reachcollective_utils-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "reachcollective-utils"
+version = "0.1.0"
+description = "Utilities for developing RESTful API, Open API projects with FastAPI and Python"
+authors = [
+    {name = "Juan Minaya",email = "minayaleon@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi[standard] (>=0.115.8,<0.116.0)",
+    "sqlmodel (>=0.0.22,<0.0.23)",
+    "pydantic (>=2.10.6,<3.0.0)"
+]
+
+[tool.poetry]
+packages = [{include = "reachcollective", from = "src"}]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

reachcollective_utils-0.1.0/src/reachcollective/utils/__init__.py

@@ -0,0 +1,7 @@
+from .datagrid.datagrid import DataGrid
+from .datagrid.filters import Filters
+from .datagrid.query_builder import QueryBuilder
+from .datagrid.query_params import QueryParams
+from .datagrid.paginator import Paginator
+from .render import APIRender
+from .exception import APIException

reachcollective_utils-0.1.0/src/reachcollective/utils/datagrid/datagrid.py

@@ -0,0 +1,32 @@
+from fastapi import Request
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from .paginator import Paginator
+from .query_builder import QueryBuilder
+from .query_params import QueryParams
+
+
+class DataGrid:
+    def __init__(self, db: AsyncSession, model, request: Request):
+
+        self.model = model
+        self.db = db
+        self.params = {}
+
+        self.qp: QueryParams = QueryParams(request)
+        self.qb: QueryBuilder | None = None
+
+    def init(self):
+        self.params = self.qp.get()
+        self.qb = QueryBuilder(self.db, self.model, self.params).init()
+
+        return self
+
+    async def get(self):
+        match self.qp.view:
+            case 'paginate':
+                return await Paginator(self.qb, self.qp).get()
+            case 'count':
+                return await self.qb.total()
+            case _:
+                return await self.qb.get()

reachcollective_utils-0.1.0/src/reachcollective/utils/datagrid/filters.py

@@ -0,0 +1,29 @@
+class Filters:
+    def __init__(self, qp=None):
+        self.qp = qp
+        self.init = {}
+        self.equals = {}
+        self.personalize = []
+        self.customize = {}
+
+    def process(self):
+        for k, v in self.qp.items():
+            if k.find('filter') >= 0:
+                attr = k[k.find('[') + 1 : k.find(']')]
+                t = self.process_value(attr, v)
+                if attr in self.personalize:
+                    self.customize = {**self.customize, **t}
+                else:
+                    self.equals = {**self.equals, **t}
+
+    def get(self):
+        r = {'init': self.init, 'equals': self.equals, 'customize': self.customize}
+        return r
+
+    @staticmethod
+    def process_value(attr, value):
+        parts = value.split('|')
+        if len(parts) > 1:
+            value = parts
+
+        return {attr: value}

reachcollective_utils-0.1.0/src/reachcollective/utils/datagrid/paginator.py

@@ -0,0 +1,45 @@
+import math
+
+from .query_builder import QueryBuilder
+from .query_params import QueryParams
+
+
+class Paginator:
+    def __init__(self, query_builder: QueryBuilder, query_params: QueryParams):
+        self.r = self.get_template()
+        self.qp = query_params
+        self.qb = query_builder
+
+    @staticmethod
+    def get_template() -> dict:
+        return {
+            'current_page': 1,
+            'data': [],
+            'total': None,
+            'per_page': None,
+            'total_pages': None
+        }
+
+    async def build(self):
+        total = await self.qb.total()
+
+        # Current Page
+        self.r['current_page'] = self.qp.page
+
+        # Data
+        offset = self.qp.size * (self.qp.page - 1)
+        self.qb.stmt = self.qb.stmt.offset(offset).limit(self.qp.size)
+        self.r['data'] = await self.qb.get()
+
+        # Total
+        self.r['total'] = total
+
+        # Per Page
+        self.r['per_page'] = self.qp.size
+
+        # Total Page
+        self.r['total_pages'] = math.ceil(total / self.qp.size)
+
+    async def get(self) -> dict:
+        await self.build()
+        return self.r

reachcollective_utils-0.1.0/src/reachcollective/utils/datagrid/query_builder.py

@@ -0,0 +1,67 @@
+from sqlmodel.ext.asyncio.session import AsyncSession
+from sqlmodel import select
+from sqlalchemy.orm import selectinload
+
+
+class QueryBuilder:
+    def __init__(self, db: AsyncSession, model, params):
+        self.model = model
+        self.stmt = None
+        self.params = params
+        self.db = db
+
+    def init(self):
+        filters = {}
+        if ('filters' in self.params) and ('equals' in self.params['filters']):
+            filters = self.params['filters']['equals']
+            if 'init' in self.params['filters']:
+                filters = {**filters, **self.params['filters']['init']}
+
+        self.stmt = select(self.model)
+        self.apply_filters(filters)
+        self.apply_sort()
+
+        if self.params['with']:
+            relationships = self.params['with']
+            self.stmt = self.stmt.options(*[selectinload(getattr(self.model, relation)) for relation in relationships])
+
+        return self
+
+    def apply_filters(self, filters: dict[str, any]):
+        for key, value in filters.items():
+            if value:
+                column = getattr(self.model, key, None)
+                if column:
+                    if isinstance(value, list):
+                        self.stmt = self.stmt.where(column.in_(value))
+                    else:
+                        self.stmt = self.stmt.where(column == value)
+
+    def apply_sort(self):
+        if self.params['sort']:
+            col = self.params['sort'][0]['col']
+            dir_ = self.params['sort'][0]['dir']
+
+            column = getattr(self.model, col, None)
+            if column:
+                if dir_ == 'desc':
+                    self.stmt = self.stmt.order_by(column.desc())
+                else:
+                    self.stmt = self.stmt.order_by(column)
+
+    async def get(self, native = False):
+        result = await self.db.exec(self.stmt)
+        if native:
+            return result.all()
+        else:
+            rows = result.all()
+            # Check only the first record, if available
+            if rows and (not hasattr(rows[0], 'to_dict') or not callable(getattr(rows[0], 'to_dict', None))):
+                return rows
+
+            # If the first record has `to_dict()`, return the transformed list
+            return [o.to_dict() for o in rows]
+
+    async def total(self) -> int:
+        all_ = await self.get(True)
+        return len(all_)

reachcollective_utils-0.1.0/src/reachcollective/utils/datagrid/query_params.py

@@ -0,0 +1,66 @@
+from fastapi import Request
+
+from .filters import Filters
+
+
+class QueryParams:
+    def __init__(self, request: Request, qp=None):
+        self.qp  = qp.copy() if qp else None
+        self.filters = Filters(self.qp)
+        self.sort = []
+        self.view = 'list'
+        self.request = request
+        self.page = 1
+        self.size = 15
+        self.r = {}
+
+    def process_sort(self) -> None:
+        if 'sort' in self.qp:
+            direction = 'asc'
+            col = self.qp['sort']
+            if self.qp['sort'].find('-', 0, 1) >= 0:
+                direction = 'desc'
+                col = self.qp['sort'][1:]
+
+            self.sort = [{'col': col, 'dir': direction, 'by': self.qp['sort']}]
+
+    def process(self) -> None:
+        self.process_sort()
+
+        if 'page' in self.qp:
+            self.page = int(self.qp['page'])
+
+        if 'size' in self.qp:
+            self.size = int(self.qp['size'])
+
+        if 'view' in self.qp:
+            self.view = self.qp['view']
+
+    def get(self):
+        self.qp = dict(self.request.query_params)
+        self.filters.qp = dict(self.request.query_params)
+
+        # Filters
+        self.process()
+        self.filters.process()
+        filters = self.filters.get()
+        if any(filters):
+            self.r['filters'] = filters
+
+        # With
+        parts = []
+        if 'with' in self.qp:
+            parts = self.qp['with'].split(',')
+            for idx, x in enumerate(parts):
+                if x.find('.'):
+                    x = x.replace('.', '__')
+
+                parts[idx] = x.strip()
+
+        self.r['with'] = parts
+        self.r['sort'] = self.sort
+        self.r['view'] = self.view
+        self.r['page'] = self.page
+        self.r['size'] = self.size
+
+        return self.r

reachcollective_utils-0.1.0/src/reachcollective/utils/exception.py

@@ -0,0 +1,18 @@
+class APIException(Exception):
+    def __init__(self,  message: str|None, code: int, detail: dict = None):
+        self.message = message
+        self.code = code
+        self.detail = detail or {}
+
+    def get_error(self) -> str|dict:
+        if self.detail:
+            # Check if resposne from External API attribute (response)
+            if 'response' in self.detail:
+                if self.detail['response']:
+                    return self.detail['response']
+                else:
+                    return self.message
+
+            return self.detail
+
+        return self.message

reachcollective_utils-0.1.0/src/reachcollective/utils/render.py

@@ -0,0 +1,161 @@
+import json
+from http import HTTPStatus
+from typing import Any
+
+from fastapi import Request, HTTPException
+from fastapi.responses import JSONResponse
+from pydantic import ValidationError
+
+from .exception import APIException
+
+
+class APIRender:
+    @staticmethod
+    def display(message, code=200):
+        message = APIRender.clean_message(message)
+        response = message if isinstance(message, dict) else {'title': message}
+        response = APIRender.format_message(response, code)
+        return JSONResponse(
+            status_code=code,
+            content=response
+        )
+
+    @staticmethod
+    def format_message(message: dict, code: int):
+        formatted_message = {
+            'title': '',
+            'type': 'about:blank',
+            'detail': None,
+            'status': code,
+            'instance': '',
+        }
+
+        if 'title' in message:
+            formatted_message['title'] = message['title']
+
+        if not formatted_message['title'] and 'message' in message:
+            formatted_message['title']  = message['message']
+
+        if 'type' in message:
+            formatted_message['type'] = message['type']
+
+        if 'detail' in message:
+            # TSL Fix
+            if 'title' not in message and isinstance(message['detail'], str):
+                formatted_message['title'] = message['detail']
+            else:
+                formatted_message['detail'] = message['detail']
+
+        if 'status' in message:
+            formatted_message['status'] = message['status']
+
+        if 'instance' in message:
+            formatted_message['instance'] = message['instance']
+
+        return formatted_message
+
+    @staticmethod
+    def clean_message(message) -> str|dict:
+        # Check if empty
+        if not message:
+            return ''
+
+        # Check if Dictionary
+        if isinstance(message, dict):
+            return message
+
+        # Check if JSON String
+        try:
+            return json.loads(message)
+        except json.JSONDecodeError:
+            return message
+
+    @staticmethod
+    def error(message=None, code=500):
+        return APIRender.display(message, code)
+
+    @staticmethod
+    def get_plain_message(message=None, code=500) -> str:
+        message = APIRender.clean_message(message)
+
+        # RCP format 1
+        if 'detail' in message:
+            message = message['detail']
+
+        # RCP format 2
+        if 'message' in message:
+            message = message['message']
+
+        if not message:
+            match code:
+                case 401:
+                    message = 'Unauthorized.'
+                case _:
+                    message = 'Unknown error.'
+
+        return message
+
+    @staticmethod
+    def request_errors(e) -> JSONResponse:
+        message = 'The given data was invalid.'
+        formatted_errors = APIRender.clean_data(APIRender.process_errors(e))
+        first_error = formatted_errors[0]
+        if 'loc' in first_error and 'type' in first_error:
+            loc = first_error['loc']
+            type_ = first_error['type']
+            message = f'Field {loc} is {type_}.' if loc != 'body' else f'Body is {type_}.'
+
+        return APIRender.display({'title': message, 'detail': ''}, 422)
+
+    @staticmethod
+    def request_validation_handler(_: Request, e: ValidationError) -> JSONResponse:
+        return APIRender.request_errors(e)
+
+    @staticmethod
+    def http_exception_handler(_: Request, e: HTTPException):
+        message = APIRender.get_plain_message(e.detail, e.status_code)
+
+        if e.status_code == HTTPStatus.UNAUTHORIZED:
+            APIRender.display('Unauthorized.', HTTPStatus.UNAUTHORIZED)
+
+        return APIRender.display(message, e.status_code)
+
+    @staticmethod
+    def app_exception_handler(_: Request, e: APIException):
+        return APIRender.display(e.get_error(), e.code)
+
+    @staticmethod
+    def not_found(resource):
+        message = f'{resource} not found.'
+        return APIRender.display(message, 404)
+
+    @staticmethod
+    def loc_to_dot_sep(loc: tuple[str | int, ...]) -> str:
+        path = ''
+        for i, x in enumerate(loc):
+            if isinstance(x, str):
+                if i > 0:
+                    path += '.'
+                path += x
+            elif isinstance(x, int):
+                path += f'[{x}]'
+            else:
+                raise TypeError('Unexpected type')
+        return path
+
+    @staticmethod
+    def process_errors(e: ValidationError) -> list[dict[str, Any]]:
+        new_errors: list[dict[str, Any]] = e.errors()
+        for error in new_errors:
+            error['loc'] = APIRender.loc_to_dot_sep(error['loc'])
+        return new_errors
+
+    @staticmethod
+    def clean_data(data):
+        cleaned_data = []
+        for item in data:
+            cleaned_item = item.copy()
+            if isinstance(cleaned_item.get('input'), type):
+                cleaned_item['input'] = str(cleaned_item['input'])
+            cleaned_data.append(cleaned_item)
+        return cleaned_data