django-pfx 1.2.dev107__tar.gz → 1.2.dev110__tar.gz

{django-pfx-1.2.dev107 → django-pfx-1.2.dev110}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.2.dev107
-Summary: Django PFX is a toolkit to build web APIs dedicated to be used by React progressive web app.
+Version: 1.2.dev110
+Summary: Django PFX is a toolkit to build rest APIs with the Django framework.
 Author: Hervé Martinet
 Author-email: herve.martinet@gmail.com
 License: BSD-3-Clause
-Project-URL: Source, https://gitlab.com/hmartinet/django-pfx
-Project-URL: Tracker, https://gitlab.com/hmartinet/django-pfx/-/issues
+Project-URL: Source, https://gitlab.com/pfx4/django-pfx
+Project-URL: Tracker, https://gitlab.com/pfx4/django-pfx/-/issues
+Project-URL: Documentation, https://pfx4.gitlab.io/django-pfx/doc/
 Classifier: Environment :: Web Environment
 Classifier: Framework :: Django
 Classifier: Framework :: Django :: 3.2
@@ -31,11 +32,8 @@ License-File: LICENSE
 
 ![logo]
 
-Django PFX is a toolkit to build web APIs dedicated to be used by React progressive web app.
+Django PFX is a toolkit to build rest APIs with the Django framework.
 
-> **WARNING**
->
-> This is an experimental projet. It should not be used in real project because it is incomplete and there is no warranty of keeping compatibility in future version.
 
 [logo]: https://gitlab.com/hmartinet/django-pfx/-/raw/master/img/pfx.png "PFX"
 [pipeline]: https://gitlab.com/hmartinet/django-pfx/badges/master/pipeline.svg "Pipeline Status"

{django-pfx-1.2.dev107 → django-pfx-1.2.dev110}/README.md

@@ -5,11 +5,8 @@
 
 ![logo]
 
-Django PFX is a toolkit to build web APIs dedicated to be used by React progressive web app.
+Django PFX is a toolkit to build rest APIs with the Django framework.
 
-> **WARNING**
->
-> This is an experimental projet. It should not be used in real project because it is incomplete and there is no warranty of keeping compatibility in future version.
 
 [logo]: https://gitlab.com/hmartinet/django-pfx/-/raw/master/img/pfx.png "PFX"
 [pipeline]: https://gitlab.com/hmartinet/django-pfx/badges/master/pipeline.svg "Pipeline Status"

{django-pfx-1.2.dev107 → django-pfx-1.2.dev110}/django_pfx.egg-info/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.2.dev107
-Summary: Django PFX is a toolkit to build web APIs dedicated to be used by React progressive web app.
+Version: 1.2.dev110
+Summary: Django PFX is a toolkit to build rest APIs with the Django framework.
 Author: Hervé Martinet
 Author-email: herve.martinet@gmail.com
 License: BSD-3-Clause
-Project-URL: Source, https://gitlab.com/hmartinet/django-pfx
-Project-URL: Tracker, https://gitlab.com/hmartinet/django-pfx/-/issues
+Project-URL: Source, https://gitlab.com/pfx4/django-pfx
+Project-URL: Tracker, https://gitlab.com/pfx4/django-pfx/-/issues
+Project-URL: Documentation, https://pfx4.gitlab.io/django-pfx/doc/
 Classifier: Environment :: Web Environment
 Classifier: Framework :: Django
 Classifier: Framework :: Django :: 3.2
@@ -31,11 +32,8 @@ License-File: LICENSE
 
 ![logo]
 
-Django PFX is a toolkit to build web APIs dedicated to be used by React progressive web app.
+Django PFX is a toolkit to build rest APIs with the Django framework.
 
-> **WARNING**
->
-> This is an experimental projet. It should not be used in real project because it is incomplete and there is no warranty of keeping compatibility in future version.
 
 [logo]: https://gitlab.com/hmartinet/django-pfx/-/raw/master/img/pfx.png "PFX"
 [pipeline]: https://gitlab.com/hmartinet/django-pfx/badges/master/pipeline.svg "Pipeline Status"

{django-pfx-1.2.dev107 → django-pfx-1.2.dev110}/django_pfx.egg-info/requires.txt

@@ -1,4 +1,4 @@
-django<4.0,>=3.2
+django<5.0,>=3.2
 django-cors-headers
 django_json_widget
 pyjwt>=2.1

{django-pfx-1.2.dev107 → django-pfx-1.2.dev110}/doc/index.rst

@@ -6,13 +6,7 @@
 Welcome to Django PFX's documentation!
 ======================================
 
-Django PFX is a toolkit to build web APIs dedicated
-to be used by React progressive web app.
-
-.. warning::
-   This is a project in development.
-   It should not be used in real project because it is incomplete
-   and changes may break the compatibility in future version.
+Django PFX is a toolkit to build rest APIs with the Django framework.
 
 
 Topics

{django-pfx-1.2.dev107 → django-pfx-1.2.dev110}/doc/source/decorator.md

@@ -1,7 +1,9 @@
 # View decorator and URL
 ## @rest_view
 Used to provide the base path of a view class
-```
+```python
+from pfx.pfxcore.decorator import rest_view
+
 @rest_view("/base-path")
 class ViewClass():
 ```
@@ -9,13 +11,18 @@ class ViewClass():
 ## @rest_api
 Used to annotate the rest services method.
 Parameters are the path and the HTTP method.
-```
+```python
+from pfx.pfxcore.decorator import rest_api
+
 @rest_api("/path", method="get")
 def class_method(self):
 ```
 
 A short example
-```
+```python
+from pfx.pfxcore.decorator import rest_view, rest_api
+from pfx.pfxcore.http import JsonResponse
+
 @rest_view("/books")
 class BookRestView():
 
@@ -27,7 +34,9 @@ class BookRestView():
 
 ### path parameters
 Path can contain parameters that are passed to the method.
-```
+```python
+from pfx.pfxcore.decorator import rest_api
+
 @rest_api("/path/<int:pk>/test/<slug:slug>", method="get")
 def class_method(self, pk, slug):
 ```
@@ -35,7 +44,8 @@ def class_method(self, pk, slug):
 ## Registering urls
 To be available, annotated view class must be registered
 in your urls.py file as follows.
-```
+
+```python
 from pfx.pfxcore import register_views
 
 from . import views
@@ -44,9 +54,11 @@ 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:
-```
+```python
+from django.urls import include, path
 from pfx.pfxcore import register_views
 
 from . import views

django-pfx-1.2.dev110/doc/source/getting_started.md

@@ -0,0 +1,179 @@
+# Getting Started with PFX
+
+## Install django pfx
+
+Using pip
+```bash
+pip install django-pfx
+```
+
+## Configuration
+
+Add pfxcore to the installed app
+
+```python
+INSTALLED_APPS = [
+    'pfx.pfxcore',
+]
+```
+
+## Create your services
+
+### Model class
+Create a simple model class.
+```python
+from django.db import models
+
+
+class Book(models.Model):
+    BOOK_TYPES = [
+        ('science_fiction', 'Science Fiction'),
+        ('heroic_fantasy', 'Heroic Fantasy'),
+        ('detective', 'Detective')]
+
+    title = models.CharField("Title", max_length=30)
+    author = models.CharField("Author", max_length=150)
+    type = models.CharField("Type", max_length=20, choices=BOOK_TYPES)
+    pub_date = models.DateField("Pub Date")
+    created_at = models.DateField("Created at", auto_now_add=True)
+
+    class Meta:
+        verbose_name = "Book"
+        verbose_name_plural = "Books"
+
+    def __str__(self):
+        return f"{self.name}"
+
+```
+
+### Views
+Create a new view
+```python
+from pfx.pfxcore.decorator import rest_view
+from pfx.pfxcore.views import RestView
+
+from book.models import Book
+
+
+@rest_view("/books")
+class BookRestView(RestView):
+    default_public = True
+    queryset = Book.objects
+    fields = ['title', 'author', 'type', 'pub_date', 'created_at']
+```
+
+### URLs
+Register the url in urls.py.
+```python
+from django.urls import path, include
+from pfx.pfxcore import register_views
+
+
+from book import views
+
+apipatterns = register_views(views.BookRestView)
+
+urlpatterns = [
+    path('api/', include(apipatterns)),
+]
+```
+
+You now have a fully functional public API for the book objet.
+
+### Test the API
+The next step is to create a test class to test your new API.
+PFX provides [some tools](testing.md) to ease the testing.
+
+```python
+from datetime import date
+from django.test import TransactionTestCase
+from pfx.pfxcore.test import TestAssertMixin, APIClient
+
+from book.models import Book, Author
+
+class BookTestClass(TestAssertMixin, TransactionTestCase):
+
+    @classmethod
+    def setUpTestData(cls):
+        # create some test data
+        cls.author = Author.objects.create(
+            first_name='Isaac',
+            last_name='Asimov')
+        cls.book1 = Book.objects.create(
+            author=cls.author,
+            title="The Caves of Steel",
+            type='science_fiction',
+            pub_date=date(1954, 1, 1))
+        cls.book2 = Book.objects.create(
+            author=cls.author,
+            title="The Naked Sun",
+            type='science_fiction',
+            pub_date=date(1957, 1, 1))
+
+    def test_get_book_list(self):
+        client = APIClient()
+        response = client.get('/api/books')
+
+        # assert response status is 200 OK
+        self.assertRC(response, 200)
+        # assert number of item returned
+        self.assertSize(response, 'items', 2)
+        # test the author of the second item is Asimov
+        self.assertJE(response, 'items.@1.author.pk', self.author.pk)
+
+    def test_get_book(self):
+        client = APIClient()
+        response = client.get(f'/api/books/{self.book2.pk}')
+
+        # assert response status is 200 OK
+        self.assertRC(response, 200)
+        # assert json content of the response
+        self.assertJE(response, 'title', "The Naked Sun")
+        self.assertJE(response, 'pub_date', "1957-01-01")
+
+    def test_create_book(self):
+        client = APIClient()
+        response = client.post(
+            '/api/books/',dict(
+                title="The Robots of Dawn",
+                author=self.author,
+                type='science_fiction',
+                pub_date=date(1983, 1, 1)
+            ))
+        self.assertRC(response, 200)
+        self.assertJE(response, 'title', "The Robots of Dawn")
+
+    def test_create_book_validation(self):
+        client = APIClient()
+        # make a post request
+        response = client.post(
+            '/api/books/',dict(
+                title=None,
+                author=self.author,
+                type='science_fiction',
+                pub_date=date(1983, 1, 1)
+            ))
+        self.assertRC(response, 422)
+        self.assertJE(
+            response, 'title.@0', "This field cannot be null.")
+
+    def test_update_book(self):
+        client = APIClient()
+        response = client.put(
+            f'/api/books/{self.book2.pk}',dict(
+                title="The Robots of Dawn",
+                pub_date=date(1983, 1, 1),
+            ))
+        self.assertRC(response, 200)
+        self.assertJE(response, 'title', "The Robots of Dawn")
+
+    def test_delete_book(self):
+        client = APIClient()
+        response = client.delete(
+            f'/api/books/{self.book2.pk}')
+        self.assertRC(response, 200)
+
+        books = Book.objects.filter(pk=self.book2.pk)
+        self.assertEqual(books.count(), 0)
+
+```

{django-pfx-1.2.dev107 → django-pfx-1.2.dev110}/doc/source/internationalisation.md

@@ -12,7 +12,7 @@ In Django, `USE_I18N` must be `True` to use internationalization. Use `LANGUAGE_
 You can optionally set `USE_L10N` to `True` (see Django documentation).
 
 In Addition, you can set the list of available languages for web services with `LANGUAGES`:
-```
+```python
 LANGUAGES = [
     ('fr', "French"),
     ('en', "English"),

{django-pfx-1.2.dev107 → django-pfx-1.2.dev110}/doc/source/model.md

@@ -5,15 +5,19 @@ 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.
+you have to annotate them with `@rest_property`.
 
 Rest property takes 2 parameters, a name and
 the type of the Field (CharField, IntegerField, etc.)
 
 Rest properties can be listed as fields to be returned in list and detail views.
-```
+
+```python
+from django.db import models
+from pfx.pfxcore.decorator import rest_property
+
 class Book(models.Model):
     name = models.CharField("Name", max_length=30)
     author = models.ForeignKey(
@@ -35,12 +39,11 @@ class Book(models.Model):
 ```
 
 ## JSONReprMixin
-
-Foreign keys are returned by {doc}`Django PFX views <pfx_views>` as a JSON
+Foreign keys are returned by [Django PFX views <pfx_views>](./pfx_views.md) as a JSON
 structure with two fields : pk, resource_name
 
 For instance for the book class, with the author foreign key  :
-```
+```python
 {
     "author": {
         "pk": 1,
@@ -60,8 +63,11 @@ by inheriting JSONReprMixin on the Model class and
 by overriding the json_repr method.
 
 For instance for the Author class :
-```
-class Author(models.Model):
+```python
+from django.db import models
+from pfx.pfxcore.models import JSONReprMixin
+
+class Author(JSONReprMixin, models.Model):
     first_name = models.CharField("First Name", max_length=30)
     last_name = models.CharField("Last Name", max_length=30)
     slug = models.SlugField("Slug", unique=True)
@@ -80,11 +86,11 @@ class Author(models.Model):
 ```
 
 Which give the following result on the book service :
-```
+```python
 {
     "author": {
         "pk": 1,
-        "resource_name": "John Ronald Reuel Tolkien"
+        "resource_name": "John Ronald Reuel Tolkien",
         "resource_slug": "john-ronald-reuel-tolkien"
     },
     "created_at": "2022-01-14",
@@ -104,9 +110,11 @@ converting `null` values to empty strings, you can use the following model field
 * `NotNullCharField`
 * `NotNullTextField`
 * `NotNullURLField`
-```
-    a_string_field = NotNullCharField(
-        _("A string"), max_length=255, blank=True, default="")
+```python
+from pfx.pfxcore.models import NotNullCharField
+
+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.dev107 → django-pfx-1.2.dev110}/doc/source/pfx_views.md

@@ -10,7 +10,9 @@ 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).
-```
+
+```python
+from pfx.pfxcore.decorator import rest_view
 from pfx.pfxcore.views import BaseRestView, DetailRestViewMixin
 
 @rest_view("/books")
@@ -24,7 +26,8 @@ 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.
 
-```
+```python
+from pfx.pfxcore.decorator import rest_view
 from pfx.pfxcore.views import BaseRestView, SlugDetailRestViewMixin
 
 @rest_view("/authors")
@@ -33,13 +36,15 @@ class AuthorRestView(SlugDetailRestViewMixin, BaseRestView):
     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.
-```
+```python
+from pfx.pfxcore.decorator import rest_view
 from pfx.pfxcore.views import BaseRestView, ListRestViewMixin
 
 @rest_view("/books")
@@ -47,11 +52,12 @@ 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:
-```
+```python
 {
-    "items": […],
+    "items": ['…'],
     "meta": {
         "page": 1,
         "page_size": 10,
@@ -66,9 +72,9 @@ 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:
-```
+```python
 {
-    "items": […],
+    "items": ['…'],
     "meta": {
         "count": 200,
         "page_count": 20,
@@ -79,24 +85,26 @@ If you pass `?subset=offset`, the response will include offset/limit data in met
 ```
 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:
-```
+Use `ModelFilter` to add a filter on an ORM field:
+```python
 from pfx.pfxcore.views import (
     RestView,
     ModelFilter)
 
-
 class AuthorRestView(RestView):
     filters = [
         ModelFilter(Author, 'name'),
     ]
 ```
+
 #### Filter
 Use `Filter` to add a custom filter:
-```
+```python
 from django.db.models import Q
 
 from pfx.pfxcore.views import (
@@ -111,12 +119,14 @@ def name_filter(value):
 
 class AuthorRestView(RestView):
     filters = [
-        Filter('name', _("Name"), FieldType.CharField, name_filter),
+        Filter('name', "Name", FieldType.CharField, name_filter),
     ]
 ```
+
 ## CreateRestViewMixin
 Provide a creation service for a model class.
-```
+```python
+from pfx.pfxcore.decorator import rest_view
 from pfx.pfxcore.views import BaseRestView, CreateRestViewMixin
 
 @rest_view("/books")
@@ -124,11 +134,15 @@ 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.
-```
+```python
+from pfx.pfxcore.decorator import rest_view
+from pfx.pfxcore.views import BaseRestView, CreateRestViewMixin
+
 @rest_view("/books")
 class BookRestView(CreateRestViewMixin, BaseRestView):
     queryset = Book.objects
@@ -137,14 +151,15 @@ class BookRestView(CreateRestViewMixin, BaseRestView):
     )
 ```
 If you need to set dynamics default values,
-you can override following methods (depending of your needs):
+you can override following methods (depending on 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.
-```
+```python
+from pfx.pfxcore.decorator import rest_view
 from pfx.pfxcore.views import BaseRestView, UpdateRestViewMixin
 
 @rest_view("/books")
@@ -155,7 +170,8 @@ class BookRestView(UpdateRestViewMixin, BaseRestView):
 
 ## DeleteRestViewMixin
 Provide a delete service for a model class.
-```
+```python
+from pfx.pfxcore.decorator import rest_view
 from pfx.pfxcore.views import BaseRestView, DeleteRestViewMixin
 
 @rest_view("/books")
@@ -175,22 +191,30 @@ 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.
-```
+```python
+from pfx.pfxcore.decorator import rest_view
+from pfx.pfxcore.views import RestView
+
 @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`:
-```
+```python
+from pfx.pfxcore.decorator import rest_view
+from pfx.pfxcore.views import RestView
+
 @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.
@@ -201,14 +225,18 @@ 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.
-```
+```python
+from pfx.pfxcore.decorator import rest_view
+from pfx.pfxcore.views import RestView
+
 @rest_view("/books")
 class BookRestView(RestView):
     queryset = Book.objects
 
-    def my_method_perm(self)
+    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)`