Recursive Serialization for Django REST framework

0.1.2 · abandoned · verified Thu Apr 16

djangorestframework-recursive is a Python library that provides a `RecursiveField` for Django REST Framework serializers, enabling the serialization of tree, linked list, or directed acyclic graph structures. Maintained by @heywbj, the last release (0.1.2) was on July 4, 2017. Due to a lack of recent maintenance, users requiring compatibility with modern Django and Django REST Framework versions are advised to consider the actively maintained fork, `drf-recursive`.

Common errors

```
RecursionError: maximum recursion depth exceeded while calling a Python object
```
cause Attempting to serialize an excessively deep recursive structure without a proper depth limit or hitting Python's default recursion limit.

fix Review your data structure for unintended cycles or extreme depth. Increase Python's recursion limit (`sys.setrecursionlimit(limit)`) if genuinely necessary, but be aware of performance implications. Consider flattening parts of the hierarchy or loading data in chunks.
```
ModuleNotFoundError: No module named 'rest_framework_recursive'
```
cause The `djangorestframework-recursive` package is not installed, or the fork `drf-recursive` was installed and the import path is incorrect.

fix Ensure `djangorestframework-recursive` is installed via `pip install djangorestframework-recursive`. If you intended to use the fork, install `drf-recursive` and import `RecursiveField` from `django_rest_framework_recursive.fields` (note the different package name).
```
TypeError: 'RecursiveField' object is not iterable
```
cause Incorrect usage of `RecursiveField` within a serializer, for example, passing it directly as a field for a `many=True` relationship without wrapping it in a `ListField` or similar.

fix For one-to-many or many-to-many recursive relationships, ensure `RecursiveField` is used as the `child` of a `serializers.ListField` or `serializers.ManyRelatedField`.

Warnings

breaking The `djangorestframework-recursive` library is no longer actively maintained. Its last release was in 2017, leading to potential incompatibility issues with modern Python (3.7+), Django (2.1+), and Django REST Framework (3.8+) versions.
Fix: Consider using the actively maintained fork, `drf-recursive` (installable via `pip install drf-recursive`), which explicitly supports modern Python, Django, and DRF versions.
gotcha Deeply nested or very wide recursive data structures can lead to `RecursionError: maximum recursion depth exceeded` during serialization, or significant performance degradation.
Fix: Implement strategies to limit recursion depth, optimize database queries with `select_related` or `prefetch_related` for related objects, or consider alternative serialization approaches for extremely large graphs. Review Python's default recursion limit (`sys.getrecursionlimit()`).
deprecated The original library explicitly supported Python 2.7. Using it with Python 2.7 is highly discouraged as Python 2.7 reached its end-of-life in 2020.
Fix: Migrate your project to Python 3. If you need recursive serialization on Python 3, use the `drf-recursive` fork.

Install

pip install djangorestframework-recursive Install latest version

Imports

RecursiveField

from rest_framework_recursive.fields import RecursiveField

Quickstart

This quickstart demonstrates how to define a recursive serializer for a tree-like structure using `RecursiveField`. It assumes a conceptual `Category` model with a self-referential `parent` foreign key, allowing for nested children. The `RecursiveField` automatically handles the self-referencing serialization.

from rest_framework import serializers
from rest_framework_recursive.fields import RecursiveField

# Example Model (assuming you have a Django model like this)
# class Category(models.Model):
#     name = models.CharField(max_length=100)
#     parent = models.ForeignKey('self', on_delete=models.CASCADE, null=True, blank=True, related_name='children')

class CategorySerializer(serializers.Serializer):
    name = serializers.CharField(max_length=100)
    children = serializers.ListField(child=RecursiveField(), required=False)

# Example usage with a dummy data structure
# In a real application, you would pass Django model instances
data = {
    'name': 'Root',
    'children': [
        {
            'name': 'Child 1',
            'children': [
                {'name': 'Grandchild 1.1'},
                {'name': 'Grandchild 1.2'}
            ]
        },
        {'name': 'Child 2'}
    ]
}

serializer = CategorySerializer(data=data)
if serializer.is_valid():
    print(serializer.data)
else:
    print(serializer.errors)

view raw JSON →