add docstring, add eagerloading for sqlalchemy data layer for include querystring parameter, increase interface conversion between logical data abstraction and real data model and add enhancements from pull requests

Author: akira-dev

flask_rest_jsonapi/api.py

@@ -1,14 +1,25 @@
 # -*- coding: utf-8 -*-
 
+"""This module contains the main class of the Api to initialize the Api, plug default decorators for each resources
+methods, speficy which blueprint to use, define the Api routes and plug additional oauth manager and permission manager
+"""
+
 import inspect
 from functools import wraps
 
 from flask_rest_jsonapi.resource import ResourceList
 
 
 class Api(object):
+    """The main class of the Api"""
 
     def __init__(self, app=None, blueprint=None, decorators=None):
+        """Initialize an instance of the Api
+
+        :param app: the flask application
+        :param blueprint: a flask blueprint
+        :param tuple decorators: a tuple of decorators plugged to each resource methods
+        """
         self.app = app
         self.blueprint = blueprint
         self.resources = []
@@ -35,6 +46,8 @@ def init_app(self, app=None, blueprint=None):
         if self.blueprint is not None:
             self.app.register_blueprint(self.blueprint)
 
+        self.app.config.setdefault('PAGE_SIZE', 30)
+
     def route(self, resource, view, *urls, **kwargs):
         """Create an api view.
 
@@ -122,8 +135,7 @@ def permission_manager(self, permission_manager):
                             self.has_permission()(getattr(resource, method.lower())))
 
     def has_permission(self, *args, **kwargs):
-        """Decorator used to check permissions before to call resource manager method
-        """
+        """Decorator used to check permissions before to call resource manager method"""
         def wrapper(view):
             if getattr(view, '_has_permissions_decorator', False) is True:
                 return view

flask_rest_jsonapi/constants.py

@@ -1,20 +1,30 @@
 # -*- coding: utf-8 -*-
 
+"""This module is a CRUD interface between resource managers and the sqlalchemy ORM"""
+
 from sqlalchemy.orm.exc import NoResultFound
 from sqlalchemy.orm.collections import InstrumentedList
 from sqlalchemy.inspection import inspect
+from sqlalchemy.orm import joinedload
+from marshmallow import class_registry
+from marshmallow.base import SchemaABC
 
-from flask_rest_jsonapi.constants import DEFAULT_PAGE_SIZE
+from flask import current_app
 from flask_rest_jsonapi.data_layers.base import BaseDataLayer
 from flask_rest_jsonapi.exceptions import RelationNotFound, RelatedObjectNotFound, JsonApiException,\
     InvalidSort, ObjectNotFound
 from flask_rest_jsonapi.data_layers.filtering.alchemy import create_filters
-from flask_rest_jsonapi.schema import get_relationships
+from flask_rest_jsonapi.schema import get_model_field, get_related_schema, get_relationships
 
 
 class SqlalchemyDataLayer(BaseDataLayer):
+    """Sqlalchemy data layer"""
 
     def __init__(self, kwargs):
+        """Initialize an instance of SqlalchemyDataLayer
+
+        :param dict kwargs: initialization parameters of an SqlalchemyDataLayer instance
+        """
         super(SqlalchemyDataLayer, self).__init__(kwargs)
 
         if not hasattr(self, 'session'):
@@ -34,7 +44,8 @@ def create_object(self, data, view_kwargs):
         self.before_create_object(data, view_kwargs)
 
         relationship_fields = get_relationships(self.resource.schema)
-        obj = self.model(**{key: value for (key, value) in data.items() if key not in relationship_fields})
+        obj = self.model(**{get_model_field(self.resource.schema, key): value
+                            for (key, value) in data.items() if key not in relationship_fields})
         self.apply_relationships(data, obj)
 
         self.session.add(obj)
@@ -93,11 +104,14 @@ def get_collection(self, qs, view_kwargs):
 
         object_count = query.count()
 
+        if getattr(self, 'eagerload_includes', True):
+            query = self.eagerload_includes(query, qs)
+
         query = self.paginate_query(query, qs.pagination)
 
         collection = query.all()
 
-        self.after_get_collection(collection, qs, view_kwargs)
+        collection = self.after_get_collection(collection, qs, view_kwargs)
 
         return object_count, collection
 
@@ -119,8 +133,8 @@ def update_object(self, obj, data, view_kwargs):
 
         relationship_fields = get_relationships(self.resource.schema)
         for key, value in data.items():
-            if hasattr(obj, key) and key not in relationship_fields:
-                setattr(obj, key, value)
+            if hasattr(obj, get_model_field(self.resource.schema, key)) and key not in relationship_fields:
+                setattr(obj, get_model_field(self.resource.schema, key), value)
 
         self.apply_relationships(data, obj)
 
@@ -380,11 +394,13 @@ def apply_relationships(self, data, obj):
         :param DeclarativeMeta obj: the sqlalchemy object to plug relationships to
         :return boolean: True if relationship have changed else False
         """
+        relationships_to_apply = []
         relationship_fields = get_relationships(self.resource.schema)
         for key, value in data.items():
             if key in relationship_fields:
-                related_model = getattr(obj.__class__, key).property.mapper.class_
-                related_id_field = self.resource.schema._declared_fields[relationship_fields[key]].id_field
+                related_model = getattr(obj.__class__,
+                                        get_model_field(self.resource.schema, key)).property.mapper.class_
+                related_id_field = self.resource.schema._declared_fields[key].id_field
 
                 if isinstance(value, list):
                     related_objects = []
@@ -393,14 +409,17 @@ def apply_relationships(self, data, obj):
                         related_object = self.get_related_object(related_model, related_id_field, {'id': identifier})
                         related_objects.append(related_object)
 
-                    setattr(obj, key, related_objects)
+                    relationships_to_apply.append({'field': key, 'value': related_objects})
                 else:
                     related_object = None
 
                     if value is not None:
                         related_object = self.get_related_object(related_model, related_id_field, {'id': value})
 
-                    setattr(obj, key, related_object)
+                    relationships_to_apply.append({'field': key, 'value': related_object})
+
+        for relationship in relationships_to_apply:
+            setattr(obj, get_model_field(self.resource.schema, relationship['field']), relationship['value'])
 
     def filter_query(self, query, filter_info, model):
         """Filter query according to jsonapi 1.0
@@ -441,13 +460,49 @@ def paginate_query(self, query, paginate_info):
         if int(paginate_info.get('size', 1)) == 0:
             return query
 
-        page_size = int(paginate_info.get('size', 0)) or DEFAULT_PAGE_SIZE
+        page_size = int(paginate_info.get('size', 0)) or current_app.config['PAGE_SIZE']
         query = query.limit(page_size)
         if paginate_info.get('number'):
             query = query.offset((int(paginate_info['number']) - 1) * page_size)
 
         return query
 
+    def eagerload_includes(self, query, qs):
+        """Use eagerload feature of sqlalchemy to optimize data retrieval for include querystring parameter
+
+        :param Query query: sqlalchemy queryset
+        :param QueryStringManager qs: a querystring manager to retrieve information from url
+        :return Query: the query with includes eagerloaded
+        """
+        for include in qs.include:
+            joinload_object = None
+
+            if '.' in include:
+                current_schema = self.resource.schema
+                for obj in include.split('.'):
+                    field = get_model_field(current_schema, obj)
+
+                    if joinload_object is None:
+                        joinload_object = joinedload(field, innerjoin=True)
+                    else:
+                        joinload_object = joinload_object.joinedload(field, innerjoin=True)
+
+                    related_schema_cls = get_related_schema(current_schema, obj)
+
+                    if isinstance(related_schema_cls, SchemaABC):
+                        related_schema_cls = related_schema_cls.__class__
+                    else:
+                        related_schema_cls = class_registry.get_class(related_schema_cls)
+
+                    current_schema = related_schema_cls
+            else:
+                field = get_model_field(self.resource.schema, include)
+                joinload_object = joinedload(field, innerjoin=True)
+
+            query = query.options(joinload_object)
+
+        return query
+
     def query(self, view_kwargs):
         """Construct the base query to retrieve wanted data
 
@@ -502,7 +557,7 @@ def after_get_collection(self, collection, qs, view_kwargs):
         :param QueryStringManager qs: a querystring manager to retrieve information from url
         :param dict view_kwargs: kwargs from the resource view
         """
-        pass
+        return collection
 
     def before_update_object(self, obj, data, view_kwargs):
         """Make checks or provide additional data before update object

flask_rest_jsonapi/data_layers/alchemy.py

@@ -1,9 +1,12 @@
 # -*- coding: utf-8 -*-
 
+"""The base class of a data layer. If you want to create your own data layer you must inherite from this base class"""
+
 import types
 
 
 class BaseDataLayer(object):
+    """Base class of a data layer"""
 
     ADDITIONAL_METHODS = ('query',
                           'before_create_object',

flask_rest_jsonapi/data_layers/base.py

@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
 
+"""Helper to create sqlalchemy filters according to filter querystring parameter"""
+
 from sqlalchemy import and_, or_, not_
 
 from flask_rest_jsonapi.exceptions import InvalidFilters
@@ -21,14 +23,23 @@ def create_filters(model, filter_info, resource):
 
 
 class Node(object):
+    """Helper to recursively create filters with sqlalchemy according to filter querystring parameter"""
 
     def __init__(self, model, filter_, resource, schema):
+        """Initialize an instance of a filter node
+
+        :param Model model: an sqlalchemy model
+        :param dict filter_: filters information of the current node and deeper nodes
+        :param Resource resource: the base resource to apply filters on
+        :param Schema schema: the serializer of the resource
+        """
         self.model = model
         self.filter_ = filter_
         self.resource = resource
         self.schema = schema
 
     def resolve(self):
+        """Create filter for a particular node of the filter tree"""
         if 'or' not in self.filter_ and 'and' not in self.filter_ and 'not' not in self.filter_:
             value = self.value
 
@@ -138,12 +149,10 @@ def related_model(self):
         """
         relationship_field = self.name
 
-        if relationship_field not in get_relationships(self.schema).values():
+        if relationship_field not in get_relationships(self.schema):
             raise InvalidFilters("{} has no relationship attribute {}".format(self.schema.__name__, relationship_field))
 
-        relationship_model_field = get_model_field(self.schema, relationship_field)
-
-        return getattr(self.model, relationship_model_field).property.mapper.class_
+        return getattr(self.model, get_model_field(self.schema, relationship_field)).property.mapper.class_
 
     @property
     def related_schema(self):
@@ -153,7 +162,7 @@ def related_schema(self):
         """
         relationship_field = self.name
 
-        if relationship_field not in get_relationships(self.schema).values():
+        if relationship_field not in get_relationships(self.schema):
             raise InvalidFilters("{} has no relationship attribute {}".format(self.schema.__name__, relationship_field))
 
         return self.schema._declared_fields[relationship_field].schema.__class__

flask_rest_jsonapi/data_layers/filtering/alchemy.py

@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
 
+"""Decorators to check headers and method requirements for each Api calls"""
+
 import json
 from functools import wraps
 
@@ -23,7 +25,7 @@ def wrapper(*args, **kwargs):
                                                     'title': 'InvalidRequestHeader',
                                                     'status': 415}]))
                 return make_response(error, 415, {'Content-Type': 'application/vnd.api+json'})
-        if request.headers.get('Accept') and not 'application/vnd.api+json' in request.accept_mimetypes:
+        if request.headers.get('Accept') and 'application/vnd.api+json' not in request.accept_mimetypes:
             error = json.dumps(jsonapi_errors([{'source': '',
                                                 'detail': "Accept header must be application/vnd.api+json",
                                                 'title': 'InvalidRequestHeader',

flask_rest_jsonapi/decorators.py

@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
 
+"""Helper to  format Api errors according to jsonapi specification"""
+
 
 def jsonapi_errors(jsonapi_errors):
     """Construct api error according to jsonapi 1.0