django-pfx 1.2.dev40__tar.gz → 1.2.dev42__tar.gz

{django-pfx-1.2.dev40 → django-pfx-1.2.dev42}/.gitignore

@@ -26,3 +26,4 @@ dev_custom.py
 
 # Other
 /local
+/doc

{django-pfx-1.2.dev40 → django-pfx-1.2.dev42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.2.dev40
+Version: 1.2.dev42
 Summary: Django PFX is a toolkit to build web APIs dedicated to be used by React progressive web app.
 Author: Hervé Martinet
 Author-email: herve.martinet@gmail.com

{django-pfx-1.2.dev40 → django-pfx-1.2.dev42}/django_pfx.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.2.dev40
+Version: 1.2.dev42
 Summary: Django PFX is a toolkit to build web APIs dedicated to be used by React progressive web app.
 Author: Hervé Martinet
 Author-email: herve.martinet@gmail.com

django-pfx-1.2.dev42/pfx/pfxcore/decorator/__init__.py

@@ -0,0 +1 @@
+from .rest import rest_api, rest_doc, rest_property, rest_view

{django-pfx-1.2.dev40 → django-pfx-1.2.dev42}/pfx/pfxcore/decorator/rest.py

@@ -1,7 +1,10 @@
 import logging
+from functools import wraps
 
 from django.utils.translation import gettext_lazy as _
 
+from apispec.utils import deepupdate
+
 from pfx.pfxcore.exceptions import APIError
 from pfx.pfxcore.http import JsonResponse
 
@@ -10,6 +13,7 @@ logger = logging.getLogger(__name__)
 
 def rest_api(path, method='get', public=None, priority=0):
     def decorator(func):
+        @wraps(func)
         def wrapper(self, request, *args, **kwargs):
             self.request = request
             self.kwargs = kwargs
@@ -43,6 +47,17 @@ def rest_property(string=None, type="CharField"):
 
 def rest_view(path):
     def decorator(cls):
-        cls.rest_view_path = path
+        cls.rest_view_path[cls] = path
+        return cls
+    return decorator
+
+
+def rest_doc(path, **vals):
+    def decorator(cls):
+        if cls not in cls.rest_view_path:
+            raise Exception(
+                "@rest_doc must be used before a @rest_view decorator")
+        cls.rest_doc[f'{cls.rest_view_path[cls]}{path}'] = deepupdate(
+            cls.rest_doc.get(path, {}), vals)
         return cls
     return decorator

{django-pfx-1.2.dev40 → django-pfx-1.2.dev42}/pfx/pfxcore/management/commands/makeapidoc.py

@@ -1,12 +1,16 @@
+import inspect
 import json
 from pathlib import Path
 
 from django.core.management.base import BaseCommand
 
 from apispec import APISpec
+from apispec.utils import deepupdate
+from apispec.yaml_utils import load_operations_from_docstring
 
 from pfx.pfxcore import __PFX_VIEWS__
 from pfx.pfxcore.settings import PFXSettings
+from pfx.pfxcore.views import ModelMixin
 
 settings = PFXSettings()
 DEFAULT_TEMPLATE = dict(
@@ -15,13 +19,30 @@ DEFAULT_TEMPLATE = dict(
     openapi_version="3.0.2")
 
 
+def get_operations(view, url):
+    for op, method_name in url['methods'].items():
+        doc = inspect.getdoc(getattr(view, method_name))
+        vars = {}
+        if issubclass(view, ModelMixin) and view.model:
+            vars.update(
+                model=view.model._meta.verbose_name.lower(),
+                models=view.model._meta.verbose_name_plural.lower())
+        if doc:
+            doc = doc.format(**vars)
+        spec = deepupdate(
+            load_operations_from_docstring(doc).get(op, {}),
+            view.rest_doc.get(url['path'], {}))
+        spec.setdefault('summary', url['path'])
+        yield op, spec
+
+
 def get_spec():
     spec = APISpec(**{**DEFAULT_TEMPLATE, **settings.PFX_OPENAPI_TEMPLATE})
     for view in __PFX_VIEWS__:
         for url in view.get_urls():
             spec.path(
                 path=url['path'],
-                operations={k: {} for k, v in url['methods'].items()})
+                operations=dict(get_operations(view, url)))
     return spec
 
 

{django-pfx-1.2.dev40 → django-pfx-1.2.dev42}/pfx/pfxcore/test.py

@@ -159,57 +159,64 @@ class TestAssertMixin:
         msg = '\n'.join([msg or '', response.formatted()])
         return self.assertEqual(response.status_code, code, msg=msg)
 
-    def get_val(self, response, key):
+    def _format_source(self, src):
+        if isinstance(src, dict):
+            return json.dumps(src, indent=2)
+        return src.formatted()
+
+    def _get_dict(self, src):
+        return src if isinstance(src, dict) else src.json_content
+
+    def get_val(self, src, key):
         def _p(k):
             return int(k[1:]) if k[0] == '@' else k
+
         try:
-            return reduce(lambda c, k: c[_p(k)], key.split("."),
-                          response.json_content)
+            return reduce(
+                lambda c, k: c[_p(k)], key.split("."), self._get_dict(src))
         except IndexError:
-            print(format_response(response, f'Index Error for key "{key}"'))
             raise Exception(f'Index Error for key "{key}"')
         except KeyError:
-            print(format_response(response, f'Key Error for key "{key}"'))
             raise Exception(f'Key Error for key "{key}"')
 
     # assert JSON content at key equals value
-    def assertJE(self, response, key, value, msg=None):
-        msg = '\n'.join([msg or '', response.formatted()])
-        return self.assertEqual(self.get_val(response, key), value, msg=msg)
+    def assertJE(self, src, key, value, msg=None):
+        msg = '\n'.join([msg or '', self._format_source(src)])
+        return self.assertEqual(self.get_val(src, key), value, msg=msg)
 
     # assert JSON content at key not equals value
-    def assertNJE(self, response, key, value, msg=None):
-        msg = '\n'.join([msg or '', response.formatted()])
+    def assertNJE(self, src, key, value, msg=None):
+        msg = '\n'.join([msg or '', self._format_source(src)])
         return self.assertNotEqual(
-            self.get_val(response, key), value, msg=msg)
+            self.get_val(src, key), value, msg=msg)
 
     # assert JSON content at key exists
-    def assertJEExists(self, response, key, msg=None):
-        msg = '\n'.join([msg or '', response.formatted()])
+    def assertJEExists(self, src, key, msg=None):
+        msg = '\n'.join([msg or '', self._format_source(src)])
         if '.' not in key:
-            return self.assertIn(key, response.json_content, msg=msg)
+            return self.assertIn(key, self._get_dict(src), msg=msg)
         path, name = key.rsplit('.', 1)
-        return self.assertIn(name, self.get_val(response, path), msg=msg)
+        return self.assertIn(name, self.get_val(src, path), msg=msg)
 
     # assert JSON content at key not exists
-    def assertJENotExists(self, response, key, msg=None):
-        msg = '\n'.join([msg or '', response.formatted()])
+    def assertJENotExists(self, src, key, msg=None):
+        msg = '\n'.join([msg or '', self._format_source(src)])
         if '.' not in key:
-            return self.assertNotIn(key, response.json_content, msg=msg)
+            return self.assertNotIn(key, self._get_dict(src), msg=msg)
         path, name = key.rsplit('.', 1)
-        return self.assertNotIn(name, self.get_val(response, path), msg=msg)
+        return self.assertNotIn(name, self.get_val(src, path), msg=msg)
 
     # assert JSON array size
-    def assertSize(self, response, key, size, msg=None):
-        msg = '\n'.join([msg or '', response.formatted()])
+    def assertSize(self, src, key, size, msg=None):
+        msg = '\n'.join([msg or '', self._format_source(src)])
         return self.assertEqual(
-            len(self.get_val(response, key)), size, msg=msg)
+            len(self.get_val(src, key)), size, msg=msg)
 
     # assert JSON array contains
-    def assertJIn(self, response, key, element, msg=None):
-        msg = '\n'.join([msg or '', response.formatted()])
+    def assertJIn(self, src, key, element, msg=None):
+        msg = '\n'.join([msg or '', self._format_source(src)])
         return self.assertIn(
-            element, self.get_val(response, key), msg=msg)
+            element, self.get_val(src, key), msg=msg)
 
 
 class TestPermsAssertMixin(TestAssertMixin):

{django-pfx-1.2.dev40 → django-pfx-1.2.dev42}/pfx/pfxcore/views/rest_views.py

@@ -180,6 +180,15 @@ class ModelResponseMixin(ModelMixin):
 
     @rest_api("/meta", method="get")
     def get_meta(self, *args, **kwargs):
+        """Retrieve the model metadata.
+        ---
+        get:
+            summary: Get {model} metadata
+            responses:
+                200:
+                content:
+                    application/json
+        """
         return JsonResponse(self.object_meta())
 
 
@@ -266,6 +275,15 @@ class ListRestViewMixin(ModelResponseMixin):
 
     @rest_api("/meta/list", method="get")
     def get_meta_list(self, *args, **kwargs):
+        """Retrieve the model list metadata.
+        ---
+        get:
+            summary: Get {models} list metadata
+            responses:
+                200:
+                content:
+                    application/json
+        """
         return JsonResponse(self.object_meta_list())
 
     def apply_view_filter(self, qs):
@@ -337,6 +355,15 @@ class ListRestViewMixin(ModelResponseMixin):
 
     @rest_api("", method="get")
     def get_list(self, *args, **kwargs):
+        """Retrieve a list of model.
+        ---
+        get:
+            summary: Get {models} list
+            responses:
+                200:
+                content:
+                    application/json
+        """
         res = {}
         meta = {}
         qs = self.get_list_queryset()
@@ -373,6 +400,15 @@ class ListRestViewMixin(ModelResponseMixin):
 class DetailRestViewMixin(ModelResponseMixin):
     @rest_api("/<int:id>", method="get")
     def get(self, id, *args, **kwargs):
+        """Retrieve the model by pk.
+        ---
+        get:
+            summary: Get {model}
+            responses:
+                200:
+                content:
+                    application/json
+        """
         obj = self.get_object(pk=id)
         return self.response(obj)
 
@@ -382,6 +418,15 @@ class SlugDetailRestViewMixin(ModelResponseMixin):
 
     @rest_api("/slug/<slug:slug>", method="get")
     def get_by_slug(self, slug, *args, **kwargs):
+        """Retrieve the model by slug.
+        ---
+        get:
+            summary: Get {model} by slug
+            responses:
+                200:
+                content:
+                    application/json
+        """
         obj = self.get_object(**{self.SLUG_FIELD: slug})
         return self.response(obj)
 
@@ -416,6 +461,15 @@ class CreateRestViewMixin(ModelBodyMixin, ModelResponseMixin):
 
     @rest_api("", method="post")
     def post(self, *args, **kwargs):
+        """Create the model.
+        ---
+        post:
+            summary: Create {model}
+            responses:
+                200:
+                content:
+                    application/json
+        """
         return self._post(*args, **kwargs)
 
 
@@ -441,6 +495,15 @@ class UpdateRestViewMixin(ModelBodyMixin, ModelResponseMixin):
 
     @rest_api("/<int:id>", method="put")
     def put(self, id, *args, **kwargs):
+        """Update the model by pk.
+        ---
+        put:
+            summary: Update {model}
+            responses:
+                200:
+                content:
+                    application/json
+        """
         return self._put(id, *args, **kwargs)
 
 
@@ -458,6 +521,15 @@ class DeleteRestViewMixin(ModelMixin):
 
     @rest_api("/<int:id>", method="delete")
     def delete(self, id, *args, **kwargs):
+        """Delete the model by pk.
+        ---
+        delete:
+            summary: Delete {model}
+            responses:
+                200:
+                content:
+                    application/json
+        """
         return self._delete(id, *args, **kwargs)
 
 
@@ -473,6 +545,16 @@ class MediaRestViewMixin(ModelMixin):
 
     @rest_api("/<int:pk>/<str:field>/upload-url/<str:filename>", method="get")
     def field_media_upload_url(self, pk, field, filename, *args, **kwargs):
+        """Get upload URL for a media field.
+        ---
+        get:
+            summary: Get upload URL
+            description: Get upload URL for a file field.
+            responses:
+                200:
+                content:
+                    application/json
+        """
         obj = self.get_object(pk=pk)
         try:
             res = self._get_model_field(field).get_upload_url(
@@ -484,6 +566,16 @@ class MediaRestViewMixin(ModelMixin):
 
     @rest_api("/<int:pk>/<str:field>", method="get")
     def field_media_get(self, pk, field, *args, **kwargs):
+        """Get a redirect for a media file file.
+        ---
+        get:
+            summary: Get file
+            description: Get a redirect for a media field file.
+            responses:
+                200:
+                content:
+                    application/json
+        """
         obj = self.get_object(pk=pk)
         try:
             url = self._get_model_field(field).get_url(self.request, obj)
@@ -523,6 +615,8 @@ class SecuredRestViewMixin(View):
 
 class BaseRestView(SecuredRestViewMixin, View):
     pfx_methods = None
+    rest_view_path = {}
+    rest_doc = {}
 
     def dispatch(self, request, *args, **kwargs):
         # Try to dispatch to the right method; if a method doesn't exist,
@@ -554,7 +648,7 @@ class BaseRestView(SecuredRestViewMixin, View):
     @classmethod
     def get_urls(cls, as_pattern=False):
         def fullpath(p2):
-            res = f'{cls.rest_view_path}{p2}'.lstrip('/')
+            res = f'{cls.rest_view_path[cls]}{p2}'.lstrip('/')
             return res if as_pattern else f'/{res}'
 
         paths = {}

{django-pfx-1.2.dev40 → django-pfx-1.2.dev42}/tests/tests/test_api_doc.py

@@ -35,6 +35,14 @@ class ApiDocTest(TestAssertMixin, TestCase):
         assertMethods(paths, '/authors/slug/<slug:slug>', {'get'})
         assertMethods(paths, '/authors/cache/<int:id>', {'get'})
 
+        # Check a inherited get with default description
+        self.assertJE(
+            paths, '/authors/<int:id>.get.summary', "Get author")
+        # Check a inherited get with custom description
+        self.assertJE(
+            paths, '/authors-annotate/<int:id>.get.summary',
+            "Get custom author")
+
     def test_view_get_urls(self):
         def assertMethods(urls, p, methods):
             self.assertEqual(next(filter(

{django-pfx-1.2.dev40 → django-pfx-1.2.dev42}/tests/views.py

@@ -4,7 +4,7 @@ from django.core.exceptions import ImproperlyConfigured
 from django.db.models import Count, Q
 from django.utils.translation import gettext as _
 
-from pfx.pfxcore.decorator import rest_api, rest_view
+from pfx.pfxcore.decorator import rest_api, rest_doc, rest_view
 from pfx.pfxcore.http import JsonResponse
 from pfx.pfxcore.views import (
     VF,
@@ -125,6 +125,7 @@ class AuthorRestView(AuthorRestViewMixin, SlugDetailRestViewMixin, RestView):
         return JsonResponse(dict(value='static:more'))
 
 
+@rest_doc('/<int:id>', summary="Get custom author")
 @rest_view("/authors-annotate")
 class AuthorAnnotateRestView(AuthorRestView):
     fields = [

django-pfx-1.2.dev40/pfx/pfxcore/decorator/__init__.py

@@ -1 +0,0 @@
-from .rest import rest_api, rest_property, rest_view