Review docblocks

Author: febus982

sqlalchemy_bind_manager/_repository/base_repository.py

@@ -82,6 +82,7 @@ def _filter_select(self, stmt: Select, search_params: Mapping[str, Any]) -> Sele
         :param stmt: a Select statement
         :type stmt: Select
         :param search_params: Any keyword argument to be used as equality filter
+        :type search_params: Mapping[str, Any]
         :return: The filtered query
         """
         # TODO: Add support for relationship eager load
@@ -110,6 +111,7 @@ def _filter_order_by(
         :param stmt: a Select statement
         :type stmt: Select
         :param order_by: a list of columns, or tuples (column, direction)
+        :type order_by: Iterable[Union[str, Tuple[str, SortDirection]]]
         :return: The filtered query
         """
         for value in order_by:
@@ -127,6 +129,24 @@ def _find_query(
         search_params: Union[None, Mapping[str, Any]] = None,
         order_by: Union[None, Iterable[Union[str, Tuple[str, SortDirection]]]] = None,
     ) -> Select:
+        """Build a query with column filters and orders.
+
+        E.g.
+        q = _find_query(search_params={"name":"John"})
+            finds all models with name = John
+
+        q = _find_query(order_by=["name"])
+            finds all models ordered by `name` column
+
+        q = _find_query(order_by=[("name", SortDirection.DESC)])
+            finds all models with reversed order by `name` column
+
+        :param search_params: Any keyword argument to be used as equality filter
+        :type search_params: Mapping[str, Any]
+        :param order_by: a list of columns, or tuples (column, direction)
+        :type order_by: Iterable[Union[str, Tuple[str, SortDirection]]]
+        :return: The filtered query
+        """
         stmt = select(self._model)
 
         if search_params:
@@ -177,19 +197,22 @@ def _cursor_paginated_query(
         is_before_cursor: bool = False,
         items_per_page: int = _max_query_limit,
     ) -> Select:
-        """Build the query offset and limit clauses from submitted parameters.
+        """Adds the clauses to retrieve the requested slice of models, after
+        or before the cursor value, plus a model before the slice and one after
+        the slice, to identify if previous or next results are available.
 
         :param stmt: a Select statement
         :type stmt: Select
-        :param before: Identifier of the last node to skip
-        :type before: Union[int, str]
-        :param after: Identifier of the last node to skip
-        :type after: Union[int, str]
+        :param cursor_reference: A cursor reference containing ordering column
+            and threshold value
+        :type cursor_reference: Union[CursorReference, None]
+        :param is_before_cursor: If True it will return items before the cursor,
+            otherwise items after
+        :type is_before_cursor: bool
         :param items_per_page: Number of models to retrieve
         :type items_per_page: int
         :return: The filtered query
         """
-
         forward_limit = self._sanitised_query_limit(items_per_page) + 1
 
         if not cursor_reference:
@@ -220,9 +243,24 @@ def _cursor_pagination_slice_query(
         self,
         stmt: Select,
         cursor_reference: CursorReference,
-        forward_limit: int,
+        limit: int,
         is_before_cursor: bool,
     ):
+        """Adds the clauses to retrieve a requested slice of models,
+        after or before the cursor value (excluding the cursor itself)
+
+        :param stmt: a Select statement
+        :type stmt: Select
+        :param cursor_reference: A cursor reference containing ordering column
+            and threshold value
+        :type cursor_reference: Union[CursorReference, None]
+        :param is_before_cursor: If True it will return items before the cursor,
+            otherwise items after
+        :type is_before_cursor: bool
+        :param limit: Number of models to retrieve
+        :type limit: int
+        :return: The filtered query
+        """
         if not is_before_cursor:
             page_query = stmt.where(
                 getattr(self._model, cursor_reference.column) > cursor_reference.value
@@ -237,11 +275,24 @@ def _cursor_pagination_slice_query(
             page_query = self._filter_order_by(
                 page_query, [(cursor_reference.column, SortDirection.DESC)]
             )
-        return page_query.limit(forward_limit)
+        return page_query.limit(limit)
 
     def _cursor_pagination_previous_item_query(
         self, stmt: Select, cursor_reference: CursorReference, is_before_cursor: bool
     ) -> Select:
+        """Adds the clauses to retrieve a single model, after or before
+        the cursor value (including the cursor itself).
+
+        :param stmt: a Select statement
+        :type stmt: Select
+        :param cursor_reference: A cursor reference containing ordering column
+            and threshold value
+        :type cursor_reference: Union[CursorReference, None]
+        :param is_before_cursor: If True it will return items before the cursor,
+            otherwise items after
+        :type is_before_cursor: bool
+        :return: The filtered query
+        """
         if not is_before_cursor:
             previous_query = stmt.where(
                 getattr(self._model, cursor_reference.column) <= cursor_reference.value
@@ -263,6 +314,11 @@ def _sanitised_query_limit(self, limit):
         return max(min(limit, self._max_query_limit), 0)
 
     def _model_pk(self) -> str:
+        """
+        Retrieves the primary key name from the repository model class.
+
+        :return:
+        """
         primary_keys = inspect(self._model).primary_key  # type: ignore
         if len(primary_keys) > 1:
             raise NotImplementedError("Composite primary keys are not supported.")

sqlalchemy_bind_manager/_repository/sync.py

@@ -123,23 +123,6 @@ def cursor_paginated_find(
         is_before_cursor: bool = False,
         search_params: Union[None, Mapping[str, Any]] = None,
     ) -> CursorPaginatedResult[MODEL]:
-        """Find models using filters and cursor based pagination
-
-        E.g.
-        find(name="John") finds all models with name = John
-
-        :param items_per_page: Number of models to retrieve
-        :type items_per_page: int
-        :param order_by: Model property to use for ordering and before/after evaluation
-        :type order_by: str
-        :param before: Identifier of the last node to skip
-        :type before: Union[int, str]
-        :param after: Identifier of the last node to skip
-        :type after: Union[int, str]
-        :param search_params: A dictionary containing equality filters
-        :return: A collection of models
-        :rtype: List
-        """
         find_stmt = self._find_query(search_params)
 
         paginated_stmt = self._cursor_paginated_query(