Clients can disable default sorting by using sort=0 query parameter

CHANGES

@@ -4,6 +4,10 @@ Changelog
 Changes in Flask-Restless-NG
 ============================
 
+Version 2.4.0 (11/11/2022):
+-------------
+- Clients can disable default sorting by using `sort=0` query parameter
+
 Version 2.3.1:
 -------------
 - Fix for an incorrect error message

docs/fetching.rst

@@ -531,6 +531,10 @@ Clients can sort according to the sorting protocol described in the `Sorting
 specification. Sorting by a nullable attribute will cause resources with null
 attributes to appear first.
 
+If ``sort`` parameter is not specified, data is sorted using the primary key
+
+Clients can disable default sorting by using ``sort=0``
+
 
 .. _pagination:
 

flask_restless/__init__.py

@@ -1,7 +1,7 @@
 # Copyright 2011 Lincoln de Sousa <lincoln@comum.org>.
 # Copyright 2012, 2013, 2014, 2015, 2016 Jeffrey Finkelstein
 #           <jeffrey.finkelstein@gmail.com> and contributors.
-# Copyright 2020, 2021 Maksym Revutskyi <maksym.revutskyi@gmail.com> and contributors.
+# Copyright 2020, 2021, 2022 Maksym Revutskyi <maksym.revutskyi@gmail.com> and contributors.
 #
 # This file is part of Flask-Restless-NG.
 #
@@ -13,7 +13,7 @@
 
 """
 #: The current version of this extension.
-__version__ = '2.3.1'
+__version__ = '2.4.0'
 
 
 # The following names are available as part of the public API for Flask-Restless-NG.

flask_restless/search.py

@@ -426,7 +426,7 @@ def get_field(obj, name):
             field = get_field(related_model, field_name)
             direction = getattr(field, direction_name)
             query = query.order_by(direction())
-    else:
+    elif sort is not None:
         pks = primary_key_names(model)
         pk_order = (getattr(model, field).asc() for field in pks)
         query = query.order_by(*pk_order)

flask_restless/views/base.py

@@ -147,8 +147,12 @@ def collection_parameters():
         # Determine sorting options.
         sort = request.args.get(SORT_PARAM)
         if sort:
-            sort = [('-', value[1:]) if value.startswith('-') else ('+', value)
-                    for value in sort.split(',')]
+            if sort == '0':
+                # '0' disables default sorting
+                sort = None
+            else:
+                sort = [('-', value[1:]) if value.startswith('-') else ('+', value)
+                        for value in sort.split(',')]
         else:
             sort = []
     except (TypeError, KeyError, ValueError) as e:

tests/test_jsonapi/models.py

@@ -110,3 +110,13 @@ class UnicodePK(Base):
     """Model with a primary key that has Unicode type. """
     __tablename__ = 'unicode_pk'
     name = Column(Unicode, primary_key=True)
+
+
+class Unsorted(Base):
+    """Model that should not have a primary_key to dest disabled sorting.
+
+    SQLAlchemy does not actually let us define a model without a primary key,
+    so the table has to be created without the PK manually before create_all()
+    """
+    __tablename__ = 'unsorted'
+    id = Column(Integer, primary_key=True)

tests/test_jsonapi/test_fetching_data.py

@@ -17,6 +17,7 @@
 from .models import Comment
 from .models import Parent
 from .models import Person
+from .models import Unsorted
 from .models import Various
 
 
@@ -36,8 +37,17 @@ def setup(self):
         manager.create_api(Parent, page_size=0)
         manager.create_api(Child)
         manager.create_api(Various)
+        manager.create_api(Unsorted)
         self.manager = manager
 
+        with self.engine.connect() as connection:
+            connection.execute("""
+            create table unsorted
+                (
+                    id int not null
+                );
+            """)
+
         Base.metadata.create_all(bind=self.engine)
         yield
         Base.metadata.drop_all(bind=self.engine)
@@ -433,6 +443,19 @@ def test_sorting_null_field(self):
         assert ['3', '2'] == person_ids[-2:]
         assert {'1', '4'} == set(person_ids[:2])
 
+    def test_disabling_sorting(self):
+        """Tests that sorting by a nullable field causes resources with a null attribute value to appear first."""
+        self.session.add(Unsorted(id=2))
+        self.session.add(Unsorted(id=1))
+        self.session.add(Unsorted(id=4))
+        self.session.add(Unsorted(id=3))
+        self.session.commit()
+        document = self.fetch_and_validate('/api/unsorted', query_string={'sort': '0'})
+        ids = [item['id'] for item in document['data']]
+        assert ids == ['2', '1', '4', '3']
+        assert 'sort=0' in document['links']['first']
+        assert 'sort=0' in document['links']['last']
+
     def test_alternative_collection_name(self):
         """Tests for fetching a single resource with an alternate collection name."""
         self.session.add(Person(pk=1))