django-pfx 1.2.dev94__tar.gz → 1.2.dev99__tar.gz

{django-pfx-1.2.dev94 → django-pfx-1.2.dev99}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.2.dev94
+Version: 1.2.dev99
 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.dev94 → django-pfx-1.2.dev99}/django_pfx.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.2.dev94
+Version: 1.2.dev99
 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.dev94 → django-pfx-1.2.dev99}/doc/conf.py

@@ -66,4 +66,6 @@ html_theme = "sphinx_rtd_theme"
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
+
+myst_heading_anchors = 3

django-pfx-1.2.dev99/doc/source/decorator.md

@@ -0,0 +1,61 @@
+# View decorator and URL
+## @rest_view
+Used to provide the base path of a view class
+```
+@rest_view("/base-path")
+class ViewClass():
+```
+
+## @rest_api
+Used to annotate the rest services method.
+Parameters are the path and the HTTP method.
+```
+@rest_api("/path", method="get")
+def class_method(self):
+```
+
+A short example
+```
+@rest_view("/books")
+class BookRestView():
+
+    @rest_api("/list", method="get")
+    def get_list(self):
+        return JsonResponse(
+            dict(books=['The Man in the High Castle', 'A Scanner Darkly']))
+```
+
+### path parameters
+Path can contain parameters that are passed to the method.
+```
+@rest_api("/path/<int:pk>/test/<slug:slug>", method="get")
+def class_method(self, pk, slug):
+```
+
+## Registering urls
+To be available, annotated view class must be registered
+in your urls.py file as follows.
+```
+from pfx.pfxcore import register_views
+
+from . import views
+
+urlpatterns = register_views(
+    views.AuthorRestView,
+    views.BookRestView)
+```
+You can include multiple views under one path, or add a path
+wih a specific class method for each HTTP methods:
+```
+from pfx.pfxcore import register_views
+
+from . import views
+
+urlpatterns = [
+    path('api/', include(register_views(
+        views.AuthorRestView,
+        views.BookRestView))),
+    path('other/thing', views.OtherRestView.as_view(
+        pfx_methods=dict(get='get_other'))),
+]
+```

{django-pfx-1.2.dev94 → django-pfx-1.2.dev99}/doc/source/getting_started.md

@@ -70,11 +70,10 @@ from django_request_mapping import UrlPattern
 
 from book import views
 
-urlpatterns = UrlPattern()
-urlpatterns.register(views.BookRestView)
+apipatterns = register_views(views.BookRestView)
 
 urlpatterns = [
-    path('api/', include(urlpatterns)),
+    path('api/', include(apipatterns)),
 ]
 ```
 

{django-pfx-1.2.dev94 → django-pfx-1.2.dev99}/doc/source/model.md

@@ -5,7 +5,7 @@ Django PFX use plain Django Models classes.
 This library only provides some helpers for properties
 and foreign keys representations.
 
-## @rest_property
+## `@rest_property`
 If you want to use properties in your model,
 you have to annotate them with @rest_property.
 
@@ -95,3 +95,18 @@ Which give the following result on the book service :
     "resource_name": "The Fellowship of the Ring",
 }
 ```
+
+## Not null char fields
+
+To avoid storing a mixture of empty strings and `null` values, while automatically
+converting `null` values to empty strings, you can use the following model fields:
+
+* `NotNullCharField`
+* `NotNullTextField`
+* `NotNullURLField`
+```
+    a_string_field = NotNullCharField(
+        _("A string"), max_length=255, blank=True, default="")
+```
+
+The `null` parameter of these fields is automatically set to `False`.

django-pfx-1.2.dev99/doc/source/pfx_views.md

@@ -0,0 +1,274 @@
+# Django PFX Views
+REST services are provided as `ViewMixin` for `BaseRestView`.
+Each of these views must set the queryset used to query the model data either
+by defining the queryset attribute or by overriding the `get_queryset` method.
+
+Fields can be listed in the fields attribute, else all the fields are provided.
+
+## DetailRestViewMixin
+Provide a get detail service for a model class.
+
+By default, all model fields are included in response. You can customize
+the response by specifying the fields attribute (see [Define Fields](pfx_views.md#define-fields) for details).
+```
+from pfx.pfxcore.views import BaseRestView, DetailRestViewMixin
+
+@rest_view("/books")
+class BookRestView(DetailRestViewMixin, BaseRestView):
+    queryset = Book.objects
+    fields = ['name', 'author', 'pub_date', 'created_at', 'type']
+```
+
+## SlugDetailRestViewMixin
+Provide a get detail service for a model class with a slug.
+Slug field is searched in the `slug` field of the model by default,
+but it can be overridden with the `SLUG_FIELD` attribute.
+
+```
+from pfx.pfxcore.views import BaseRestView, SlugDetailRestViewMixin
+
+@rest_view("/authors")
+class AuthorRestView(SlugDetailRestViewMixin, BaseRestView):
+    queryset = Author.objects
+    SLUG_FIELD = "slug"
+    fields = ['name', 'slug', 'created_at', 'type']
+```
+## ListRestViewMixin
+Provide a list service for a model class.
+
+By default, list fields are taken from fields attributes.
+They can also be listed in the list_fields attribute if you need to have
+different fields in the list than in other views.
+```
+from pfx.pfxcore.views import BaseRestView, ListRestViewMixin
+
+@rest_view("/books")
+class BookRestView(ListRestViewMixin, BaseRestView):
+    queryset = Book.objects
+    list_fields = ['name', 'author', 'pub_date', 'created_at', 'type']
+```
+### Pagination
+If you pass `?subset=pagination`, the response will include pagination data in meta:
+```
+{
+    "items": […],
+    "meta": {
+        "page": 1,
+        "page_size": 10,
+        "count": 200,
+        "page_count": 20,
+        "subset": [1, 2, 3, 4, 5],
+        "page_subset": 5
+    }
+}
+```
+The page_size cannot be greater than `PFX_MAX_LIST_RESULT_SIZE` settings.
+Override `pagination_result(self, qs)` to customize the behavior.
+
+If you pass `?subset=offset`, the response will include offset/limit data in meta:
+```
+{
+    "items": […],
+    "meta": {
+        "count": 200,
+        "page_count": 20,
+        "limit": 10,
+        "offset": 0
+    }
+}
+```
+The limit cannot be greater than `PFX_MAX_LIST_RESULT_SIZE` settings.
+Override `offset_result(self, qs)` to customize the behavior.
+### Filters
+List view can have filters.
+#### ModelFilter
+Use `ModelFilter` to add a filter on a ORM field:
+```
+from pfx.pfxcore.views import (
+    RestView,
+    ModelFilter)
+
+
+class AuthorRestView(RestView):
+    filters = [
+        ModelFilter(Author, 'name'),
+    ]
+```
+#### Filter
+Use `Filter` to add a custom filter:
+```
+from django.db.models import Q
+
+from pfx.pfxcore.views import (
+    RestView,
+    FieldType,
+    Filter)
+
+
+def name_filter(value):
+    return Q(first_name__icontains=value) | Q(last_name__icontains=value)
+
+
+class AuthorRestView(RestView):
+    filters = [
+        Filter('name', _("Name"), FieldType.CharField, name_filter),
+    ]
+```
+## CreateRestViewMixin
+Provide a creation service for a model class.
+```
+from pfx.pfxcore.views import BaseRestView, CreateRestViewMixin
+
+@rest_view("/books")
+class BookRestView(CreateRestViewMixin, BaseRestView):
+    queryset = Book.objects
+    fields = ['name', 'author', 'pub_date', 'created_at', 'type']
+```
+### Default values
+You can set default values for fields in the ORM object field. But if
+you need to set it at view level, you can use the `default_values`
+class attribute.
+```
+@rest_view("/books")
+class BookRestView(CreateRestViewMixin, BaseRestView):
+    queryset = Book.objects
+    default_values = dict(
+        format='octavo'
+    )
+```
+If you need to set dynamics default values,
+you can override following methods (depending of your needs):
+* `get_default_values(self)`: return `default_values`.
+* `new_object(self)`: return a new object instance with `get_default_values()`.
+* `is_valid(self, obj, created=False, rel_data=None)`: persist the instance after validation.
+
+## UpdateRestViewMixin
+Provide an update service for a model class.
+```
+from pfx.pfxcore.views import BaseRestView, UpdateRestViewMixin
+
+@rest_view("/books")
+class BookRestView(UpdateRestViewMixin, BaseRestView):
+    queryset = Book.objects
+    fields = ['name', 'author', 'pub_date', 'created_at', 'type']
+```
+
+## DeleteRestViewMixin
+Provide a delete service for a model class.
+```
+from pfx.pfxcore.views import BaseRestView, DeleteRestViewMixin
+
+@rest_view("/books")
+class BookRestView(DeleteRestViewMixin, BaseRestView):
+    queryset = Book.objects
+```
+
+## SecuredRestViewMixin
+`SecuredRestViewMixin` allows you to define whether methods
+are public or private (requires a logged-in user),
+and to check access conditions to the method for a user.
+
+If you inherit `BaseRestView` or `RestView`, `SecuredRestViewMixin` is
+already included. The only way to ignore it or defining your custom security
+system from scratch id to inherit Django original `View` instead.
+
+### Default behavior
+By default, all methods are private. You can modify
+the `default_public` attribute to change this.
+```
+@rest_view("/books")
+class BookRestView(RestView):
+    queryset = Book.objects
+    default_public = True
+```
+### Public method
+If you want to define specific methods as a public methods,
+add corresponding attributes `${method_name}_public`:
+```
+@rest_view("/books")
+class BookRestView(RestView):
+    queryset = Book.objects
+    get_public = True
+    get_list_public = True
+```
+### Check user access
+For private methods, you can verify user access in two steps:
+* By overriding the `perm(self)` method.
+* By overriding the `${method_name}_perm(self)` method.
+
+the `perm` method is called first, and if it returns `false`, access is denied.
+If it returns `true` (default behavior), access is allowed
+if `${method_name}_perm(self)` method does not exists.
+If `${method_name}_perm` exists, it is called and must
+return `true` to allow access.
+```
+@rest_view("/books")
+class BookRestView(RestView):
+    queryset = Book.objects
+
+    def my_method_perm(self)
+        return self.request.user.is_admin
+```
+### Check user access based on data
+You can check user access based on data by overriding following methods:
+* `object_create_perm(self, data)`
+* `object_update_perm(self, obj, data)`
+* `object_delete_perm(self, obj)`
+Where `data` is the dictionary of new values and `obj` the existing object.
+
+These methods are called by the put/post/delete methods of standard mixins
+before validation. If you write a custom method and you want to use
+one of these method, you have to call it yourself.
+
+## Base classes
+You can use PFX view mixins with following base classes:
+
+* `View`: the Django base view class.
+* `BaseRestView`: The PFX base view for API, inherits `SecuredRestViewMixin` and `View`.
+* `RestView`: The PFX base view for a Rest API, inherits:
+  * `ListRestViewMixin`
+  * `DetailRestViewMixin`
+  * `CreateRestViewMixin`
+  * `UpdateRestViewMixin`
+  * `DeleteRestViewMixin`
+  * `BaseRestView`
+
+## Define Fields
+Fields in `fields` and `list_fields` attributes can be:
+* A string: the field attribute name.
+* A `pfx.pfxcore.views.VF` object.
+
+`VF` object can be used to customize field behavior and must define at least the field name:
+```
+field = [VF('name')]
+```
+You can specify following optional attributes:
+* `verbose_name`
+* `field_type`
+* `alias`
+* `readonly`
+* `readonly_create`
+* `readonly_update`
+* `choices`
+* `select`
+* `json_repr`
+
+Refer to method documentation for details.
+
+### Meta
+
+The `ModelResponseMixin` (included in every mixin with a service whose response is a simple object),
+exposes a `/meta` service to identify fields (and their characteristics: type, required, readonly, ...),
+to enable automatic generation of forms.
+
+See the generated API documentation for more details.
+
+On the same principle, `ListRestViewMixin` exposes the `/meta/list` service, which,
+in addition to the fields, returns the list of available filters and
+the list of available fields to order the list.
+
+#### Notes for future releases
+
+In a future version, these services should return a JSON OpenAPI structure. The list
+of orderable fields is resource-intensive to compute and should be removed and moved
+in the generated API doc.

{django-pfx-1.2.dev94 → django-pfx-1.2.dev99}/doc/source/testing.md

@@ -18,12 +18,12 @@ so that each request header contains
 the HTTP_X_CUSTOM_LANGUAGE attribute with the locale.
 
 Example :
-```
+```python
 client = APIClient(default_locale='en_GB')
 ```
 Each request to a service can also override the locale.
 Example :
-```
+```python
 client = APIClient()
 response = client.get('/api/authors', locale='fr_CH')
 ```
@@ -33,7 +33,7 @@ response = client.get('/api/authors', locale='fr_CH')
 Send a get request.
 
 Example :
-```
+```python
 client = APIClient()
 response = client.get('/api/authors')
 ```
@@ -42,7 +42,7 @@ response = client.get('/api/authors')
 Send a post request with content type 'application/json'.
 
 Example :
-```
+```python
 client = APIClient()
 response = client.post(
     '/api/authors', {
@@ -54,7 +54,7 @@ response = client.post(
 Send a put request with content type 'application/json'.
 
 Example :
-```
+```python
 client = APIClient()
 response = self.client.put(
     f'/api/authors/{author_pk}',
@@ -67,13 +67,12 @@ response = self.client.put(
 Send a delete request with content type 'application/json'.
 
 Example :
-```
+```python
 client = APIClient()
 response = client.delete(
     f'/api/authors/{author_pk}')
 ```
 
-
 ### Login
 If you use PFX authentication views you can use this login method.
 
@@ -81,7 +80,7 @@ Once you called login, you can call any other method
 listed above, the authentication token will be sent with the requests.
 
 Example :
-```
+```python
 client = APIClient()
 client.login(
     username='jrr.tolkien',
@@ -98,7 +97,7 @@ Test the response code of a response.
 It takes two parameters, the response and the expected status code.
 
 Example :
-```
+```python
 class ATestClass(TestAssertMixin, TransactionTestCase):
 
     def a_test(self):
@@ -110,12 +109,12 @@ class ATestClass(TestAssertMixin, TransactionTestCase):
         self.assertRC(response, 200)
 ```
 
-### assertJE
-Test the value of a json property in the json_content of the response.
-It takes 3 parameters, the response, the key and the expected value.
-It allows you to specify the path to reach an element in the json structure.
+### get_val
+
+Get a value for a python dictionary or a json HTTP response by a string path key.
+The src parameter can be a Python dictionary or an object with `json_content` attribute.
 For instance if you have a response like
-```
+```python
 {
     "author": {
         "pk": 2,
@@ -125,32 +124,58 @@ For instance if you have a response like
     "pk": 6,
 }
 ```
-you can reach the author pk by providing "author.pk" as the key.
+you can reach the author pk by providing `"author.pk"` as the key.
 
-AssertJE also allows to specify the index in an array.
-The syntax is "@index".
+get_val also allows to specify the index in an array.
+The syntax is `"@index"`.
 
 For instance if you want the pk of the author of the
-third item in an array of books you can specify "items.@3.author.pk"
+third item in an array of books you can specify `"items.@3.author.pk"`
 
 Example :
+```python
+class ATestClass(TestAssertMixin, TransactionTestCase):
+
+    def a_test(self):
+        client = APIClient()
+        response = client.get('/api/books')
+        author_pk = self.get_val(response, 'items.@3.author.pk')
 ```
+
+### assertJE
+Test the value of a dictionary property (using `get_val`).
+It takes 3 parameters, the source, the key and the expected value.
+
+Example :
+```python
 class ATestClass(TestAssertMixin, TransactionTestCase):
 
     def a_test(self):
         client = APIClient()
         response = client.get('/api/books')
-        self.assertJE(response, 'items.@3.author.pk', 6)
+        author_pk = self.assertJE(response, 'items.@3.author.pk', 6)
 ```
 
 ### assertNJE
-Assert NJE is the same as AssertJE, but it tests that the value is not equal.
+`AssertNJE` is the same as `AssertJE`, but it tests that the value is not equal.
+
+### assertJEExists
+Assert the path exists in the source.
+
+### assertJENotExists
+Assert the path does not exists in the source.
+
+### assertSize
+Test the size of a value (if the value is a collection).
+
+### assertJIn
+Test that an element is part of a collection value.
 
 ## Print Response
 You can use the print_response helper to print a response in the console.
 
 Example :
-```
+```python
 client = APIClient()
 response = client.get('/api/books')
 print_response(response)
@@ -158,7 +183,7 @@ print_response(response)
 
 will produce
 
-```
+```plain
 *********************http response*********************
 Status :  200 OK
 Headers :
@@ -186,3 +211,54 @@ Content :
 }
 *******************************************************
 ```
+
+## PermsAPITest
+
+This test class can be used to test permissions on services with multiple users.
+
+Create multiple users in `setUpTestData` and add a method for each service
+you want to test.
+
+You can test the response status code or the response list count for items list responses.
+
+Example :
+```python
+class BookPermsAPITest(PermsAPITest):
+    def setUp(self):
+        self.client = APIClient(with_cookie=True)
+
+    @classmethod
+    def setUpTestData(cls):
+        # Create your users here
+
+    def list(self):
+        # Create a book
+        return self.client.get('/api/books?items=1&count=1')
+
+    def get(self):
+        # book = … (create a book)
+        return self.client.get(f'/api/books/{book.pk}')
+
+    def post(self):
+        return self.client.post('/api/books', dict(
+            name="Test new"))
+
+    def put(self):
+        return self.client.put(
+            f'/api/books/{self.organization.pk}', dict(
+                name="Updated"))
+
+    def delete(self):
+        # book = … (create a book)
+        return self.client.delete(f'/api/books/{book.pk}')
+
+    USER_TESTS = {
+        "admin@user.org": dict(
+            list=200, list__count=1, get=200
+            post=200, put=200, delete=200),
+        "user@user.org": dict(
+            list=200, list__count=1, get=200,
+            post=403, put=403, delete=403),
+    }
+
+```

django-pfx-1.2.dev94/doc/source/decorator.md

@@ -1,45 +0,0 @@
-# View decorator and URL
-## @rest_view
-Used to provide the base path of a view class
-```
-    @rest_view("/base-path")
-    class ViewClass():
-```
-
-## @rest_api
-Used to annotate the rest services method.
-Parameters are the path and the HTTP method.
-```
-    @rest_api("/path", method="get")
-    def class_method(self):
-```
-
-A short example
-```
-@rest_view("/books")
-class BookRestView():
-
-    @rest_api("/list", method="get")
-    def get_list(self):
-        return JsonResponse(
-            dict(books=['The Man in the High Castle', 'A Scanner Darkly']))
-```
-
-### path parameters
-Path can contain parameters that are passed to the method.
-```
-    @rest_api("/path/<int:id>/test/<slug:slug>", method="get")
-    def class_method(self, id, slug):
-```
-
-## Registering urls
-To be available, annotated view class must be registered
-in your urls.py file as follows.
-```
-from django_request_mapping import UrlPattern
-
-from . import views
-
-urlpatterns = UrlPattern()
-urlpatterns.register(views.BookRestView)
-```

django-pfx-1.2.dev94/doc/source/pfx_views.md

@@ -1,100 +0,0 @@
-# Django PFX Views
-REST services are provided as ViewMixin.
-Each of these views must set the queryset used to query the model data either
-by defining the queryset attribute or by overriding the get_queryset method.
-
-Fields can be listed in the fields attribute, else all the fields are provided.
-
-## ListRestViewMixin
-Provide a list service for a model class.
-
-By default, list fields are taken from fields attributes if defined.
-They can also be listed in the list_fields attribute if you need to have
-different fields in the list than in other views.
-```
-@rest_view("/books")
-class BookRestView(ListRestViewMixinRestView):
-    queryset = Book.objects
-    list_fields = ['name', 'author', 'pub_date', 'created_at', 'type']
-```
-### Meta
-### Pagination
-
-### Filters
-List view can have filters.
-
-TODO explain filters.
-
-## DetailRestViewMixin
-Provide a get detail service for a model class.
-
-```
-@rest_view("/books")
-class BookRestView(DetailRestViewMixin):
-    queryset = Book.objects
-    fields = ['name', 'author', 'pub_date', 'created_at', 'type']
-```
-### Meta
-
-## CreateRestViewMixin
-Provide a creation service for a model class.
-Readonly fields can be provided in the read_only attribute.
-
-TODO : explain "default_values"
-```
-@rest_view("/books")
-class BookRestView(CreateRestViewMixin):
-    queryset = Book.objects
-    fields = ['name', 'author', 'pub_date', 'created_at', 'type']
-    readonly_fields = ['created_at']
-```
-
-## UpdateRestViewMixin
-Provide an update service for a model class.
-Readonly fields can be provided in the read_only attribute.
-```
-@rest_view("/books")
-class BookRestView(UpdateRestViewMixin):
-    queryset = Book.objects
-    fields = ['name', 'author', 'pub_date', 'created_at', 'type']
-    readonly_fields = ['created_at']
-```
-
-## DeleteRestViewMixin
-Provide a delete service for a model class.
-
-```
-@rest_view("/books")
-class BookRestView(DeleteRestViewMixin):
-    queryset = Book.objects
-```
-
-## SlugDetailRestViewMixin
-Provide a get detail service for a model class with a slug.
-Slug field is searched in the "slug" field of the model by default,
-but it can be overridden with the "SLUG_FIELD" attribute.
-
-```
-@rest_view("/authors")
-class AuthorRestView(SlugDetailRestViewMixin):
-    queryset = Author.objects
-    SLUG_FIELD = "slug"
-    fields = ['name', 'slug', 'created_at', 'type']
-```
-
-## SecuredRestViewMixin
-TODO Explain :
-- default_public = True
-- def perm(self):
-- {func_name}_perm
-
-
-## RestView
-A base class that inherits :
-        ListRestViewMixin,
-        DetailRestViewMixin,
-        CreateRestViewMixin,
-        UpdateRestViewMixin,
-        DeleteRestViewMixin,
-        SecuredRestViewMixin,
-        django.views.View