Documentation review (#54)

febus982 · web-flow · commit 974c49103eb4 · 2024-03-22T13:59:13.000Z
* Documentation review
diff --git a/docs/.pages b/docs/.pages
@@ -3,4 +3,5 @@ nav:
   - Bind manager: manager
   - Repository: repository
   - Components life cycle: lifecycle.md
+  - API Reference: api_reference
   - ...
diff --git a/docs/api_reference/.pages b/docs/api_reference/.pages
@@ -0,0 +1,5 @@
+nav:
+  - bind_manager.md
+  - repository.md
+  - exceptions.md
+  - ...
diff --git a/docs/api_reference/bind_manager.md b/docs/api_reference/bind_manager.md
@@ -0,0 +1,6 @@
+::: sqlalchemy_bind_manager
+    options:
+      members:
+      - SQLAlchemyBindManager 
+      - SQLAlchemyConfig 
+      - SQLAlchemyAsyncConfig 
diff --git a/docs/api_reference/exceptions.md b/docs/api_reference/exceptions.md
@@ -0,0 +1 @@
+::: sqlalchemy_bind_manager.exceptions
diff --git a/docs/api_reference/repository.md b/docs/api_reference/repository.md
@@ -0,0 +1,9 @@
+::: sqlalchemy_bind_manager.protocols
+    options:
+      members:
+      - SQLAlchemyRepositoryInterface
+      - SQLAlchemyAsyncRepositoryInterface
+      - SortDirection
+      - PaginatedResult
+      - CursorPaginatedResult
+      - CursorReference
diff --git a/docs/index.md b/docs/index.md
@@ -98,6 +98,6 @@ It's not recommended to create long-lived sessions like:
 session = sa_manager.get_session()
 ```
 
-This can create unexpected because of global variables and multi-threading.
-More details can be found in the [session page](manager/session/#note-on-multithreaded-applications)
+This can create unexpected behaviours because of global variables and multi-threading.
+More details can be found in the [session page](manager/session.md#note-on-multithreaded-applications)
 ///
diff --git a/docs/manager/session.md b/docs/manager/session.md
@@ -24,16 +24,18 @@ multiple threads, like spawning a thread per request, then you should not store
 initialised session in a global variable, otherwise the state of your models will be shared
 among the threads and produce undesired changes in the database.
 
-This is not thread safe:
+This is **not** thread safe:
 
 /// note | db.py (a module to have an easy to use session)
 ```python
+sa_manager = SQLAlchemyBindManager(some_config)
+
 session = sa_manager.get_session()
 ```
 ///
 
 
-/// note | some_other_module.py (a module to have an easy-to=use session)
+/// note | some_other_module.py
 ```python
 from db import session
 
@@ -45,9 +47,16 @@ session.commit()
 
 This instead would be thread safe:
 
-/// note | some_other_module.py (a module to have an easy-to=use session)
+/// note | db.py (a module to have an easy to use SQLAlchemyBindManager)
+```python
+sa_manager = SQLAlchemyBindManager(some_config)
+```
+///
 
+/// note | some_other_module.py
 ```python
+from db import sa_manager
+
 def do_something():
     session = sa_manager.get_session()
     session.add(model)
@@ -57,8 +66,7 @@ def do_something():
 do_something()
 ```
 
-The `do_something` function can be also in another method, as long as
-the `session` variable has no global scope it will be safe.
+As long as the `session` variable has no global scope it will be safe.
 ///
 
 /// tip | Using the `get_session()` context manager is much easier
@@ -77,3 +85,7 @@ session = scoped_session(sa_manager.get_bind().session_class())
 Handling the life cycle of scoped sessions is not supported by this documentations.
 Please refer to [SQLAlchemy documentation](https://docs.sqlalchemy.org/en/20/orm/contextual.html)
 about this.
+
+/// tip | The repository implementation will handle the session life cycle for you
+
+///
diff --git a/docs/repository/uow.md b/docs/repository/uow.md
@@ -27,14 +27,11 @@ with uow.transaction(read_only=True):
     model2 = uow.repository("repo_b").get(2)
 ```
 
-/// admonition | The unit of work implementation is still experimental.
+/// admonition | The unit of work implementation is limited to repositories using the same bind.
     type: warning
 
-There are some limitations in the current implementation that could radically change
-the implementation:
-
-* Distributed transactions are not yet supported. 
-* The direct use of `SQLAlchemyRepository` and `SQLAlchemyAsyncRepository` classes is not yet supported.
+[Two-phase commits](https://docs.sqlalchemy.org/en/20/orm/session_transaction.html#enabling-two-phase-commit)
+are not yet supported.
 ///
 
 Both the UnitOfWork classes create an internal `scoped_session` or `async_scoped_session`, behaving
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -11,15 +11,33 @@ plugins:
   - search
   - awesome-pages
   - mike
-  - gen-files:
-      scripts:
-        - scripts/gen_pages.py  # or any other name or path
+#  - gen-files:
+#      scripts:
+#        - scripts/gen_pages.py  # or any other name or path
   - mkdocstrings:
+      default_handler: python
       handlers:
         python:
           options:
+            # General options
+            show_source: true
+            show_bases: false
+            # Headings options
+            show_root_heading: true
+            show_root_members_full_path: true
+            # Members options
+            inherited_members: true
+            group_by_category: true
+            members_order: source
+            # Docstrings options
             docstring_style: sphinx
-            docstring_section_style: spacy
+            merge_init_into_class: false
+            show_if_no_docstring: false
+            # Signature options
+            show_signature_annotations: true
+            separate_signature: true
+            signature_crossrefs: true
+            unwrap_annotated: true
 
 theme:
   name: material
diff --git a/sqlalchemy_bind_manager/_bind_manager.py b/sqlalchemy_bind_manager/_bind_manager.py
@@ -39,12 +39,20 @@
 
 
 class SQLAlchemyConfig(BaseModel):
+    """
+    Configuration for synchronous engines
+    """
+
     engine_url: str
     engine_options: Union[dict, None] = None
     session_options: Union[dict, None] = None
 
 
 class SQLAlchemyAsyncConfig(BaseModel):
+    """
+    Configuration for asynchronous engines
+    """
+
     engine_url: str
     engine_options: Union[dict, None] = None
     session_options: Union[dict, None] = None
@@ -68,11 +76,6 @@ class SQLAlchemyAsyncBind(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
 
-_SQLAlchemyConfig = Union[
-    Mapping[str, Union[SQLAlchemyConfig, SQLAlchemyAsyncConfig]],
-    SQLAlchemyConfig,
-    SQLAlchemyAsyncConfig,
-]
 DEFAULT_BIND_NAME = "default"
 
 
@@ -81,7 +84,11 @@ class SQLAlchemyBindManager:
 
     def __init__(
         self,
-        config: _SQLAlchemyConfig,
+        config: Union[
+            Mapping[str, Union[SQLAlchemyConfig, SQLAlchemyAsyncConfig]],
+            SQLAlchemyConfig,
+            SQLAlchemyAsyncConfig,
+        ],
     ) -> None:
         self.__binds = {}
         if isinstance(config, Mapping):
@@ -162,31 +169,54 @@ def __build_async_bind(
             declarative_base=registry_mapper.generate_base(),
         )
 
-    def get_binds(self) -> Mapping[str, Union[SQLAlchemyBind, SQLAlchemyAsyncBind]]:
-        return self.__binds
-
     def get_bind_mappers_metadata(self) -> Mapping[str, MetaData]:
         """
-        Returns the mappers metadata in a format that can be used
-        in Alembic configuration
+        Returns the registered mappers metadata in a format
+        that can be used in Alembic configuration
 
         :returns: mappers metadata
-        :rtype: dict
         """
         return {k: b.registry_mapper.metadata for k, b in self.__binds.items()}
 
     def get_bind(
         self, bind_name: str = DEFAULT_BIND_NAME
     ) -> Union[SQLAlchemyBind, SQLAlchemyAsyncBind]:
+        """
+        Returns a bind object by name.
+
+        :param bind_name: A registered bind name
+        :return: a bind object
+        """
         try:
             return self.__binds[bind_name]
         except KeyError:
             raise NotInitializedBindError("Bind not initialized")
 
+    def get_binds(self) -> Mapping[str, Union[SQLAlchemyBind, SQLAlchemyAsyncBind]]:
+        """
+        Returns all the registered bind objects.
+
+        :returns: A mapping containing the registered binds
+        """
+        return self.__binds
+
+    def get_mapper(self, bind_name: str = DEFAULT_BIND_NAME) -> registry:
+        """
+        Returns the registered SQLAlchemy registry_mapper for the given bind name
+
+        :param bind_name: A registered bind name
+        :return: the registered registry_mapper
+        """
+        return self.get_bind(bind_name).registry_mapper
+
     def get_session(
         self, bind_name: str = DEFAULT_BIND_NAME
     ) -> Union[Session, AsyncSession]:
-        return self.get_bind(bind_name).session_class()
+        """
+        Returns a SQLAlchemy Session object, ready to be used either
+        directly or as a context manager
 
-    def get_mapper(self, bind_name: str = DEFAULT_BIND_NAME) -> registry:
-        return self.get_bind(bind_name).registry_mapper
+        :param bind_name: A registered bind name
+        :return: The SQLAlchemy Session object
+        """
+        return self.get_bind(bind_name).session_class()
diff --git a/sqlalchemy_bind_manager/exceptions.py b/sqlalchemy_bind_manager/exceptions.py
@@ -20,32 +20,66 @@
 
 
 class NotInitializedBindError(Exception):
+    """
+    Raised when a bind object does not exist (i.e. not yet initialized)
+    """
+
     pass
 
 
 class UnsupportedBindError(Exception):
+    """
+    Raised when the internal session handler is given an unsupported bind object.
+    Usually it happens when Async and Sync implementation are mixed up
+    (i.e. initializing an `AsyncUnitOfWork` instance with a Sync bind)
+    """
+
     pass
 
 
 class InvalidConfigError(Exception):
+    """
+    Raised when a class is initialized with an invalid configuration and/or parameters.
+    """
+
     pass
 
 
 class ModelNotFoundError(Exception):
+    """
+    Raised when a Repository is not able to find a model using the provided primary key.
+    """
+
     pass
 
 
 class InvalidModelError(Exception):
-    pass
+    """
+    Raised when an invalid model is passed to a Repository object or class.
 
+    i.e.:
+
+     * Trying to instantiate a repository with a non SQLAlchemy model
+     * Trying to save a model belonging to another Repository class
+    """
 
-class UnmappedPropertyError(Exception):
     pass
 
 
-class SessionNotFoundError(Exception):
+class UnmappedPropertyError(Exception):
+    """
+    Raised when trying to execute queries using not mapped column names.
+    (i.e. passing a non-existing column to `search_params`
+    or `order_by` parameters when invoking `find()`)
+    """
+
     pass
 
 
 class RepositoryNotFoundError(Exception):
+    """
+    Raised when trying to use a repository that has not been registered
+    with the unit of work instance.
+    """
+
     pass
diff --git a/sqlalchemy_bind_manager/protocols.py b/sqlalchemy_bind_manager/protocols.py
diff --git a/tests/conftest.py b/tests/conftest.py
diff --git a/tests/repository/result_presenters/test_cursor_paginated_result_presenter.py b/tests/repository/result_presenters/test_cursor_paginated_result_presenter.py
diff --git a/tests/repository/test_common.py b/tests/repository/test_common.py
