Merge pull request #333 from yezyilomo/release_v0.17.0

Release v0.17.0

Author: yezyilomo

README.md

@@ -150,6 +150,14 @@ Full documentation for this project is available at [https://yezyilomo.github.io
 `python runtests.py`
 
 
+## Writing & Deploying Docs
+Run `pip3 install mkdocs-material` to install mkdocs-material
+
+Run `mkdocs serve` to serve docs locally
+
+Run `mkdocs gh-deploy --force` to deploy docs to gh-page
+
+
 ## Credits
 * Implementation of this library is based on the idea behind [GraphQL](https://graphql.org/).
 * My intention is to extend the capability of [drf-dynamic-fields](https://github.com/dbrgn/drf-dynamic-fields) library to support more functionalities like allowing to query nested fields both flat and iterable at any level and allow writing on nested fields while maintaining simplicity.

django_restql/__init__.py

@@ -1,7 +1,7 @@
 __title__ = 'Django RESTQL'
 __description__ = 'Turn your API made with Django REST Framework(DRF) into a GraphQL like API.'
 __url__ = 'https://yezyilomo.github.io/django-restql'
-__version__ = '0.16.2'
+__version__ = '0.17.0'
 __author__ = 'Yezy Ilomo'
 __author_email__ = '[email protected]'
 __license__ = 'MIT'

docs/mutating_data.md

@@ -447,6 +447,75 @@ This will remove all books associated with a course being updated.
 <br>
 
 
+### delete_on_null kwarg
+When dealing with nested fields, there are scenarios where the previously assigned object or resource is no longer needed after the field is cleared (i.e. set to `null`). In such cases, passing `delete_on_null=True` kwarg enables automatic deletion of the previously assigned resource when the nested field is explicitly updated to `null`.
+
+This keyword argument applies only to `ForeignKey` or `OneToOne` relationships.
+The default value for `delete_on_null` kwarg is `False`.
+
+Below is an example showing how to use `delete_on_null` kwarg.
+```py
+from rest_framework import serializers 
+from django_restql.fields import NestedField
+from django_restql.serializers import NestedModelSerializer
+
+from app.models import Location, Property
+
+
+class LocationSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Location
+        fields = ["id", "city", "country"]
+
+
+class PropertySerializer(NestedModelSerializer):
+    location = NestedField(LocationSerializer, delete_on_null=True)
+    class Meta:
+        model = Property
+        fields = [
+            'id', 'price', 'location'
+        ]
+```
+
+Assuming we have a property with this structure
+```js
+{
+    "id": 1,
+    "price": 30000,
+    "location": {
+        "id": 5,
+        "city": "Arusha",
+        "country": "Tanzania"
+    }
+}
+```
+
+Sending a mutation request to update this property by removing a location
+
+```PUT/PATCH  /api/property/1/```
+
+Request Body
+```js
+{
+    "location": null
+}
+```
+
+Response
+```js
+{
+    "id": 1,
+    "price": 30000,
+    "location": null
+}
+```
+
+In this case, the property’s location is updated to null, and the previously assigned Location instance (with id: 5) is deleted from the database.
+
+!!! note
+    `delete_on_null=True` can only be used when both `accept_pk=False` and `accept_pk_only=False`. This is because `accept_pk=True` or `accept_pk_only=True` typically implies that the nested object is not tightly coupled to the parent and may be referenced elsewhere. Automatically deleting it in such cases could lead to unintended side effects or broken references.
+
+
 ## Using DynamicFieldsMixin and NestedField together
 You can use `DynamicFieldsMixin` and `NestedModelSerializer` together if you want your serializer to be writable(on nested fields) and support querying data, this is very common. Below is an example which shows how you can use `DynamicFieldsMixin` and `NestedField` together.