Move and fix interface docblocks to protocols

Author: febus982

README.md

@@ -200,6 +200,7 @@ The classes provide some common use methods:
 * `delete`: Delete a model
 * `find`: Search for a list of models (basically an adapter for SELECT queries)
 * `paginated_find`: Search for a list of models, with pagination support
+* `cursor_paginated_find`: Search for a list of models, with cursor based pagination support
 
 ### Session lifecycle in repositories
 

sqlalchemy_bind_manager/_repository/async_.py

@@ -65,11 +65,6 @@ async def _get_session(self, commit: bool = True) -> AsyncIterator[AsyncSession]
             yield self._external_session
 
     async def save(self, instance: MODEL) -> MODEL:
-        """Persist a model.
-
-        :param instance: A mapped object instance to be persisted
-        :return: The model instance after being persisted
-        """
         async with self._get_session() as session:
             session.add(instance)
         return instance
@@ -78,24 +73,11 @@ async def save_many(
         self,
         instances: Iterable[MODEL],
     ) -> Iterable[MODEL]:
-        """Persist many models in a single database get_session.
-
-        :param instances: A list of mapped objects to be persisted
-        :type instances: Iterable
-        :return: The model instances after being persisted
-        """
         async with self._get_session() as session:
             session.add_all(instances)
         return instances
 
     async def get(self, identifier: PRIMARY_KEY) -> MODEL:
-        """Get a model by primary key.
-
-        :param identifier: The primary key
-        :return: A model instance
-        :raises ModelNotFound: No model has been found using the primary key
-        """
-        # TODO: implement get_many()
         async with self._get_session(commit=False) as session:
             model = await session.get(self._model, identifier)
         if model is None:
@@ -106,11 +88,6 @@ async def delete(
         self,
         entity: Union[MODEL, PRIMARY_KEY],
     ) -> None:
-        """Deletes a model.
-
-        :param entity: The model instance or the primary key
-        :type entity: Union[MODEL, PRIMARY_KEY]
-        """
         # TODO: delete without loading the model
         if isinstance(entity, self._model):
             obj = entity
@@ -124,20 +101,6 @@ async def find(
         search_params: Union[None, Mapping[str, Any]] = None,
         order_by: Union[None, Iterable[Union[str, Tuple[str, SortDirection]]]] = None,
     ) -> List[MODEL]:
-        """Find models using filters
-
-        E.g.
-        find(search_params={"name": "John"}) finds all models with name = John
-
-        :param order_by:
-        :param search_params: A dictionary containing equality filters
-        :param limit: Number of models to retrieve
-        :type limit: int
-        :param offset: Number of models to skip
-        :type offset: int
-        :return: A collection of models
-        :rtype: List
-        """
         stmt = self._find_query(search_params, order_by)
 
         async with self._get_session() as session:
@@ -147,25 +110,10 @@ async def find(
     async def paginated_find(
         self,
         items_per_page: int,
-        page: int,
+        page: int = 1,
         search_params: Union[None, Mapping[str, Any]] = None,
         order_by: Union[None, Iterable[Union[str, Tuple[str, SortDirection]]]] = None,
     ) -> PaginatedResult[MODEL]:
-        """Find models using filters and 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 page: Page to retrieve
-        :type page: int
-        :param search_params: A dictionary containing equality filters
-        :param order_by:
-        :return: A collection of models
-        :rtype: List
-        """
-
         find_stmt = self._find_query(search_params, order_by)
         paginated_stmt = self._paginate_query_by_page(find_stmt, page, items_per_page)
 
@@ -191,23 +139,6 @@ async 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(
             find_stmt,

sqlalchemy_bind_manager/_repository/sync.py

@@ -41,14 +41,6 @@ def __init__(
         session: Union[Session, None] = None,
         model_class: Union[Type[MODEL], None] = None,
     ) -> None:
-        """
-        :param bind: A configured instance of SQLAlchemyBind
-        :type bind: Union[SQLAlchemyBind, None]
-        :param session: An externally managed session
-        :type session: Union[Session, None]
-        :param model_class: A mapped SQLAlchemy model
-        :type model_class: Union[Type[MODEL], None]
-        """
         super().__init__(model_class=model_class)
         if not (bool(bind) ^ bool(session)):
             raise InvalidConfig("Either `bind` or `session` have to be used, not both")
@@ -65,46 +57,23 @@ def _get_session(self, commit: bool = True) -> Iterator[Session]:
             yield self._external_session
 
     def save(self, instance: MODEL) -> MODEL:
-        """Persist a model.
-
-        :param instance: A mapped object instance to be persisted
-        :return: The model instance after being persisted
-        """
         with self._get_session() as session:
             session.add(instance)
         return instance
 
     def save_many(self, instances: Iterable[MODEL]) -> Iterable[MODEL]:
-        """Persist many models in a single database get_session.
-
-        :param instances: A list of mapped objects to be persisted
-        :type instances: Iterable
-        :return: The model instances after being persisted
-        """
         with self._get_session() as session:
             session.add_all(instances)
         return instances
 
     def get(self, identifier: PRIMARY_KEY) -> MODEL:
-        """Get a model by primary key.
-
-        :param identifier: The primary key
-        :return: A model instance
-        :raises ModelNotFound: No model has been found using the primary key
-        """
-        # TODO: implement get_many()
         with self._get_session(commit=False) as session:
             model = session.get(self._model, identifier)
         if model is None:
             raise ModelNotFound("No rows found for provided primary key.")
         return model
 
     def delete(self, entity: Union[MODEL, PRIMARY_KEY]) -> None:
-        """Deletes a model.
-
-        :param entity: The model instance or the primary key
-        :type entity: Union[MODEL, PRIMARY_KEY]
-        """
         # TODO: delete without loading the model
         if isinstance(entity, self._model):
             obj = entity
@@ -118,16 +87,6 @@ def find(
         search_params: Union[None, Mapping[str, Any]] = None,
         order_by: Union[None, Iterable[Union[str, Tuple[str, SortDirection]]]] = None,
     ) -> List[MODEL]:
-        """Find models using filters
-
-        E.g.
-        find(name="John") finds all models with name = John
-
-        :param search_params: A dictionary containing equality filters
-        :param order_by:
-        :return: A collection of models
-        :rtype: List
-        """
         stmt = self._find_query(search_params, order_by)
 
         with self._get_session() as session:
@@ -137,25 +96,10 @@ def find(
     def paginated_find(
         self,
         items_per_page: int,
-        page: int,
+        page: int = 1,
         search_params: Union[None, Mapping[str, Any]] = None,
         order_by: Union[None, Iterable[Union[str, Tuple[str, SortDirection]]]] = None,
     ) -> PaginatedResult[MODEL]:
-        """Find models using filters and page 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 page: Page to retrieve
-        :type page: int
-        :param search_params: A dictionary containing equality filters
-        :param order_by:
-        :return: A collection of models
-        :rtype: List
-        """
-
         find_stmt = self._find_query(search_params, order_by)
         paginated_stmt = self._paginate_query_by_page(find_stmt, page, items_per_page)