Add filtering support, rename endpoints, refactor object extend (closes #17) (#30)

* Add filtering support, rename endpoints, refactor object extend

* Remove type hint that breaks Travis Python3.5 test

* Fix overlooked edit from switching filters= to rules=

* Fix default dict, fix indent bug

* Refactor rules query parm, remove handle query parm

Author: cdhorn

gramps_webapi/api/__init__.py

@@ -10,6 +10,7 @@
 from .resources.citation import CitationResource, CitationsResource
 from .resources.event import EventResource, EventsResource
 from .resources.family import FamiliesResource, FamilyResource
+from .resources.filters import FilterResource
 from .resources.media import MediaObjectResource, MediaObjectsResource
 from .resources.metadata import MetadataResource
 from .resources.note import NoteResource, NotesResource
@@ -31,49 +32,51 @@ def register_endpt(resource: Type[Resource], url: str, name: str):
 
 
 # Person
-register_endpt(PersonResource, "/person/<string:handle>", "person")
-register_endpt(PeopleResource, "/person/", "people")
+register_endpt(PersonResource, "/people/<string:handle>", "person")
+register_endpt(PeopleResource, "/people/", "people")
 # Family
-register_endpt(FamilyResource, "/family/<string:handle>", "family")
-register_endpt(FamiliesResource, "/family/", "families")
+register_endpt(FamilyResource, "/families/<string:handle>", "family")
+register_endpt(FamiliesResource, "/families/", "families")
 # Source
-register_endpt(SourceResource, "/source/<string:handle>", "source")
-register_endpt(SourcesResource, "/source/", "sources")
+register_endpt(SourceResource, "/sources/<string:handle>", "source")
+register_endpt(SourcesResource, "/sources/", "sources")
 # Citation
-register_endpt(CitationResource, "/citation/<string:handle>", "citation")
-register_endpt(CitationsResource, "/citation/", "citations")
+register_endpt(CitationResource, "/citations/<string:handle>", "citation")
+register_endpt(CitationsResource, "/citations/", "citations")
 # Event
-register_endpt(EventResource, "/event/<string:handle>", "event")
-register_endpt(EventsResource, "/event/", "events")
+register_endpt(EventResource, "/events/<string:handle>", "event")
+register_endpt(EventsResource, "/events/", "events")
 # Media Object
 register_endpt(MediaObjectResource, "/media/<string:handle>", "media_object")
 register_endpt(MediaObjectsResource, "/media/", "media_objects")
 # Place
-register_endpt(PlaceResource, "/place/<string:handle>", "place")
-register_endpt(PlacesResource, "/place/", "places")
+register_endpt(PlaceResource, "/places/<string:handle>", "place")
+register_endpt(PlacesResource, "/places/", "places")
 # Repository
-register_endpt(RepositoryResource, "/repository/<string:handle>", "repository")
-register_endpt(RepositoriesResource, "/repository/", "repositories")
+register_endpt(RepositoryResource, "/repositories/<string:handle>", "repository")
+register_endpt(RepositoriesResource, "/repositories/", "repositories")
 # Note
-register_endpt(NoteResource, "/note/<string:handle>", "note")
-register_endpt(NotesResource, "/note/", "notes")
+register_endpt(NoteResource, "/notes/<string:handle>", "note")
+register_endpt(NotesResource, "/notes/", "notes")
 # Tag
-register_endpt(TagResource, "/tag/<string:handle>", "tag")
-register_endpt(TagsResource, "/tag/", "tags")
+register_endpt(TagResource, "/tags/<string:handle>", "tag")
+register_endpt(TagsResource, "/tags/", "tags")
 # Token
 register_endpt(TokenResource, "/login/", "token")
 register_endpt(TokenRefreshResource, "/refresh/", "token_refresh")
 # Bookmark
-register_endpt(BookmarkResource, "/bookmark/<string:category>", "bookmark")
-register_endpt(BookmarksResource, "/bookmark/", "bookmarks")
+register_endpt(BookmarkResource, "/bookmarks/<string:namespace>", "bookmark")
+register_endpt(BookmarksResource, "/bookmarks/", "bookmarks")
+# Filter
+register_endpt(FilterResource, "/filters/<string:namespace>", "filter")
 # Translate
-register_endpt(TranslationResource, "/translate/<string:code>", "translation")
-register_endpt(TranslationsResource, "/translate/", "translations")
+register_endpt(TranslationResource, "/translations/<string:code>", "translation")
+register_endpt(TranslationsResource, "/translations/", "translations")
 # Relation
 register_endpt(
     RelationResource,
-    "/relation/<string:handle1>/<string:handle2>",
-    "relation",
+    "/relations/<string:handle1>/<string:handle2>",
+    "relations",
 )
 # Metadata
 register_endpt(MetadataResource, "/metadata/<string:datatype>", "metadata")

gramps_webapi/api/resources/base.py

@@ -7,12 +7,14 @@
 from gramps.gen.db.base import DbReadBase
 from gramps.gen.errors import HandleError
 from gramps.gen.lib.primaryobj import BasicPrimaryObject as GrampsObject
-from webargs import fields
+from webargs import fields, validate
 from webargs.flaskparser import use_args
 
 from ..util import get_dbstate
 from . import ProtectedResource, Resource
 from .emit import GrampsJSONEncoder
+from .filters import apply_filter
+from .util import get_extended_attributes
 
 
 class GrampsObjectResourceHelper(GrampsJSONEncoder):
@@ -23,9 +25,11 @@ class GrampsObjectResourceHelper(GrampsJSONEncoder):
     def gramps_class_name(self):
         """To be set on child classes."""
 
-    @abstractmethod
     def object_extend(self, obj: GrampsObject, args: Dict) -> GrampsObject:
         """Extend the base object attributes as needed."""
+        if "extend" in args:
+            obj.extended = get_extended_attributes(self.db_handle, obj)
+        return obj
 
     @property
     def db_handle(self) -> DbReadBase:
@@ -52,11 +56,11 @@ class GrampsObjectResource(GrampsObjectResourceHelper, Resource):
 
     @use_args(
         {
-            "strip": fields.Boolean(missing=False),
-            "keys": fields.DelimitedList(fields.Str()),
+            "strip": fields.Str(validate=validate.Length(equal=0)),
+            "keys": fields.DelimitedList(fields.Str(), missing=[]),
             "skipkeys": fields.DelimitedList(fields.Str(), missing=[]),
-            "profile": fields.Boolean(missing=False),
-            "extend": fields.Boolean(missing=False),
+            "profile": fields.Str(validate=validate.Length(equal=0)),
+            "extend": fields.Str(validate=validate.Length(equal=0)),
         },
         location="query",
     )
@@ -65,22 +69,24 @@ def get(self, args: Dict, handle: str) -> Response:
         try:
             obj = self.get_object_from_handle(handle)
         except HandleError:
-            return abort(404)
-        return self.response(self.object_extend(obj, args), args)
+            abort(404)
+        return self.response(200, self.object_extend(obj, args), args)
 
 
 class GrampsObjectsResource(GrampsObjectResourceHelper, Resource):
     """Resource for multiple objects."""
 
     @use_args(
         {
-            "gramps_id": fields.Str(),
-            "handle": fields.Str(),
-            "strip": fields.Boolean(missing=False),
-            "keys": fields.DelimitedList(fields.Str()),
+            "gramps_id": fields.Str(validate=validate.Length(min=1)),
+            "handle": fields.Str(validate=validate.Length(min=1)),
+            "strip": fields.Str(validate=validate.Length(equal=0)),
+            "keys": fields.DelimitedList(fields.Str(), missing=[]),
             "skipkeys": fields.DelimitedList(fields.Str(), missing=[]),
-            "profile": fields.Boolean(missing=False),
-            "extend": fields.Boolean(missing=False),
+            "profile": fields.Str(validate=validate.Length(equal=0)),
+            "extend": fields.Str(validate=validate.Length(equal=0)),
+            "filter": fields.Str(validate=validate.Length(min=1)),
+            "rules": fields.Str(validate=validate.Length(min=1)),
         },
         location="query",
     )
@@ -89,19 +95,24 @@ def get(self, args: Dict) -> Response:
         if "gramps_id" in args:
             obj = self.get_object_from_gramps_id(args["gramps_id"])
             if obj is None:
-                return abort(404)
-            return self.response([self.object_extend(obj, args)], args)
-        if "handle" in args:
-            try:
-                obj = self.get_object_from_handle(args["handle"])
-            except HandleError:
-                return abort(404)
-            return self.response([self.object_extend(obj, args)], args)
-        iter_method = self.db_handle.method("iter_%s_handles", self.gramps_class_name)
+                abort(404)
+            return self.response(200, [self.object_extend(obj, args)], args)
         query_method = self.db_handle.method(
             "get_%s_from_handle", self.gramps_class_name
         )
+        if "filter" in args or "rules" in args:
+            handle_list = apply_filter(self.db_handle, args, self.gramps_class_name)
+            return self.response(
+                200,
+                [
+                    self.object_extend(query_method(handle), args)
+                    for handle in handle_list
+                ],
+                args,
+            )
+        iter_method = self.db_handle.method("iter_%s_handles", self.gramps_class_name)
         return self.response(
+            200,
             [
                 self.object_extend(query_method(handle), args)
                 for handle in iter_method()

gramps_webapi/api/resources/bookmark.py

@@ -16,30 +16,30 @@ def db_handle(self) -> DbReadBase:
         """Get the database instance."""
         return get_dbstate().db
 
-    def get(self, category: str) -> Response:
-        """Get list of bookmarks by category."""
+    def get(self, namespace: str) -> Response:
+        """Get list of bookmarks by namespace."""
         db_handle = self.db_handle
-        if category == "person":
+        if namespace == "people":
             result = db_handle.get_bookmarks()
-        elif category == "family":
+        elif namespace == "families":
             result = db_handle.get_family_bookmarks()
-        elif category == "media":
+        elif namespace == "media":
             result = db_handle.get_media_bookmarks()
-        elif category == "event":
+        elif namespace == "events":
             result = db_handle.get_event_bookmarks()
-        elif category == "citation":
+        elif namespace == "citations":
             result = db_handle.get_citation_bookmarks()
-        elif category == "note":
+        elif namespace == "notes":
             result = db_handle.get_note_bookmarks()
-        elif category == "place":
+        elif namespace == "places":
             result = db_handle.get_place_bookmarks()
-        elif category == "source":
+        elif namespace == "sources":
             result = db_handle.get_source_bookmarks()
-        elif category == "repository":
+        elif namespace == "repositories":
             result = db_handle.get_repo_bookmarks()
         else:
-            return abort(404)
-        return self.response(result)
+            abort(404)
+        return self.response(200, result)
 
 
 class BookmarksResource(ProtectedResource, GrampsJSONEncoder):
@@ -48,17 +48,18 @@ class BookmarksResource(ProtectedResource, GrampsJSONEncoder):
     def get(self) -> Response:
         """Get the list of bookmark types."""
         return self.response(
+            200,
             {
-                "categories": [
-                    "citation",
-                    "event",
-                    "family",
+                "namespaces": [
+                    "citations",
+                    "events",
+                    "families",
                     "media",
-                    "note",
-                    "person",
-                    "place",
-                    "repository",
-                    "source",
+                    "notes",
+                    "people",
+                    "places",
+                    "repositories",
+                    "sources",
                 ]
-            }
+            },
         )

gramps_webapi/api/resources/citation.py

@@ -19,7 +19,7 @@ class CitationResourceHelper(GrampsObjectResourceHelper):
 
     def object_extend(self, obj: Citation, args: Dict) -> Citation:
         """Extend citation attributes as needed."""
-        if args["extend"]:
+        if "extend" in args:
             db_handle = self.db_handle
             obj.extended = get_extended_attributes(db_handle, obj)
             obj.extended["source"] = get_source_by_handle(db_handle, obj.source_handle)

gramps_webapi/api/resources/emit.py

@@ -1,7 +1,7 @@
 """Gramps Json Encoder."""
 
 import inspect
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 import gramps.gen.lib as lib
 from flask import Response
@@ -26,19 +26,23 @@ def __init__(self):
             getattr(lib, key) for key, value in inspect.getmembers(lib, inspect.isclass)
         ]
 
-    def response(self, payload: Any, args: Dict = {}) -> Response:
-        # pylint:disable=dangerous-default-value
+    def response(
+        self, status: int = 200, payload: Any = {}, args: Optional[Dict] = None
+    ) -> Response:
         """Prepare response."""
+        args = args or {}
         if "strip" in args:
-            self.strip_empty_keys = args["strip"]
+            self.strip_empty_keys = True
+        else:
+            self.strip_empty_keys = False
         if "keys" in args:
             self.filter_only_keys = args["keys"]
         if "skipkeys" in args:
             self.filter_skip_keys = args["skipkeys"]
 
         return Response(
             response=self.encode(payload),
-            status=200,
+            status=status,
             mimetype="application/json",
         )
 

gramps_webapi/api/resources/event.py

@@ -24,9 +24,9 @@ class EventResourceHelper(GrampsObjectResourceHelper):
     def object_extend(self, obj: Event, args: Dict) -> Event:
         """Extend event attributes as needed."""
         db_handle = self.db_handle
-        if args["profile"]:
+        if "profile" in args:
             obj.profile = get_event_profile_for_object(db_handle, obj)
-        if args["extend"]:
+        if "extend" in args:
             obj.extended = get_extended_attributes(db_handle, obj)
             obj.extended["place"] = get_place_by_handle(db_handle, obj.place)
         return obj

gramps_webapi/api/resources/family.py

@@ -24,11 +24,11 @@ class FamilyResourceHelper(GrampsObjectResourceHelper):
     def object_extend(self, obj: Family, args: Dict) -> Family:
         """Extend family attributes as needed."""
         db_handle = self.db_handle
-        if args["profile"]:
+        if "profile" in args:
             obj.profile = get_family_profile_for_object(
                 db_handle, obj, with_events=True
             )
-        if args["extend"]:
+        if "extend" in args:
             obj.extended = get_extended_attributes(db_handle, obj)
             obj.extended["father"] = get_person_by_handle(db_handle, obj.father_handle)
             obj.extended["mother"] = get_person_by_handle(db_handle, obj.mother_handle)