django-pfx 1.4.dev50__tar.gz → 1.4.dev54__tar.gz

{django_pfx-1.4.dev50 → django_pfx-1.4.dev54}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.4.dev50
+Version: 1.4.dev54
 Summary: Django PFX is a toolkit designed to streamline the development of RESTful APIs using the Django framework.
 Author: Hervé Martinet
 Author-email: herve.martinet@gmail.com

{django_pfx-1.4.dev50 → django_pfx-1.4.dev54}/django_pfx.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.4.dev50
+Version: 1.4.dev54
 Summary: Django PFX is a toolkit designed to streamline the development of RESTful APIs using the Django framework.
 Author: Hervé Martinet
 Author-email: herve.martinet@gmail.com

{django_pfx-1.4.dev50 → django_pfx-1.4.dev54}/django_pfx.egg-info/SOURCES.txt

@@ -122,6 +122,7 @@ tests/tests/__init__.py
 tests/tests/basic_api_errors.py
 tests/tests/basic_api_test.py
 tests/tests/test_api_doc.py
+tests/tests/test_api_doc_search.py
 tests/tests/test_auth_api.py
 tests/tests/test_body_mixin.py
 tests/tests/test_cache.py

{django_pfx-1.4.dev50 → django_pfx-1.4.dev54}/doc/source/api.views.rst

@@ -47,6 +47,89 @@ API Reference
 ``pfx.pfxcore.views``
 *********************
 
+Query parameters & groups
+-------------------------
+
+.. autoclass:: pfx.pfxcore.views.parameters.ListCount
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.ListItems
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.ListMode
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.ListOrder
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.ListSearch
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.MediaRedirect
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.MetaFields
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.groups.MetaFilters
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.groups.MetaOrders
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.groups.SubsetLimit
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.groups.SubsetOffset
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.groups.SubsetPageSize
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.groups.SubsetPageSubset
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.groups.SubsetPage
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.groups.MetaList
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.views.parameters.groups.List
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 Base services
 -------------
 

{django_pfx-1.4.dev50 → django_pfx-1.4.dev54}/doc/source/generate_openapi.md

@@ -158,6 +158,55 @@ from .parameters import ListGroup
 @rest_api("/", method="get", parameters=[ListGroup])
 ```
 
+#### Pre defined query parameters
+
+A number of predefined parameters and groups are used by view mixins, and are reusable and inheritable:
+See [API reference | Query parameters & groups](api.views.rst#query-parameters-groups) for details.
+
+For {class}`pfx.pfxcore.views.parameters.ListSearch`, you can redefine the behaviour by annotation:
+either with `@rest_doc` on the view (useful if the view inherits from {class}`pfx.pfxcore.views.ListRestViewMixin`),
+or with `@rest_api` on the service (useful if you reuse the {class}`pfx.pfxcore.views.parameters.ListSearch` parameter
+or the {class}`pfx.pfxcore.views.parameters.groups.List` group).
+
+```python
+from pfx.pfxcore.decorator.rest import rest_doc, rest_view
+from pfx.pfxcore.views import BaseRestView, ListRestViewMixin
+
+# Do not add the search param in api doc:
+@rest_doc("", "get", search=False)
+@rest_view("/my-view")
+class MyView(ListRestViewMixin, BaseRestView):
+    pass
+```
+
+```python
+from pfx.pfxcore.decorator.rest import rest_doc, rest_view
+from pfx.pfxcore.views import BaseRestView, ListRestViewMixin
+
+# Customize the search param description in api doc:
+@rest_doc("", "get", search="Search the string in name and summary fields.")
+@rest_view("/my-view")
+class MyView(ListRestViewMixin, BaseRestView):
+    pass
+```
+
+```python
+from pfx.pfxcore.decorator.rest import rest_doc, rest_view
+from pfx.pfxcore.views import BaseRestView
+
+@rest_view("/custom")
+class MyView(BaseRestView):
+
+    # Use parameters.groups.List with custom description for search param:
+    @rest_api(
+        "", method="get",
+        parameters=[parameters.groups.List],
+        search="A custom description.")
+    def get(self, *args, **kwargs):
+        return JsonResponse({})
+```
+
+
 ### Body and response schema
 
 When using standard mixins to provide basic Rest services, the body

{django_pfx-1.4.dev50 → django_pfx-1.4.dev54}/pfx/pfxcore/apidoc/parameters.py

@@ -21,12 +21,12 @@ class Parameter:
         return cls.__name__
 
     @classmethod
-    def as_parameter(cls):
+    def as_parameter(cls, doc=None):
         res = dict(name=cls.name)
         res['in'] = cls.location
-        doc = inspect.getdoc(cls)
-        if doc:
-            res['description'] = doc
+        description = doc or inspect.getdoc(cls)
+        if description:
+            res['description'] = description
         members = inspect.getmembers(
             cls, predicate=lambda x: not (
                 inspect.ismethod(x)))

{django_pfx-1.4.dev50 → django_pfx-1.4.dev54}/pfx/pfxcore/decorator/rest.py

@@ -17,7 +17,7 @@ def rest_api(
         path, method='get', public=None, priority=0, priority_doc=0,
         parameters=None,
         request_schema=None, response_schema=None, filters=False,
-        groups=None):
+        search=False, groups=None):
     def decorator(func):
         @wraps(func)
         def wrapper(self, request, *args, **kwargs):
@@ -47,6 +47,7 @@ def rest_api(
         wrapper.rest_api_request_schema = request_schema
         wrapper.rest_api_response_schema = response_schema
         wrapper.rest_api_filters = filters
+        wrapper.rest_api_search = search
         wrapper.rest_api_groups = set(groups or [])
         wrapper.rest_api_public = public
         return wrapper

{django_pfx-1.4.dev50 → django_pfx-1.4.dev54}/pfx/pfxcore/locale/fr/LC_MESSAGES/django.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2024-04-23 14:41+0200\n"
+"POT-Creation-Date: 2024-08-20 12:22+0200\n"
 "PO-Revision-Date: 2021-06-22 23:31+0200\n"
 "Last-Translator: \n"
 "Language-Team: \n"
@@ -275,11 +275,11 @@ msgstr "{model} {obj} créé."
 msgid "{model} {obj} updated."
 msgstr "{model} {obj} modifié."
 
-#: views/rest_views.py:1076
+#: views/rest_views.py:1077
 #, python-brace-format
 msgid "{model} {obj} deleted."
 msgstr "{model} {obj} supprimé."
 
-#: views/rest_views.py:1138 views/rest_views.py:1166
+#: views/rest_views.py:1169 views/rest_views.py:1209
 msgid "Unexpected storage error"
 msgstr "Erreur de stockage inattendue"

{django_pfx-1.4.dev50 → django_pfx-1.4.dev54}/pfx/pfxcore/management/commands/makeapidoc.py

@@ -63,6 +63,14 @@ def global_parameters(spec, method):
         p.get('name', '#N/A') for p in spec.get('parameters', [])
         if isinstance(p, dict)}
     for qp in extend_groups(method.rest_api_params):
+        if qp.name == 'search':
+            search = (
+                spec['search'] if 'search' in spec else method.rest_api_search)
+            if not search:
+                continue
+            if isinstance(search, str):
+                yield qp.as_parameter(doc=search)
+                continue
         if qp.name in existings:
             # Ignore path parameters that are manually described.
             continue

{django_pfx-1.4.dev50 → django_pfx-1.4.dev54}/pfx/pfxcore/test.py

@@ -255,6 +255,12 @@ class TestAssertMixin:
         return self.assertIn(
             element, self.get_val(src, key, msg=msg), msg=msg)
 
+    # assert JSON array contains
+    def assertJNotIn(self, src, key, element, msg=None):
+        msg = '\n'.join([msg or '', self.format_json(src)])
+        return self.assertNotIn(
+            element, self.get_val(src, key, msg=msg), msg=msg)
+
 
 class TestPermsAssertMixin(TestAssertMixin):
     USER_TESTS = {}

{django_pfx-1.4.dev50 → django_pfx-1.4.dev54}/pfx/pfxcore/views/parameters/groups.py

@@ -26,10 +26,12 @@ class ModelSerialization(ParameterGroup):
 
 
 class MetaList(ParameterGroup):
+    """Parameters group for meta list services."""
     parameters = [MetaFields, MetaFilters, MetaOrders]
 
 
 class List(ParameterGroup):
+    """Parameters group for list services."""
     parameters = [
         ListCount, ListItems, ListSearch, ListOrder, ListMode,
         Subset, SubsetPage, SubsetPageSize,

{django_pfx-1.4.dev50 → django_pfx-1.4.dev54}/pfx/pfxcore/views/rest_views.py

@@ -808,7 +808,8 @@ class ListRestViewMixin(ModelResponseMixin):
         return JsonResponse(res)
 
     @rest_api(
-        "", method="get", parameters=[parameters.groups.List], filters=True,
+        "", method="get", parameters=[parameters.groups.List],
+        filters=True, search=True,
         response_schema='model_list_schema', priority_doc=-20)
     def get_list(self, *args, **kwargs):
         """Entrypoint for :code:`GET /` route.
@@ -1123,11 +1124,41 @@ class MediaRestViewMixin(ModelMixin):
         ---
         get:
             summary: Get upload URL
-            description: Get upload URL for a file field.
+            description: |
+                Get upload URL for a `MediaField` field.
+
+                You can upload a file ont the received URL. When the upload
+                query is done, you have to confirm the process with an
+                update request (`PUT`) on {model}. The body of this request
+                must contain the name of the `MediaField` with the contents
+                of the `file` value in the response of this request.
+
+                1. `GET /<int:pk>/<str:field>/upload-url/<str:filename>`
+                    → `data`
+                2. `PUT data.url aFile Content-Type: aFile.type`
+                3. `PUT /<int:pk> {{field: data.file}}`
             parameters extras:
-                pk: the {model} pk
-                field: the {model} field name
-                filename: the desired filename
+                pk: The {model} pk.
+                field: The {model} field name. Must be the name of
+                    a `MediaField` field.
+                filename: The desired filename.
+            responses:
+                200:
+                    description: The upload URL
+                    content:
+                        application/json:
+                            schema:
+                                properties:
+                                    url:
+                                        type: string
+                                        format: uri
+                                    file:
+                                        type: object
+                                        properties:
+                                            name:
+                                                type: string
+                                            key:
+                                                type: string
         """
         obj = self.get_object(pk=pk)
         try:
@@ -1157,6 +1188,18 @@ class MediaRestViewMixin(ModelMixin):
             parameters extras:
                 pk: the {model} pk
                 field: the {model} field name
+            responses:
+                200:
+                    description: The file URL, if `redirect` is `false`.
+                    content:
+                        application/json:
+                            schema:
+                                properties:
+                                    url:
+                                        type: string
+                                        format: uri
+                302:
+                    description: The redirect, if `redirect` is `true`.
         """
         obj = self.get_object(pk=pk)
         try:

{django_pfx-1.4.dev50 → django_pfx-1.4.dev54}/tests/tests/__init__.py

@@ -1,6 +1,7 @@
 from .basic_api_errors import BasicAPIErrorTest
 from .basic_api_test import BasicAPITest
 from .test_api_doc import ApiDocTest
+from .test_api_doc_search import TestAPIDocSearch
 from .test_auth_api import AuthAPITest
 from .test_body_mixin import TestBodyMixin
 from .test_cache import TestCache

django_pfx-1.4.dev54/tests/tests/test_api_doc_search.py

@@ -0,0 +1,110 @@
+from django.http import JsonResponse
+from django.test import TestCase, override_settings
+from django.urls import include, path
+
+from pfx.pfxcore.decorator.rest import rest_api, rest_doc, rest_view
+from pfx.pfxcore.management.commands.makeapidoc import get_spec
+from pfx.pfxcore.shortcuts import register_views
+from pfx.pfxcore.test import APIClient, TestAssertMixin
+from pfx.pfxcore.views import (
+    BaseRestView,
+    ListRestViewMixin,
+    ModelResponseMixin,
+    parameters,
+)
+from tests.models import Author
+
+
+@rest_view("/list/default")
+class DefaultListView(ListRestViewMixin, ModelResponseMixin, BaseRestView):
+    model = Author
+    default_public = True
+
+
+@rest_doc("", "get", search=False)
+@rest_view("/list/no-search")
+class NoSearchListView(ListRestViewMixin, ModelResponseMixin, BaseRestView):
+    model = Author
+    default_public = True
+
+
+@rest_doc("", "get", search="A custom description.")
+@rest_view("/list/custom-description")
+class CustomDescriptionListView(
+        ListRestViewMixin, ModelResponseMixin, BaseRestView):
+    model = Author
+    default_public = True
+
+
+@rest_view("/custom")
+class CustomServiceView(BaseRestView):
+    model = Author
+    default_public = True
+
+    @rest_api(
+        "/default", method="get", parameters=[parameters.groups.List],
+        search=True)
+    def get_default(self, *args, **kwargs):
+        return JsonResponse({})
+
+    @rest_api(
+        "/no-search", method="get", parameters=[parameters.groups.List],
+        search=False)
+    def get_no_search(self, *args, **kwargs):
+        return JsonResponse({})
+
+    @rest_api(
+        "/custom-description", method="get",
+        parameters=[parameters.groups.List],
+        search="A custom description.")
+    def get_custom_description(self, *args, **kwargs):
+        return JsonResponse({})
+
+
+urlpatterns = [
+    path('api/', include(register_views(
+        DefaultListView,
+        NoSearchListView,
+        CustomDescriptionListView,
+        CustomServiceView))),
+    path('api/', include('pfx.pfxcore.urls'))
+]
+
+
+@override_settings(ROOT_URLCONF=__name__)
+class TestAPIDocSearch(TestAssertMixin, TestCase):
+    def setUp(self):
+        self.client = APIClient(default_locale='en')
+
+    def test_body_to_model(self):
+        def get_params(spec, path):
+            for p in self.get_val(spec, f'paths.{path}.get.parameters'):
+                yield p.get('$ref') or p.get('name'), p
+
+        spec = get_spec(set()).to_dict()
+
+        params = dict(get_params(spec, '/list/default'))
+        self.assertJEExists(params, '#/components/parameters/ListSearch')
+        self.assertJENotExists(params, 'search')
+
+        params = dict(get_params(spec, '/list/no-search'))
+        self.assertJENotExists(params, '#/components/parameters/ListSearch')
+        self.assertJENotExists(params, 'search')
+
+        params = dict(get_params(spec, '/list/custom-description'))
+        self.assertJENotExists(params, '#/components/parameters/ListSearch')
+        self.assertJEExists(params, 'search')
+        self.assertJE(params, 'search.description', "A custom description.")
+
+        params = dict(get_params(spec, '/custom/default'))
+        self.assertJEExists(params, '#/components/parameters/ListSearch')
+        self.assertJENotExists(params, 'search')
+
+        params = dict(get_params(spec, '/custom/no-search'))
+        self.assertJENotExists(params, '#/components/parameters/ListSearch')
+        self.assertJENotExists(params, 'search')
+
+        params = dict(get_params(spec, '/custom/custom-description'))
+        self.assertJENotExists(params, '#/components/parameters/ListSearch')
+        self.assertJEExists(params, 'search')
+        self.assertJE(params, 'search.description', "A custom description.")