Add max_depth argument to control recursion without explicitly declaring relationships to ignore

Author: nxet

README.md

@@ -187,6 +187,42 @@ item.to_dict('-children.children')
 In this case only the first level of `children` will be included
 See [Max recursion](#Max-recursion)
 
+Alternatively you can pass the `max_depth` kwarg, which allows to control recursion in general without having to explicitly list each attribute you don't want recursed.  
+Please note that this check is performed at the beginning of `serialize_model()`, which means every other nested Iterable is *not affected* by this setting.  
+The default value returned when recursion is no longer permitted is a string in the form `tablename.id` (e.g. `users.123`), with fallback to `repr(item)` in case the `id` attribute is not available for the model.  
+This option can be disabled using `max_depth=-1`, which is also the default.  
+```python
+# Stop recursion at top level, meaning all relationships will be "dropped"
+# For example:
+#  item = User(id=123, name="john", articles=[Article(id=10), Article(id=11)])
+# will be serialized to
+#  {
+#    "id": 123, "name": "john",
+#    "articles": ["articles.10", "articles.11"]
+#  }
+item.to_dict(max_depth=0)
+
+# Stop at first level, meaning only the first children will be processed
+# For example, the same user above will be serialized to:
+#  {
+#    "id": 123, "name": "john",
+#    "articles": [
+#      {"id": 10, "title": ...},
+#      {"id": 11, "title": ...},
+#    ]
+#  }
+item.to_dict(max_depth=1)
+```
+The `max_depth` option can be also configured at mixin level, setting the `serialize_max_depth` class attribute which avoids passing it to each `to_dict` call.
+```python
+# Set max_depth option in mixin
+class SomeModel(db.Model, SerializerMixin):
+  serialize_max_depth = 0
+
+# Call to_dict without max_depth arg
+item.to_dict()
+```
+
 # Custom formats
 If you want to change datetime/date/time/decimal format in one model you can specify it like below:
 ```python

sqlalchemy_serializer/serializer.py

@@ -21,7 +21,7 @@
 
 Options = namedtuple(
     "Options",
-    "date_format datetime_format time_format decimal_format tzinfo serialize_types",
+    "date_format datetime_format time_format decimal_format tzinfo serialize_types max_depth",
 )
 
 
@@ -197,7 +197,12 @@ def serialize_dict(self, value: dict) -> dict:
                 logger.debug("Skip key:%s of dict", k)
         return res
 
-    def serialize_model(self, value) -> dict:
+    def serialize_model(self, value) -> t.Any:
+        # Check if user set a recursion limit and we can no longer recurse
+        if self.serialization_depth > self.opts.max_depth > -1:
+            # Return early calling internal helper
+            return self.serialize_model_fallback(value)
+
         self.schema.update(only=value.serialize_only, extend=value.serialize_rules)
 
         res = {}
@@ -220,6 +225,19 @@ def serialize_model(self, value) -> dict:
                 logger.debug("Skip key:%s of model:%s", k, get_type(value))
         return res
 
+    def serialize_model_fallback(self, value) -> t.Any:
+        """
+        Called when serialization can no longer recurse.
+        Default output is a string like "tablename.id", e.g. "users.123", if attributes
+        are not available it will return "repr(value)".
+        Override this method to implement own logic.
+        :return: str
+        """
+        try:
+            return f'{value.__tablename__}.{value.id}'
+        except AttributeError:
+            return repr(value)
+
 
 def serialize_collection(iterable: t.Iterable, *args, **kwargs) -> list:
     return [item.to_dict(*args, **kwargs) for item in iterable]
@@ -254,6 +272,9 @@ class SerializerMixin:
     time_format = "%H:%M"
     decimal_format = "{}"
 
+    # Maximum recursion depth, setting to "-1" disables logic
+    serialize_max_depth: int = -1
+
     # Serialize fields of the model defined as @property automatically
     auto_serialize_properties: bool = False
 
@@ -277,6 +298,7 @@ def to_dict(
         tzinfo=None,
         decimal_format=None,
         serialize_types=None,
+        max_depth=None
     ):
         """
         Returns SQLAlchemy model's data in JSON compatible format
@@ -293,6 +315,7 @@ def to_dict(
         :param decimal_format: str
         :param serialize_types:
         :param tzinfo: datetime.tzinfo converts datetimes to local user timezone
+        :param max_depth: int maximum recursion depth allowed, "-1" disables logic
         :return: data: dict
         """
         s = self.serialize_class(
@@ -302,5 +325,6 @@ def to_dict(
             decimal_format=decimal_format or self.decimal_format,
             tzinfo=tzinfo or self.get_tzinfo(),
             serialize_types=serialize_types or self.serialize_types,
+            max_depth=max_depth if max_depth is not None else self.serialize_max_depth,
         )
         return s(self, only=only, extend=rules)